@sabaiway/agent-workflow-engine 4.3.0 → 4.4.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to the methodology engine. Versions are this **package's** n
 they are distinct from the **deployment-lineage** stamp written into a project's `docs/ai/`
 (which tracks the shared `agent-workflow` lineage, head `3.0.0`).
 
+## 4.4.0 — the plan cap counts rows, the readers sweep opens self-review, the consult order and the round render are canon (AD-125)
+
+`references/planning.md`: the cap is 100 lines AND ≤25 ledger rows, 200 UTF-8 bytes per row counted
+without the path and anchor fields (the 8000-byte cap is deleted); an extension phase rides only
+before Cleanup; the two checker commands (`plan-shape-cli.mjs --check` before the first review,
+`--verify` at Cleanup) are named at the point of use. `references/procedures.md`: `plan-authoring`
+carries `Slots: author, fold, review`; step 3 opens with the readers sweep (one literal search per
+changed key, symbol, receipt field or canon sentence — every reader becomes a row, a non-goal or a
+pinned "unchanged"); step 5 of BOTH activities carries the consult-before-fold order (ASK the review
+member that raised the finding, WAIT, READ, fold only as accepted or corrected; a self-review finding
+folds directly); plan-authoring's step 5 additionally names the round render as the source of the
+per-round emission's verdict half — the crossover stop is a computed signal, the origin tally the
+orchestrator's judgment. The canon tests
+pin every sentence (spec `plan-review-loop` S13, S18); the procedures-to-planning size pin is a 1.2
+ratio, declared.
+
 ## 4.3.0 — the fifth recipe, the third activity, and a carrier that is never the one who commits (AD-124)
 
 `references/orchestration.md` admits the CARRIER wherever it said backend: the orchestrator, a bridge

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-engine
 description: Canonical home of the agent-workflow planning methodology — the capped plan shape (goal and boundary, module ledger, verification), plan lifecycle, queue.md series index, mandatory Cleanup phase, the feature-spec canon (the durable per-feature contract layer with its frozen schema and Out-of-scope discipline), the bounded methodology slot fragment, the orchestration-recipe vocabulary (Solo / Reviewed / Council / Delegated / Subagent), and the activity-procedures canon (plan-authoring / plan-execution / routine, with typed recipe slots). A published, installable npm package (available:true) that *provides* the methodology text; it mutates nothing. The composition root (agent-workflow-kit) reads this canon LIVE from the installed engine and injects the bounded slots from it — one source of truth, no bundled mirror; `npx @sabaiway/agent-workflow-kit@latest init` installs the engine.
 disable-model-invocation: true
 metadata:
-  version: '4.3.0'
+  version: '4.4.0'
 ---
 
 # agent-workflow-engine

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-engine",
   "kind": "methodology-engine",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "available": true,
   "provides": ["plan"],
   "roles": {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-engine",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "Canonical home of the agent-workflow planning methodology — the capped plan shape (goal and boundary, module ledger, verification), plan lifecycle, queue.md series index, and mandatory Cleanup phase, consumed by the kit (composition root). The methodology engine of the agent-workflow family.",
   "keywords": [
     "ai-agents",

package/references/planning.md

@@ -8,8 +8,9 @@ plan tells it which files to open, what each one may become, and how the result
 
 ## Shape
 
-The whole file is capped at **100 lines and 8000 bytes** — both, because a line cap alone is paid off
-with longer lines. The headings are LITERAL, copied bare: tooling extracts sections by exact match.
+The whole file is capped at **100 lines and at most 25 ledger rows**. Before its first review and
+after every authoring fold, run `node <kit>/tools/plan-shape-cli.mjs --check <plan>`. The headings are
+LITERAL, copied bare: tooling extracts sections by exact match.
 
 ```
 # Plan: <title>
@@ -20,6 +21,9 @@ with longer lines. The headings are LITERAL, copied bare: tooling extracts secti
 ## Next steps
 ```
 
+A project-declared `## Phase: <name>` may ride between Verification and Cleanup; it is bounded by
+the whole-file line cap and may not reuse the Cleanup name.
+
 A plan that does not fit is not under-described. Either the TASK is too big — split it along
 independently verifiable boundaries, never by document size — or it is a SWEEP (below).
 
@@ -34,7 +38,8 @@ independently verifiable boundaries, never by document size — or it is a SWEEP
 
 ## Module ledger
 
-One row per path, ≤200 bytes per row, six fields:
+One row per path, six fields. A row is capped at **200 UTF-8 bytes counted without its path and
+anchor**: id, verb, responsibility and budget after trimming, including their three ` | ` separators.
 
 ```
 <check-id> | create|modify|delete | <path> | <responsibility, one sentence> | <max lines | n/a> | <anchor>
@@ -71,9 +76,9 @@ the sweep, and breaks the intermediate states.
 ## Verification
 
 Exact existing commands plus the acceptance check for the goal. The ledger is validated by ONE
-command over its `check-id`s — existence and budget for create/modify, absence for delete, the count
-for a sweep, and the total line. Per-row assertions in prose are the repetition this section exists
-to avoid.
+command: `node <kit>/tools/plan-shape-cli.mjs --verify <plan>` — existence and budget for
+create/modify, absence for delete, the count for a sweep, and the total line. Per-row assertions in
+prose are the repetition this section exists to avoid.
 
 **The acceptance criteria ARE the `- ` bullets.** Every top-level `- ` bullet in this section is one
 acceptance criterion, and they are the whole list — nothing outside a bullet is one. That makes the

package/references/procedures.md

@@ -6,7 +6,7 @@ The ordered steps of each named activity, with **typed recipe slots** bound to t
 live and parses only each section's `Slots:` line.
 
 A **recipe slot**: `review` accepts `solo | reviewed | council`; `execute` accepts
-`solo | delegated | subagent`; a carrier slot (`author`, `carrier`) accepts `solo | subagent`;
+`solo | delegated | subagent`; a carrier slot (`author`, `fold`, `carrier`) accepts `solo | subagent`;
 `parallel` is a switch (`on | off`), not a recipe. The per-project default lives in
 `docs/ai/orchestration.json`.
 
@@ -30,7 +30,7 @@ inline plus the link.
 
 ## plan-authoring
 
-Slots: author, review
+Slots: author, fold, review
 
 1. **Research** — the exact files, contracts and constraints touched.
 2. **Draft** — write to the shape [`planning.md`](planning.md) fixes; its *Module ledger* decides
@@ -41,21 +41,35 @@ Slots: author, review
    Subagent: the orchestrator writes a BRIEF (goal, governing specs, ledger
    constraints, files) and the subagent drafts the plan and any `create` / `modify`
    spec row from it, and the orchestrator reviews the draft as its own before step 3.
-3. **Self-review** — apply *What gets cut*; fold by code (read and cite the `file:line`); update
-   `queue.md` for a series, to the shape *The queue* fixes.
+3. **Self-review** — run the **readers sweep before the first review**: for every config key,
+   registry entry, exported constant, receipt field or canon sentence the plan changes, use one
+   literal repository search to list its readers (validators, renders, seeds, docs and the tests
+   that pin the text). Every reader becomes a ledger row, a stated non-goal, or unchanged with
+   the test or fixture that proves it. Then apply *What gets cut*; fold by code
+   (read and cite the `file:line`); update `queue.md` for a series, to the shape *The queue* fixes.
 4. **review {recipe}** — Solo (self-review only) / Reviewed (one backend) / Council (both; you
    synthesize), as the resolved `review` recipe selects.
-5. **Fold + loop** — fold every finding and re-review; CLEAN is **0 blockers + 0 majors** from every
-   backend the recipe names — folding ≠ convergence. Fold a code-touching finding **test-as-spec**,
-   with **no code-mechanics** in the plan: only **checked syntax** its Verification runs; un-run,
+5. **Fold + loop** — before folding a finding raised by a **review member**, **ASK** that member whether the
+   proposed fold solves it without a new problem; **WAIT**, **READ**, then hand the accepted or
+   corrected fold to the resolved `fold` carrier. Self-review findings, or findings with no review
+   member, are folded directly. Forms: `agy-review --continue --decided @f` for agy, a
+   fresh `codex-review plan <consult-brief>` for
+   codex, or a fresh re-dispatch of the same lens vehicle for a lens member; write the finding and
+   fold before the tree changes. Solo: orchestrator edits. Subagent: the round's findings with their
+   dispositions are the slice; it edits the plan or contract and returns; orchestrator runs the
+   self-consistency read.
+   Fold and re-review every finding; CLEAN is **0 blockers + 0 majors** from each named backend;
+   folding ≠ convergence. Fold code findings **test-as-spec**, with **no code-mechanics** in the
+   plan: only **checked syntax** its Verification runs; un-run,
    **logic-bearing** syntax never enters prose (*Un-run syntax never ships in prose*). Council runs
    every named backend **every round** (recipe fidelity, `orchestration.md` §4). Cap architecture
    review at **≤2 rounds**; **backend divergence** (one ships, one keeps revising mechanics) IS the
-   **crossover** — resolve the surviving major at altitude, never by exhausting the strictest
-   backend; a **self-consistency** read precedes each re-review; an all-mechanics or prose-only
-   artifact takes a thin plan + **diff-review** (*The plan must read cold*). Each round MUST emit
-   **{round N · finding-origin tally · per-backend verdict}**. At the cap, classify each surviving
-   blocker or major: **fixable-bug** (fold ONCE as a red→green test, re-review) /
+   **crossover** — resolve the major at altitude, not by exhausting that backend.
+   A **self-consistency** read precedes each re-review; all-mechanics or prose-only takes a thin plan
+   + **diff-review** (*The plan must read cold*). Each round MUST emit
+   **{round N · finding-origin tally · per-backend verdict}**: READ its verdict half from the round
+   render (`review-rounds`, the kit's table over the review receipts); append the orchestrator's finding-origin tally
+   judgment. At the cap, classify surviving blockers/majors: **fixable-bug** (fold ONCE as a red→green test, re-review) /
    **inherent-layer-residual** (raise to an acceptance criterion) / **escalate**.
 6. **Present for approval** — never execute here: a harness "approved — start coding" prompt
    (**ExitPlanMode**) authorizes the PLAN only; `plan-execution` is a deliberate transition once
@@ -83,14 +97,24 @@ Each ledger row is one logical commit.
    Verification, under the project's reuse and clean-code rules; fold by code (cite the
    `file:line`); **characterize-first**: pin uncovered code's behaviour in a green test before
    editing it; fold each finding test-as-spec (red→green); atomic, reversible edits.
-5. **review {recipe}** — the **heavy review at the diff** (*The plan must read cold*): real code and
-   the full suite. The plan-authoring loop applies unchanged — every named backend every round,
-   **0 blockers + 0 majors**, the **{round N · finding-origin tally · per-backend verdict}**
-   emission, **fixable-bug / inherent-layer-residual / escalate** at the cap. Its instruments:
+5. **review {recipe}** — the **heavy review at the diff** (*The plan must read cold*): real code +
+   full suite. Authoring loop applies unchanged: every named backend every round; a finding raised
+   by a **review member**: **ASK**, **WAIT**, **READ**, fold only as accepted or corrected; a
+   self-review finding is folded directly (forms: its step 5). CLEAN:
+   **0 blockers + 0 majors**; the **{round N · finding-origin tally · per-backend verdict}**
+   emission; **fixable-bug / inherent-layer-residual / escalate** at the cap. Its instruments:
    `core-evidence red-proof` declares each bugfix red BEFORE the fix; `core-evidence
    degrade` records an unavailable backend; reviews run on the STAGED tree; `run-gates --final`
    mints the ONE receipt `commit-guard --check` gates the commit against.
 
+   On an **ARMED flow**, a **bridge-raised** finding uses this order: the round is open; dispatch
+   its consult with a nonce; WAIT and READ; accept or correct the fold; run
+   `flow-writer consult-attestation <planId> --backend <id> --nonce <n> --proposed-fix-digest
+   <the-sha256-of-the-fold-text>`; then edit. The attestation records the manifest and fold digest,
+   never the run or answer. A **lens-raised** finding instead re-dispatches the lens without a nonce
+   (WAIT and READ, edit as accepted or corrected); it mints no manifest and no attestation; only its
+   per-round participation rides `internal-attestation`.
+
    **Finding scope** — every finding NAMES the invariant its fix enforces, BEFORE the edit, every
    round. Already an acceptance criterion (*Verification*'s `- ` bullets) → **fold here**. It would
    have to be ADDED → the **narrow fix** for the found site ships now (red first) and ONLY the