# Track state for nagent_review_20260608
# Reference/analysis track — no implementation phases
# Updated by Tier 2 Tech Lead as track progresses (currently: complete)

[meta]
track_id = "nagent_review_20260608"
name = "nagent Review (Mike Acton's data-oriented LLM agent reference)"
status = "active"
current_phase = 0  # 0 = pre-completion; this track produces no code phases
last_updated = "2026-06-12"

[user_corrections_log]
# Corrections applied to the first draft based on direct user feedback during review
# Format: 2026-06-08_NN = "correction" (NN is sequence number to ensure TOML key uniqueness)
2026-06-08_1 = "Editable discussions: PARTIAL -> PARITY (DIFFERENT FOCUS). User pointed at HistoryManager, project_manager.branch_discussion, UISnapshot — Manual Slop has editable UI state, not editable raw transcripts."
2026-06-08_2 = "Per-file memory: DOMAIN MISMATCH -> MANUAL SLOP IS STRONGER IN CURATION DIMENSION. User pointed at FileItem (path + view_mode + ast_mask + custom_slices), ContextPreset, aggregate.py. Manual Slop's per-file memory is the curation kind, not the conversation-log kind."
2026-06-08_3 = "Sub-conversations: removed 'PARITY stronger' claim. User clarified MMA has it but 1:1 discussions do not. Added 'GAP for 1:1 discussions' + user-flagged 'want' for future sub-conversation track."
2026-06-08_4 = "RAG: clarified as opt-in, not gap. User wants pre-staging via sub-conversation ('Would be cool to have a sub agent maybe prepare a rag chunks before I use them in a run')."
2026-06-08_5 = "Personas: reframed as config bundling, not gap. User noted personas can be completely opted out by using AI settings directly. They 'just bundle preparatory cruft.'"
2026-06-08_6 = "Tool discovery: downgraded to 'intentional, low priority'. User has 'intent based DSL' idea but 'no where near that ideation yet.'"
2026-06-08_7 = "Editable discussions: REVISED AGAIN. User pointed out the report's §3 verdict (PARITY/DIFFERENT FOCUS) didn't enumerate the per-entry operations. After re-reading gui_2.py:3770-3853 (render_discussion_entry) and gui_2.py:4239-4260 (render_discussion_entry_controls) and history.py (UISnapshot/HistoryManager), the report's §3 now lists the full A1-A7 per-entry + B1-B11 discussion-level + C1-C5 undo/redo operations. The 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. The 'raw transcript is in process globals' framing in the previous draft is still correct as a *layer* description, but the report now correctly characterizes Manual Slop's editing as comprehensive at the user-visible layer."

[tasks]
# Reference track; no implementation tasks. Future-track candidates live in decisions.md.
# Listing for accountability:

t_reference_01 = { status = "completed", commit_sha = "", description = "Read nagent README + bin/nagent in full" }
t_reference_02 = { status = "completed", commit_sha = "", description = "Read all 6 nagent helper files in full (cli, llm, file_edit, file_split, file_patch, file_summarize)" }
t_reference_03 = { status = "completed", commit_sha = "", description = "Read all 4 nagent executable scripts in full (nagent-file-edit, nagent-file-split, nagent-file-patch, nagent-file-summarize)" }
t_reference_04 = { status = "completed", commit_sha = "", description = "Read Manual Slop docs/ in full (12 guides + Readme)" }
t_reference_05 = { status = "completed", commit_sha = "", description = "Read Manual Slop src/ files selectively for user-corrections (models.py FileItem + ContextPreset, context_presets.py, project_manager.py, aggregate.py, history.py)" }
t_write_01 = { status = "completed", commit_sha = "", description = "Draft spec.md (track wrapper)" }
t_write_02 = { status = "completed", commit_sha = "", description = "Draft report.md (14-section deep-dive analysis; primary deliverable)" }
t_write_03 = { status = "completed", commit_sha = "", description = "Draft comparison_table.md (flat side-by-side reference)" }
t_write_04 = { status = "completed", commit_sha = "", description = "Draft decisions.md (10 future-track candidates)" }
t_write_05 = { status = "completed", commit_sha = "", description = "Create metadata.json + state.toml" }
t_write_06 = { status = "completed", commit_sha = "", description = "Draft nagent_takeaways_20260608.md (10 actionable patterns; companion to report.md)" }
t_write_07 = { status = "pending",    commit_sha = "", description = "Add entry to conductor/tracks.md (post-commit)" }
t_write_08 = { status = "pending",    commit_sha = "", description = "Human review of report.md + nagent_takeaways_20260608.md (final)" }
t_archive = { status = "pending",       commit_sha = "", description = "Move track to conductor/tracks/archive/ when follow-up tracks are specced (or sooner if no value remains)" }

# v2 review (2026-06-12): 8 new nagent commits since v1; README restructured; knowledge harvest is the major new pattern
t_v2_review_01 = { status = "completed", commit_sha = "", description = "v2 review: enumerate 8 new nagent commits between 2026-06-08 and 2026-06-12" }
t_v2_review_02 = { status = "completed", commit_sha = "", description = "v2 review: document knowledge harvest (nagent-gc) pattern + per-file notes" }
t_v2_review_03 = { status = "completed", commit_sha = "", description = "v2 review: document stable-to-volatile context ordering for prompt caching" }
t_v2_review_04 = { status = "completed", commit_sha = "", description = "v2 review: document conversation compaction (--compact) vs summarization" }
t_v2_review_05 = { status = "completed", commit_sha = "", description = "v2 review: document project context files, claude-code provider, save-with-graceful-failure" }
t_v2_review_06 = { status = "completed", commit_sha = "", description = "v2 review: map staleness in v1 report.md / comparison_table.md / decisions.md / nagent_takeaways_20260608.md" }
t_v2_review_07 = { status = "completed", commit_sha = "", description = "v2 review: propose 5 new future-track candidates (11-15) with priority and effort" }
t_v2_review_08 = { status = "completed", commit_sha = "", description = "v2 review: write nagent_review_v2_20260612.md (new file; v1 preserved)" }
t_v2_review_pending_01 = { status = "pending", commit_sha = "", description = "User to surface Candidate 11 (Knowledge Harvest) as the primary v2 finding" }
t_v2_review_pending_02 = { status = "pending", commit_sha = "", description = "Tier 2 source-read: verify Candidate 15 (save-with-graceful-summary-failure) is potentially a latent bug" }
t_v2_review_pending_03 = { status = "pending", commit_sha = "", description = "Update v1 decisions.md to add Candidates 11-15 and refresh re-rankings" }
t_v2_review_pending_04 = { status = "pending", commit_sha = "", description = "Update v1 comparison_table.md to add 4 new rows and 4 row updates" }
t_v2_review_pending_05 = { status = "pending", commit_sha = "", description = "Update v1 nagent_takeaways_20260608.md to add 3 new takeaways and refresh 6 existing" }
t_v2_review_pending_06 = { status = "pending", commit_sha = "", description = "Update agent workflow docs (AGENTS.md, conductor/workflow.md, conductor/product-guidelines.md) to incorporate v2 design principles" }
t_v2_review_pending_07 = { status = "pending", commit_sha = "", description = "Tier 2 source-read: verify 8 items in nagent_review_v2_20260612.md §8 before any new candidate is scoped" }

# v2.1 review (2026-06-12, second user iteration): user corrections to v2
# v2 file is PRESERVED as the draft; v2.1 is the user-revised version
t_v2_1_review_01 = { status = "completed", commit_sha = "", description = "v2.1: read full nagent source (bin/nagent, nagent_gc_lib.py, nagent_tags.py, nagent_llm.py, nagent_gc CLI, prompts/*.md, context/data-oriented-design.md, CLAUDE.md) — 18 files in full" }
t_v2_1_review_02 = { status = "completed", commit_sha = "", description = "v2.1: reframe Candidate 11 from 'RAG alternative' to 'third memory dimension' (curation + discussion + RAG + knowledge)" }
t_v2_1_review_03 = { status = "completed", commit_sha = "", description = "v2.1: swap CLAUDE.md → AGENTS.md throughout (Manual Slop has AGENTS.md, not CLAUDE.md)" }
t_v2_1_review_04 = { status = "completed", commit_sha = "", description = "v2.1: add cache TTL GUI controls (sub-candidate 12b) — per the user's explicit ask for 'how long the caches are available for (gemini has a limit for example)'" }
t_v2_1_review_05 = { status = "completed", commit_sha = "", description = "v2.1: add new RAG integration discipline sub-section (§2.10) — 'we should be conservative' about wiring RAG; codify when RAG fits (semantic search across large codebases) and when it does not (curation/discussion/knowledge)" }
t_v2_1_review_06 = { status = "completed", commit_sha = "", description = "v2.1: preserve v2 as the draft (NON-DESTRUCTIVE write to nagent_review_v2_1_20260612.md)" }
t_v2_1_review_07 = { status = "completed", commit_sha = "", description = "v2.1: preserve Readme.md and docs/Readme.md as human-facing; propose new agent-facing files instead (AGENTS.md @import update; new ./docs/AGENTS.md)" }
t_v2_1_review_08 = { status = "completed", commit_sha = "", description = "v2.1: write nagent_review_v2_1_20260612.md (new file, ~59KB) with the reframe, the swap, the new styleguide list, the new docs list, and the workflow doc update plan" }

# v2.1 pending (for the next turn)
t_v2_1_review_pending_01 = { status = "pending", commit_sha = "", description = "User review of v2.1 + confirmation of which new artifacts to create in the next turn" }
t_v2_1_review_pending_02 = { status = "pending", commit_sha = "", description = "Create canonical DOD file at conductor/code_styleguides/data_oriented_design.md (cloned/adapted from nagent's context/data-oriented-design.md)" }
t_v2_1_review_pending_03 = { status = "pending", commit_sha = "", description = "Update AGENTS.md to add @conductor/code_styleguides/data_oriented_design.md import + 'what this is' section" }
t_v2_1_review_pending_04 = { status = "pending", commit_sha = "", description = "Create ./docs/AGENTS.md as agent-facing mirror of docs/Readme.md (which stays human-facing)" }
t_v2_1_review_pending_05 = { status = "pending", commit_sha = "", description = "Write 5 new styleguides (agent_memory_dimensions.md, rag_integration_discipline.md, cache_friendly_context.md, knowledge_artifacts.md, feature_flags.md)" }
t_v2_1_review_pending_06 = { status = "pending", commit_sha = "", description = "Write 3 new docs (guide_knowledge_curation.md, guide_caching_strategy.md, guide_agent_memory_dimensions.md)" }
t_v2_1_review_pending_07 = { status = "pending", commit_sha = "", description = "Update existing workflow docs (conductor/workflow.md, conductor/product-guidelines.md, docs/guide_mma.md, docs/guide_ai_client.md) with v2.1 patterns" }
t_v2_1_review_pending_08 = { status = "pending", commit_sha = "", description = "Verify Candidate 15 (save-with-graceful-summary-failure) by reading src/ai_client.py:run_discussion_compression" }

# v2.2 review (2026-06-12, third iteration): user finished intent_dsl_survey_20260612 report_v1.2;
# v2.1 was the seed for survey §6 Claims 4 and 5; v2.2 applies the new style preferences (tables,
# SSDL tags, no JSON) and explicitly cross-references the survey
# v2 and v2.1 are PRESERVED; v2.2 is non-destructive new file
t_v2_2_review_01 = { status = "completed", commit_sha = "", description = "v2.2: read intent_dsl_survey_20260612/report_v1.2.md §1, §3, §4, §5, §6, §7 (~600 lines; 10 prior-art clusters, 4 anchor claims, ~42-verb vocab, 10 AI-Agent Properties)" }
t_v2_2_review_02 = { status = "completed", commit_sha = "", description = "v2.2: applied the user's data-format preferences (table-based, forth/array-like, no JSON) — JSON blocks in v2.1 §2.1 replaced with §4.4 7-column tables (Symbol, Name, Signature, Semantics, Example, Borrowed from, Shape)" }
t_v2_2_review_03 = { status = "completed", commit_sha = "", description = "v2.2: adopted SSDL shape tags ([I], ->, o->, [B], [M], [N], [Q], [S], ───) for the comparison table and future-track candidate list" }
t_v2_2_review_04 = { status = "completed", commit_sha = "", description = "v2.2: cross-referenced the intent DSL survey's 10 AI-Agent Properties (§6 Claims 1-10) — Claims 4 and 5 explicitly cite v2.1 §2.1 and §2.2 as their source" }
t_v2_2_review_05 = { status = "completed", commit_sha = "", description = "v2.2: applied the survey's grammar primitives (name := value, for x .. n, if cond { ... }, tape { ... }, try { ... } recover err { ... }, sandbox { ... }, audit msg, fuzzy { ... }) where applicable" }
t_v2_2_review_06 = { status = "completed", commit_sha = "", description = "v2.2: added new §11 'In dialogue with intent DSL survey' — the 9 mutual cross-references and the 3 the user should know about" }
t_v2_2_review_07 = { status = "completed", commit_sha = "", description = "v2.2: reformatted §3 future-track candidates as a single 16-row table with all metadata columns (Symbol, Name, Domain, Priority, Effort, Shape, Depends on, Cross-refs)" }
t_v2_2_review_08 = { status = "completed", commit_sha = "", description = "v2.2: added Candidate 12b (cache TTL GUI controls) and Candidate 16 (AGENTS.md @import + canonical DOD file) to the table; re-ranked priorities" }
t_v2_2_review_09 = { status = "completed", commit_sha = "", description = "v2.2: wrote nagent_review_v2_2_20260612.md (new file, ~35KB) — focused delta, not a full rewrite; v2 and v2.1 are preserved" }
t_v2_2_review_10 = { status = "completed", commit_sha = "", description = "v2.2: format commitment for the upcoming next-turn artifacts — all new styleguides and project docs will follow the §4.4 table format" }

# v2.2 pending (for the next turn)
t_v2_2_review_pending_01 = { status = "pending", commit_sha = "", description = "User review of v2.2 + confirmation of which new artifacts to create in the next turn" }
t_v2_2_review_pending_02 = { status = "pending", commit_sha = "", description = "Create canonical DOD file at conductor/code_styleguides/data_oriented_design.md (in §4.4 table format)" }
t_v2_2_review_pending_03 = { status = "pending", commit_sha = "", description = "Update AGENTS.md to add @conductor/code_styleguides/data_oriented_design.md import (in §4.4 table format)" }
t_v2_2_review_pending_04 = { status = "pending", commit_sha = "", description = "Create ./docs/AGENTS.md as agent-facing mirror of docs/Readme.md (in §4.4 table format)" }
t_v2_2_review_pending_05 = { status = "pending", commit_sha = "", description = "Write 5 new styleguides in §4.4 table format (agent_memory_dimensions.md, rag_integration_discipline.md, cache_friendly_context.md, knowledge_artifacts.md, feature_flags.md)" }
t_v2_2_review_pending_06 = { status = "pending", commit_sha = "", description = "Write 3 new project docs in §4.4 table format (guide_knowledge_curation.md, guide_caching_strategy.md, guide_agent_memory_dimensions.md)" }
t_v2_2_review_pending_07 = { status = "pending", commit_sha = "", description = "Update existing workflow docs (conductor/workflow.md, conductor/product-guidelines.md, docs/guide_mma.md, docs/guide_ai_client.md) using survey grammar primitives and §4.4 table format" }

[user_wants_recorded]
# User explicitly wants these in priority order (see decisions.md for full detail)
want_1_sub_conversation_runner = "EXPLICIT: 'I probably want to add that for just 1:1 discussions where I use a sub-agent manually for specific points'"
want_2_rag_pre_staging = "EXPLICIT: 'Would be cool to have a sub agent maybe prepare a rag chunks before I use them in a run'"
deferred_intent_dsl = "EXPLICIT but deferred: 'I want to add an intent based dsl to help with discovery or combinatorics but no where near that ideation yet'"

[verification]
# Reference/analysis track; verification is artifact presence + user-correction application

report_md_exists = true
comparison_table_md_exists = true
decisions_md_exists = true
spec_md_exists = true
metadata_json_exists = true
state_toml_exists = true
nagent_takeaways_md_exists = true

# All 14 nagent principles have a corresponding section in report.md
all_14_principles_covered = true

# All user-corrections applied to first draft
all_user_corrections_applied = true

# All pitfalls are domain-tagged (Application / Meta-Tooling / Both)
all_pitfalls_domain_tagged = true

# Track produces no code (it's a reference/analysis track)
no_code_modified = true

# No links broken in comparison_table.md, decisions.md, report.md, spec.md, nagent_takeaways_20260608.md
all_internal_links_valid = true  # verified by post-edit grep

# 10 actionable takeaways grounded in actual code (file:line refs)
takeaways_grounded_in_code = true

[nagent_principles_covered]
# 14 of 14 — full coverage
durable_work = "covered in report §1"
text_in_text_out = "covered in report §2"
editable_state = "covered in report §3"
visible_protocol = "covered in report §4"
the_loop = "covered in report §5"
per_file_memory = "covered in report §6"
repo_history = "covered in report §7"
neighborhoods = "covered in report §8"
sub_conversations = "covered in report §9"
controlled_writes = "covered in report §10"
large_files = "covered in report §11"
tool_discovery = "covered in report §12"
differences_from_frameworks = "covered in report §13"
build_your_own = "covered in report §14"

[future_track_candidates]
# See decisions.md for full detail. 10 candidates.

candidate_01_sub_conversation_runner = { priority = "HIGH",     user_flag = "explicit want", domain = "App + MT", effort = "Medium" }
candidate_02_rag_pre_staging = { priority = "HIGH",     user_flag = "explicit want", domain = "App",      effort = "Small (depends on #1)" }
candidate_03_stateless_llm_client = { priority = "MEDIUM",  user_flag = "none",          domain = "App",      effort = "Large" }
candidate_04_intent_dsl = { priority = "LOW",      user_flag = "explicit but deferred", domain = "MT", effort = "Research" }
candidate_05_self_describing_tools = { priority = "LOW",  user_flag = "implicit",    domain = "BOTH",    effort = "Medium (subsumed by mcp_architecture_refactor)" }
candidate_06_git_history_injection = { priority = "MEDIUM",  user_flag = "none",          domain = "App",      effort = "Medium" }
candidate_07_per_file_conversation_log = { priority = "LOW", user_flag = "none",          domain = "App",      effort = "Small" }
candidate_08_coedited_files_tools = { priority = "LOW",    user_flag = "none",          domain = "App",      effort = "Small (bundle with #6)" }
candidate_09_split_patch_lib = { priority = "DEFER",   user_flag = "none",          domain = "App",      effort = "Medium (defer until need)" }
candidate_10_raw_transcript_persistence = { priority = "LOW", user_flag = "none",         domain = "App",      effort = "Small" }

[status]
# Track is a reference/analysis track; "active" means the artifacts are ready for review
# The track will move to "completed" and be archived when:
#   (a) At least one of the follow-up tracks (candidates 1-2) is specced, OR
#   (b) The user explicitly says the analysis is no longer needed
status = "active (reference artifacts ready; awaiting human review + follow-up track scoping)"