@sabaiway/agent-workflow-engine 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -4,6 +4,36 @@ 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 `1.3.0`).
 
+## 1.7.0 — Harden the planning canon: process-fidelity + regression-free editing
+
+A **feature** release. The methodology canon gains **seven invariants** that close recurring
+process-fidelity slips and fold-induced churn — each pinned in its natural home and guarded by the engine
+canon tests (+ the kit's extended cross-package `lens-mirror.test.mjs`):
+
+- **`references/planning.md` §6 — *ExitPlanMode ≠ execute*.** A harness "approved — start coding" prompt
+  authorizes the PLAN only; "continue in-session" is a DELIBERATE transition into `plan-execution` after
+  the plan + cold-start prompt exist, never an implicit slide (disambiguates §6 vs the Definition of Done).
+- **`references/planning.md` §9 — regression-free editing + the convergence bar.** *No code-mechanics in
+  the plan*, *test-as-spec* (fold a code-touching finding into a red→green test, not prose),
+  *characterize-first* (pin uncovered behavior before editing), *heavy review at the diff*, and a CLEAN
+  loop defined as **0 blockers + 0 majors from every named backend** (folding ≠ convergence).
+- **`references/orchestration.md` §4/§5 — *recipe fidelity*.** Council runs every ready backend **every
+  round**; quietly dropping a ready backend is a forbidden silent downgrade (the converse of the
+  unavailable-backend degrade), and the §5 quota guard is explicitly not a licence to drop one.
+- **`references/procedures.md`** — terse pointers weave all of the above into both activity steps.
+
+The deployment-lineage head stays **`1.3.0`** (no `docs/ai` structural change, no migration); the npm
+package version is a separate axis.
+
+## 1.6.0 — Loosen the agy Issue-001 caveat (grounded review is sound)
+
+A **feature** release. `references/orchestration.md` §5 reframes the `agy` health advisory: the grounded
+`agy-review` contract removes agy's stale-model / partial-diff **false positives**, so `agy` is a **sound**
+second opinion now — no longer something to merely avoid. The real **service-stall** caveat (Issue-001) is
+kept — it is a separate risk that grounding does not remove — as is the codex-before-agy tie-break for
+large / latency-sensitive substantive reviews and the `--add-dir` escalation path. The deployment-lineage
+head stays **`1.3.0`** (no `docs/ai` structural change).
+
 ## 1.5.0 — Right-altitude & code-grounded folds in the canon
 
 A **feature** release. The planning canon (`references/planning.md`, read **live** by the composition

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-engine
 description: Canonical home of the agent-workflow planning methodology — the Plan→Phase→Step→Substep vocabulary, plan lifecycle, queue.md series index, mandatory Cleanup phase, the bounded methodology slot fragment, the orchestration-recipe vocabulary (Solo / Reviewed / Council / Delegated), and the activity-procedures canon (plan-authoring / plan-execution, 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: '1.5.0'
+  version: '1.7.0'
 ---
 
 # agent-workflow-engine

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-engine",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Canonical home of the agent-workflow planning methodology — the Plan→Phase→Step vocabulary, 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/orchestration.md

@@ -22,8 +22,8 @@ Each backend declares what it can do in its `capability.json` `provides` / `role
 - **`codex-cli-bridge`** (`codex`) — `provides: ["execute", "review"]`. It can run a bounded
   execution sub-task (`codex-exec`, output: a diff) and give an advisory review (`codex-review`,
   modes `plan` / `code`).
-- **`antigravity-cli-bridge`** (`agy`) — `provides: ["review", "probe"]`. It can give an advisory
-  review and answer a bounded probe (both via `agy-run`).
+- **`antigravity-cli-bridge`** (`agy`) — `provides: ["review", "probe"]`. It gives an advisory,
+  grounded review via `agy-review` (modes `code` / `plan` / `diff`) and answers a bounded probe via `agy-run`.
 
 Both are **subscription** backends with a **finite quota** — spend deliberately.
 
@@ -69,18 +69,38 @@ always reported, never silently dropped:
 - **Delegated → Solo.** No backend provides `execute` and is `ready` → Solo, with the reason.
 - **Reviewed → Solo.** No backend provides `review` and is `ready` → Solo, with the reason.
 
+**Recipe fidelity — the converse: every ready backend, every round.** Degradation is the *only*
+licence to run fewer backends than the recipe names. When the resolved recipe is `council` and BOTH
+reviewers are `ready`, EVERY review round runs BOTH — skipping a ready backend for quota, convenience,
+or "the other one already shipped" is a **SILENT downgrade of Council → Reviewed, and is forbidden**.
+The distinction is strict: an *unavailable* backend is a LOUD, stated degrade (the lattice above); a
+*ready* backend you quietly drop is a fidelity breach, not a degrade. The same holds for any recipe
+that names ≥2 backends. Folding a finding and re-reviewing (the convergence bar, [`planning.md`](planning.md)
+§9) re-runs **every named backend each round** — convergence is reached only when one round comes back
+clean from all of them.
+
 ## 5. Quota & health guard (advisory)
 
 Backends are **subscription** services with **finite** quota. The orchestrator should: prefer the
 cheapest model that fits the task; not reach for a top-tier model by reflex; and remember that
 **Council spends two backends' quota** for one decision.
 
+This guides *which recipe to choose up front* and *which model to run within a backend* — it is
+**never a licence to drop a ready backend mid-Council** (that is the §4 fidelity breach, not a quota
+saving). Once `council` is the resolved recipe and both backends are `ready`, the two-backend cost is
+already accepted: run both, every round, until a round comes back clean.
+
 A **standing health advisory** applies to `agy`: the Antigravity service can **stall on substantive
 prompts** (a long hang that returns nothing — an external service issue, not a setup problem;
 tracked as **Issue-001** in the kit's known issues). It is **invisible to file-presence detection**,
-so it is *not* a readiness signal — it is a static caveat attached whenever a recipe would use `agy`. While it lasts, **prefer `codex`** for substantive
-reviews (this is the Reviewed tie-break in §3). The recipe machinery **never runs a subscription
-CLI** to check — detection stays read-only.
+so it is *not* a readiness signal — only a standing caveat. The **grounded** `agy-review` contract
+makes `agy` a **sound** second opinion — it removes the stale-model / partial-diff **false positives**
+that the old ungrounded, `--add-dir`-roaming reviews produced — so `agy` is no longer something to
+merely avoid. But the *service* stall is a **separate, real** risk that grounding does **not** remove,
+so keep reviews **focused** (the inherited hard timeout is the guard) and **prefer `codex`** for large
+or latency-sensitive substantive reviews and for the `--add-dir` escalation path (the deterministic
+Reviewed tie-break in §3). The recipe machinery **never runs a subscription CLI** to check — detection
+stays read-only.
 
 ## 6. The orchestrator always commits
 

package/references/planning.md

@@ -78,6 +78,10 @@ The volume trigger above (files / LoC / tokens) is necessary but not sufficient.
 - **Continue** in the current session when ALL hold: (1) exploration was *targeted-deep* — you read the exact files to be created/modified/copied, so execution would just re-read them; (2) no new heavy exploration is needed to execute; (3) the context budget is healthy (far from the window limit / Lost-in-the-Middle).
 - When continuing, each Phase's Verification block is a natural checkpoint. If different Phases need different cold context, continue only through the warm Phases, then split.
 
+### ExitPlanMode authorizes the plan, not execution
+
+A harness "approved — you can now start coding" prompt (e.g. Claude Code's **ExitPlanMode**) authorizes the **PLAN only** — this methodology overrides that generic prompt. A planning session is not done until the plan is landed in `docs/plans/` **and** the cold-start execution prompt is emitted (the plan-authoring Definition of Done). So **"Continue in-session" above is a DELIBERATE transition into `plan-execution`, taken *after* both of those exist** — never an implicit slide from plan-approval straight into editing tracked files. Plan-approval is not a licence to execute the plan in the same breath; the boundary holds whether you split or continue.
+
 ## 7. Plan-document structure
 
 ```
@@ -107,10 +111,20 @@ The volume trigger above (files / LoC / tokens) is necessary but not sufficient.
 
 ## 9. Right-altitude & code-grounded folds
 
-Two disciplines keep a plan converging instead of churning. They govern authoring, every review round, and execution.
+These disciplines keep a plan converging instead of churning, and keep a fold or edit from shipping a new bug. They govern authoring, every review round, and execution. The honest premise: prose has no checker, so the only guarantee that a fold/edit ships no regression is a deterministic, non-vacuous, auto-run gate — hence test-as-spec + characterize-first below.
 
 **Right altitude.** A plan pins *intent + architecture + invariants + acceptance criteria* — the named tests that must stay green and the new tests that must pass. It does NOT spell out fine code-mechanics in prose: those are resolved in code at Execute (against the real files + the per-Step review + the gates), where prose cannot diverge from reality. Most "blockers" that resurface across review rounds are code-level details that never belonged in a prose plan.
 
+**No code-mechanics in the plan.** A Step still carries its exact paths + commands (§7, §8); the ceiling is on *fold-bred* detail — a review fold must not push fine code-mechanics (`cd`, an env default, a flag) into prose, where they diverge from reality. A fold that needs a mechanic is the trigger to write the test (test-as-spec) instead.
+
 **Fold by code, not prose.** Before folding any code-touching finding into the plan, READ the cited `file:line`; the fold cites it. A fold grounded in prose alone drifts from the code and seeds the next bug.
 
+**Test-as-spec.** Fold a code-touching review finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker, and a paragraph cannot self-check. A bug may still be written, but the test catches a fold-/edit-induced regression before it ships.
+
+**Characterize-first.** Before editing UNCOVERED code, first write a test pinning its current behavior (green), then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible (one logical change = one gated commit), and prefer SUBTRACTIVE folds.
+
+**Heavy review at the diff, not the plan.** Plan-review settles architecture only (≤2 rounds, stop at the pre-existing→fold-induced crossover); the exhaustive per-Step review runs against real compiling code + the full suite, where a regression fails a gate immediately. The plan is the wrong place for an exhaustive line-by-line review.
+
+**Convergence bar.** A review loop is CLEAN only when one round returns **0 blockers + 0 majors** from EVERY named backend the recipe runs (nits / non-blocking + a ship verdict is the stop). FOLDING a finding is NOT convergence — re-review after folding. This §9 governs the ALTITUDE at which you reach clean (fix the major, or raise it to an explicit acceptance invariant Execute must meet) — it NEVER lowers the bar to "majors folded".
+
 **Convergence heuristic.** When a review round keeps finding code-mechanism issues on a stable architecture, STOP refining prose — either raise the spec to invariant + acceptance altitude, or hand the mechanics to Execute. Do not re-litigate code mechanics in the plan.

package/references/procedures.md

@@ -53,8 +53,18 @@ Produce a self-contained, cold-readable plan, reviewed to the configured depth b
 4. **review {recipe}** — review the draft at the depth the resolved `review` recipe selects: Solo
    (self-review only), Reviewed (one backend reviews), or Council (both backends review, you
    synthesize). The kit resolves the effective recipe from `docs/ai/orchestration.json` + readiness.
-5. **Fold + loop** — fold every finding back into the draft and re-review until the review is clean.
-6. **Present for approval** — surface the finished plan to the user; do not begin execution here.
+5. **Fold + loop** — fold every finding back into the draft and re-review. A loop is CLEAN only at
+   **0 blockers + 0 majors** from every backend the recipe names (the convergence bar,
+   [`planning.md`](planning.md) §9); folding ≠ convergence — re-review after folding. Fold a
+   code-touching finding **test-as-spec** (a named acceptance test, not a prose paragraph); a fold must
+   add **no code-mechanics** to the plan — a Step still carries its own exact paths + commands, but a
+   fold needing a mechanic is the trigger to name the test instead. Council runs every named backend
+   **every round** (recipe fidelity,
+   [`orchestration.md`](orchestration.md) §4) — never quietly drop a ready backend.
+6. **Present for approval** — surface the finished plan to the user; do not begin execution here. A
+   harness "approved — start coding" prompt (**ExitPlanMode**) authorizes the PLAN only
+   ([`planning.md`](planning.md) §6); continuing into `plan-execution` is a deliberate transition taken
+   after the plan + its cold-start prompt exist, never an implicit slide.
 
 **Required output (Definition of Done):** a planning session produces a self-contained plan in
 `docs/plans/` **and** a cold-start execution prompt to begin the next session — **both produced without
@@ -78,9 +88,14 @@ Execute an approved plan Step by Step; each Step is one logical commit.
    following the project's reuse + clean-code rules.
 4. **Self-review** — run the [`planning.md`](planning.md) §8 self-review on the change, applying the
    [`planning.md`](planning.md) §9 lens — fold by code (read and cite the `file:line`), and hold the
-   right altitude.
+   right altitude. Edit-time corollary: **characterize-first** — before editing uncovered code, pin its
+   current behavior in a green test, then edit (any unintended change goes red); fold each finding
+   **test-as-spec** (red→green), and keep edits atomic/reversible.
 5. **review {recipe}** — review the result at the resolved `review` depth (Solo / Reviewed / Council),
-   exactly as in plan-authoring.
+   exactly as in plan-authoring. This is the **heavy review at the diff** — real compiling code + the
+   full suite, where a regression fails a gate immediately ([`planning.md`](planning.md) §9). Council
+   runs every named backend **every round** (recipe fidelity, [`orchestration.md`](orchestration.md) §4);
+   loop to **0 blockers + 0 majors** from every backend before the gate.
 6. **Gates** — run the project's verification gate (tests + checks) to green before committing.
 7. **Commit boundary** — the orchestrator makes the single commit for the Step; a backend never
    commits. The project's commit-approval policy (e.g. ask first) lives in the project's own rules.