feat(scripts): roadmap settle is code — writer call sites, check gate, unit-cycle settle

CHANGELOG.md

@@ -98,6 +98,7 @@ How pinning actually works, verified against the `skills` CLI:
 
 #### [`@gtrabanco/pi-agentic-workflow`](packages/pi-agentic-workflow/)
 | Version | Date | Type | What changed |
+| 0.35.1 | 2026-10-27 | patch | **Issue #316 — the roadmap's `done` settle is code, and its call sites execute.** Publishes the skill content this unit changed: `execute-phase` 6.3.1 and `unit-lane` 2.5.1 name the **executable** settle form — `roadmap <table-path> rowUpsert '<json>'` with the index path and the row's own cells — and stop at the kind boundary (`rowUpsert` is the roadmap's writer; a fix index has no `NN` column). The rest of the unit rides the same content: `scripts/roadmap-settle.mjs` fails closed offline when a unit doc carries a PR URL its index row does not settle (`done · [#N](<same url>)`), `scripts/unit-cycle.mjs` writes the row itself and now grades through the crate's `checkUnitDoc` instead of a second, weaker rule, and `roadmap rowUpsert`/`annotate` refuse a bare subcommand as a usage error instead of resolving it as a table path. No package code change — the bump exists because the shipped skill content changed (`skills/**` trigger set). Re-cut above `main`'s published `0.35.0` (issue #321, rebased) so the shipped version stays above the base's. |
 | 0.35.0 | 2026-10-26 | minor | **The Serena bridge is replaced by native MCP registration (issue #321).** **BREAKING CHANGE:** `@bacnh85/pi-serena` is removed — from `dependencies` and from `pi.extensions` — so the package no longer ships the bridge's `serena_*` tools; Serena is provisioned through pi's native MCP support instead (`pi mcp add serena -- serena start-mcp-server --context claude-code`, documented by the bundled `init-workspace` 4.3.0's new pi row). The bridge pinned the package to one external repo's in-process Python coupling of Serena's internal APIs, last touched before Serena 2.0.0 existed; `serena start-mcp-server` is Serena's maintained, version-stable interface, so `serena-agent` upgrades (1.7.0 → 2.1.0 today) need no change here. The pin-watch gains the PyPI half (issue #321): `serena-agent` installed-vs-latest is watched and a drift issue is filed — never a silent upgrade — with drift/clean/degraded/skipped covered offline. `scripts/serena-activation-check.mjs` is reworked: it proves the packed artifact carries no bridge dependency and only its own extension entry, instead of booting a scratch pi session to count bridge tools; the AC1 pin/entry tests are replaced by their inverse (bridge absent, own entry intact). The `serena-readiness` nudge is unchanged. |
 | 0.34.2 | 2026-10-26 | patch | **The runner pin catches up (registry drift).** `@gtrabanco/agentic-workflow` moves from the 0.2.0 pin to 0.4.0 — the version the registry actually serves. The crate table records 0.3.0 as a repository-only bump that never published, so npm jumped 0.2.0 → 0.4.0, and until this pin moved the registry half of the version-parity gate rejected **every** pull request with `dependency-pin-drift`, including ones that touched no dependency (main's own runs went red the moment 0.4.0 published). 0.4.0 is additive over 0.2.0 (`agentic-workflow memory probe`, feature 66 P1) — no removed subcommand, no changed argv — so the pin moves without a consumer change. No skill content and no package code change: the dependency alone moves, and the suite passes on the bumped pin (471 tests). This is the follow-up the 0.34.1 row deferred ("it moves when that package actually publishes"). |
 | 0.34.1 | 2026-10-26 | patch | **The schema pin catches up (registry drift).** `@gtrabanco/agentic-workflow-schema` moves from the 4.7.0 pin to 4.8.0, the version the 4.8.0 row's own pin rule deferred to a deliberate `fix(deps)` PR once it published — until then the registry half of the version-parity gate rejected every push to `main` (`dependency-pin-drift`). No skill content and no package code change: the dependency alone moves, and the suite passes on both runtimes (471 tests, bun and node). The pin on `@gtrabanco/agentic-workflow` stays at the published 0.2.0 for the same reason the crate's own publish gate is red — it moves when that package actually publishes. |
@@ -174,6 +175,7 @@ How pinning actually works, verified against the `skills` CLI:
 
 #### [`@gtrabanco/agentic-workflow`](packages/agentic-workflow/)
 | Version | Date | Type | What changed |
+| 0.5.0 | 2026-10-26 | minor | **Issue #316 — `roadmap check`, the cross-document settle check, and the writer accepts the table that exists.** `agentic-workflow roadmap check <unit-doc-path> [--roadmap <file>] [--index <file>] [--json]` compares a unit doc's own facts (NN and slug from its folder, PR URLs from its own lifecycle surfaces — `## Next`, `## Log`, `## Evidence`, the References `- PR:` line) with its index row and fails closed with the closed code set `ROADMAP_CHECK_CODES` (`row-missing`, `slug-mismatch`, `pr-url-unsettled`); exit contract 0 consistent · 1 violations · 2 usage. The invariant it mechanizes: a unit doc that carries a PR URL must have its row reading `done · [#N](<same url>)` (backtick-tolerant; fix-index rows removed post-merge are convention, not contradiction). `findRow(table, nn)` is exported for callers that re-emit a row through `rowUpsert` without clobbering the cells they do not touch. The separator rule now matches any pipes/dashes/colons rule (≥3 dashes) — the old literal `|---|` match refused this repository's own `|----|------|…` separator, so the writer the issue names could not write the repo's real roadmap; rowUpsert/annotate receipts are byte-identical. |
 | 0.4.0 | 2026-10-22 | minor | **Feature 66 P1 — `memory probe`, the bounded memory-substrate health check** (issue #262, AC2). `agentic-workflow memory probe [--json]` runs five checks over the Engram layer and prints one `memory-probe@1` verdict (`ok` \| `degraded`): `http-health` (`GET :7437/health`, body `status` must be `ok`), `mcp-runner` (one JSON-RPC `initialize` against a spawned `engram mcp --tools=agent` — no MCP *tool* call is ever issued, so the probe cannot mutate the memory layer), `binary-version` (`engram --version`), `sync-staleness` (`engram sync --status`, `Pending import` must be 0), and `session-ambiguity` (the two check-scoped `engram doctor --json --check` calls — never the 12–23 s full sweep, and **both answers reported**: stopping at the first non-`ok` id would silence `sync_target_closed_space` permanently on a machine whose session attribution is ambiguous). Bounds: 4 s per HTTP/runner/version call, 10 s per staleness/session call, 30 s whole-probe ceiling; the five independent checks are launched together, so the run costs the slowest bound rather than the sum of five (32 s against a 30 s ceiling), and a bound hit fails that check instead of hanging. `ok` requires all five. Two measured rather than assumed rules: `engram doctor` exits 0 while its JSON says `status: "error"`, so every check parses its answer, and a responding server that has not synced is not `ok` (that is the staleness signal). **The command always exits 0** — `degraded` is an answer to record in Evidence, never a blocked unit. `runProbe({ fetchImpl, runImpl, timeoutMs })` takes its side effects by injection (the `src/doc/embeddings.mjs` `fetchImpl ?? fetch` shape), so the 20-test suite drives timeout, missing-binary, missing-runner, stale and healthy fixtures, both doctor findings and the shared-clock ceiling with fakes and millisecond bounds — no network, no PATH, no real engram process. |
 | 0.3.0 | 2026-10-21 | minor | **Feature 66 pre-work — the pin the published 0.2.0 could not carry.** Repository-only version bump recorded here so the crate's `package.json` and this table agree: `0.2.0` stays the version on the registry (the crate publishes from CI on merge, so an unpublished bump is not a release note), and this row exists because `scripts/check-changelog-row.mjs` requires a row per version. No functional change in this row. |
 | 0.2.0 | 2026-10-01 | minor | **Feature 65 — the `doc` retrieval entry point** (issue #192, half B): `agentic-workflow doc` gains `--sync | --query | --status | --rebuild [--json-only] [--quiet]` over a gitignored SQLite/FTS5 store (`.agentic-workflow/index/`), with the canonical TypeBox-validated envelope (`{ok, command, results[], degradations[], store}`, frozen key order), the closed degradation vocabulary, hash-incremental sync with a canonical manifest export (byte-identical for an unchanged corpus), the freshness invariant checked on every query, the AC14 session-log filter, and hybrid RRF fusion behind the AC15 judge gate with pi-style provider precedence (CLI > env > config > none ⇒ keyword-only). Crate's first pinned dependencies: `typebox@1.3.7` (zero transitive). Engines floor raised to `node >= 24` (D7). Ships to target projects via the pi package. |
@@ -315,6 +317,8 @@ How pinning actually works, verified against the `skills` CLI:
 
 #### `execute-phase`
 | Version | Date | Type | What changed |
+| 6.3.1 | 2026-10-27 | patch | **Issue #316 review F4 — the settle call site names the form that runs.** `6.3.0` shipped the settle as prose-calling-code but named `agentic-workflow roadmap rowUpsert` with no table path, and that argv resolved the subcommand word as a filename: every bare invocation refused with `ENOENT` on a file named `rowUpsert`. The close-out now names the executable form — `roadmap docs/features/ROADMAP.md rowUpsert '{"nn","slug","status"}'`, re-emitting the row's own `dependsOn`/`description` cells — and stops at the kind boundary: a fix index has no `NN` column, so `rowUpsert` is the roadmap's writer only and a fix unit writes its `docs/fix/README.md` status cell. `bun scripts/roadmap-settle.mjs` stays the offline validator for both. |
+| 6.3.0 | 2026-10-26 | minor | **Issue #316 — the whole-unit close-out settles the roadmap row through the crate's writer.** §7's close-out (open PR on `main` with `Closes #N`, `- PR: <url>` into References) now ends with `agentic-workflow roadmap rowUpsert` writing `done · [#N](<pr-url>)` with every other cell preserved, validated by `bun scripts/roadmap-settle.mjs` exiting 0 — the done settle is code, never prose. Per-phase mode is unchanged: the lane's release step owns the settle there. |
 |---|---|---|---|
 | 6.2.1 | 2026-10-23 | patch | **The memory pointer states attribution the way `MEMORY.md` §5 now defines it (feature 66 review-fold F7).** The Post-step item said "with an explicit `project` and `session_id`" — a parameter the host-side memory surface does not accept. It now reads "explicit `project` and explicit session attribution (§5 names what carries it on each write surface)", still pointing at the protocol's single home and never restating it. No rule changes. |
 | 6.2.0 | 2026-10-22 | minor | **The phase-transition memory boundary (feature 66 P2).** A unit's phases are now memory boundaries: the turn contract gains a box requiring each phase's outcome to be saved under `topic_key: \"unit/<NN-slug>/doc\"` — or the mirror marked pending when the layer is degraded — and Post-step gains a fifth item naming the obligation (probe once before the session's first memory read, save after the step, recall `mem_context` → scoped search → one explicit `all_projects: true` retry). The full protocol is never restated here: the item points at `skills/unit-lane/references/MEMORY.md`. A degraded memory layer is recorded and never blocks a phase. |
@@ -737,6 +741,8 @@ How pinning actually works, verified against the `skills` CLI:
 
 #### `unit-lane`
 | Version | Date | Type | What changed |
+| 2.5.1 | 2026-10-27 | patch | **Issue #316 review F4 — the release checklist names the form that runs.** `2.5.0`'s checklist item called `agentic-workflow roadmap rowUpsert` with no table path, which resolved the subcommand word as the file to open (`ENOENT` on a file named `rowUpsert`, exit 2) — the step the issue exists to make code could not run as written. The item now carries the index path and the JSON, and distinguishes the kind: `docs/features/ROADMAP.md` through `rowUpsert` for a feature, the `docs/fix/README.md` status cell for a fix (no `NN` column there). |
+| 2.5.0 | 2026-10-26 | minor | **Issue #316 — the release step calls the writer and the plan step emits the settle as a task.** `references/RELEASE.md`'s checklist replaces the prose "Roadmap row updated to `done`" with the `agentic-workflow roadmap rowUpsert` call (cells preserved, `bun scripts/roadmap-settle.mjs` exits 0); `references/PLAN.md`'s Tasks contract gains the `P<n+1>` release-settle task for units that open a PR (the sole exception to "no docs/release tasks"), so the executor owns the transition and a skipped write is a failed task. Unit-cycle writes the row itself regardless — the prose was the defect. |
 |---|---|---|---|
 | 2.4.1 | 2026-10-23 | patch | **Session attribution named the way the tools actually carry it (feature 66 review-fold F7).** §5 required an explicit `session_id` on every write, but the installed memory surface has no such parameter: Engram's own MCP server exposes it, the host-side provider binds the runtime session itself and refuses when that identity is ambiguous. The rule is unchanged — a write that cannot say which session it owns is a write that did not happen — the *carrier* is now stated per surface, with a table for the two shapes, the obligation never to write before the session is open, and the note that passing an argument a tool does not declare is an invalid call, not explicit attribution. §2's payload line, the checklist and the Forbidden list follow it; `execute-phase` 6.2.1 mirrors the pointer. Wording fix, no new behaviour. |
 | 2.4.0 | 2026-10-22 | minor | **The Engram memory protocol (feature 66 P2).** `references/MEMORY.md` is the protocol's single home: the bounded probe (`agentic-workflow memory probe`) before a session's first read; three save boundaries — unit start, each phase transition, unit close — under the stable `unit/<NN-slug>/doc` topic with an explicit `project` and `session_id`; the fixed recall order (`mem_context` → scoped search with an explicit `project` → one explicit `all_projects: true` retry → `mem_get_observation` → the unit doc wins); the disclosed keyword-bound ceiling (a miss is not evidence of absence); session attribution (`mem_session_end` only on confirmed-stale ids, the explicit project fallback for `mem_session_summary`); the D2 split against `docs/LOGS.md`; and the degradation rule (mirror marked pending, local progress preserved, both sides read back). SKILL.md gains one turn-contract box and the §5b boundary step. Memory is required substrate, never a hard failure dependency. |

README.md

@@ -85,7 +85,7 @@ review the change → audit → merge.**
 
 | Skill           | What it does                                                                                                                                                                                                                                                                                                                                                                      |
 | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `execute-phase` | Executes **one phase per turn** (`<NN> P<k>`, tier attached) with its own acceptance-blob check, phase/invariant/dependency gates, tests, docs, and commit — the closing hand-off names the next single phase and the catalog tier, and resumes `unit-lane` after the last phase. Looping all remaining phases (`<NN>` with no phase) is an explicit operator choice only. Halts on red/no-progress/attempt budget. Discoveries become `Autofix`, `Opportunistic Fix`, or a proposal—never an automatic issue. Each phase's pre-flight runs `bun scripts/phase-lint.mjs <plan>` and pastes its output. It never interviews: a missing input runs the three-tier dispatch and then `scripts/needs-input.mjs` prints the `open-questions@1` block and the run stops, routed back to the stage that owns the fact. |
+| `execute-phase` | Executes **one phase per turn** (`<NN> P<k>`, tier attached) with its own acceptance-blob check, phase/invariant/dependency gates, tests, docs, and commit — the closing hand-off names the next single phase and the catalog tier, and resumes `unit-lane` after the last phase. Looping all remaining phases (`<NN>` with no phase) is an explicit operator choice only. Halts on red/no-progress/attempt budget. Discoveries become `Autofix`, `Opportunistic Fix`, or a proposal—never an automatic issue. Each phase's pre-flight runs `bun scripts/phase-lint.mjs <plan>` and pastes its output. The whole-unit close-out settles the roadmap row through the crate's writer (`bun scripts/roadmap-settle.mjs` exits 0, issue #316). It never interviews: a missing input runs the three-tier dispatch and then `scripts/needs-input.mjs` prints the `open-questions@1` block and the run stops, routed back to the stage that owns the fact. |
 
 ### Review & audit — _change → PR → product_