@sabaiway/agent-workflow-kit 5.5.0 → 5.7.0

package/tools/tracked-tree-census.mjs

@@ -0,0 +1,102 @@
+// tracked-tree-census.mjs — how much of a project's TRACKED tree the changed-line coverage domain
+// can actually assess, in the closed vocabulary that domain already speaks. A LEAF: it imports the
+// classification and nothing else, and it spawns exactly one read-only `git ls-files`.
+//
+// Why this exists: the coverage checker's domain is `.mjs/.cjs/.js` by design, and on a TS project
+// that domain is a rounding error of the tree. Certifying it and calling the flow optimal is the
+// false green one layer up. The census is the FACT that turns "certified" into "certified over the
+// assessable minority" — it never changes what a run may certify.
+//
+// Read-only: never writes, never commits. Dependency-free, Node >= 22. No side effects on import.
+
+import { spawnSync } from 'node:child_process';
+import { classifyChangedPath } from './changed-surface.mjs';
+
+const GIT_MAX_BUFFER = 256 * 1024 * 1024; // a large tracked tree; never truncate
+
+export const CENSUS_VERDICT = Object.freeze({ NARROW: 'domain-narrow', WITHIN_DOMAIN: 'within-domain' });
+
+// The tracked tree is listed with -z and split on NUL. A newline-split of the plain form would be
+// wrong twice over: git C-QUOTES a path carrying quotes/control/non-ASCII bytes (so the classifier
+// would read `"src/\303\251.ts"`, extension and all, as some other path), and a path containing a
+// real newline would split into two phantom entries. -z emits raw bytes and never quotes.
+//
+// DE-DUPLICATED, because `ls-files` lists per INDEX ENTRY, not per file: during an unresolved merge
+// one conflicted path appears once per stage (probed: three times for a content conflict). Counting
+// those would inflate one population and could flip a tie into the narrow verdict on nothing but a
+// merge in progress.
+//
+// The split and the de-duplication happen on RAW BYTES, before any decoding. A filename is a byte
+// string on this platform and need not be valid UTF-8; decoding first turns every invalid sequence
+// into the same replacement character, so two genuinely different paths would collapse into one and
+// the de-duplication — added to fix an over-count — would become an UNDER-count. Decoding happens
+// once per surviving entry, for the classifier only.
+const NUL = 0;
+const splitOnNul = (buffer) => {
+  const parts = [];
+  let start = 0;
+  for (let at = buffer.indexOf(NUL, start); at !== -1; at = buffer.indexOf(NUL, start)) {
+    if (at > start) parts.push(buffer.subarray(start, at));
+    start = at + 1;
+  }
+  if (start < buffer.length) parts.push(buffer.subarray(start));
+  return parts;
+};
+
+const listTrackedPaths = (root, spawn) => {
+  const result = spawn('git', ['ls-files', '-z'], { cwd: root, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+  if (result.error || result.status !== 0) {
+    const reason = result.error ? (result.error.code ?? result.error.message) : `git exited ${result.status}`;
+    throw Object.assign(new Error(`tracked-tree census unavailable: ${reason}`), { code: 'CENSUS_UNAVAILABLE' });
+  }
+  // A spawn seam may hand back a string (an injected fixture); anything else is the real Buffer.
+  const raw = Buffer.isBuffer(result.stdout) ? result.stdout : Buffer.from(String(result.stdout ?? ''), 'utf8');
+  const seenBytes = new Set();
+  const paths = [];
+  for (const part of splitOnNul(raw)) {
+    const identity = part.toString('latin1'); // byte-exact key: one char per byte, never lossy
+    if (seenBytes.has(identity)) continue;
+    seenBytes.add(identity);
+    paths.push(part.toString('utf8'));
+  }
+  return paths;
+};
+
+// takeCensus(root) → { counts, unsupportedExtensions, verdict, total }.
+//
+// The verdict fires on STRICT DOMINANCE only — the unsupported population must strictly outnumber
+// the assessable one. A tie, or a lone `.d.ts` shim beside a real JS tree, is not a narrow domain
+// and must not raise an item the project cannot act on. `.d.ts` counts as unsupported like any
+// other `.ts` (stated: the classification is by extension, and this leaf adds no exceptions to it).
+// Anything outside both sets — `.py`, `.go`, a README — is `out-of-domain` and counted, never
+// judged: detecting whole out-of-domain-language projects is deliberately not this census's job.
+// An UNAVAILABLE census throws (a non-git tree, a broken git) — the caller's stated-skip lane. It
+// never returns a verdict it could not compute; a silent "within-domain" would be the same false
+// green one layer down.
+export const takeCensus = (root, { spawn = spawnSync } = {}) => {
+  const counts = { assessable: 0, unsupported: 0, 'out-of-domain': 0, 'excluded-test': 0 };
+  const unsupportedExtensions = new Set();
+  for (const path of listTrackedPaths(root, spawn)) {
+    const kind = classifyChangedPath(path);
+    counts[kind] += 1;
+    if (kind === 'unsupported') {
+      const base = path.split('/').pop();
+      unsupportedExtensions.add(base.slice(base.lastIndexOf('.')));
+    }
+  }
+  const verdict = counts.unsupported > counts.assessable ? CENSUS_VERDICT.NARROW : CENSUS_VERDICT.WITHIN_DOMAIN;
+  return {
+    counts,
+    unsupportedExtensions: [...unsupportedExtensions].sort(),
+    verdict,
+    total: Object.values(counts).reduce((sum, n) => sum + n, 0),
+  };
+};
+
+// censusFact(census) → the canonical string an acknowledgment binds. It carries the VERDICT and the
+// sorted set of unsupported extensions present — never the per-file counts. A count-bound fact
+// would re-fire the moment any file is added, turning a durable acknowledgment into a nag; the
+// FACT the maintainer acknowledged ("this tree is dominated by .ts/.tsx, and certification covers
+// the JS minority") is exactly what stays stable while the tree grows, and exactly what changes
+// when a new unsupported language arrives or the verdict flips back.
+export const censusFact = (census) => `${census.verdict}:${census.unsupportedExtensions.join(',')}`;

package/tools/upgrade-runlist.mjs

@@ -0,0 +1,92 @@
+// upgrade-runlist.mjs — the ORDERED registry of the upgrade step-3 operations: the ONE home for
+// their identity (stable id · exact command · consent gate · relayed outcome vocabulary).
+//
+// references/modes/upgrade.md step 3 opens with a checklist rendered from these entries — the
+// structure test (test/upgrade-runlist.test.mjs) binds checklist rows ↔ entries: same backticked
+// ids, same order, each row carrying its registry command and naming its outcomes — and the future
+// reconcile driver reads its item tokens from here (queue row UPGRADE-RECONCILE-DRIVER).
+//
+// A PURE LEAF with zero imports (the ensure-vocabulary.mjs pattern): reading operation identity
+// must never drag an operation's implementation — and through it the writers — into a read-only
+// consumer's import graph. The `configs` outcomes are a literal copy of RELAYED_ENSURE_TOKENS
+// (ensure-vocabulary.mjs stays the owner); the structure test asserts the copy never drifts.
+//
+// `consent` is null for an operation the agent runs outright, else the ONE consent gate the mode
+// doc teaches for it. `outcomes` is the vocabulary the doc names for relaying that operation's
+// result — for `configs` the closed ensure tokens, elsewhere the doc's own outcome words.
+
+const entry = (id, command, consent, outcomes) =>
+  Object.freeze({ id, command, consent, outcomes: Object.freeze(outcomes) });
+
+export const UPGRADE_RUNLIST = Object.freeze([
+  entry(
+    'pointers',
+    'node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs reconcile <project>/AGENTS.md',
+    null,
+    ['added', 'already present', 'skipped', 'STOP'],
+  ),
+  entry(
+    'footprint',
+    'node ${CLAUDE_SKILL_DIR}/tools/hide-footprint.mjs --dir <project> --reconcile --dry-run',
+    'ambiguous → ask the user which it is; hidden → the conditional re-run without --dry-run (surfaced paths ask per bootstrap step 9)',
+    ['visible', 'ambiguous', 'hidden'],
+  ),
+  entry(
+    'configs',
+    'node ${CLAUDE_SKILL_DIR}/tools/ensure-configs.mjs --reconcile --cwd <project>',
+    null,
+    [
+      'seeded',
+      'note-refreshed',
+      'already-current',
+      'customized-preserved',
+      'malformed-preserved',
+      'already-present',
+      'skipped-no-node',
+      'old-adr-layout-migration-instructed',
+      'failed',
+    ],
+  ),
+  entry(
+    'gates-migration',
+    'node ${CLAUDE_SKILL_DIR}/references/scripts/migrate-gates.mjs --kit-tools ${CLAUDE_SKILL_DIR}/tools --cwd <project>',
+    'preview first — apply only on an explicit yes, re-run with --apply',
+    ['preview', 'INERT', 'CUSTOMIZED'],
+  ),
+  entry(
+    'bridges',
+    'node ${CLAUDE_SKILL_DIR}/tools/setup-backends.mjs --refresh-placed',
+    null,
+    [
+      'refreshed',
+      'already current',
+      'skipped',
+      'not placed',
+      'newer than the bundle',
+      'unsupported host',
+      'skipped-readonly',
+      'could not refresh',
+    ],
+  ),
+  entry(
+    'lens',
+    'node ${CLAUDE_SKILL_DIR}/tools/lens-region.mjs reconcile <project>/docs/ai/agent_rules.md',
+    null,
+    [
+      'refreshed',
+      'already current',
+      'custom edit preserved',
+      'file absent',
+      'engine too old',
+      'over the line cap — refused',
+      'section absent — noted',
+      'STOP',
+    ],
+  ),
+  entry(
+    'bridge-settings',
+    'node ${CLAUDE_SKILL_DIR}/tools/bridge-settings.mjs --reconcile',
+    null,
+    ['ok', 'absent', 'flagged', 'duplicates', 'unusable'],
+  ),
+]);

package/tools/velocity-profile.mjs

@@ -168,6 +168,19 @@ export const KIT_WRITER_PREVIEW_TOOLS = Object.freeze([
   'tools/cheap-agents.mjs',
   'tools/gate-hook.mjs',
 ]);
+// The source-size checker: a WRITER tool (--write-baseline, --adopt) whose ONE read-only mode is
+// seeded, and only in that exact byte-form. It joins neither list above on purpose — a wildcard
+// would cover its writers, and its arg-free invocation is a usage error rather than a dry-run, so
+// the writer-preview class does not describe it either.
+//
+// What this rule covers, stated exactly because the near-miss is easy to assume: the AGENT's own
+// direct `node <abs> --check`. It is NOT the byte-string a declared gate carries — gates-init emits
+// the path DOUBLE-QUOTED (a kit path with a space must survive), while a seedable allow rule may
+// carry no quotes at all, so the two spellings cannot be one string. The DECLARED gate's
+// promptlessness is the gate-approval hook's job, byte-exact against gates.json; this rule exists
+// for the invocation an agent types itself, which no declaration covers.
+export const KIT_SOURCE_SIZE_TOOL = 'tools/source-size-check.mjs';
+const SOURCE_SIZE_CHECK_FLAG = '--check';
 const KIT_WILDCARD_TOOLS = Object.freeze(KIT_READONLY_TOOLS.filter((rel) => rel !== KIT_RUN_GATES_TOOL));
 // The kit root this tool runs from (tools/..) — the tier's seed-time path anchor.
 const KIT_ROOT = fileURLToPath(new URL('..', import.meta.url));
@@ -363,8 +376,9 @@ Allowlist mode (default): seeds the fixed read-only Claude Code allowlist into .
 Default is --dry-run. --apply writes; --accept-edits only sets defaultMode when applying.
 --kit-tools additionally seeds the audited kit-tool tier: ${KIT_WILDCARD_TOOLS.length} read-only kit tools by resolved
 absolute path (args wildcard), run-gates.mjs as ONE exact project-root-pinned byte-string
-(project-exec - it runs YOUR declared gates.json), and the writers' exact arg-free dry-run
-preview byte-strings. Never touches settings.local.json.
+(project-exec - it runs YOUR declared gates.json), source-size-check.mjs as ONE exact --check
+byte-string (its read-only mode only - its writers keep prompting), and the writers' exact arg-free
+dry-run preview byte-strings. Never touches settings.local.json.
 --bridge-tier (own consent) seeds the bridge REVIEW wrappers' CODE mode for PLACED bridges
 (codex-review code, agy-review code - never the execution/probe wrappers, never plan/diff modes)
 + the quoted grounding pre-step rule, and the wrapper names into sandbox.excludedCommands (they
@@ -663,7 +677,7 @@ const formatAllowlist = (result) => [
 // The tier's honest posture, printed on every --kit-tools run: run-gates is project-exec (never
 // "read-only"), previews stay dry-run-only, and the tier gets none of the hook's residual ask-net.
 const KIT_TIER_NOTICE =
-  'kit-tools tier: paths are resolved absolute at seed time (fail-safe - a moved skill or stale path simply prompts again); run-gates.mjs is seeded as ONE exact byte-string pinned to this project root and is project-exec - it runs YOUR declared gates.json commands, never "read-only"; writer previews are exact dry-run byte-strings - every --apply/--write/--yes still prompts; tier entries get NO PreToolUse-hook residual coverage EXCEPT repo-search.mjs and path-inventory.mjs, whose invocations the hook scans because they take caller-supplied argument bytes (settings-level posture only for the rest - see the velocity mode notes).';
+  'kit-tools tier: paths are resolved absolute at seed time (fail-safe - a moved skill or stale path simply prompts again); run-gates.mjs is seeded as ONE exact byte-string pinned to this project root and is project-exec - it runs YOUR declared gates.json commands, never "read-only"; source-size-check.mjs is seeded as ONE exact --check byte-string - its --write-baseline/--adopt writers are NOT covered and still prompt; writer previews are exact dry-run byte-strings - every --apply/--write/--yes still prompts; tier entries get NO PreToolUse-hook residual coverage EXCEPT repo-search.mjs and path-inventory.mjs, whose invocations the hook scans because they take caller-supplied argument bytes (settings-level posture only for the rest - see the velocity mode notes).';
 
 const formatKitTier = (result) =>
   result.kitTools
@@ -763,6 +777,12 @@ export const screenAllowlistEntry = (pattern) => {
   if (tokens[0] !== KIT_TOOL_INVOKER) return false;
   // Writer preview: the arg-free dry-run byte-string of a preview-class writer.
   if (tokens.length === 2) return isKitToolPathToken(tokens[1], KIT_WRITER_PREVIEW_TOOLS);
+  // source-size: EXACTLY `node <abs source-size-check> --check` — its read-only mode and nothing
+  // else, and no --cwd, because this rule covers the invocation an AGENT types directly. It is not
+  // the declared gate's byte-string (the fill quotes that path); see the tier constant above.
+  if (tokens.length === 3) {
+    return isKitToolPathToken(tokens[1], [KIT_SOURCE_SIZE_TOOL]) && tokens[2] === SOURCE_SIZE_CHECK_FLAG;
+  }
   // run-gates: EXACTLY `node <abs run-gates> --cwd <abs root>` — any other form keeps prompting.
   return (
     tokens.length === 4 &&
@@ -803,6 +823,7 @@ export const deriveKitToolsAllowlist = ({ projectDir } = {}) => {
   return Object.freeze([
     ...KIT_WILDCARD_TOOLS.map((rel) => `Bash(${KIT_TOOL_INVOKER} ${join(KIT_ROOT, rel)}:*)`),
     `Bash(${KIT_TOOL_INVOKER} ${join(KIT_ROOT, KIT_RUN_GATES_TOOL)} ${RUN_GATES_CWD_FLAG} ${projectRoot})`,
+    `Bash(${KIT_TOOL_INVOKER} ${join(KIT_ROOT, KIT_SOURCE_SIZE_TOOL)} ${SOURCE_SIZE_CHECK_FLAG})`,
     ...KIT_WRITER_PREVIEW_TOOLS.map((rel) => `Bash(${KIT_TOOL_INVOKER} ${join(KIT_ROOT, rel)})`),
   ]);
 };