@sabaiway/agent-workflow-kit 1.21.0 → 1.23.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 1.23.0 — Surface the review-loop economics + the resolved backend set in the procedures advisor
+
+A **feature** release. `/agent-workflow-kit procedures <activity>` now makes the review-loop discipline
+mechanical at the point of use:
+
+- **Backend-set aid.** Each resolved recipe prints its EXPLICIT wrapper set beside the recipe name
+  (`review: council → run every backend every round: codex-review + agy-review`; `reviewed → codex-review`;
+  `delegated → codex-exec`; solo prints none), so recipe fidelity is visible where the advisor is invoked.
+  Sourced from `planRecipe().dispatch` + a new role-keyed `detect-backends.wrapperCmdFor` (reading
+  `KNOWN_BACKENDS[].roleCmds`, now the source of truth; the deduped `wrapperCmds` readiness list is derived
+  from it). Drift-guarded against each bridge manifest `roles[role].cmd`.
+- **Review-loop economics block.** For a review slot resolving reviewed|council (omitted for solo) the
+  advisor prints the ≤2-round cap, the bar-met-by-raising-a-major rule, the backend-divergence crossover
+  stop, the thin-plan/diff-review carve-out, a self-consistency read, and the required per-round emission
+  {round N · finding-origin · per-backend verdict}. `--json` carries per-slot `backends` + a top-level
+  `reviewLoop`.
+- The fallback `agent_rules.md` **§2.5** lens mirror gains the same review-loop disciplines (byte-identical
+  to memory's §2.6).
+
+Read-only; no resolution behaviour change. Deployment-lineage head stays `1.3.0`.
+
+## 1.22.0 — Harden the planning canon: two-set lens drift guard + the deployed lens
+
+A **feature** release. The kit's fallback `agent_rules.md` **§2.5** lens is generalized from *Right-altitude
+& code-grounded* to **Planning, review & process-fidelity invariants** (byte-identical to memory's §2.6
+block) and now carries all **seven** methodology invariants. The cross-package **`test/lens-mirror.test.mjs`**
+is extended to **two scoped, non-vacuous token sets**:
+
+- **Set 1 (cross-all-four)** pins the §9-native review/fold + convergence disciplines in EVERY region —
+  planning §9, procedures (`## plan-authoring` onward), and both template lens blocks: `0 blockers + 0
+  majors`, `test-as-spec`, `no code-mechanics`, `at the diff`, `characterize-first` (alongside the
+  existing `fold by code` / `file:line` / `altitude`).
+- **Set 2 (template-scoped)** pins the process-fidelity invariants A1/A2 (`ExitPlanMode`, recipe-fidelity
+  `every round`) PRESENT in both template lens blocks — closing the gap the byte-identical check alone
+  cannot (it only proves the two templates AGREE, so both could drop A1/A2 and stay green).
+
+The lens heading + the `extractLensBlock` regex move in lockstep. The deployment-lineage head stays
+**`1.3.0`** (no `docs/ai` structural change, no migration); the kit **package** version is a separate axis.
+
 ## 1.21.0 — Ships the antigravity-cli-bridge 2.0.0 mirror (grounded agy-review)
 
 A **feature** release. The kit now bundles the **antigravity-cli-bridge 2.0.0** byte-identical mirror —

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '1.21.0'
+  version: '1.23.0'
 ---
 
 # agent-workflow-kit

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/templates/agent_rules.md

@@ -61,10 +61,19 @@ Before proposing changes or committing, review against:
 ### 2.4. Quality Gates
 - Always run type-checker, linter, and all tests before committing.
 
-### 2.5. Right-altitude & code-grounded (planning + review)
+### 2.5. Planning, review & process-fidelity invariants
+Apply these when authoring a plan, reviewing, folding a finding, or editing code — the layer read **before any code change**. (Full canon: the project's planning / workflow-methodology + orchestration canon.)
 - **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
 - **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
-- **Convergence heuristic.** When a review round keeps finding mechanism issues on a stable architecture, stop refining prose — raise the altitude or hand it to Execute. (Full canon: the project's planning methodology / workflow-methodology canon.)
+- **No code-mechanics in the plan.** A Step still carries its exact paths + commands (the plan-structure / self-review canon); the ceiling is on *fold-bred* detail — a review fold must not push fine code-mechanics (`cd`, an env default, a flag) into prose. A fold that needs a mechanic is the trigger to write the test instead.
+- **Test-as-spec.** Fold a code-touching finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker; a paragraph cannot self-check.
+- **Characterize-first.** Before editing UNCOVERED code, pin its current behavior in a green test, then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible; prefer SUBTRACTIVE folds.
+- **Fold minimally — prose has no checker.** An ephemeral, gitignored plan is prose with no executable checker; fold **minimally, in ONE place** and run a **self-consistency** read across the plan before every re-review — a fold that drifts several prose spots is what turns a 2-round review into churn.
+- **Heavy review at the diff.** 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. **Backend divergence** (one backend grounded-ships while another keeps revising mechanics) IS that crossover — resolve at altitude, don't exhaust the strictest backend; route an all-mechanics/CI or prose-only artifact to a **thin plan + diff-review**.
+- **Convergence bar.** A review loop is CLEAN only when one round returns **0 blockers + 0 majors** from EVERY backend the recipe names (nits + a ship verdict is the stop). Folding ≠ convergence — re-review after folding.
+- **Per-round emission.** Every review round emits **{round N · finding-origin tally · per-backend verdict}** so the crossover is a computed, visible signal, not a remembered rule.
+- **Recipe fidelity.** Council runs every backend the recipe names, **every round**; silently dropping a ready backend for quota/convenience is a forbidden downgrade — an unavailable backend is a LOUD, stated degrade, never a quiet drop.
+- **ExitPlanMode ≠ execute.** A harness "approved — start coding" prompt authorizes the PLAN only; this methodology overrides it. Continue into execution only as a DELIBERATE transition after the plan + cold-start prompt exist, never an implicit slide.
 
 ---
 

package/tools/detect-backends.mjs

@@ -51,13 +51,15 @@ const EXPECTED_KIND = 'execution-backend';
 // The kit-owned registry: the per-backend facts the detector needs even when a bridge is NOT
 // installed (no manifest on disk to read). Kept in lockstep with the in-repo manifests by the
 // drift-guard test. `credential.env: null` → no env override exists (do not invent one).
-// `wrapperCmds` is the EXPECTED deduped roles[].cmd set the CURRENT kit bundles — readiness probes
-// THIS set (not the installed manifest's), so a stale install missing a wrapper surfaces DEGRADED.
-export const KNOWN_BACKENDS = [
+// `roleCmds` is the role-keyed source of truth (role → the PATH wrapper cmd), mirroring each bridge
+// manifest `roles[role].cmd`, drift-guarded. Two derivations ride on it, both drift-guarded against the
+// manifests: `wrapperCmds` (the deduped set the readiness probe checks — a stale install missing one
+// surfaces DEGRADED) and `wrapperCmdFor(backend, role)` (which concrete wrapper the backend-set aid prints).
+const RAW_BACKENDS = [
   {
     name: 'codex-cli-bridge',
     installed: { env: 'CODEX_CLI_BRIDGE_DIR', default: '~/.claude/skills/codex-cli-bridge', file: 'SKILL.md' },
-    wrapperCmds: ['codex-exec', 'codex-review'],
+    roleCmds: { execute: 'codex-exec', review: 'codex-review' },
     bin: 'codex',
     credential: { env: 'CODEX_HOME', default: '~/.codex', file: 'auth.json' },
     setupUrl: 'https://github.com/sabaiway/agent-workflow/blob/main/codex-cli-bridge/setup/README.md',
@@ -69,7 +71,7 @@ export const KNOWN_BACKENDS = [
   {
     name: 'antigravity-cli-bridge',
     installed: { env: 'ANTIGRAVITY_CLI_BRIDGE_DIR', default: '~/.claude/skills/antigravity-cli-bridge', file: 'SKILL.md' },
-    wrapperCmds: ['agy-review', 'agy-run'],
+    roleCmds: { review: 'agy-review', probe: 'agy-run' },
     bin: 'agy',
     credential: { env: null, default: '~/.gemini/antigravity-cli', file: 'antigravity-oauth-token' },
     setupUrl: 'https://github.com/sabaiway/agent-workflow/blob/main/antigravity-cli-bridge/setup/README.md',
@@ -78,6 +80,17 @@ export const KNOWN_BACKENDS = [
   },
 ];
 
+// The deduped roles[].cmd set the CURRENT kit bundles, derived from roleCmds in first-seen order — one
+// source, so the readiness-probe list can never drift from the role-keyed map.
+const wrapperCmdsFromRoles = (roleCmds) => [...new Set(Object.values(roleCmds ?? {}))];
+export const KNOWN_BACKENDS = RAW_BACKENDS.map((entry) => ({ ...entry, wrapperCmds: wrapperCmdsFromRoles(entry.roleCmds) }));
+
+// Resolve a dispatched (backend manifest name, role) to its concrete PATH wrapper cmd (e.g.
+// codex-cli-bridge + review → "codex-review") from the role-keyed registry — the backend-set aid
+// consumes this to print WHICH wrapper each dispatched backend runs. `null` when the pair is unknown.
+export const wrapperCmdFor = (backendName, role) =>
+  KNOWN_BACKENDS.find((b) => b.name === backendName)?.roleCmds?.[role] ?? null;
+
 // ── pure helpers ─────────────────────────────────────────────────────────────
 
 // Expand a leading "~" / "~/x" against home; absolute and relative paths pass through untouched.

package/tools/procedures.mjs

@@ -19,8 +19,8 @@
 import { readFileSync, lstatSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { pathToFileURL } from 'node:url';
-import { detectBackends } from './detect-backends.mjs';
-import { ACTIVITIES, resolveActivityRecipe } from './recipes.mjs';
+import { detectBackends, wrapperCmdFor } from './detect-backends.mjs';
+import { ACTIVITIES, resolveActivityRecipe, planRecipe } from './recipes.mjs';
 import { resolveEngineDir, readEngineFragment, PROCEDURES_FRAGMENT_REL } from './engine-source.mjs';
 // The config schema/read core lives in orchestration-config.mjs (the single config contract). procedures
 // is READ-ONLY: it imports the reader + the SHARED slot/recipe validity, never the fs-writer
@@ -126,10 +126,16 @@ export const extractSection = (text, activity) => {
 // ── resolution + rendering ─────────────────────────────────────────────────────────
 
 const resolveAllSlots = ({ activity, config, detection, overrides }) =>
-  Object.keys(ACTIVITIES[activity].slots).map((slot) => ({
-    slot,
-    ...resolveActivityRecipe({ config: config ?? {}, readiness: detection, activity, slot, override: overrides[slot] }),
-  }));
+  Object.keys(ACTIVITIES[activity].slots).map((slot) => {
+    const resolved = resolveActivityRecipe({ config: config ?? {}, readiness: detection, activity, slot, override: overrides[slot] });
+    // The concrete wrapper set this slot's EFFECTIVE recipe dispatches (empty for solo). Reuse
+    // planRecipe's drift-guarded dispatch for WHICH backends, then resolve each (backend, role) to its
+    // manifest wrapper cmd via the bridge registry — no wrapper name is hand-composed here.
+    const backends = planRecipe(resolved.recipe, detection).dispatch
+      .map((d) => wrapperCmdFor(d.backend, d.role))
+      .filter(Boolean);
+    return { slot, ...resolved, backends };
+  });
 
 // An unsatisfiable EXPLICIT override is the only "warning" (loud, flagged for the agent to relay). A
 // graceful config/default degradation is reported as a per-slot reason, not a warning.
@@ -147,6 +153,35 @@ const SOURCE_LABEL = {
   override: 'from --override',
 };
 
+// The explicit wrapper set a review/execute recipe dispatches, printed beside the recipe name so the A2
+// recipe-fidelity obligation ("run every named backend, every round") is mechanical at the point of use.
+// ≥2 backends (Council) → the every-round reminder; exactly 1 → the lone wrapper; Solo dispatches none → ''.
+const backendSetLabel = (backends) =>
+  !backends || backends.length === 0
+    ? ''
+    : backends.length >= 2
+      ? ` → run every backend every round: ${backends.join(' + ')}`
+      : ` → ${backends[0]}`;
+
+// The review-loop economics block (M1 + M6's firing half) — printed when the activity engages a review
+// backend (a slot resolving reviewed | council) and OMITTED for solo. It paraphrases the §9 +
+// orchestration §4 canon (no rival rule): the ≤2-round architecture cap, the bar met by RAISING a
+// surviving major to an acceptance invariant (not exhausting prose), backend divergence = the crossover
+// stop, the thin-plan/diff-review carve-out, a self-consistency read before every re-review, and the
+// REQUIRED per-round structured emission {round N · finding-origin tally · per-backend verdict}. Only a
+// review slot can resolve reviewed|council (execute floors at solo|delegated), so gate on the recipe.
+const REVIEW_RECIPES = new Set(['reviewed', 'council']);
+const reviewLoopAdvice = (slots) =>
+  slots.some((s) => REVIEW_RECIPES.has(s.recipe))
+    ? [
+        'Review-loop economics (planning.md §9 · orchestration.md §4) — the review this recipe runs:',
+        '  • Cap architecture plan-review at ≤2 rounds; the bar is met by RAISING a surviving major to an acceptance invariant (or handing it to Execute/diff-review), never by exhausting the strictest backend.',
+        '  • Backend divergence (one backend grounded-ships while another keeps revising mechanics) IS the crossover stop.',
+        '  • Route an all-mechanics/CI or prose-only artifact to a thin plan + diff-review; run a self-consistency read before every re-review.',
+        '  • Each round MUST emit {round N · finding-origin tally (first-draft / fold-induced / mechanics) · per-backend verdict} so the crossover is a computed signal.',
+      ]
+    : [];
+
 const formatHuman = ({ activity, section, slots, warnings }) => {
   const lines = [
     section,
@@ -155,9 +190,11 @@ const formatHuman = ({ activity, section, slots, warnings }) => {
   ];
   for (const s of slots) {
     const arrow = s.degradedFrom ? ` (requested ${s.degradedFrom} → degraded)` : '';
-    lines.push(`  ${s.slot}: ${s.recipe} — ${SOURCE_LABEL[s.source]}${arrow}`);
+    lines.push(`  ${s.slot}: ${s.recipe} — ${SOURCE_LABEL[s.source]}${arrow}${backendSetLabel(s.backends)}`);
     if (s.reason) lines.push(`      ↳ ${s.reason}`);
   }
+  const advice = reviewLoopAdvice(slots);
+  if (advice.length) lines.push('', ...advice);
   if (warnings.length) {
     lines.push('', 'warnings:');
     for (const w of warnings) lines.push(`  ⚠ ${w}`);
@@ -169,8 +206,9 @@ const buildJson = ({ activity, section, slots, configSource, warnings }) => ({
   activity,
   section,
   slots: Object.fromEntries(
-    slots.map((s) => [s.slot, { recipe: s.recipe, source: s.source, degradedFrom: s.degradedFrom, reason: s.reason }]),
+    slots.map((s) => [s.slot, { recipe: s.recipe, source: s.source, degradedFrom: s.degradedFrom, reason: s.reason, backends: s.backends }]),
   ),
+  reviewLoop: reviewLoopAdvice(slots),
   configSource,
   warnings,
 });