{
  "track_id": "nagent_review_20260608",
  "name": "nagent Review (Mike Acton's data-oriented LLM agent reference)",
  "initialized": "2026-06-08",
  "owner": "tier2-tech-lead",
  "priority": "medium",
  "status": "active",
  "type": "reference + analysis + future-track scoping",
  "scope": {
    "new_files": [
      "conductor/tracks/nagent_review_20260608/spec.md",
      "conductor/tracks/nagent_review_20260608/report.md",
      "conductor/tracks/nagent_review_20260608/comparison_table.md",
      "conductor/tracks/nagent_review_20260608/decisions.md",
      "conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md"
    ],
    "modified_files": [],
    "external_resources": [
      "nagent README: https://github.com/macton/nagent/blob/main/README.md",
      "nagent source: https://github.com/macton/nagent (all 11 source files read in full)"
    ]
  },
  "blocked_by": [],
  "blocks": [
    "sub_conversation_runner_app_1to1_20260608_PLACEHOLDER",
    "rag_pre_staging_sub_convo_20260608_PLACEHOLDER",
    "llm_client_stateless_class_20260608_PLACEHOLDER",
    "intent_dsl_for_meta_tooling_20260608_PLACEHOLDER",
    "git_history_injection_20260608_PLACEHOLDER",
    "per_file_conversation_log_20260608_PLACEHOLDER",
    "py_coedited_files_tool_20260608_PLACEHOLDER",
    "ts_c_coedited_files_tool_20260608_PLACEHOLDER",
    "split_patch_lib_20260608_PLACEHOLDER",
    "raw_transcript_persistence_per_take_20260608_PLACEHOLDER"
  ],
  "estimated_phases": 0,
  "spec": "spec.md",
  "plan": null,
  "v2_review": {
    "date": "2026-06-12",
    "report": "nagent_review_v2_20260612.md",
    "nagent_commits_reviewed": [
      "2c3c78b (2026-06-11 03:32:50) Add conversation compaction and restore initial context on load",
      "67a3ea5 (2026-06-11 23:09:57) Add knowledge harvest, tag parser, and claude-code provider",
      "5e269ca (2026-06-12 00:17:34) Add project context, prompt caching, and conversation direction",
      "ee72cb4 (2026-06-11 23:10:12) Rewrite README prompt around a teaching arc and regenerate README"
    ],
    "nagent_pushed_at_review": "2026-06-12T00:25:52Z",
    "nagent_head_at_review": "eb6be32a",
    "new_patterns_identified": [
      "Knowledge harvest (nagent-gc) - new Candidate 11, HIGH priority",
      "Stable-to-volatile context ordering for prompt caching - new Candidate 12, MEDIUM priority",
      "Conversation compaction (--compact) - new Candidate 13, MEDIUM priority",
      "Project context files (context.yaml) - new Candidate 14, LOW priority",
      "Save-with-graceful-summary-failure - new Candidate 15, TBD pending source read",
      "claude-code provider (subscription auth) - existing Gemini CLI analog, no new track",
      "Per-file knowledge notes (knowledge/files/{file_id}.md) - bundle with Candidate 11",
      "Delete-to-turn-off feature flags - design pattern, not a track",
      "Delegation reframed as context management (not parallelism) - design pattern, not a track"
    ],
    "v1_artifacts_staleness": {
      "report_md": "9 of 16 sections need updates; new sub-sections on knowledge harvest, compaction, caching, project context, claude-code",
      "comparison_table_md": "4 existing rows need updates; 4 new rows needed (knowledge harvest, prompt caching strategy, compaction, per-file notes)",
      "decisions_md": "4 existing candidates need updates; 5 new candidates (11-15) needed",
      "nagent_takeaways_20260608_md": "6 of 10 takeaways need updates; 3 new takeaways needed",
      "spec_md": "Still correct; no change needed",
      "state_toml_and_metadata_json": "Updated to reflect v2 review (this file)"
    },
    "v1_artifacts_preserved": "All v1 files preserved per user instruction ('don't delete the old report'). v2 is additive.",
    "user_signal_recorded_for_v2": "User has not yet seen v2 findings; primary surface is Candidate 11 (knowledge harvest) and verification of Candidate 15 (save-with-graceful-failure).",
    "next_steps_recommended": [
      "User review of v2 report",
      "If user approves: update v1 decisions.md / comparison_table.md / nagent_takeaways_20260608.md to integrate v2 findings",
      "Update agent workflow docs (AGENTS.md, conductor/workflow.md, conductor/product-guidelines.md) with v2 design principles",
      "Tier 2 source-read: verify 8 items in v2 report §8 before any new candidate is scoped",
      "After integration: consider whether to mark v1 track as completed (preserved in archive/) or leave active for further iterations"
    ]
  },
  "v2_1_review": {
    "date": "2026-06-12",
    "report": "nagent_review_v2_1_20260612.md",
    "status": "v2.1 is the user-revised version; v2 is preserved as the draft per user instruction",
    "user_corrections_applied": [
      "CLAUDE.md → AGENTS.md swap throughout (Manual Slop has AGENTS.md, not CLAUDE.md)",
      "Reframed Candidate 11 from 'RAG alternative' to 'third memory dimension' (curation + discussion + RAG + knowledge); removed heavy RAG emphasis",
      "Added new sub-section 2.10 'RAG integration discipline' (conservative RAG wiring; where RAG fits; where it does not)",
      "Expanded Candidate 12 with cache TTL GUI controls (sub-candidate 12b) per user's explicit 'how long the caches are available for (gemini has a limit for example)'",
      "Preserved v2 as the draft (NON-DESTRUCTIVE write to nagent_review_v2_1_20260612.md)",
      "Preserved Readme.md and docs/Readme.md as human-facing; proposed new agent-facing files (AGENTS.md @import update; new ./docs/AGENTS.md) instead"
    ],
    "nagent_source_reads_in_full": [
      "bin/nagent (2524 lines) — main loop, build_initial_context at 606-745, conversation_cache_boundaries at 970-987, call_llm at 990-1019, compact_conversation at 1975-2019, --save-conversation at 2147, --branch-conversation at 2157, --compact at 2178",
      "bin/helpers/nagent_gc_lib.py (~700 lines, 27KB) — the knowledge harvest library",
      "bin/helpers/nagent_tags.py — the new explicit tag parser (replaces regex)",
      "bin/helpers/nagent_llm.py — 5+1 providers, cache_prefix_blocks, claude-code provider",
      "bin/nagent-gc — the GC CLI wrapper",
      "prompts/compact-conversation.md — compaction guidance prompt",
      "prompts/harvest-conversation.md — strict-JSON harvest prompt",
      "context/data-oriented-design.md (13084 bytes) — the canonical DOD reference (Tier 0/1/2, simplification pass, enforceable deliverables)",
      "CLAUDE.md (5832 bytes) — the agent-facing rules file with @import pattern"
    ],
    "new_candidates_proposed": [
      "Candidate 11 REFRAMED (HIGH) — third memory dimension (not RAG alternative)",
      "Candidate 12 EXPANDED (MEDIUM) — 12a stable-to-volatile ordering + 12b cache TTL GUI controls",
      "Candidate 16 NEW (HIGH) — AGENTS.md @import pattern + canonical DOD file (foundation for other styleguides)"
    ],
    "new_artifacts_proposed_for_next_turn": {
      "new_agent_facing_files": [
        "conductor/code_styleguides/data_oriented_design.md (NEW canonical DOD file)",
        "AGENTS.md (UPDATE — add @import line)",
        "./docs/AGENTS.md (NEW — agent-facing mirror of docs/Readme.md)"
      ],
      "new_styleguides": [
        "conductor/code_styleguides/agent_memory_dimensions.md",
        "conductor/code_styleguides/rag_integration_discipline.md",
        "conductor/code_styleguides/cache_friendly_context.md",
        "conductor/code_styleguides/knowledge_artifacts.md",
        "conductor/code_styleguides/feature_flags.md"
      ],
      "new_project_docs": [
        "docs/guide_knowledge_curation.md",
        "docs/guide_caching_strategy.md",
        "docs/guide_agent_memory_dimensions.md"
      ],
      "updates_to_existing_workflow_docs": [
        "conductor/workflow.md (TDD protocol additions)",
        "conductor/product-guidelines.md (memory dimensions section)",
        "docs/guide_mma.md (context management framing)",
        "docs/guide_ai_client.md (cache TTL section)"
      ]
    },
    "preserved_files_NOT_modified": [
      "nagent_review_v2_20260612.md (v2 draft, per user instruction)",
      "report.md, comparison_table.md, decisions.md, nagent_takeaways_20260608.md (v1 review artifacts)",
      "spec.md, state.toml (original), metadata.json (pre-v2.1)",
      "Readme.md (project root, human-facing)",
      "docs/Readme.md (docs index, human-facing)"
    ]
  },
  "nagent_principles_covered": [
    "Durable work, disposable workers",
    "Text in, text out",
    "Conversations are editable state",
    "Visible output protocol",
    "The loop",
    "Per-file memory",
    "Repository history as data",
    "Historical coupling & artifact neighborhoods",
    "Disposable sub-conversations",
    "Controlled writes",
    "Large files as explicit artifacts",
    "Tool discovery",
    "Differences from frameworks",
    "Build your own"
  ],
  "manual_slop_features_audited": [
    "Context composition (FileItem + ContextPreset + custom_slices + ast_mask)",
    "Discussion Takes + branching (project_manager.branch_discussion + promote_take)",
    "UI Snapshot history (HistoryManager + UISnapshot)",
    "Personas (Persona + PersonaManager)",
    "RAG (RAGEngine + ChromaDB + summarization)",
    "Multi-provider AI client (ai_client + 5 providers)",
    "MMA conductor (mma_exec.py + ConductorEngine + WorkerPool)",
    "MCP tools (45 tools + 3-layer security)",
    "Hook API (api_hooks + api_hook_client)",
    "GUI App/Controller state delegation"
  ],
  "user_corrections_applied": [
    "Editable discussions: PARTIAL -> PARITY (DIFFERENT FOCUS)",
    "Per-file memory: DOMAIN MISMATCH -> MANUAL SLOP IS STRONGER IN CURATION DIMENSION",
    "Sub-conversations: removed 'PARITY stronger' claim; added 'GAP for 1:1 discussions'",
    "RAG: clarified as opt-in, not gap; user wants pre-staging via sub-conversation",
    "Personas: reframed as config bundling (not gap; can opt out via AI settings)",
    "Tool discovery: downgraded to 'intentional, low priority'; user has deferred DSL idea",
    "Editable discussions (second pass): report §3 now enumerates the full per-entry (A1-A7) + discussion-level (B1-B11) + undo/redo (C1-C5) operation matrix. Verdict remains PARITY (DIFFERENT FOCUS) but the gap is more precisely scoped: Manual Slop's editing is more granular at the typed-entry layer; nagent's is deeper at the raw-transcript layer."
  ],
  "domain_classification": {
    "Application_domain_pitfalls": [
      "Provider-specific history in process globals",
      "AI client is a stateful singleton with module-level globals",
      "No non-MMA disposable sub-conversations (1:1 gap)",
      "RAG is not 'history as data' (fuzzy vs exact)",
      "Optional raw-transcript persistence (niche)"
    ],
    "Meta_Tooling_domain_pitfalls": [
      "No structured output protocol (opaque function calling)",
      "Hard-coded tool discovery"
    ],
    "Application_features": [
      "Context composition with FileItem-level curation memory",
      "Discussion Takes + branching (project_manager.branch_discussion + promote_take)",
      "UI Snapshot history (HistoryManager + UISnapshot)",
      "Personas as config bundling",
      "RAG as opt-in semantic search",
      "3-layer MCP security model + Execution Clutch"
    ],
    "Meta_Tooling_features_to_borrow": [
      "nagent-style --description self-describing executables",
      "Intent-based DSL for compact tool calls"
    ]
  },
  "verification_criteria": [
    "spec.md exists and covers the 14 nagent principles",
    "report.md exists and is the primary deliverable",
    "comparison_table.md exists as flat side-by-side reference",
    "decisions.md exists with 10 future-track candidates",
    "nagent_takeaways_20260608.md exists with 10 actionable patterns (companion to report.md)",
    "Every pitfall is tagged with Application / Meta-Tooling / Both",
    "Pitfall #3 (conversations are editable) verdict is corrected to PARITY (DIFFERENT FOCUS) per user feedback",
    "Pitfall #6 (per-file memory) verdict is corrected to 'Manual Slop is stronger in curation dimension' per user feedback",
    "Pitfall #9 (sub-conversations) verdict notes MMA vs 1:1 distinction per user feedback",
    "Report §3 enumerates the per-entry (A1-A7) + discussion-level (B1-B11) + undo/redo (C1-C5) operation matrix for Manual Slop's editable-discussion system, with file:line citations into gui_2.py and history.py",
    "nagent_takeaways_20260608.md grounds each pattern in actual code with file:line references into both nagent source and Manual Slop source",
    "No code was modified by this track (reference/analysis only)"
  ],
  "links": {
    "report": "report.md",
    "comparison_table": "comparison_table.md",
    "decisions": "decisions.md",
    "takeaways": "nagent_takeaways_20260608.md",
    "user_signal_recorded": "User explicitly flagged SubConversationRunner + RAG pre-staging as wants during review",
    "related_tracks": [
      "data_oriented_error_handling_20260606 (Fleury/Acton alignment)",
      "qwen_llama_grok_integration_20260606 (OpenAI-compatible helper)",
      "mcp_architecture_refactor_20260606 (sub-MCP extraction)",
      "data_structure_strengthening_20260606 (type aliases)"
    ],
    "external": [
      "https://github.com/macton/nagent (nagent source code)",
      "https://github.com/macton/nagent/blob/main/README.md (nagent README)"
    ]
  },
  "v2_2_review": {
    "date": "2026-06-12",
    "report": "nagent_review_v2_2_20260612.md",
    "status": "v2.2 is the focused delta applying the user's data-format preferences and cross-referencing intent_dsl_survey_20260612; v2 and v2.1 are preserved",
    "user_input_acknowledged": [
      "User published intent_dsl_survey_20260612/report_v1.2.md (1367 lines, 10 prior-art clusters, 4 anchor claims, ~42-verb vocab, 10 AI-Agent Properties)",
      "User said: 'I don't really like JSON, I like table based formats more, or things that are forth/array-like'",
      "Survey's §6 Claims 4 and 5 explicitly cite nagent_review_v2_1 §2.1 and §2.2 as the source for the 4 memory dimensions and stable-to-volatile cache ordering"
    ],
    "v2_2_user_corrections_applied": [
      "Data-format preferences: tables (§4.4 7-column format from survey), SSDL shape tags, no JSON, forth/array notation (for x .. n, name := value, if cond { ... }, tape { ... }, try { ... } recover err { ... }, sandbox { ... })",
      "JSON block in v2.1 §2.1 (harvest output schema) replaced with a §4.4-style table",
      "Comparison table (§5) reformatted with SSDL shape tags",
      "Future-track candidate list (§6) reformatted as a single 16-row table with metadata columns (Symbol, Name, Domain, Priority, Effort, Shape, Depends on, Cross-refs)",
      "Proposed new artifacts (§8) reformatted in table form",
      "New §11: 'In dialogue with the intent DSL survey' — the 9 mutual cross-references"
    ],
    "intent_dsl_survey_dependencies": [
      "report_v1.2.md §1 (4 anchor claims) — applied to the nagent review",
      "report_v1.2.md §3.5 (try/recover envelope) — applied to the compaction pattern",
      "report_v1.2.md §4.4 (Tier 4 table format) — adopted as the new style for the nagent review",
      "report_v1.2.md §6 Claim 4 (4 memory dimensions) — formally codifies nagent v2.1 §2.1",
      "report_v1.2.md §6 Claim 5 (stable-to-volatile cache ordering) — formally codifies nagent v2.1 §2.2",
      "report_v1.2.md §6 Claim 9 (sandbox as IEventTarget) — referenced",
      "report_v1.2.md §6 Claim 10 (reads are free) — referenced"
    ],
    "v2_2_focused_delta": "v2.2 is a FOCUSED DELTA, not a full rewrite. Tables adopt the survey's §4.4 7-column layout. JSON blocks become tables. The 16 future-track candidates are a single table with all metadata columns. The 9 cross-references to the survey are consolidated in a new §11.",
    "next_turn_format_commitment": "All new styleguides and project docs proposed in v2.1/v2.2 §8 will follow the §4.4 7-column table format. No JSON code blocks. SSDL shape tags where applicable. Survey grammar primitives (name := value, for x .. n, if cond { ... }, tape { ... }, try { ... } recover err { ... }, sandbox { ... }, audit msg, fuzzy { ... }) used in code examples.",
    "preserved_files_NOT_modified": [
      "nagent_review_v2_20260612.md (v2 draft, preserved per user instruction)",
      "nagent_review_v2_1_20260612.md (v2.1 user-revised, preserved per user instruction)",
      "nagent_review_v2_2_20260612.md (v2.2 focused delta, preserved)",
      "report.md, comparison_table.md, decisions.md, nagent_takeaways_20260608.md (v1 review artifacts, preserved)",
      "Readme.md (project root, human-facing, preserved)",
      "docs/Readme.md (docs index, human-facing, preserved)",
      "spec.md (preserved)"
    ]
  },
  "v2_3_review": {
    "date": "2026-06-12",
    "report": "nagent_review_v2_3_20260612.md",
    "status": "v2.3 is the FULL REWRITE — the most comprehensive review of the latest nagent corpus. Stand-alone (does not reference v1, v2, v2.1, or v2.2).",
    "length": "271703 bytes, 3965 lines (longer than v2 at 68KB, v2.1 at 59KB, v2.2 at 35KB). Combined v2.1's breadth with v2.2's terse DSL style + full source-line citations + new content the prior reviews did not have.",
    "user_input": [
      "User: 'I want a full rewrite via a v2.3 I guess.'",
      "User: 'don't ref v1 ref v2 related I want his latest corpus not something outdated mixed in with my intent-based report mixed in'",
      "User: 'I want LONG REPORTS. make v2.3 the longest, i never said I don't want to be long.'",
      "User: 'You actually trucated info with 2.3. 2.1 had the breadth. you should make 2.3 have both 2.1 breadth and 2.2 terse DSL stuff, etc.'"
    ],
    "v2_3_fixes": [
      "Full rewrite (not a delta)",
      "Pure nagent corpus focus (no references to v1/v2/v2.1/v2.2; the v2/v2.1/v2.2 files are preserved but not cross-referenced)",
      "Pure nagent corpus focus (no references to the intent_dsl_survey_20260612 report as a primary source; only the user-preferred data format from the SSDL digest + ASCII sketch workflow is applied)",
      "Combined v2.1's breadth (the 14 patterns deep-dived; the 12 new additions deep-dived) with v2.2's terse DSL style (tables, SSDL tags, forth/array notation, no JSON code blocks)",
      "All 14 README patterns covered in detail with file:line citations into nagent source",
      "All 12 new additions (2026-06-08 to 2026-06-12) covered in detail with file:line citations",
      "3 deep-dives added (harvest pipeline, cache strategy, compaction pattern)",
      "Architecture section (4 reading levels + tag protocol + state model + write boundaries + large-file pipeline)",
      "Vocabulary section (8 tags + per-tag guidance + 4-tier structure)",
      "File-ops section (split / patch / summarize pipeline)",
      "16 future-track candidates with full specifications and dependencies",
      "14 new artifacts proposed for the next turn (styleguides + project docs + workflow updates)",
      "Format commitment for the new artifacts (7-column tables, no JSON, SSDL tags, forth/array notation)"
    ],
    "preserved_files_NOT_modified": [
      "nagent_review_v2_20260612.md (v2 draft, preserved per user instruction)",
      "nagent_review_v2_1_20260612.md (v2.1 user-revised, preserved per user instruction)",
      "nagent_review_v2_2_20260612.md (v2.2 focused delta, preserved)",
      "report.md, comparison_table.md, decisions.md, nagent_takeaways_20260608.md (v1 review artifacts, preserved)",
      "Readme.md (project root, human-facing, preserved)",
      "docs/Readme.md (docs index, human-facing, preserved)",
      "spec.md (preserved)"
    ]
  }
}