@sabaiway/agent-workflow-engine 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ 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.5.0 — Right-altitude & code-grounded folds in the canon
+
+A **feature** release. The planning canon (`references/planning.md`, read **live** by the composition
+root) gains a `## 9. Right-altitude & code-grounded folds` section + a §8 self-review bullet; the
+activity-procedures canon (`references/procedures.md`) weaves a terse §9 review-lens pointer into the
+rendered Self-review steps of **both** activities (binding to §9, not restating it). Two guards pin the
+disciplines: a new `test/planning-canon.test.mjs` and an extended `test/procedures-canon.test.mjs`. The
+deployment-lineage head stays **`1.3.0`** (no `docs/ai` structural change); the npm package version is a
+separate axis.
+
+- **Right altitude.** A plan pins intent + architecture + invariants + acceptance criteria; fine
+  code-mechanics are resolved at Execute, not spelled out in prose.
+- **Fold by code, not prose.** Before folding a code-touching finding, read the cited `file:line` and cite it.
+- **Convergence heuristic.** A stable architecture + recurring code-mechanism findings ⇒ raise the
+  altitude or hand the mechanics to Execute.
+- The procedures lens stays a terse pointer (the terseness invariant holds: `procedures.md` < `planning.md`).
+
 ## 1.4.0 — Durable session contracts in the canon: read-at-start, Definition of Done, communication
 
 A **feature** release. The activity-procedures canon (`references/procedures.md`, read **live** by the

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

package/capability.json

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

package/package.json

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

@@ -103,3 +103,14 @@ The volume trigger above (files / LoC / tokens) is necessary but not sufficient.
 - Vocabulary is strict (§1); the Plan ends with **Phase N: Cleanup** (§4).
 - If part of a series: `queue.md` is initialised / updated (§3).
 - No `git add <plan>` and no "commit the plan" wording in the final report.
+- Every code-touching decision cites the `file:line` it is grounded in; the plan stays at intent / invariant / acceptance altitude, leaving fine code-mechanics to Execute (§9).
+
+## 9. Right-altitude & code-grounded folds
+
+Two disciplines keep a plan converging instead of churning. They govern authoring, every review round, and execution.
+
+**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.
+
+**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.
+
+**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

@@ -48,6 +48,8 @@ Produce a self-contained, cold-readable plan, reviewed to the configured depth b
    with exact paths and commands per Step. Bind to that structure; do not restate it here.
 3. **Self-review** — run the [`planning.md`](planning.md) §8 checklist (exact paths/commands, strict
    vocabulary, every out-of-plan recommendation folded into a Step, `queue.md` updated for a series).
+   Apply the [`planning.md`](planning.md) §9 lens — fold by code (read and cite the `file:line`), and
+   hold the right altitude.
 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.
@@ -74,7 +76,9 @@ Execute an approved plan Step by Step; each Step is one logical commit.
    directly.
 3. **Implement / integrate** — apply the change (your own edits, or the reviewed delegated diff),
    following the project's reuse + clean-code rules.
-4. **Self-review** — run the [`planning.md`](planning.md) §8 self-review on the change.
+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.
 5. **review {recipe}** — review the result at the resolved `review` depth (Solo / Reviewed / Council),
    exactly as in plan-authoring.
 6. **Gates** — run the project's verification gate (tests + checks) to green before committing.