@sabaiway/agent-workflow-kit 5.11.1 → 6.0.0

package/tools/flow-vocabulary.mjs

@@ -0,0 +1,96 @@
+// flow-vocabulary.mjs — the CLOSED flow-record vocabulary (kinds, purposes, terminal lanes, the
+// design seed assignment, the allowed-transition table) plus the five shared form bindings every
+// validator states its refusals in: HEX64_RE, isPlainObject, isNonEmptyString, isHex64 and refuse.
+// Split out of flow-record.mjs unchanged (baseline-practices tranche 3), which now re-exports the
+// ten public names here; the five shared bindings stay OFF that surface (plan D3) — the leaves that
+// need them import this module, so the record family's named grammars have exactly one home and no
+// copy can drift.
+//
+// The LOWEST leaf of the family and pure form: no filesystem, no git, no CLI, no side effects on
+// import, and orchestration-config.mjs (the schema version) is its only tools sibling. Imports run
+// ONE way — the shape, identity, legality and manifest leaves compose this module; nothing here
+// reaches back up to the facade.
+
+import { FLOW_SCHEMA_VERSION } from './orchestration-config.mjs';
+
+export { FLOW_SCHEMA_VERSION };
+
+const deepFreeze = (value) => {
+  if (value !== null && typeof value === 'object') {
+    Object.values(value).forEach(deepFreeze);
+    Object.freeze(value);
+  }
+  return value;
+};
+
+// ── the closed vocabulary ─────────────────────────────────────────────────────────────────────────
+
+export const CHAIN_KIND = 'chain';
+export const CHAIN_PURPOSES = deepFreeze(['adoption', 'round', 'refresh', 're-baseline', 'freeze', 'unfreeze', 'park', 'resume', 'converged', 'complete']);
+export const STEP_SCOPED_PURPOSES = deepFreeze(['round', 'refresh', 're-baseline', 'freeze', 'unfreeze', 'converged']);
+export const PLAN_LANE_PURPOSES = deepFreeze(['adoption', 'park', 'resume', 'complete']);
+export const GLOBAL_KINDS = deepFreeze(['internal-attestation', 'down-mark', 'down-mark-up', 'down-mark-clear', 'degrade-justification', 'rerun-cause', 'bookkeeping-delta', 'maintainer-override', 'consult-attestation', 'subset-attempt']);
+export const FLOW_KINDS = deepFreeze([CHAIN_KIND, ...GLOBAL_KINDS]);
+
+// Reserved lane-typed terminals (#16): converged terminates a CYCLE (its step's sequence), complete
+// terminates the PLAN. Park is a resumable suspension, never a terminal (#59).
+export const TERMINAL_LANES = deepFreeze({ converged: 'cycle', complete: 'plan' });
+
+// Design §5 seed member → family assignment; the drift-guard test binds this map to the verbatim
+// seed list on one side and to the shipped CHAIN_PURPOSES/GLOBAL_KINDS on the other.
+export const DESIGN_SEED_ASSIGNMENT = deepFreeze({
+  adoption: { family: 'chain', purpose: 'adoption' },
+  'round-chain': { family: 'chain', purpose: 'round' },
+  refresh: { family: 'chain', purpose: 'refresh' },
+  're-baseline': { family: 'chain', purpose: 're-baseline' },
+  unfreeze: { family: 'chain', purpose: 'unfreeze' },
+  freeze: { family: 'chain', purpose: 'freeze' },
+  converged: { family: 'chain', purpose: 'converged' },
+  park: { family: 'chain', purpose: 'park' },
+  resume: { family: 'chain', purpose: 'resume' },
+  complete: { family: 'chain', purpose: 'complete' },
+  'internal-attestation': { family: 'global', kind: 'internal-attestation' },
+  'down-mark': { family: 'global', kind: 'down-mark' },
+  'down-mark up': { family: 'global', kind: 'down-mark-up' },
+  'down-mark clear': { family: 'global', kind: 'down-mark-clear' },
+  'degrade-justification': { family: 'global', kind: 'degrade-justification' },
+  'rerun-cause': { family: 'global', kind: 'rerun-cause' },
+  'bookkeeping-delta': { family: 'global', kind: 'bookkeeping-delta' },
+  'maintainer-override': { family: 'global', kind: 'maintainer-override' },
+  'consult-attestation': { family: 'global', kind: 'consult-attestation' },
+});
+
+// The allowed-transition table — an exported frozen structure, never prose. Within a step:
+// converged ends the sequence (only the unfreeze lane reopens it, and only in its own cycle);
+// freeze admits only unfreeze/converged. Plan lane: park admits only resume (and both preserve the
+// pre-park cycle/round); complete admits nothing; adoption is only ever the chain's first record.
+// The boundary lane (between steps): the opener round, the unfreeze reopen, and a re-baseline for
+// disjoint base motion that reopens nothing. The cross-step edge (the opener's prior-terminal
+// reference) is enforced by validateChainSequence, distinct from the within-step successor rule.
+export const ALLOWED_TRANSITIONS = deepFreeze({
+  stepOpening: 'round',
+  withinStep: {
+    round: ['round', 'refresh', 're-baseline', 'freeze', 'converged'],
+    refresh: ['round', 'refresh', 're-baseline', 'freeze', 'converged'],
+    're-baseline': ['round', 'refresh', 're-baseline', 'freeze', 'converged'],
+    freeze: ['unfreeze', 'converged'],
+    unfreeze: ['round', 'refresh', 're-baseline', 'freeze', 'converged'],
+    converged: ['unfreeze'],
+  },
+  planLane: {
+    adoption: ['round', 'park', 'complete'],
+    park: ['resume'],
+    resume: ['round', 'park', 'complete'],
+    complete: [],
+  },
+  boundary: ['round', 'unfreeze', 're-baseline'],
+});
+
+// ── the shared form bindings (D3) — the record family's named grammars, off the public surface ────
+
+export const HEX64_RE = /^[0-9a-f]{64}$/;
+export const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+export const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
+export const isHex64 = (v) => typeof v === 'string' && HEX64_RE.test(v);
+
+export const refuse = (reason) => ({ ok: false, reason });

package/tools/grounding.mjs

@@ -6,11 +6,9 @@
 //
 //   --constraints        slice the root AGENTS.md `## 🚫 Hard Constraints` section, verbatim
 //                        (exactly-one-match — 0 or >1 headings is a loud STOP, never a guess);
-//   --plan <path>        extract the plan's decision-bearing canonical sections, verbatim + whole:
-//                        `## Approach` (REQUIRED — its "What we are NOT doing" text rides inside;
-//                        it is not a heading in canon) and `## Verification` (REQUIRED — STOP if
-//                        missing), plus `## Decisions (locked)` (optional-if-absent, the engine §7
-//                        heading this release adds); a DUPLICATE heading is always a STOP.
+//   --plan <path>        extract the plan's three canon sections, verbatim + whole — `## Goal and
+//                        boundary`, `## Module ledger`, `## Verification` (the engine planning.md
+//                        literal headings; each REQUIRED — a missing or DUPLICATE heading is a STOP).
 //   --extra <text|@file> append orchestrator-supplied facts verbatim AFTER the mechanical halves
 //                        (repeatable; @file reads are confined to the work tree + the system temp
 //                        surface — the merge happens INSIDE the tool, corpus #88/#95).
@@ -46,18 +44,14 @@ export const DEFAULT_MAX_PROMPT_BYTES = 120000;
 export const ARGV_HARD_MAX = 131000;
 
 export const CONSTRAINTS_HEADING = /^## .*Hard Constraints$/;
-export const PLAN_SECTIONS = [
-  { heading: '## Approach', optional: false },
-  { heading: '## Verification', optional: false },
-  { heading: '## Decisions (locked)', optional: true },
-];
+export const PLAN_SECTIONS = ['## Goal and boundary', '## Module ledger', '## Verification'];
 
 // ── pure section slicing (exactly-one-match; the inject-methodology discipline) ────────
 
 // Slice ONE `## `-level section (its heading line through the line before the next `## ` heading),
 // verbatim. `heading` is a string (trimmed-line equality) or a RegExp over the trimmed line.
-// 0 matches → null when optional, else STOP; >1 matches → always STOP (never guess which).
-export const sliceSection = (text, heading, { optional = false, label = 'document' } = {}) => {
+// 0 matches → STOP; >1 matches → STOP (never guess which).
+export const sliceSection = (text, heading, { label = 'document' } = {}) => {
   const lines = text.split('\n');
   const matchesAt = [];
   for (let i = 0; i < lines.length; i += 1) {
@@ -66,7 +60,6 @@ export const sliceSection = (text, heading, { optional = false, label = 'documen
   }
   const shown = typeof heading === 'string' ? heading : String(heading);
   if (matchesAt.length === 0) {
-    if (optional) return null;
     throw fail(1, `${label}: required section "${shown}" not found — STOP (nothing sliced)`);
   }
   if (matchesAt.length > 1) {
@@ -95,10 +88,7 @@ export const assembleGrounding = ({ constraintsText = null, autonomyText = null,
   // how autonomous this session is → what this plan decides).
   if (autonomyText != null) parts.push(autonomyText);
   if (planText != null) {
-    for (const { heading, optional } of PLAN_SECTIONS) {
-      const section = sliceSection(planText, heading, { optional, label: planLabel });
-      if (section != null) parts.push(section);
-    }
+    for (const heading of PLAN_SECTIONS) parts.push(sliceSection(planText, heading, { label: planLabel }));
   }
   // Orchestrator extras ride LAST, verbatim in argv order — live judgment facts read after the
   // mechanical slices, and the merge happens INSIDE the tool (corpus #88/#95: a shell append onto
@@ -268,9 +258,9 @@ Usage:
                        stated source line; absent file → the computed defaults ARE the policy
                        (exit 0); malformed/unreadable → fail-closed STOP (exit 1); informational —
                        enforcement stays the sandbox + the orchestrator
-  --plan <path>        extract the plan's decision-bearing sections verbatim + whole:
-                       "## Approach" + "## Verification" (REQUIRED — STOP if missing),
-                       "## Decisions (locked)" when present; a duplicate heading is a STOP
+  --plan <path>        extract the plan's three canon sections verbatim + whole: "## Goal and
+                       boundary", "## Module ledger", "## Verification" (each REQUIRED — a
+                       missing or duplicate heading is a STOP)
   --extra <text|@file> append orchestrator-supplied extra facts byte-verbatim AFTER the
                        mechanical sections (repeatable, argv order; the agy-review --facts
                        convention: literal text, or @path read whole through a race-free

package/tools/inject-methodology.mjs

@@ -84,6 +84,8 @@ export const AUTONOMY_EMPTY_SLOT = `${AUTONOMY_START_MARKER}\n${AUTONOMY_END_MAR
 export const KNOWN_PRIOR_METHODOLOGY_SLOT = [
   // v1.3.0 — pre-communication-contract methodology pointer (procedures route, no §1.9 clause).
   '> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`. Full vocabulary, lifecycle, and the plan-then-execute split live in the project\'s **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5. Named activities (plan-authoring, plan-execution) have procedures — see `/agent-workflow-kit procedures <activity>` for the steps + resolved recipe.',
+  // engine 2.1.0 — the pre-canon-rewrite pointer (vocabulary + plan-then-execute wording, with the communication contract).
+  '> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`. Full vocabulary, lifecycle, and the plan-then-execute split live in the project\'s **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5. Named activities (plan-authoring, plan-execution) have procedures — see `/agent-workflow-kit procedures <activity>` for the steps + resolved recipe. **Communication:** user-facing messages deliver the artifact inline (paste the prompt / diff / command — never "see §X" as a substitute), lead with the result, show exactly what was asked, and never read as mockery (a large artifact: a real summary inline + a link).',
 ];
 export const KNOWN_PRIOR_ORCH_SLOT = [
   // v1.3.0 — pre-read-at-start orchestration pointer (recipes vocabulary, no orchestration.json clause).

package/tools/procedures.mjs

@@ -208,8 +208,8 @@ const backendSetLabel = (backends) =>
       : ` → ${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
+// backend (a slot resolving reviewed | council) and OMITTED for solo. It paraphrases the procedures.md
+// Fold + loop step + 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
@@ -221,7 +221,7 @@ const REVIEW_RECIPES = new Set(['reviewed', 'council']);
 const reviewLoopAdvice = (slots, activity) =>
   slots.some((s) => REVIEW_RECIPES.has(s.recipe))
     ? [
-        'Review-loop economics (planning.md §9 · orchestration.md §4) — the review this recipe runs:',
+        'Review-loop economics (procedures.md Fold + loop · 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.',
@@ -299,7 +299,7 @@ const autonomyAdvice = (activity, facts) => {
 };
 
 // The cost-lane advisory block (cost-tiered execution — orchestration.md §5 canon, paraphrased
-// at the point of use like reviewLoopAdvice paraphrases §9/§4). Rendered UNCONDITIONALLY for
+// at the point of use like reviewLoopAdvice paraphrases procedures.md Fold + loop / orchestration §4). Rendered UNCONDITIONALLY for
 // every activity — the lanes route EVERY step, review-backed or not (unlike reviewLoopAdvice,
 // which fires only when a review backend engages). It may name the kit's own GENERIC L0
 // surfaces (the gate runner, the rotation checks, the cheap-agents vehicles) — point-of-use
@@ -368,9 +368,9 @@ const flowHalvesAdvice = (flow, probe) => {
 };
 
 // ── the declared source-size practice (D-17 U1) ────────────────────────────────────
-// A practice the agent meets only when a gate refuses is a practice learned too late: the caps, their
-// reason and the plan-time rung ride EVERY named-activity render, so the layout is cut to them while
-// the plan is being written. Composed from the project's live declaration, never from constants here.
+// A practice the agent meets only when a gate refuses is a practice learned too late: the caps and
+// their reason ride EVERY named-activity render, so the plan's Module ledger is cut to them while the
+// plan is being written. Composed from the project's live declaration, never from constants here.
 // Each config state speaks as itself: ABSENT renders NOTHING (a project that declares no practice must
 // not be handed invented limits); AUTHORED and INCOMPLETE render the declared caps plus the honest
 // "nothing is recorded yet" line — both are pre-mint states, and treating INCOMPLETE as MINTED would
@@ -406,7 +406,6 @@ const declaredPracticeAdvice = (cwd, readFile, lstat) => {
       ? `  recorded: ${facts.recordedFiles} file(s) carry a recorded size (debt, not permission) · aggregate ${facts.aggregateLines} line(s), EXACT — growth takes a reasoned bump, never free headroom.`
       : unmintedRecord,
     `  why: ${SOURCE_SIZE_WHY}`,
-    '  at plan time: every Step that CREATES a file names the file and its single responsibility, and the planned layout fits these caps — the gate is the backstop, never the teacher.',
   ];
 };