@sabaiway/agent-workflow-engine 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -4,6 +4,40 @@ 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.9.0 — Honest installer messaging: the verb states what was observed, the note states facts
+
+A **feature** release (installer output contract only; the canon text is unchanged). `bin/install.mjs`
+no longer claims "updated the canon to vX" on every run and no longer accuses the npx cache on a
+same-version re-run:
+
+- **The final verb is keyed on the OBSERVED version comparison**, never on mere presence: fresh or
+  legacy/unstamped → `installed` (no transition claim when the prior version is unknowable); older →
+  `updated the canon to vX`; same → `refreshed the already-current canon`; newer → `downgraded the
+  canon to vX` (reachable only under the explicit `--allow-downgrade`).
+- **The same-version note states observable facts only** — the copy still ran (a re-run repairs
+  locally modified or deleted files) — plus a CONDITIONAL hint: *if you expected a newer version*,
+  invoke the `@latest` tag explicitly. The "npx likely served a cached build" accusation is gone
+  (not observable without a network check).
+- The never-downgrade gate, its refusal wording, and the read-before-write ordering are untouched.
+
+## 1.8.0 — Mechanize the §9 review-loop discipline (round cap · crossover · finding-origin)
+
+A **feature** release. The methodology canon institutionalizes the review-loop economics so the round
+cap, the crossover stop, and the finding-origin discipline stop being deletable prose:
+
+- **`planning.md` §9** gains a *Fold minimally — a prose plan has no checker* bullet (a self-consistency
+  read; fold minimally in ONE place), and the *Heavy review at the diff* bullet now names
+  **backend divergence** as the crossover and routes an all-mechanics/CI or prose-only artifact to a
+  **thin plan + diff-review**.
+- **`orchestration.md` §4/§5** adds the **backend-divergence stop-signal**, reconciled with recipe
+  fidelity: divergence bounds the *rounds*, never drops a ready backend within one.
+- **`procedures.md`** requires a per-round emission **{round N · finding-origin tally · per-backend
+  verdict}** at the loop point of *both* activities.
+
+Guarded non-vacuously: `planning-`/`procedures-`/`orchestration-canon` gain region-scoped tokens; the
+kit's `lens-mirror` registers the five review-loop tokens (Set-1) + the M6 `finding-origin` token (Set-2).
+Deployment-lineage head stays `1.3.0` (no `docs/ai` migration).
+
 ## 1.7.0 — Harden the planning canon: process-fidelity + regression-free editing
 
 A **feature** release. The methodology canon gains **seven invariants** that close recurring

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.7.0'
+  version: '1.9.0'
 ---
 
 # agent-workflow-engine

package/bin/install.mjs

@@ -241,15 +241,25 @@ const main = async () => {
   await Promise.all(
     PAYLOAD.map((entry) => copyRecursive(resolve(PKG_ROOT, entry), resolve(target, entry), target)),
   );
-  console.log(
-    `[agent-workflow-engine] ${wasPresent ? 'updated the canon to' : 'installed'} v${version} -> ${tildify(target)}`,
-  );
+  // Verb keyed on the OBSERVED version relation (cmp), never on mere presence: null (fresh install,
+  // or a legacy/unstamped one whose prior version is unknowable) → "installed"; -1 → a real update;
+  // 0 → already current (the copy still ran — see the note below); 1 is reachable only under
+  // --allow-downgrade (the gate above refused otherwise) and says so plainly.
+  const verb =
+    cmp === 0 ? 'refreshed the already-current canon'
+    : cmp === 1 ? 'downgraded the canon to'
+    : cmp === -1 ? 'updated the canon to'
+    : 'installed';
+  console.log(`[agent-workflow-engine] ${verb} v${version} -> ${tildify(target)}`);
 
-  // No-op re-run (same version) → almost always npx served a cached build; say so + point at @latest.
+  // Same-version re-run: state observable facts only. The copy DID run (repair-on-rerun is a feature —
+  // it restores locally modified/deleted files), and whether npx served a cached build is NOT
+  // observable here (no network), so the note never claims it; the @latest hint is conditional.
   if (cmp === 0) {
     console.log(
-      `[agent-workflow-engine] note: no version change — the canon was already v${version}. If you ` +
-        `expected an update, npx likely served a cached build; re-run bypassing the cache:\n` +
+      `[agent-workflow-engine] note: the canon was already v${version} — the copy still ran, restoring ` +
+        `any locally modified or deleted canon file to this version's packaged contents. If you ` +
+        `expected a NEWER version, invoke the @latest tag explicitly:\n` +
         `    npx @sabaiway/agent-workflow-engine@latest init`,
     );
   }

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-engine",
-  "version": "1.7.0",
+  "version": "1.9.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

@@ -79,6 +79,15 @@ that names ≥2 backends. Folding a finding and re-reviewing (the convergence ba
 §9) re-runs **every named backend each round** — convergence is reached only when one round comes back
 clean from all of them.
 
+**Backend divergence is the crossover stop — it bounds the ROUNDS, never the backends.** Running every
+named backend every round CONVERGES when one round returns **0 blockers + 0 majors** from all of them.
+But when the backends **diverge** — one grounded-**ships** while another keeps line-by-line **revising**
+mechanics round after round — that **backend divergence** IS the crossover the loop must stop at: resolve
+at **altitude** (raise the surviving major to an explicit acceptance invariant Execute must meet, or hand
+the mechanics to the diff), NOT by exhausting the strictest line-by-line backend. This is the exact
+converse of the fidelity rule above: divergence bounds how many ROUNDS the loop runs, and never licenses
+dropping a ready backend within a round — both still run every round.
+
 ## 5. Quota & health guard (advisory)
 
 Backends are **subscription** services with **finite** quota. The orchestrator should: prefer the
@@ -88,7 +97,9 @@ cheapest model that fits the task; not reach for a top-tier model by reflex; and
 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.
+already accepted: run both, every round, until a round comes back clean — or until **backend divergence**
+marks the crossover (§4), resolved at altitude rather than by exhausting the strictest backend. Spending
+quota to line-by-line re-review mechanics past that crossover is the over-run the divergence stop prevents.
 
 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;

package/references/planning.md

@@ -123,7 +123,9 @@ These disciplines keep a plan converging instead of churning, and keep a fold or
 
 **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.
+**Fold minimally — a prose plan has no checker.** An ephemeral, gitignored plan is PROSE with no executable checker, so a single fold that silently drifts one of several prose spots seeds the next churn round (this is what turns a 2-round review into a 6-round one). Fold **minimally, in ONE place**, run a **self-consistency** read across the whole plan before every re-review, and keep the plan SHORT. The only runtime firing an ephemeral plan can carry is the point-of-use advisor's printed review-loop checkpoint — there is no other checker.
+
+**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. **Backend divergence** — one backend grounded-ships while another keeps revising line-by-line mechanics — IS that crossover: resolve at altitude (raise the surviving major to an acceptance invariant, or hand the mechanics to Execute), do not exhaust the strictest backend. Route an all-mechanics/CI or prose-only artifact to a **thin plan + diff-review**, where the runner and gates settle it, not another prose round. 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".
 

package/references/procedures.md

@@ -60,7 +60,14 @@ Produce a self-contained, cold-readable plan, reviewed to the configured depth b
    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.
+   [`orchestration.md`](orchestration.md) §4) — never quietly drop a ready backend. Cap architecture
+   plan-review at **≤2 rounds**, stopping at the **crossover** where **backend divergence** (one backend
+   grounded-ships while another keeps revising mechanics) IS the stop — the bar is still met by RESOLVING
+   the surviving major at altitude (raise it to an acceptance invariant, or hand it to Execute), never by
+   exhausting the strictest backend. Run a **self-consistency** read before every re-review and route an
+   all-mechanics/CI or prose-only artifact to a **thin plan + diff-review** ([`planning.md`](planning.md)
+   §9). Each round MUST emit **{round N · finding-origin tally (first-draft / fold-induced / mechanics) ·
+   per-backend verdict}** so the crossover is a computed signal, not a remembered rule.
 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
@@ -95,7 +102,9 @@ Execute an approved plan Step by Step; each Step is one logical commit.
    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.
+   loop to **0 blockers + 0 majors** from every backend before the gate. Each round MUST emit
+   **{round N · finding-origin tally · per-backend verdict}**; when backends diverge, that is the
+   crossover — resolve at altitude, not by exhausting the strictest backend.
 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.