@sabaiway/agent-workflow-kit 5.8.0 → 5.10.0

package/tools/ensure-vocabulary.mjs

@@ -8,12 +8,12 @@
 // read-only tool's import graph. Vocabulary here, behaviour in ensure-ops.mjs.
 
 // The FIXED order the CLI runs them in — the order references/modes/upgrade.md already prescribed.
-export const ENSURE_OPS = Object.freeze(['orchestration', 'gates', 'autonomy', 'scripts']);
+export const ENSURE_OPS = Object.freeze(['orchestration', 'gates', 'autonomy', 'scripts', 'index']);
 
 // Tokens that assert a WRITE happened. --dry-run may never emit one of these (the CLI's contract test
 // walks this set), and each has exactly one `would-` counterpart below.
-export const WRITE_TOKENS = Object.freeze(['seeded', 'note-refreshed']);
-export const DRY_RUN_TOKENS = Object.freeze(['would-seed', 'would-refresh-note']);
+export const WRITE_TOKENS = Object.freeze(['seeded', 'note-refreshed', 'regenerated']);
+export const DRY_RUN_TOKENS = Object.freeze(['would-seed', 'would-refresh-note', 'would-regenerate']);
 
 // The CLOSED outcome vocabulary. Closed at RUNTIME, not by convention: composing an outcome with a
 // token outside this list throws, so an op cannot quietly invent a word the mode doc has never heard
@@ -43,8 +43,21 @@ export const FAILURE_CAUSES = Object.freeze([
   'wrong-node-kind',
   'write-refused',
   'unexpected-error',
+  // The navigator ensure drives a SEPARATE PROCESS (the bundled generator), so its failures split by
+  // how far that process got: it never launched · it launched and did not succeed · the freshness
+  // probe itself could not answer · it claimed a regeneration the re-probe still finds stale. Only
+  // the first and third are provably pre-mutation; the other two DISCLOSE a possible partial write.
+  'generator-unlaunchable',
+  'generator-failed',
+  'index-probe-failed',
+  'index-stale-after-write',
 ]);
 
+// The causes the mode doc must TEACH, so an agent relaying a `failed` line knows every word that can
+// open one. Bound into references/modes/upgrade.md by doc-parity — the executable half of "a failed
+// line names its cause": a cause the tool can print but the doc never named fails the lint.
+export const RELAYED_FAILURE_CAUSES = FAILURE_CAUSES;
+
 // The subset references/modes/upgrade.md enumerates, so the agent relaying an upgrade knows every
 // outcome by name. doc-parity binds each of these into that doc: a reworded doc that drops one fails
 // the check instead of silently teaching an outcome set the tool no longer has. The dry-run pair is
@@ -52,6 +65,7 @@ export const FAILURE_CAUSES = Object.freeze([
 export const RELAYED_ENSURE_TOKENS = Object.freeze([
   'seeded',
   'note-refreshed',
+  'regenerated',
   'already-current',
   'customized-preserved',
   'malformed-preserved',

package/tools/known-footprint.mjs

@@ -36,6 +36,9 @@ export const stop = (message, fields = {}) =>
 // never a silent un-track. `/docs/plans/` + both `.claude/settings*.json` are listed because a pure
 // hidden deploy has no tracked `.gitignore`; the classifier drops any candidate a tracked `.gitignore`
 // already covers, so in a repo that DOES track those ignores they are never re-written.
+// The enumeration must cover EVERY file the deploy copies into `scripts/` (bootstrap step 8 copies
+// `references/scripts/*.mjs` + `*.test.mjs` wholesale): a name missing here is a file a hidden
+// deployment leaves visible in `git status` — the exact leak this registry exists to prevent.
 export const KIT_OWN_PATHS = [
   '/AGENTS.md',
   '/CLAUDE.md',
@@ -49,11 +52,18 @@ export const KIT_OWN_PATHS = [
   '/scripts/archive-issues.mjs',
   '/scripts/archive-issues.test.mjs',
   '/scripts/archiver-structure.test.mjs',
+  '/scripts/check-docs-size-cli.test.mjs',
+  '/scripts/check-docs-size-ensure.test.mjs',
   '/scripts/check-docs-size.mjs',
   '/scripts/check-docs-size.test.mjs',
+  '/scripts/install-git-hooks-repo-exec.test.mjs',
   '/scripts/install-git-hooks.mjs',
+  '/scripts/install-git-hooks.test.mjs',
   '/scripts/markdown-blocks.mjs',
   '/scripts/markdown-blocks.test.mjs',
+  '/scripts/migrate-gates-branches.test.mjs',
+  '/scripts/migrate-gates.mjs',
+  '/scripts/migrate-gates.test.mjs',
   '/docs/plans/',
   '/.claude/settings.local.json',
   '/.claude/settings.json',

package/tools/lens-region.mjs

@@ -49,7 +49,19 @@ Apply this as part of §2 before any user-facing summary:
 - **Large artifact (≈>100 lines):** deliver a real summary or the key excerpt inline **and** link the file — never flood the reader with a 2000-line paste, never hide the answer behind a bare pointer.`;
 const COMMS_PRIOR_AD054 = `${COMMS_PRIOR_PRE_AD054}
 - **Live host/session facts are tool-composed only.** Any claim about the current host or session state (prompts fired, sandbox scope, whether a bypass was needed, network reachability, approval counts) must trace to **live tool output** from **this session**; a memory/handover snapshot is **context, never report facts**, and a claim with no live signal is **omitted or explicitly marked unverified** — never asserted from recollection.`;
-export const COMMS_PRIORS = [COMMS_PRIOR_PRE_AD054, COMMS_PRIOR_AD054];
+// The canon that shipped between the plain-language bullet and the closing-state-block contract.
+// Written out in full rather than composed from the constant above: the plain-language bullet LEADS
+// the block, so an append-based composition would produce a body that never shipped and would then
+// match no deployed file at all.
+const COMMS_PRIOR_PLAIN_LANGUAGE = `### 2.x. Communication (user-facing messages)
+Apply this as part of §2 before any user-facing summary:
+- **Plain language.** User-facing narration is short, clear, plain words of the dialogue language; when the dialogue language is not English, transliterated English jargon is banned — an English term survives only as the NAME of a thing (a flag / command / file / test), glossed in plain words when helpful; plain English stays plain for English-dialogue users.
+- **Deliver the artifact IN the message** — paste the prompt / diff / version / command inline; never "see §X / open the file / run it and you'll see" as a *substitute* for showing what was asked.
+- **Lead with the result**, then the details; show exactly what was asked — no deflection, no "almost done" when the ask was the finished thing.
+- **No condescension, no filler.** Own a miss plainly and fix it in the same message.
+- **Large artifact (≈>100 lines):** deliver a real summary or the key excerpt inline **and** link the file — never flood the reader with a 2000-line paste, never hide the answer behind a bare pointer.
+- **Live host/session facts are tool-composed only.** Any claim about the current host or session state (prompts fired, sandbox scope, whether a bypass was needed, network reachability, approval counts) must trace to **live tool output** from **this session**; a memory/handover snapshot is **context, never report facts**, and a claim with no live signal is **omitted or explicitly marked unverified** — never asserted from recollection.`;
+export const COMMS_PRIORS = [COMMS_PRIOR_PRE_AD054, COMMS_PRIOR_AD054, COMMS_PRIOR_PLAIN_LANGUAGE];
 
 const stripCr = (line) => (line.endsWith('\r') ? line.slice(0, -1) : line);
 const isBoundary = (bareLine) => bareLine === '---' || /^#{2,3} /.test(bareLine);

package/tools/source-size-scope.mjs

@@ -31,6 +31,8 @@ const GITLINK_MODE = '160000';
 // Raw bytes in, raw bytes out: `ls-files -s -z` emits mode, object and stage, then a TAB, then the
 // path, then a NUL — and the path half is never decoded before it has been matched, so a name
 // carrying a tab or a newline survives intact (splitting on lines would mangle it).
+// The object id is carried through rather than dropped: the record already holds it, and a consumer
+// that must read what the index HOLDS (not what the worktree happens to show) needs exactly that.
 const parseIndexEntries = (buf) => {
   const entries = [];
   let start = 0;
@@ -41,7 +43,7 @@ const parseIndexEntries = (buf) => {
     const tab = record.indexOf(TAB);
     if (tab !== -1) {
       const head = record.subarray(0, tab).toString('utf8').split(' ');
-      entries.push({ mode: head[0], stage: Number(head[2]), path: record.subarray(tab + 1) });
+      entries.push({ mode: head[0], sha: head[1], stage: Number(head[2]), path: record.subarray(tab + 1) });
     }
     start = end + 1;
   }

package/tools/upgrade-runlist.mjs

@@ -38,6 +38,7 @@ export const UPGRADE_RUNLIST = Object.freeze([
     [
       'seeded',
       'note-refreshed',
+      'regenerated',
       'already-current',
       'customized-preserved',
       'malformed-preserved',