@sabaiway/agent-workflow-kit 1.25.0 → 1.27.0

package/bin/install.mjs

@@ -23,8 +23,10 @@
 // member — the memory substrate (`npx @sabaiway/agent-workflow-memory@latest init`, best-effort: a
 // failure is a loud DEGRADED success, never silent — skippable with `--no-memory`) and the
 // methodology engine the kit reads live (`npx @sabaiway/agent-workflow-engine@latest init`, fatal —
-// the live read STOPs without it — skippable with `--no-engine`). The bridges are NOT installed by
-// `init` (placed by `/agent-workflow-kit setup`). No tracking either way.
+// the live read STOPs without it — skippable with `--no-engine`). The bridges are never PLACED by
+// `init` (first placement stays `/agent-workflow-kit setup`, opt-in); once placed, `init` REFRESHES
+// them from this package's own bundled copies — a purely LOCAL copy, no third server contact —
+// skippable with `--no-bridges`. No tracking either way.
 //
 // Dependency-free, Node >= 18.
 
@@ -35,11 +37,22 @@ import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { copyTreeRefresh } from '../tools/fs-safe.mjs';
+// Dependency-free semver, shared with the family registry's bridge freshness probe (one leaf, no
+// second drifting copy). The null-on-unparseable contract is load-bearing here: legacy installs
+// predate any version stamp, so an unparseable side means "no gate", never a false ordering.
+import { compareSemver } from '../tools/semver-lite.mjs';
 // The ONE registry of family members (npm packages, kinds). The init-refresh cascade derives its
 // membership from this table — no second source of "who gets refreshed" — so it can't drift from the
 // manifests (a drift-guard test pins the derivation). Imported from the DATA LEAF (family-members.mjs),
-// NOT family-registry.mjs, so the npx cold-start path stays lean (no status/presenter graph pulled in).
+// NOT family-registry.mjs. Leanness note: the bridge-refresh driver below does pull in the backend
+// detector + the manifest validator (setup-backends' imports), but still NOT the status/presenter
+// graph (family-registry, renderers, recipes) — the npx cold-start path stays presenter-free.
 import { FAMILY_MEMBERS } from '../tools/family-members.mjs';
+// The refresh-only bridge driver (shared with `/agent-workflow-kit setup --refresh-placed` and the
+// upgrade reconcile): refreshes ONLY a bridge `setup` already placed — an absent bridge is a stated
+// skip (never a first placement, AD-009/AD-011) and a placed bridge newer than this kit's bundled
+// mirror is a stated skip too (never a downgrade). Every line it returns is tool-composed.
+import { refreshPlacedBridges } from '../tools/setup-backends.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
@@ -81,22 +94,6 @@ const readVersion = async () => {
   }
 };
 
-// Dependency-free semver: parse the leading `x.y.z` (prerelease/build ignored — kit versions are
-// plain). compareSemver returns -1 | 0 | 1, or null when either side is unparseable (legacy installs
-// predate any version stamp). No `let`: a small functional comparison (AGENTS.md §2.3).
-const parseSemver = (str) => {
-  const m = typeof str === 'string' ? str.trim().match(/^(\d+)\.(\d+)\.(\d+)/) : null;
-  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
-};
-
-const compareSemver = (a, b) => {
-  const pa = parseSemver(a);
-  const pb = parseSemver(b);
-  if (!pa || !pb) return null;
-  const firstDiff = [0, 1, 2].map((i) => (pa[i] === pb[i] ? 0 : pa[i] < pb[i] ? -1 : 1)).find((c) => c !== 0);
-  return firstDiff ?? 0;
-};
-
 // Extract the version that is a DIRECT child of the top-level `metadata:` key — never a top-level
 // or deeper-nested decoy `version:` (mirrors the manifest validator's rigor; the kit ships manifest
 // fixtures that probe exactly those decoys). Pure string walk over the frontmatter block, no deps.
@@ -157,6 +154,7 @@ const parseArgs = (argv) => {
     noLaunchers: argv.includes('--no-launchers'),
     noMemory: argv.includes('--no-memory'),
     noEngine: argv.includes('--no-engine'),
+    noBridges: argv.includes('--no-bridges'),
     force: argv.includes('--force'),
     allowDowngrade: argv.includes('--allow-downgrade'),
     dir: dirFlag >= 0 ? argv[dirFlag + 1] : undefined,
@@ -278,7 +276,7 @@ const printHelp = (version) => {
   console.log(`agent-workflow-kit ${version}
 
 Usage:
-  npx @sabaiway/agent-workflow-kit@latest init [--dir <path>] [--no-launchers] [--no-memory] [--no-engine] [--force] [--allow-downgrade]
+  npx @sabaiway/agent-workflow-kit@latest init [--dir <path>] [--no-launchers] [--no-memory] [--no-engine] [--no-bridges] [--force] [--allow-downgrade]
   npx @sabaiway/agent-workflow-kit@latest --version
   npx @sabaiway/agent-workflow-kit@latest --help
 
@@ -294,8 +292,10 @@ Installs/refreshes the kit at ~/.claude/skills/agent-workflow-kit
   stale, refresh it yourself + restart — a miss is otherwise a non-fatal degraded success,
   never the engine's hard STOP); --no-engine skips the engine install (the live methodology
   read then STOPs until you install it by hand); --force replaces a pre-existing non-kit
-  launcher file (backed up first). The bridges are NOT installed by init (placed by
-  /agent-workflow-kit setup). init is additive — it never deletes your settings. If the
+  launcher file (backed up first). The bridges are never PLACED by init (first placement
+  stays /agent-workflow-kit setup, opt-in); once placed, init refreshes them from the kit's
+  own bundled copies — local files only, never a downgrade — and --no-bridges skips that
+  refresh. init is additive — it never deletes your settings. If the
   installed kit is newer than the version you ran, init refuses (no network — it compares
   the version on disk) and points you at @latest; --allow-downgrade overrides that
   refusal (distinct from --force, which is launcher-only).
@@ -376,15 +376,26 @@ const main = async () => {
       console.log(`[agent-workflow-kit] removed retired file ${tildify(retired)} (now read live from the engine).`);
     }
   }
-  console.log(`[agent-workflow-kit] ${wasPresent ? 'updated the kit to' : 'installed'} v${version} -> ${tildify(target)}`);
-
-  // No-op re-run: the install just refreshed the skill with the SAME version it already had. For a
-  // user who ran `init` expecting an upgrade, that almost always means npx reused a cached build —
-  // say so explicitly and point at @latest (the no-network signal that catches the reported scenario).
+  // 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. One message contract
+  // with the engine installer (same shapes, member noun differs).
+  const verb =
+    cmp === 0 ? 'refreshed the already-current kit'
+    : cmp === 1 ? 'downgraded the kit to'
+    : cmp === -1 ? 'updated the kit to'
+    : 'installed';
+  console.log(`[agent-workflow-kit] ${verb} v${version} -> ${tildify(target)}`);
+
+  // 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-kit] note: no version change — the kit was already v${version}. If you expected ` +
-        `an update, npx likely served a cached build; re-run bypassing the cache:\n` +
+      `[agent-workflow-kit] note: the kit was already v${version} — the copy still ran, restoring ` +
+        `any locally modified or deleted kit file to this version's packaged contents. If you ` +
+        `expected a NEWER version, invoke the @latest tag explicitly:\n` +
         `    npx @sabaiway/agent-workflow-kit@latest init`,
     );
   }
@@ -404,6 +415,40 @@ const main = async () => {
     }
   }
 
+  // Placed-bridge refresh — AFTER the kit copy (the bundled bridges/ just landed), BEFORE the two
+  // network cascade steps (this one is LOCAL files only: bundle → placed copy). Refresh-only, so the
+  // AD-009/AD-011 honesty claim survives as "init never PLACES bridges; it refreshes what setup
+  // already placed" — an absent bridge is a stated skip, a placed-newer one a stated skip too (never
+  // a downgrade). Best-effort in the memory DEGRADED shape: any miss is a loud warning + a
+  // host-runnable recovery composed from the RESOLVED target (a --dir / AGENT_WORKFLOW_KIT_DIR
+  // install must get a line that runs) + exit 0 — never silent, never the engine's hard STOP.
+  const bridgeRefreshCmd = `node ${tildify(resolve(target, 'tools/setup-backends.mjs'))} --refresh-placed`;
+  if (args.noBridges) {
+    console.log(
+      `[agent-workflow-kit] --no-bridges: skipped refreshing the placed bridges. If one is stale, ` +
+        `refresh it yourself:\n    ${bridgeRefreshCmd}`,
+    );
+  } else if (process.platform === 'win32') {
+    console.log('[agent-workflow-kit] Windows: skipped the placed-bridge refresh (POSIX wrappers — refresh under WSL).');
+  } else {
+    console.log('[agent-workflow-kit] refreshing the bridges setup already placed (an absent bridge is never placed here):');
+    try {
+      const results = refreshPlacedBridges();
+      for (const r of results) console.log(r.line);
+      if (results.some((r) => r.outcome === 'failed')) {
+        console.warn(
+          `[agent-workflow-kit] could not refresh every placed bridge — continuing; the kit itself IS ` +
+            `installed and works. Re-run the refresh yourself:\n    ${bridgeRefreshCmd}`,
+        );
+      }
+    } catch (err) {
+      console.warn(
+        `[agent-workflow-kit] could not refresh the placed bridges (${err.message}) — continuing; the ` +
+          `kit itself IS installed and works. Re-run the refresh yourself:\n    ${bridgeRefreshCmd}`,
+      );
+    }
+  }
+
   // Memory substrate refresh — AFTER the kit + launchers, BEFORE the (fatal) engine and the success
   // block, so a returning `init` leaves no stale memory. Unlike the engine, a memory miss is a
   // DEGRADED success: warn with the exact recovery command + the on-disk version (read crash-proof)

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "1.25.0",
+  "version": "1.27.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.25.0",
+  "version": "1.27.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/agents/changelog-skeleton.md

@@ -0,0 +1,23 @@
+---
+name: changelog-skeleton
+description: Cheap-lane changelog fact-skeleton — drafts the factual bones of a changelog or release-notes entry from diff/log facts. The orchestrator (frontier) writes the lead and owns the final text; use only for the mechanical draft, never for persuasive copy.
+model: haiku
+effort: low
+tools: Read, Grep, Glob
+---
+
+You are a changelog-skeleton drafter on the cheap lane (L1). You turn diff facts the orchestrator
+gives you (changed files, commit subjects, version bumps, test counts) into the FACTUAL BONES of
+a changelog entry. The orchestrator writes the lead sentence and all user-facing framing — the
+final wording is never yours (asymmetric pairing: cheap drafts, frontier signs).
+
+Rules:
+- Only facts present in the provided input or the files you are pointed at; every claim must be
+  traceable to a named file, commit, or diff hunk. Never invent a feature, a motivation, or an
+  impact statement.
+- Structure: grouped bullet lists (Added / Changed / Fixed / Internal), each bullet naming the
+  artifact (`path`, tool, mode, version) it describes.
+- Versions, package names, commands, and paths are quoted verbatim from the input.
+- Mark anything uncertain as `VERIFY:` rather than asserting it.
+- No superlatives, no persuasion, no summary paragraph — that is the frontier's red-line work.
+- Read-only: you never modify files.

package/references/agents/gate-triage.md

@@ -0,0 +1,23 @@
+---
+name: gate-triage
+description: Cheap-lane gate-failure triage — reads failing gate/test output and produces a structured classification (which gate, first real error, implicated files) for the orchestrator to act on. Use to digest long failing output, never to fix code or decide what to do.
+model: haiku
+effort: low
+tools: Read, Grep, Glob
+---
+
+You are a gate-triage agent on the cheap lane (L1). You digest FAILING verification output (a
+gate runner table, a test-suite log, a validator report) into a compact, structured triage the
+orchestrator can act on. You never fix anything and never decide what to do next.
+
+Rules:
+- For each failing gate/test, report: the gate/test id · the FIRST real error line (quoted
+  verbatim) · the implicated `file:line` if the output names one · the failure class
+  (assertion / crash / timeout / missing-file / config).
+- Separate signal from noise: strip repeated stack frames and progress spam; keep the shortest
+  quote that still identifies the failure.
+- Preserve counts exactly as printed (`N passed, M failed`) — never recompute or estimate.
+- If output is truncated or ambiguous, say so (`TRUNCATED` / `AMBIGUOUS`) — never guess a cause.
+- Output: one section per failing gate, ordered as the run reported them. No fix suggestions,
+  no root-cause speculation beyond the failure class, no code.
+- Read-only: you never modify files, never re-run commands.

package/references/agents/mechanical-sweep.md

@@ -0,0 +1,20 @@
+---
+name: mechanical-sweep
+description: Cheap-lane extraction sweeps — inventories, session-record extraction, doc checklists, multi-file fact collection. Use for mechanical reading at scale, never for judgment, code review, or writing code.
+model: haiku
+effort: low
+tools: Read, Grep, Glob
+---
+
+You are a mechanical extraction agent on the cheap lane (L1). Your job is READING AT SCALE and
+returning structured facts — never conclusions, never opinions, never code.
+
+Rules:
+- Extract exactly what was asked: inventories, lists, counts, quoted lines, checklist states.
+- Cite every fact as `file:line` (or `file` for whole-file facts) so the orchestrator can verify
+  it deterministically. A fact you cannot cite does not go in the output.
+- Quote verbatim; never paraphrase an identifier, version, command, or path.
+- If a requested item is absent, say `ABSENT` explicitly — never guess, never fill gaps.
+- Output format: the structure the prompt asks for (list / table / JSON). No preamble, no
+  commentary, no recommendations — the orchestrator applies judgment, you supply facts.
+- Read-only: you never modify files, never run commands, never propose edits.

package/references/contracts.md

@@ -26,6 +26,7 @@ diverge:
 | Pattern | Owner | Kind | Commit-risk name? | Note |
 |---|---|---|---|---|
 | `/.claude/skills/` | Claude Code | dir | no | local-dev skills; absorbs the AD-013 one-off |
+| `/.claude/agents/` | Claude Code | dir | no | project subagent definitions (incl. the kit-placed cheap-lane vehicles) |
 | `/.cursor/rules/` | Cursor | dir | no | project rule files |
 | `/.cursorrules` | Cursor (legacy) | file | **yes** | legacy single-file rules |
 | `/.codeium/` | Codeium/Windsurf | dir | no | home-scoped launchers live under `~/`, out of scope |