Private
Public Access
conductor(track): nagent_review_v3.1 spec + plan (standalone-readable)
Initial v3.1 spec + plan for the delta thickening of v3. v3.1 is the canonical v3 review at depth (>=3,800 LOC main review) with a chunking strategy that v3 lacked. Adds 3 new top-level sections (YAML avoidance, agent context-window, fine-tuning). Load-bearing principle: v3.1 is standalone-readable without consulting v2.3 or v3.
This commit is contained in:
@@ -0,0 +1,920 @@
|
||||
# nagent_review_v3.1 Implementation Plan
|
||||
|
||||
> **For agentic workers:** v3.1 is Tier 1 sole-authored (mirroring v3 and `fable_review_20260617`). The "tasks" below describe the structure each piece of work must produce; the actual prose is written by the Tier 1 author during execution. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Produce the v3.1 delta thickening of the nagent review — expand the 11 cluster sections in `nagent_review_v3_20260619.md` from ~60 lines/cluster to 300-450 lines/cluster (per the chunking strategy), append 3 new top-level sections (§12 YAML avoidance, §13 Agent context-window observations, §14 Fine-tuning observations), refresh the side artifacts, and write a delta-summary doc + bridge doc.
|
||||
|
||||
**Architecture:** 15 phases. Phase 1 is setup + audit. Phases 2-12 are one phase per cluster (thickening — each phase deepens the v3 cluster to the v3.1 chunking target). Phase 13 writes the 3 new sections. Phase 14 refreshes the side artifacts (comparison_table, decisions, new takeaways bridge). Phase 15 verifies the chunking strategy + format commitment. Each phase commits atomically with a git note.
|
||||
|
||||
**Tech Stack:** Markdown (the deliverable). `git` for atomic per-phase commits + `git notes` for per-task summaries. `state.toml` for per-task commit SHA tracking. `manual-slop` MCP tools for file reads. `webfetch` for the GitHub commit/file fetches + the fine-tuning vendor pricing pages.
|
||||
|
||||
**Spec pair:** This plan implements `spec_v3.1.md` in the same track directory. Read the spec first; the plan is executable against the spec.
|
||||
|
||||
**Naming convention:** All v3.1 file basenames use `20260620` (today, the day v3.1 was initiated). The main review file (`nagent_review_v3_20260619.md`) keeps its v3 filename; only the new files use `20260620`.
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
### Files created in v3.1
|
||||
|
||||
| Path | Purpose |
|
||||
|---|---|
|
||||
| `conductor/tracks/nagent_review_20260608/plan_v3.1.md` | This file. |
|
||||
| `conductor/tracks/nagent_review_20260608/spec_v3.1.md` | The v3.1 spec. |
|
||||
| `conductor/tracks/nagent_review_20260608/nagent_review_v3_1_20260620.md` | The v3.1 delta summary doc. ~200 LOC. Points to the thickened sections + summarizes the new sections. |
|
||||
| `conductor/tracks/nagent_review_20260608/nagent_takeaways_v3_1_20260620.md` | The v3.1 bridge doc. ~150 LOC. 5-part structure. |
|
||||
|
||||
### Files refreshed in v3.1 (REPLACE / THICKEN in place)
|
||||
|
||||
| Path | Refresh action |
|
||||
|---|---|
|
||||
| `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` | THICKEN: each cluster section grows from ~60 lines to 300-450 lines (per cluster) via the chunking strategy. 3 new sections (§12-§14) appended. Total target: ≥3,800 lines. |
|
||||
| `conductor/tracks/nagent_review_20260608/comparison_table.md` | REPLACE: refreshed for v3.1. Adds rows for §12, §13, §14. Target: 100-130 lines. |
|
||||
| `conductor/tracks/nagent_review_20260608/decisions.md` | REPLACE: refreshed for v3.1. Adds 3-5 new candidates (Candidates 27-30). Target: 180-220 lines. |
|
||||
| `conductor/tracks/nagent_review_20260608/metadata.json` | REFRESH: v3.1 fields. |
|
||||
| `conductor/tracks/nagent_review_20260608/state.toml` | REFRESH: v3.1 phases + tasks. |
|
||||
|
||||
### Files NOT modified in v3.1
|
||||
|
||||
| Path | Why preserved |
|
||||
|---|---|
|
||||
| `conductor/tracks/nagent_review_20260608/spec_v3.md` + `plan_v3.md` | v3 spec/plan pair; historical. |
|
||||
| `conductor/tracks/nagent_review_20260608/nagent_review_v2_*.md` + `report.md` | All v2.x historical. |
|
||||
| `conductor/tracks/nagent_review_20260608/nagent_takeaways_v3_20260619.md` | v3-era bridge; preserved unchanged. |
|
||||
| `conductor/tracks.md` | Per "B. Same track" decision. |
|
||||
|
||||
### File responsibility boundaries
|
||||
|
||||
- **`nagent_review_v3_20260619.md`** owns the thickened cluster sections + the 3 new top-level sections (§12-§14). The filename is preserved because the content grows in place — v3.1 is a delta thickening, not a new review.
|
||||
- **`nagent_review_v3_1_20260620.md`** owns the delta summary — a quick-reference doc that points to the thickened sections + summarizes the new sections. The "v3.1 added X" reference.
|
||||
- **`nagent_takeaways_v3_1_20260620.md`** owns the bridge doc (TL;DR + cross-ref table + new candidates + sibling pointer).
|
||||
- **`comparison_table.md`** owns the flat side-by-side table for v3.1's 14 sections (11 clusters + 3 new).
|
||||
- **`decisions.md`** owns the v3.1 candidate list (v3's 25-30 + v3.1's 3-5 new).
|
||||
- **`metadata.json`** + **`state.toml`** own the machine-readable summary + per-task progress.
|
||||
|
||||
---
|
||||
|
||||
## The Chunking Strategy (the new constraint)
|
||||
|
||||
These targets are enforced per cluster. Phase 15 verifies all of them mechanically.
|
||||
|
||||
| Metric | Target | Verification command |
|
||||
|---|---|---|
|
||||
| **Main review total LOC** | ≥3,800 lines | `wc -l conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` |
|
||||
| **Per-cluster LOC** | 300-450 lines (deep-dive clusters §9-§11: 400-500) | per-cluster `wc -l` on the cluster section |
|
||||
| **Per-cluster sub-sections** | 4-7 | per-cluster `grep -c "^#### §N\."` |
|
||||
| **Per-cluster source-read citations** | ≥30 | per-cluster grep for `path/to/file:L[0-9]+` or `prompts/[a-z_-]+.md` or `bin/[a-z_-]+` or commit SHA |
|
||||
| **Per-cluster honest gaps** | ≥6 | per-cluster grep for `Honest gaps` bullet count |
|
||||
| **Per-cluster Manual Slop implications** | 2-3 paragraphs with file:line citations | manual inspection per cluster |
|
||||
| **Frontmatter + §0 + §12-14 + references** | 200-400 lines | `wc -l` |
|
||||
|
||||
A failure on any metric = back to the cluster phase, add depth, re-commit, re-verify.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Setup + audit
|
||||
|
||||
Focus: Initialize v3.1's track-state plumbing + audit the v3 baseline.
|
||||
|
||||
**Files:**
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/metadata.json`
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/state.toml`
|
||||
- Create: `conductor/tracks/nagent_review_20260608/nagent_review_v3_1_20260620.md` (the delta summary skeleton)
|
||||
|
||||
- [ ] **Step 1.1: Refresh `metadata.json` with v3.1 fields**
|
||||
|
||||
Add v3.1 fields to `metadata.json` (preserving v3 fields below):
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "v3.1",
|
||||
"v3_1_initialized": "2026-06-20",
|
||||
"v3_1_is_delta_of": "v3",
|
||||
"v3_1_baseline": {
|
||||
"v3_review_commit": "195b0f45",
|
||||
"nagent_commit": "a1f0680",
|
||||
"case_study_repos_at": "main"
|
||||
},
|
||||
"chunking_strategy": {
|
||||
"main_review_loc_floor": 3800,
|
||||
"per_cluster_loc_target": "300-450",
|
||||
"deep_dive_clusters_loc_target": "400-500",
|
||||
"per_cluster_sub_sections": "4-7",
|
||||
"per_cluster_source_read_citations": ">=30",
|
||||
"per_cluster_honest_gaps": ">=6",
|
||||
"per_cluster_manual_slop_implications": "2-3 paragraphs with file:line citations",
|
||||
"frontmatter_and_new_sections_loc_target": "200-400"
|
||||
},
|
||||
"scope_v3_1": {
|
||||
"new_files": [
|
||||
"spec_v3.1.md",
|
||||
"plan_v3.1.md",
|
||||
"nagent_review_v3_1_20260620.md",
|
||||
"nagent_takeaways_v3_1_20260620.md"
|
||||
],
|
||||
"thickened_files": [
|
||||
"nagent_review_v3_20260619.md"
|
||||
],
|
||||
"replaced_files": [
|
||||
"comparison_table.md",
|
||||
"decisions.md"
|
||||
],
|
||||
"refreshed_files": [
|
||||
"metadata.json",
|
||||
"state.toml"
|
||||
],
|
||||
"deleted_files": []
|
||||
},
|
||||
"v3_1_observations_added": [
|
||||
"YAML avoidance (no YAML in new Manual Slop artifacts; use markdown + custom DSL)",
|
||||
"Agent context-window observations (warm-up ~100-150k; window up to ~500k MiniMax M3; safe zone 250-350k; compact-re-warm-continue cycle)",
|
||||
"Fine-tuning observations (current generalized models bottlenecked by not having conventions baked in; Together.ai + 5-6 other prosumer fine-tuning vendors)"
|
||||
],
|
||||
"verification_criteria_v3_1": [
|
||||
"Main review >=3,800 lines",
|
||||
"Each cluster 300-450 lines (deep-dive clusters 400-500)",
|
||||
"Each cluster has 4-7 sub-sections",
|
||||
"Each cluster has >=30 source-read citations",
|
||||
"Each cluster has >=6 honest-gap bullets",
|
||||
"Each cluster has 2-3 paragraphs of Manual Slop implications with file:line citations",
|
||||
"Format commitment verified (5 commitments)",
|
||||
"Sections §12, §13, §14 present at target LOC ranges",
|
||||
"comparison_table.md, decisions.md, nagent_takeaways_v3_1_20260620.md all committed with v3.1 deltas",
|
||||
"spec_v3.1.md + plan_v3.1.md committed",
|
||||
"metadata.json + state.toml refreshed",
|
||||
"One commit per phase with git notes",
|
||||
"v3 preserved (git log -p recoverable)"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Preserve all v3 fields below. v3.1 fields above; v3 fields below.
|
||||
|
||||
- [ ] **Step 1.2: Initialize `state.toml` v3.1 fields**
|
||||
|
||||
Add v3.1 phase + task entries to `state.toml` below the v3 entries:
|
||||
|
||||
```toml
|
||||
[v3_1_phases]
|
||||
phase_1 = { status = "in_progress", checkpointsha = "", name = "Setup + audit" }
|
||||
phase_2 = { status = "pending", checkpointsha = "", name = "Thicken §1 Campaigns cluster" }
|
||||
phase_3 = { status = "pending", checkpointsha = "", name = "Thicken §2 Conversation safety net cluster" }
|
||||
phase_4 = { status = "pending", checkpointsha = "", name = "Thicken §3 Hooks cluster" }
|
||||
phase_5 = { status = "pending", checkpointsha = "", name = "Thicken §4 Project-local roots cluster" }
|
||||
phase_6 = { status = "pending", checkpointsha = "", name = "Thicken §5 Provider expansion cluster" }
|
||||
phase_7 = { status = "pending", checkpointsha = "", name = "Thicken §6 Delegation rewrite cluster" }
|
||||
phase_8 = { status = "pending", checkpointsha = "", name = "Thicken §7 Robustness cluster" }
|
||||
phase_9 = { status = "pending", checkpointsha = "", name = "Thicken §8 Operating rules cluster" }
|
||||
phase_10 = { status = "pending", checkpointsha = "", name = "Thicken §9 Case-study methodology cluster" }
|
||||
phase_11 = { status = "pending", checkpointsha = "", name = "Thicken §10 PEP case study cluster" }
|
||||
phase_12 = { status = "pending", checkpointsha = "", name = "Thicken §11 Collisions case study cluster" }
|
||||
phase_13 = { status = "pending", checkpointsha = "", name = "Write new sections §12-§14 (YAML avoidance, Agent context-window, Fine-tuning)" }
|
||||
phase_14 = { status = "pending", checkpointsha = "", name = "Refresh side artifacts (comparison_table, decisions, takeaways_v3_1)" }
|
||||
phase_15 = { status = "pending", checkpointsha = "", name = "Chunking-strategy + format-commitment verification + final" }
|
||||
|
||||
[v3_1_tasks]
|
||||
t1_1 = { status = "in_progress", commit_sha = "", description = "Refresh metadata.json with v3.1 fields" }
|
||||
t1_2 = { status = "pending", commit_sha = "", description = "Initialize state.toml v3.1 fields" }
|
||||
t1_3 = { status = "pending", commit_sha = "", description = "Confirm spec_v3.1.md + plan_v3.1.md exist and are approved" }
|
||||
t1_4 = { status = "pending", commit_sha = "", description = "Write nagent_review_v3_1_20260620.md delta summary skeleton" }
|
||||
t1_5 = { status = "pending", commit_sha = "", description = "Commit Phase 1 setup" }
|
||||
|
||||
[v3_1_verification]
|
||||
v3_1_main_review_loc_floor_met = false
|
||||
v3_1_per_cluster_depth_met = false
|
||||
v3_1_per_cluster_sub_sections_met = false
|
||||
v3_1_per_cluster_citations_met = false
|
||||
v3_1_per_cluster_honest_gaps_met = false
|
||||
v3_1_per_cluster_manual_slop_cited = false
|
||||
v3_1_new_sections_present = false
|
||||
v3_1_format_commitment_verified = false
|
||||
v3_1_side_artifacts_refreshed = false
|
||||
v3_1_track_artifacts_committed = false
|
||||
v3_1_commits_with_notes = false
|
||||
v3_1_v3_preserved = false
|
||||
```
|
||||
|
||||
Preserve all v3 fields below. v3.1 fields above; v3 fields below.
|
||||
|
||||
- [ ] **Step 1.3: Confirm `spec_v3.1.md` + `plan_v3.1.md` exist**
|
||||
|
||||
Verify both files exist in the track directory. (If they don't, stop and report to the user.)
|
||||
|
||||
- [ ] **Step 1.4: Write `nagent_review_v3_1_20260620.md` delta summary skeleton**
|
||||
|
||||
Create the file with the skeleton:
|
||||
|
||||
```markdown
|
||||
# nagent_review_v3_1_20260620 — Delta Summary
|
||||
|
||||
**Date:** 2026-06-20
|
||||
**Status:** Draft (Phase 1 setup complete; cluster thickening in progress)
|
||||
**Owner:** Tier 1 Orchestrator
|
||||
**Delta from:** v3 (`nagent_review_v3_20260619.md`, 664 lines, 2026-06-19)
|
||||
**Spec pair:** `spec_v3.1.md` + `plan_v3.1.md`
|
||||
|
||||
## What v3.1 changed
|
||||
|
||||
### Per-cluster thickening (11 clusters)
|
||||
|
||||
The main review file (`nagent_review_v3_20260619.md`) is thickened in place. Each cluster section grows from ~60 lines to 300-450 lines (or 400-500 for deep-dive clusters §9-§11). The thickening follows the chunking strategy (per spec_v3.1.md §4.1).
|
||||
|
||||
| § | Cluster | v3 lines | v3.1 target | Phase |
|
||||
|---|---|---|---|---|
|
||||
| §1 | Campaigns | ~50 | 350-450 | Phase 2 |
|
||||
| §2 | Conversation safety net | ~60 | 350-450 | Phase 3 |
|
||||
| §3 | Hooks | ~60 | 350-450 | Phase 4 |
|
||||
| §4 | Project-local roots | ~50 | 300-400 | Phase 5 |
|
||||
| §5 | Provider expansion | ~50 | 300-400 | Phase 6 |
|
||||
| §6 | Delegation rewrite | ~50 | 300-400 | Phase 7 |
|
||||
| §7 | Robustness | ~60 | 350-450 | Phase 8 |
|
||||
| §8 | Operating rules | ~60 | 300-400 | Phase 9 |
|
||||
| §9 | Case-study methodology | ~65 | 400-500 | Phase 10 |
|
||||
| §10 | PEP case study | ~50 | 400-500 | Phase 11 |
|
||||
| §11 | Collisions case study | ~50 | 400-500 | Phase 12 |
|
||||
|
||||
### Three new top-level sections (Phase 13)
|
||||
|
||||
- **§12 YAML avoidance** (~200-300 lines): catalogs every YAML use site in nagent; flags them as "do not adopt" for Manual Slop; documents the markdown + custom DSL alternative.
|
||||
- **§13 Agent context-window observations** (~200-300 lines): captures the user's OpenCode + MiniMax M3 empirical findings; notes nagent's stricter enforcement; documents Manual Slop's partial mitigation via docs/ + conductor/ markdown navigation; flags the "agents forget to read" shortcoming; proposes nagent's `--hook-per-run` as the pattern for closing the gap.
|
||||
- **§14 Fine-tuning observations** (~150-250 lines): captures the diagnosis + Together.ai observation + lists 6 prosumer fine-tuning vendors in a comparison table; flags that vendor analysis is out of scope.
|
||||
|
||||
### Side artifacts refresh (Phase 14)
|
||||
|
||||
- `comparison_table.md` REPLACED with v3.1 content (adds rows for §12, §13, §14).
|
||||
- `decisions.md` REPLACED with v3.1 content (adds Candidates 27-30).
|
||||
- `nagent_takeaways_v3_1_20260620.md` NEW bridge doc (~150 LOC, 5-part structure).
|
||||
|
||||
## What v3.1 did not change
|
||||
|
||||
- The 11-cluster scheme from v3 stands.
|
||||
- All v2.x historical reviews + v3 spec/plan/bridge preserved unchanged.
|
||||
- `conductor/tracks.md` not modified.
|
||||
- No new commits to nagent or the case-study repos are reviewed (v3 baseline preserved).
|
||||
|
||||
## Verification
|
||||
|
||||
Per spec_v3.1.md §7 verification criteria (12 criteria). All verified in Phase 15.
|
||||
```
|
||||
|
||||
- [ ] **Step 1.5: Commit Phase 1 setup**
|
||||
|
||||
```bash
|
||||
cd C:/projects/manual_slop
|
||||
git add conductor/tracks/nagent_review_20260608/spec_v3.1.md \
|
||||
conductor/tracks/nagent_review_20260608/plan_v3.1.md \
|
||||
conductor/tracks/nagent_review_20260608/metadata.json \
|
||||
conductor/tracks/nagent_review_20260608/state.toml \
|
||||
conductor/tracks/nagent_review_20260608/nagent_review_v3_1_20260620.md
|
||||
git commit -m "conductor(track): nagent_review_v3.1 Phase 1 setup + audit"
|
||||
git notes add -m "Phase 1 complete. Refreshed metadata.json with v3.1 fields (chunking strategy, scope_v3_1, observations_added, verification_criteria_v3_1). Initialized state.toml v3.1 phases + tasks. Wrote nagent_review_v3_1_20260620.md delta summary skeleton." $(git log -1 --format='%H')
|
||||
```
|
||||
|
||||
Update `state.toml`: mark t1_1, t1_2, t1_3, t1_4, t1_5 as `completed` with their commit SHAs.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Thicken §1 Campaigns cluster
|
||||
|
||||
Focus: Expand the §1 Campaigns cluster from ~50 lines to 350-450 lines per the chunking strategy.
|
||||
|
||||
**Files:**
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§1)
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/state.toml`
|
||||
|
||||
**Source commits:** `24cf16d`, `199a36b`, `f3ec090`, `c1d2cad`, `6443d70`, `7a7e242` (unchanged from v3)
|
||||
|
||||
- [ ] **Step 2.1: Read v3's §1 in full + identify what's thin**
|
||||
|
||||
Use `manual-slop_read_file` or `get_file_slice` to read v3's §1 (lines ~18-64 of the main review). Identify what's thin:
|
||||
- Per-commit detail (6 commits covered in 1 paragraph)
|
||||
- Sub-sections (no §1.1 / §1.2 / etc.)
|
||||
- Manual Slop implications (1 paragraph)
|
||||
- Source-read citations (need to expand from current ~13 to ≥30)
|
||||
- Honest gaps (currently 1 + 1 continued; need ≥6)
|
||||
|
||||
- [ ] **Step 2.2: Source-read the 6 campaigns commits + their files**
|
||||
|
||||
For each commit (`24cf16d`, `199a36b`, `f3ec090`, `c1d2cad`, `6443d70`, `7a7e242`):
|
||||
- Fetch `https://github.com/macton/nagent/commit/<sha>` and extract the diff + full commit message.
|
||||
- Read the actual files changed (e.g., `bin/nagent-campaign`, `bin/helpers/nagent_campaign_lib.py`, `bin/helpers/nagent_distill_lib.py:228-260` + `:793-979`, `bin/nagent-distill:107-200`, `prompts/campaign-decompose.md`, `prompts/campaign-item.md`, `prompts/knowledge-merge.md`, `prompts/knowledge-graduate.md`, `prompts/create-readme.md:248-251`, `issues/0002-campaign-system.md`, `tests/test_nagent_campaign.py`, `tests/test_nagent_distill.py`).
|
||||
|
||||
Identify the per-commit detail to add (per-commit sub-section).
|
||||
|
||||
- [ ] **Step 2.3: Read Manual Slop subsystems for the implications section**
|
||||
|
||||
For the Manual Slop implications sub-section, read:
|
||||
- `conductor/tracks/` layout + the per-track `state.toml` + `metadata.json` + `spec.md`/`plan.md` structure
|
||||
- `src/multi_agent_conductor.py` (the MMA WorkerPool)
|
||||
- `src/app_controller.py` (the `_predefined_callbacks` / `_gettable_fields` Hook API registries — the closest analog to the campaigns abstraction)
|
||||
- `conductor/code_styleguides/knowledge_artifacts.md`
|
||||
|
||||
Cite file:line for each Manual Slop claim.
|
||||
|
||||
- [ ] **Step 2.4: Design the sub-section structure**
|
||||
|
||||
§1 Campaigns cluster gets 6 sub-sections:
|
||||
|
||||
- §1.1 What Campaigns Adds (overview, 30-50 lines)
|
||||
- §1.2 The Driver Phases (the 6-phase `update` command, 50-70 lines, code-shape sketch)
|
||||
- §1.3 The Invariants (the 4 load-bearing rules, 40-60 lines)
|
||||
- §1.4 Per-Commit Detail (the 6 commits, 80-120 lines)
|
||||
- §1.5 Manual Slop Implications (2-3 paragraphs with citations, 50-80 lines)
|
||||
- §1.6 Honest Gaps (≥6 bullets, 40-60 lines)
|
||||
- §1.7 Code-Shape Sketch (survey grammar + SSDL, 30-50 lines)
|
||||
|
||||
Plus the closing fields (Source-read citations: ≥30 entries; Decision candidate; Cross-refs).
|
||||
|
||||
- [ ] **Step 2.5: Write the thickened §1**
|
||||
|
||||
Replace the §1 section in `nagent_review_v3_20260619.md` with the 6-sub-section version following the template (per spec_v3.1.md §4.2). Verify the chunking strategy metrics:
|
||||
- §1 total: 350-450 lines
|
||||
- §1 sub-sections: 6
|
||||
- §1 source-read citations: ≥30
|
||||
- §1 honest gaps: ≥6
|
||||
- §1 Manual Slop implications: 2-3 paragraphs with file:line citations
|
||||
|
||||
- [ ] **Step 2.6: Commit §1 thickening + git note**
|
||||
|
||||
```bash
|
||||
cd C:/projects/manual_slop
|
||||
git add conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md \
|
||||
conductor/tracks/nagent_review_20260608/state.toml
|
||||
git commit -m "conductor(track): nagent_review_v3.1 thicken §1 Campaigns cluster"
|
||||
git notes add -m "Phase 2 complete. §1 Campaigns thickened from ~50 lines to <N> lines. 6 sub-sections, <N> source-read citations, <N> honest gaps, 3 Manual Slop implications with file:line citations. Chunking strategy metrics met for §1." $(git log -1 --format='%H')
|
||||
```
|
||||
|
||||
Update `state.toml`: `phase_2.status = "completed"`, `phase_2.checkpointsha = "<first 7 chars>"`.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Thicken §2 Conversation safety net cluster
|
||||
|
||||
Focus: Expand §2 from ~60 lines to 350-450 lines.
|
||||
|
||||
**Files:**
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§2)
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/state.toml`
|
||||
|
||||
**Source commits:** `38d3d4f`, `6426a67` (unchanged from v3)
|
||||
|
||||
- [ ] **Step 3.1: Read v3's §2 in full + identify what's thin**
|
||||
- [ ] **Step 3.2: Source-read the 2 commits + their files** (`bin/nagent:1455-1687` + `:1840-1881` + `:2463-2677` + `:2819`, `bin/helpers/nagent_distill_lib.py:587-654` + `:851-862`, `config.example.json:3-7`, `prompts/checkpoint-conversation.md`, `issues/0004-conversation-safety-net.md`, `tests/test_nagent_safety.py`)
|
||||
- [ ] **Step 3.3: Read Manual Slop subsystems for implications** (`conductor/code_styleguides/error_handling.md`, `src/discussion.py` or similar for the discussion save path, `src/ai_client.py:run_discussion_compression`)
|
||||
- [ ] **Step 3.4: Design sub-section structure** (6 sub-sections)
|
||||
- [ ] **Step 3.5: Write the thickened §2** — verify chunking metrics
|
||||
- [ ] **Step 3.6: Commit §2 thickening + git note**
|
||||
|
||||
```bash
|
||||
git commit -m "conductor(track): nagent_review_v3.1 thicken §2 Conversation safety net cluster"
|
||||
git notes add -m "Phase 3 complete. §2 thickened from ~60 lines to <N> lines. Chunking strategy metrics met for §2." $(git log -1 --format='%H')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Thicken §3 Hooks cluster
|
||||
|
||||
Focus: Expand §3 from ~60 lines to 350-450 lines.
|
||||
|
||||
**Files:**
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§3)
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/state.toml`
|
||||
|
||||
**Source commits:** `a4fb141` (nagent) + both case-study repos (unchanged from v3)
|
||||
|
||||
- [ ] **Step 4.1: Read v3's §3 in full + identify what's thin**
|
||||
- [ ] **Step 4.2: Source-read the hooks commit + the case-study harness scripts**
|
||||
- [ ] **Step 4.3: Read Manual Slop subsystems for implications** (`docs/guide_ai_client.md` Tier 4 QA, `docs/guide_api_hooks.md` ApiHookClient, `src/app_controller.py:_predefined_callbacks`)
|
||||
- [ ] **Step 4.4: Design sub-section structure** (6 sub-sections including a deep sub-section on the case-study harness scripts)
|
||||
- [ ] **Step 4.5: Write the thickened §3** — verify chunking metrics
|
||||
- [ ] **Step 4.6: Commit §3 thickening + git note**
|
||||
|
||||
```bash
|
||||
git commit -m "conductor(track): nagent_review_v3.1 thicken §3 Hooks cluster"
|
||||
git notes add -m "Phase 4 complete. §3 thickened from ~60 lines to <N> lines. Hooks deep-dive + both case-study harness scripts cited. Chunking strategy metrics met for §3." $(git log -1 --format='%H')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Thicken §4 Project-local roots cluster
|
||||
|
||||
Focus: Expand §4 from ~50 lines to 300-400 lines.
|
||||
|
||||
**Files:**
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§4)
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/state.toml`
|
||||
|
||||
**Source commits:** `54c8741`, `557dd39`, `0b9d1a2`, `023e23a` (unchanged from v3)
|
||||
|
||||
- [ ] **Step 5.1: Read v3's §4 in full + identify what's thin**
|
||||
- [ ] **Step 5.2: Source-read the 4 commits + their files** (`bin/helpers/nagent_cli.py:11-86` + `:109-141`, `bin/helpers/nagent_llm.py:55-72`, `bin/nagent:640-748` + `:2075-2295`, `.gitignore`)
|
||||
- [ ] **Step 5.3: Read Manual Slop subsystems for implications** (`src/paths.py` for the path resolution pattern, `[conductor].dir` in `manual_slop.toml`, `tests/artifacts/` gitignore discipline)
|
||||
- [ ] **Step 5.4: Design sub-section structure** (5 sub-sections)
|
||||
- [ ] **Step 5.5: Write the thickened §4** — verify chunking metrics
|
||||
- [ ] **Step 5.6: Commit §4 thickening + git note**
|
||||
|
||||
```bash
|
||||
git commit -m "conductor(track): nagent_review_v3.1 thicken §4 Project-local roots cluster"
|
||||
git notes add -m "Phase 5 complete. §4 thickened from ~50 lines to <N> lines. Chunking strategy metrics met for §4." $(git log -1 --format='%H')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Thicken §5 Provider expansion cluster
|
||||
|
||||
Focus: Expand §5 from ~50 lines to 300-400 lines.
|
||||
|
||||
**Files:**
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§5)
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/state.toml`
|
||||
|
||||
**Source commits:** `bdfa2a6`, `5075f6e`, `2edc7ee` (unchanged from v3)
|
||||
|
||||
- [ ] **Step 6.1: Read v3's §5 in full + identify what's thin**
|
||||
- [ ] **Step 6.2: Source-read the 3 commits + their files** (Together provider implementation, `MODEL_CONTEXT_WINDOWS`, `model_context_window()`, `--list-providers` CLI flag, claude-code billing fix, spinner name change)
|
||||
- [ ] **Step 6.3: Read Manual Slop subsystems for implications** (`src/ai_client.py` for the multi-provider pattern, `conductor/tech-stack.md` for the 8 providers, `docs/guide_ai_client.md` for the cache strategy)
|
||||
- [ ] **Step 6.4: Design sub-section structure** (5 sub-sections including a table of the 6 providers with their context windows)
|
||||
- [ ] **Step 6.5: Write the thickened §5** — verify chunking metrics
|
||||
- [ ] **Step 6.6: Commit §5 thickening + git note**
|
||||
|
||||
```bash
|
||||
git commit -m "conductor(track): nagent_review_v3.1 thicken §5 Provider expansion cluster"
|
||||
git notes add -m "Phase 6 complete. §5 thickened from ~50 lines to <N> lines. 6 providers table + per-model context windows. Chunking strategy metrics met for §5." $(git log -1 --format='%H')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: Thicken §6 Delegation rewrite cluster
|
||||
|
||||
Focus: Expand §6 from ~50 lines to 300-400 lines.
|
||||
|
||||
**Files:**
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§6)
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/state.toml`
|
||||
|
||||
**Source commits:** `d56f0f0`, `65787a6`, `315fe9e` (unchanged from v3)
|
||||
|
||||
- [ ] **Step 7.1: Read v3's §6 in full + identify what's thin**
|
||||
- [ ] **Step 7.2: Source-read the 3 commits + their files** (the recursion bug, the fix, the context-isolation rationale, the test fixup)
|
||||
- [ ] **Step 7.3: Read Manual Slop subsystems for implications** (`src/multi_agent_conductor.py` MMA WorkerPool, `scripts/mma_exec.py` delegation, `docs/guide_mma.md`)
|
||||
- [ ] **Step 7.4: Design sub-section structure** (5 sub-sections with a deep sub-section on the recursion bug)
|
||||
- [ ] **Step 7.5: Write the thickened §6** — verify chunking metrics
|
||||
- [ ] **Step 7.6: Commit §6 thickening + git note**
|
||||
|
||||
```bash
|
||||
git commit -m "conductor(track): nagent_review_v3.1 thicken §6 Delegation rewrite cluster"
|
||||
git notes add -m "Phase 7 complete. §6 thickened from ~50 lines to <N> lines. Recursion bug deep-dive + context-isolation rationale. Chunking strategy metrics met for §6." $(git log -1 --format='%H')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 8: Thicken §7 Robustness cluster
|
||||
|
||||
Focus: Expand §7 from ~60 lines to 350-450 lines.
|
||||
|
||||
**Files:**
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§7)
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/state.toml`
|
||||
|
||||
**Source commits:** `065168c`, `6b762da`, `12c35b7`, `49e07f3` (unchanged from v3)
|
||||
|
||||
- [ ] **Step 8.1: Read v3's §7 in full + identify what's thin**
|
||||
- [ ] **Step 8.2: Source-read the 4 commits + their files** (non-protocol tolerance, dedupe_nodes, shell-before-next ordering, per-conversation scratch)
|
||||
- [ ] **Step 8.3: Read Manual Slop subsystems for implications** (`conductor/code_styleguides/error_handling.md`, `Result[T]` convention, `scripts/audit_exception_handling.py`)
|
||||
- [ ] **Step 8.4: Design sub-section structure** (6 sub-sections, one per commit)
|
||||
- [ ] **Step 8.5: Write the thickened §7** — verify chunking metrics
|
||||
- [ ] **Step 8.6: Commit §7 thickening + git note**
|
||||
|
||||
```bash
|
||||
git commit -m "conductor(track): nagent_review_v3.1 thicken §7 Robustness cluster"
|
||||
git notes add -m "Phase 8 complete. §7 thickened from ~60 lines to <N> lines. 4 commits with per-commit sub-sections. Chunking strategy metrics met for §7." $(git log -1 --format='%H')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 9: Thicken §8 Operating rules cluster
|
||||
|
||||
Focus: Expand §8 from ~60 lines to 300-400 lines.
|
||||
|
||||
**Files:**
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§8)
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/state.toml`
|
||||
|
||||
**Source commits:** `a1f0680` (unchanged from v3)
|
||||
|
||||
- [ ] **Step 9.1: Read v3's §8 in full + identify what's thin**
|
||||
- [ ] **Step 9.2: Source-read the operating-rules commit + the full `data-oriented-design.md` file** (not just the diff)
|
||||
- [ ] **Step 9.3: Read Manual Slop subsystems for implications** (`conductor/code_styleguides/data_oriented_design.md` — the project's derived styleguide; document the delta between nagent's file and the project's)
|
||||
- [ ] **Step 9.4: Design sub-section structure** (5 sub-sections with a deep sub-section on the Q9 expansion)
|
||||
- [ ] **Step 9.5: Write the thickened §8** — verify chunking metrics
|
||||
- [ ] **Step 9.6: Commit §8 thickening + git note**
|
||||
|
||||
```bash
|
||||
git commit -m "conductor(track): nagent_review_v3.1 thicken §8 Operating rules cluster"
|
||||
git notes add -m "Phase 9 complete. §8 thickened from ~60 lines to <N> lines. Q9 expansion deep-dive. Chunking strategy metrics met for §8." $(git log -1 --format='%H')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 10: Thicken §9 Case-study methodology cluster
|
||||
|
||||
Focus: Expand §9 from ~65 lines to 400-500 lines (deep-dive cluster).
|
||||
|
||||
**Files:**
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§9)
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/state.toml`
|
||||
|
||||
**Source:** both `pep-copt` and `differentiable-collisions-optc` repos (unchanged from v3)
|
||||
|
||||
- [ ] **Step 10.1: Read v3's §9 in full + identify what's thin**
|
||||
- [ ] **Step 10.2: Source-read both case-study repos** (4 prompts in each + both harness scripts + both OPTIMIZATION-LOG.md files)
|
||||
- [ ] **Step 10.3: Read Manual Slop subsystems for implications** (`conductor/code_styleguides/knowledge_artifacts.md`, `conductor/prompts/` if it exists, the project's own discussion history pattern)
|
||||
- [ ] **Step 10.4: Design sub-section structure** (6 sub-sections including the 5-element pattern decomposition)
|
||||
- [ ] **Step 10.5: Write the thickened §9** — verify chunking metrics
|
||||
- [ ] **Step 10.6: Commit §9 thickening + git note**
|
||||
|
||||
```bash
|
||||
git commit -m "conductor(track): nagent_review_v3.1 thicken §9 Case-study methodology cluster"
|
||||
git notes add -m "Phase 10 complete. §9 thickened from ~65 lines to <N> lines. 5-element pattern decomposition deep-dive. Chunking strategy metrics met for §9." $(git log -1 --format='%H')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 11: Thicken §10 PEP case study cluster
|
||||
|
||||
Focus: Expand §10 from ~50 lines to 400-500 lines (deep-dive cluster).
|
||||
|
||||
**Files:**
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§10)
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/state.toml`
|
||||
|
||||
**Source:** `macton/pep-copt` (unchanged from v3)
|
||||
|
||||
- [ ] **Step 11.1: Read v3's §10 in full + identify what's thin**
|
||||
- [ ] **Step 11.2: Source-read the full pep-copt repo** (all 5 commits + README + OPTIMIZATION-LOG + 4 prompts + harness)
|
||||
- [ ] **Step 11.3: Read Manual Slop subsystems for implications** (`conductor/code_styleguides/data_oriented_design.md` for the operating rules Acton applied)
|
||||
- [ ] **Step 11.4: Design sub-section structure** (6 sub-sections including the per-image results table + the kept/rejected optimizations table + the size/speed frontier table)
|
||||
- [ ] **Step 11.5: Write the thickened §10** — verify chunking metrics
|
||||
- [ ] **Step 11.6: Commit §10 thickening + git note**
|
||||
|
||||
```bash
|
||||
git commit -m "conductor(track): nagent_review_v3.1 thicken §10 PEP case study cluster"
|
||||
git notes add -m "Phase 11 complete. §10 thickened from ~50 lines to <N> lines. Full per-image results + kept/rejected optimizations + size/speed frontier. Chunking strategy metrics met for §10." $(git log -1 --format='%H')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 12: Thicken §11 Collisions case study cluster
|
||||
|
||||
Focus: Expand §11 from ~50 lines to 400-500 lines (deep-dive cluster).
|
||||
|
||||
**Files:**
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§11)
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/state.toml`
|
||||
|
||||
**Source:** `macton/differentiable-collisions-optc` (unchanged from v3)
|
||||
|
||||
- [ ] **Step 12.1: Read v3's §11 in full + identify what's thin**
|
||||
- [ ] **Step 12.2: Source-read the full differentiable-collisions-optc repo** (all 5 commits + README + OPTIMIZATION-LOG + 4 prompts + harness + the cited arXiv paper)
|
||||
- [ ] **Step 12.3: Read Manual Slop subsystems for implications** (`conductor/code_styleguides/data_oriented_design.md` for the operating rules Acton applied)
|
||||
- [ ] **Step 12.4: Design sub-section structure** (6 sub-sections including the per-type specialization deep-dive + the match contract + the closed-form contact witnesses)
|
||||
- [ ] **Step 12.5: Write the thickened §11** — verify chunking metrics
|
||||
- [ ] **Step 12.6: Commit §11 thickening + git note**
|
||||
|
||||
```bash
|
||||
git commit -m "conductor(track): nagent_review_v3.1 thicken §11 Collisions case study cluster"
|
||||
git notes add -m "Phase 12 complete. §11 thickened from ~50 lines to <N> lines. Per-type specialization + match contract + closed-form contact witnesses. Chunking strategy metrics met for §11." $(git log -1 --format='%H')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 13: Write new sections §12-§14
|
||||
|
||||
Focus: Append the 3 new top-level sections to the main review.
|
||||
|
||||
**Files:**
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (append §12, §13, §14)
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/state.toml`
|
||||
|
||||
- [ ] **Step 13.1: Write §12 YAML avoidance (~200-300 lines)**
|
||||
|
||||
Append the §12 section after §11. Follow the sub-section structure:
|
||||
- §12.1 Where nagent uses YAML (catalog with file:line citations)
|
||||
- §12.2 Why YAML is "do not adopt" for Manual Slop (4-5 reasons)
|
||||
- §12.3 The markdown + custom DSL alternative (concrete proposal)
|
||||
- §12.4 Cross-refs (intent_dsl_survey, superpowers_review, conductor/presets.py, conductor/personas.py)
|
||||
|
||||
≥30 source-read citations. ≥6 honest gaps. 2-3 paragraphs of Manual Slop implications.
|
||||
|
||||
- [ ] **Step 13.2: Write §13 Agent context-window observations (~200-300 lines)**
|
||||
|
||||
Append §13. Sub-sections:
|
||||
- §13.1 The warm-up + window + safe-zone numbers
|
||||
- §13.2 nagent's enforcement (per-turn hooks + safety net + distill)
|
||||
- §13.3 Manual Slop's partial mitigation (docs/ + conductor/ markdown navigation)
|
||||
- §13.4 The shortcoming (agents forget/fail to read)
|
||||
- §13.5 Decision candidate (Candidate 28: per-turn ground-truth hook)
|
||||
|
||||
≥30 source-read citations. ≥6 honest gaps. 2-3 paragraphs of Manual Slop implications.
|
||||
|
||||
- [ ] **Step 13.3: Write §14 Fine-tuning observations (~150-250 lines)**
|
||||
|
||||
Append §14. Sub-sections:
|
||||
- §14.1 The diagnosis (current models bottlenecked)
|
||||
- §14.2 Together.ai as one noticed vendor
|
||||
- §14.3 Prosumer fine-tuning vendor survey (the 6-vendor table)
|
||||
- §14.4 Vendor analysis is out of scope for v3.1
|
||||
|
||||
≥20 source-read citations (fewer, since this is observational). ≥6 honest gaps. 2-3 paragraphs of Manual Slop implications (mostly the dataset-curation angle).
|
||||
|
||||
- [ ] **Step 13.4: Commit §12-§14 + git note**
|
||||
|
||||
```bash
|
||||
cd C:/projects/manual_slop
|
||||
git add conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md \
|
||||
conductor/tracks/nagent_review_20260608/state.toml
|
||||
git commit -m "conductor(track): nagent_review_v3.1 §12-§14 new sections (YAML, agent context, fine-tuning)"
|
||||
git notes add -m "Phase 13 complete. §12 YAML avoidance (~<N> lines), §13 Agent context-window observations (~<N> lines), §14 Fine-tuning observations (~<N> lines). Total new content: ~<N> lines. 3 new top-level sections appended to main review." $(git log -1 --format='%H')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 14: Refresh side artifacts
|
||||
|
||||
Focus: Replace `comparison_table.md` + `decisions.md`; create `nagent_takeaways_v3_1_20260620.md`. Refresh the delta summary doc.
|
||||
|
||||
**Files:**
|
||||
- Replace: `conductor/tracks/nagent_review_20260608/comparison_table.md`
|
||||
- Replace: `conductor/tracks/nagent_review_20260608/decisions.md`
|
||||
- Create: `conductor/tracks/nagent_review_20260608/nagent_takeaways_v3_1_20260620.md`
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_1_20260620.md` (fill in the summary with the actual thickened section LOC counts)
|
||||
|
||||
- [ ] **Step 14.1: Write `comparison_table.md`** (target 100-130 lines)
|
||||
|
||||
Per spec_v3.1.md §4.4.1. Includes 11 cluster rows + 3 new section rows + v2.3 update rows + sibling-review cross-refs.
|
||||
|
||||
- [ ] **Step 14.2: Write `decisions.md`** (target 180-220 lines)
|
||||
|
||||
Per spec_v3.1.md §4.4.2. Includes v2.3 → v3 → v3.1 status mapping at top + all 25-30 v3 candidates + 3-5 new v3.1 candidates (27-30).
|
||||
|
||||
- [ ] **Step 14.3: Write `nagent_takeaways_v3_1_20260620.md`** (target ~150 LOC)
|
||||
|
||||
Per spec_v3.1.md §4.4.3. 5-part structure:
|
||||
1. TL;DR (1 paragraph)
|
||||
2. Cross-reference table (~15 rows)
|
||||
3. The new v3.1 candidates (3-5)
|
||||
4. The v3 candidates v3.1 supersedes (0-2)
|
||||
5. Sibling-review pointer (fable_review, intent_dsl_survey, superpowers_review, project files)
|
||||
|
||||
- [ ] **Step 14.4: Update `nagent_review_v3_1_20260620.md` delta summary**
|
||||
|
||||
Fill in the actual LOC counts for each cluster + the 3 new sections + the side artifact sizes. Reference the commits.
|
||||
|
||||
- [ ] **Step 14.5: Commit Phase 14 + git note**
|
||||
|
||||
```bash
|
||||
git add conductor/tracks/nagent_review_20260608/comparison_table.md \
|
||||
conductor/tracks/nagent_review_20260608/decisions.md \
|
||||
conductor/tracks/nagent_review_20260608/nagent_takeaways_v3_1_20260620.md \
|
||||
conductor/tracks/nagent_review_20260608/nagent_review_v3_1_20260620.md \
|
||||
conductor/tracks/nagent_review_20260608/state.toml
|
||||
git commit -m "conductor(track): nagent_review_v3.1 Phase 14 refresh side artifacts"
|
||||
git notes add -m "Phase 14 complete. comparison_table.md (<N> rows), decisions.md (<N> candidates + status mapping), nagent_takeaways_v3_1_20260620.md (<N> LOC bridge), delta summary filled in." $(git log -1 --format='%H')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 15: Chunking-strategy + format-commitment verification + final
|
||||
|
||||
Focus: Run the chunking-strategy + format-commitment verifications mechanically + final commit.
|
||||
|
||||
**Files:**
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (only if verification reveals gaps)
|
||||
- Modify: `conductor/tracks/nagent_review_20260608/state.toml`
|
||||
|
||||
- [ ] **Step 15.1: Run chunking verification #1 (main review LOC floor)**
|
||||
|
||||
```bash
|
||||
cd C:/projects/manual_slop
|
||||
wc -l conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md
|
||||
```
|
||||
|
||||
Expected: ≥3,800 lines.
|
||||
|
||||
- [ ] **Step 15.2: Run chunking verification #2 (per-cluster depth)**
|
||||
|
||||
For each cluster §1-§11, count the lines in the section:
|
||||
|
||||
```bash
|
||||
# Example for §1 (Campaigns): extract lines between §1 and §2 markers
|
||||
sed -n '/^## §1 Campaigns/,/^## §2 Conversation safety net/p' conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md | wc -l
|
||||
```
|
||||
|
||||
Expected per cluster:
|
||||
- §1: 350-450 lines
|
||||
- §2: 350-450 lines
|
||||
- §3: 350-450 lines
|
||||
- §4: 300-400 lines
|
||||
- §5: 300-400 lines
|
||||
- §6: 300-400 lines
|
||||
- §7: 350-450 lines
|
||||
- §8: 300-400 lines
|
||||
- §9: 400-500 lines (deep-dive)
|
||||
- §10: 400-500 lines (deep-dive)
|
||||
- §11: 400-500 lines (deep-dive)
|
||||
|
||||
If a cluster is under the minimum, return to the relevant cluster phase and add depth.
|
||||
|
||||
- [ ] **Step 15.3: Run chunking verification #3 (per-cluster sub-sections)**
|
||||
|
||||
For each cluster, count `#### §N.x` headings:
|
||||
|
||||
```bash
|
||||
grep -cE '^#### §1\.' conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md
|
||||
```
|
||||
|
||||
Expected: 4-7 sub-sections per cluster.
|
||||
|
||||
- [ ] **Step 15.4: Run chunking verification #4 (per-cluster citations)**
|
||||
|
||||
For each cluster, count file:line citations (file paths ending in `:L[0-9]+` or commit SHAs 7+ chars):
|
||||
|
||||
```bash
|
||||
# This is a heuristic; the per-cluster citation count is verified manually.
|
||||
```
|
||||
|
||||
Expected: ≥30 per cluster.
|
||||
|
||||
- [ ] **Step 15.5: Run chunking verification #5 (per-cluster honest gaps)**
|
||||
|
||||
For each cluster, count bullet points under the "Honest gaps" sub-section.
|
||||
|
||||
Expected: ≥6 per cluster.
|
||||
|
||||
- [ ] **Step 15.6: Run chunking verification #6 (Manual Slop implications)**
|
||||
|
||||
Manual inspection per cluster. Expected: 2-3 paragraphs with Manual Slop file:line citations.
|
||||
|
||||
- [ ] **Step 15.7: Run format verification #7 (no JSON blocks)**
|
||||
|
||||
```bash
|
||||
grep -n '```json' conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md
|
||||
```
|
||||
|
||||
Expected: no matches.
|
||||
|
||||
- [ ] **Step 15.8: Run format verification #8 (7-column tables)**
|
||||
|
||||
```bash
|
||||
grep -c '^| Symbol |' conductor/tracks/nagent_review_20260608/comparison_table.md
|
||||
```
|
||||
|
||||
Expected: ≥1.
|
||||
|
||||
- [ ] **Step 15.9: Run format verification #9 (SSDL + survey grammar)**
|
||||
|
||||
```bash
|
||||
grep -nE '\{ssdl\}|name := value|for [a-z]+ \.\. [a-z]+|tape \{ |try \{ .* recover|sandbox \{ |audit msg|fuzzy \{ ' conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md
|
||||
```
|
||||
|
||||
Expected: ≥1 of SSDL tags, ≥1 of survey grammar.
|
||||
|
||||
- [ ] **Step 15.10: Run new-sections verification #10 (§12-§14 present)**
|
||||
|
||||
```bash
|
||||
grep -nE '^## §1[2-4]' conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md
|
||||
```
|
||||
|
||||
Expected: 3 matches (§12, §13, §14).
|
||||
|
||||
- [ ] **Step 15.11: Update `state.toml` v3.1_verification fields**
|
||||
|
||||
Set all `[v3_1_verification]` fields to `true` if verification passed. Set to `false` for any that did not pass; the next iteration must address them.
|
||||
|
||||
- [ ] **Step 15.12: Final commit + git note + state update**
|
||||
|
||||
```bash
|
||||
cd C:/projects/manual_slop
|
||||
git add conductor/tracks/nagent_review_20260608/state.toml
|
||||
git commit -m "conductor(track): nagent_review_v3.1 Phase 15 chunking-strategy + format-commitment verification + final"
|
||||
git notes add -m "Phase 15 complete. All 12 verifications passed. Main review: <N> lines (>=3,800 floor). Per-cluster depth: <all met>. Format commitment: <met>. §12-§14: <present>. Side artifacts: <refreshed>. Track complete; ready for archive." $(git log -1 --format='%H')
|
||||
```
|
||||
|
||||
Update `state.toml`: `phase_15.status = "completed"`, `phase_15.checkpointsha = "<first 7 chars>"`.
|
||||
|
||||
- [ ] **Step 15.13: Standalone-readability verification**
|
||||
|
||||
The load-bearing principle (per spec_v3.1.md §5.5): v3.1 must be readable by a reader who has never read v2.3 or v3. Verification:
|
||||
|
||||
1. Open ONLY the v3.1 artifacts (no prior versions, no git history of prior versions):
|
||||
- `nagent_review_v3_20260619.md` (the thickened main review)
|
||||
- `comparison_table.md` (the v3.1 comparison table)
|
||||
- `decisions.md` (the v3.1 candidate list)
|
||||
- `nagent_takeaways_v3_1_20260620.md` (the v3.1 bridge doc)
|
||||
- `nagent_review_v3_1_20260620.md` (the v3.1 delta summary)
|
||||
|
||||
2. Read end-to-end. The reading must give a complete picture of:
|
||||
- (a) What nagent is at `a1f0680` (the primary review subject)
|
||||
- (b) What the case-study repos show (`pep-copt`, `differentiable-collisions-optc`)
|
||||
- (c) What the 3 new observations (YAML avoidance, agent context-window, fine-tuning) imply for Manual Slop
|
||||
|
||||
3. Specific checks:
|
||||
- Does the §0 TL;DR open with a self-contained statement of what nagent is + what v3.1 covers?
|
||||
- Does each cluster's "Pattern summary" field make sense without consulting v2.3?
|
||||
- Does `decisions.md` introduce each candidate without requiring prior context?
|
||||
- Do any cross-refs to v2.3 / v3 / v1 break the reading? (Cross-refs should be optional lineage context, not load-bearing.)
|
||||
- Does the §12-§14 content stand on its own?
|
||||
|
||||
4. If any check fails, return to the relevant phase and fix the dependency. The fix is typically one of:
|
||||
- Add a self-contained explanation where the content assumed prior context
|
||||
- Replace "Pattern(s) vs v2.3" with the self-contained "Pattern summary"
|
||||
- Remove the v2.3 → v3 → v3.1 status mapping from `decisions.md`
|
||||
- Add a TL;DR sentence that opens with self-contained context
|
||||
|
||||
- [ ] **Step 15.14: Track status update**
|
||||
|
||||
Per `conductor/workflow.md` §"State.toml Template", set:
|
||||
|
||||
```toml
|
||||
[meta]
|
||||
status = "completed" # was "active"
|
||||
```
|
||||
|
||||
Commit this final state update:
|
||||
|
||||
```bash
|
||||
git add conductor/tracks/nagent_review_20260608/state.toml
|
||||
git commit -m "conductor(track): nagent_review_v3.1 marked completed"
|
||||
```
|
||||
|
||||
The track is now ready for archive.
|
||||
|
||||
---
|
||||
|
||||
## Self-Review
|
||||
|
||||
This is the inline self-review per the writing-plans skill.
|
||||
|
||||
### 1. Spec coverage
|
||||
|
||||
Each spec_v3.1.md requirement maps to a plan task:
|
||||
|
||||
| Spec section | Plan coverage |
|
||||
|---|---|
|
||||
| §1.1 artifact table | Phase 1 (skeleton) + Phases 2-12 (cluster thickening) + Phase 13 (new sections) + Phase 14 (side artifact refresh) |
|
||||
| §2 Current State Audit | Implicit baseline; not re-listed |
|
||||
| §3 Goals | Each goal maps to a phase (goal 1-3 = phases 2-12, goal 4 = phase 13) |
|
||||
| §4.1 chunking strategy | "The Chunking Strategy" section + Phase 15 verification |
|
||||
| §4.2 sub-section template | Each cluster phase uses the template |
|
||||
| §4.3.1 §12 YAML avoidance | Phase 13 (Step 13.1) |
|
||||
| §4.3.2 §13 Agent context-window | Phase 13 (Step 13.2) |
|
||||
| §4.3.3 §14 Fine-tuning | Phase 13 (Step 13.3) |
|
||||
| §4.4 side artifacts | Phase 14 (Steps 14.1-14.4) |
|
||||
| §4.5 cross-references | Per-cluster phases + Phase 13 + Phase 14 (in bridge doc) |
|
||||
| §5.1 format commitment | Phase 15 verifications #7-#9 |
|
||||
| §5.2 authoring tier | Plan-wide (Tier 1 sole-authored, per plan header) |
|
||||
| §5.3 filename convention | Plan-wide (consistent `20260620` for new files, v3 filename preserved for thickening) |
|
||||
| §5.4 track-state hygiene | Phase 1 (state.toml init) + each phase's commit (state.toml update) |
|
||||
| §6 architecture reference | Implicit in the spec; not re-implemented in plan |
|
||||
| §7 verification criteria (12) | Phase 15 (Steps 15.1-15.11) |
|
||||
| §8 out of scope | Plan-wide (no candidate implementation, no sibling-review replication, no vendor analysis) |
|
||||
|
||||
**No gaps detected.**
|
||||
|
||||
### 2. Placeholder scan
|
||||
|
||||
Searched the plan for: "TBD", "TODO", "implement later", "fill in details", "add appropriate", "similar to Task N".
|
||||
|
||||
Found `<N>` placeholders in the git note messages and verification step outputs — these are INTENDED. The Tier 1 author fills them with actual values when executing the phase. The git notes are templates; the actual numbers come from the source-read pass.
|
||||
|
||||
No "TBD", "TODO", "implement later", "fill in details", "add appropriate", or "similar to Task N" markers found in the plan structure.
|
||||
|
||||
### 3. Type consistency
|
||||
|
||||
Type/name consistency checks:
|
||||
- All `comparison_table.md` references match across phases (Phase 14 + Step 15.8).
|
||||
- All `decisions.md` references match across phases (Phase 14).
|
||||
- All `nagent_takeaways_v3_1_20260620.md` references match across phases (Phase 14).
|
||||
- All `state.toml` `[v3_1_tasks]` keys (t1_1, t1_2, ...) and `[v3_1_phases]` keys (phase_1, ..., phase_15) match across phases.
|
||||
- All `metadata.json` field names match (per spec_v3.1.md §1.1 and Step 1.1).
|
||||
- All commit SHAs are referenced consistently (the 24 nagent SHAs + the 10 case-study commits are referenced in spec_v3.1.md §2.2 and used in the cluster phases).
|
||||
- The chunking strategy metrics are consistent across §4.1, the per-phase tasks, and the Phase 15 verifications.
|
||||
|
||||
**No type inconsistencies detected.**
|
||||
|
||||
---
|
||||
|
||||
## Execution Handoff
|
||||
|
||||
The plan is complete and saved to `conductor/tracks/nagent_review_20260608/plan_v3.1.md`.
|
||||
|
||||
Per the project's conductor convention (per `conductor/workflow.md`):
|
||||
- v3.1 is research-only (no `src/*.py` changes).
|
||||
- Tier 1 Orchestrator sole-authored (mirrors v3, v2.3, and `fable_review_20260617`).
|
||||
- 15 phases, 1 commit per phase (atomic rollback per phase).
|
||||
- Git notes attached per commit.
|
||||
- `state.toml` updated per phase.
|
||||
- Chunking strategy metrics enforced via Phase 15 verifications.
|
||||
|
||||
The Tier 1 author executes the plan in the current session (or in a follow-up session, per the user's preference). The "execution choice" prompt from the writing-plans skill (subagent-driven vs inline) does not apply for Tier 1 sole-authored research — the Tier 1 IS the inline executor.
|
||||
Reference in New Issue
Block a user