@sabaiway/agent-workflow-kit 1.17.0 → 1.19.0

package/tools/family-members.mjs

@@ -0,0 +1,67 @@
+// family-members.mjs — the pure DATA LEAF: the one authoritative table of agent-workflow family members.
+//
+// Extracted from family-registry.mjs so the two consumers that only need the static table — the npx
+// installer (bin/install.mjs, which derives its init-refresh cascade from it) and family-registry
+// itself — can import the DATA without dragging in the whole status/presenter graph
+// (detect-backends, the manifest validator, hide-footprint, engine-source, recipes, the renderers …).
+// install.mjs runs on the npx cold-start hot path, so the leaner import matters; single-source-of-truth
+// + the drift-guard (family-registry.test.mjs pins FAMILY_MEMBERS to the 5 in-repo capability.json)
+// are preserved — the table just lives in a dependency-free leaf now.
+//
+// Pure data, no imports, no side effects, Node >= 18.
+
+// ── the unified registry ───────────────────────────────────────────────────────
+// One entry per family member. `installed` is the detect.installed spec (env + home-relative default
+// + marker file); `deployed` is the project-relative stamp a deploy writes (kit + memory only);
+// `npm` is the install package (null for the bridges, which are placed by `setup`, not npm);
+// `wrapperCmds` is the deduped roles[].cmd set the `setup` linker creates on PATH (bridges only).
+// Kept in lockstep with the 5 in-repo capability.json by the drift-guard test. The two release skills
+// (release-engineering / release-marketing) are deliberately NOT here — they are not family members
+// (AD-013): no capability.json, not in the kit tarball, not in the role vocabulary.
+export const FAMILY_MEMBERS = [
+  {
+    name: 'agent-workflow-kit',
+    kind: 'composition-root',
+    installed: { env: 'AGENT_WORKFLOW_KIT_DIR', default: '~/.claude/skills/agent-workflow-kit', file: 'SKILL.md' },
+    deployed: { file: 'docs/ai/.workflow-version' },
+    npm: '@sabaiway/agent-workflow-kit',
+    wrapperCmds: [],
+  },
+  {
+    name: 'agent-workflow-memory',
+    kind: 'memory-substrate',
+    installed: { env: 'AGENT_WORKFLOW_MEMORY_DIR', default: '~/.claude/skills/agent-workflow-memory', file: 'SKILL.md' },
+    deployed: { file: 'docs/ai/.memory-version' },
+    npm: '@sabaiway/agent-workflow-memory',
+    wrapperCmds: [],
+  },
+  {
+    name: 'agent-workflow-engine',
+    kind: 'methodology-engine',
+    installed: { env: 'AGENT_WORKFLOW_ENGINE_DIR', default: '~/.claude/skills/agent-workflow-engine', file: 'SKILL.md' },
+    deployed: null,
+    npm: '@sabaiway/agent-workflow-engine',
+    wrapperCmds: [],
+  },
+  {
+    name: 'codex-cli-bridge',
+    kind: 'execution-backend',
+    installed: { env: 'CODEX_CLI_BRIDGE_DIR', default: '~/.claude/skills/codex-cli-bridge', file: 'SKILL.md' },
+    deployed: null,
+    npm: null,
+    wrapperCmds: ['codex-exec', 'codex-review'],
+  },
+  {
+    name: 'antigravity-cli-bridge',
+    kind: 'execution-backend',
+    installed: { env: 'ANTIGRAVITY_CLI_BRIDGE_DIR', default: '~/.claude/skills/antigravity-cli-bridge', file: 'SKILL.md' },
+    deployed: null,
+    npm: null,
+    wrapperCmds: ['agy-run'],
+  },
+];
+
+// A GLOBAL skill (lives under ~/.claude/skills) may be shared by other projects on the host — the
+// uninstaller warns before removing one (there is no cross-project dependency tracking). All current
+// members are global skills; the field is explicit so the warning is data-driven, not hardcoded.
+export const isGlobalSkill = (member) => member.kind !== undefined; // every member is a global skill today

package/tools/family-registry.mjs

@@ -25,7 +25,9 @@ import { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from
 import { START_MARKER, excludePath, inferVisibility } from './hide-footprint.mjs';
 import { readEngineFragment, ORCHESTRATION_FRAGMENT_REL, PROCEDURES_FRAGMENT_REL } from './engine-source.mjs';
 import { ACTIVITIES, resolveActivityRecipe } from './recipes.mjs';
-import { loadConfig } from './procedures.mjs';
+// The config reader lives in orchestration-config.mjs (the single config contract). The read-only status
+// settings-survey reuses THIS reader (one strict-JSON + loud-on-malformed contract), not a second copy.
+import { loadConfig } from './orchestration-config.mjs';
 // The deployment-lineage head + the shared settings readers are reused from velocity-profile so the
 // `--json` envelope/settings-survey has ONE implementation each, never a drifting copy:
 //   EXPECTED_WORKFLOW_VERSION — the head literal (drift-guarded vs memory LINEAGE_HEAD)
@@ -39,73 +41,52 @@ import {
   readSettingsFile,
   resolveEffectiveMode,
 } from './velocity-profile.mjs';
-
-// ── manifestState values (the detect-backends precedence, generalized to any member kind) ──────────
-export const NOT_INSTALLED = 'not-installed';
-export const UNSUPPORTED_SCHEMA = 'unsupported-schema';
-export const INVALID_MANIFEST = 'invalid-manifest';
-export const STUB = 'stub';
-export const FOREIGN = 'foreign';
-export const OK = 'ok';
-// The marker could not be probed (a non-ENOENT fs error — EACCES/EIO). Surfaced explicitly instead of
-// being masked as not-installed (no silent failure); uninstall treats it as "do not touch" (skip).
-export const UNKNOWN = 'unknown';
+// The status vocabulary (manifestState constants, internal→public maps, display names, the no-leak
+// forbidden set) lives in the frozen labels.mjs LEAF (Plan §4.2 B1) so the import graph is acyclic —
+// nothing imports family-registry for vocabulary. Imported here for internal use; the public subset is
+// re-exported below.
+import {
+  NOT_INSTALLED,
+  UNSUPPORTED_SCHEMA,
+  INVALID_MANIFEST,
+  STUB,
+  FOREIGN,
+  OK,
+  UNKNOWN,
+  STATE_PUBLIC,
+  VISIBILITY_PUBLIC,
+  DISPLAY_NAMES,
+  displayOf,
+} from './labels.mjs';
+// The capability-adaptive direct-CLI presenter (Plan §4.2/§4.5): the surface detector, the
+// envelope→ViewModel transform, and the plain/ansi renderers. main() composes them; the agent-mediated
+// `status` surface ignores them (it consumes --json). These are leaves — no import cycle.
+import { detectSurface } from './surface.mjs';
+import { toViewModel } from './view-model.mjs';
+import { render } from './renderers.mjs';
+
+// ── manifestState values — re-export the EXACT public subset family-registry exported before B1 ─────
+// (the 7 state constants + DISPLAY_NAMES) so every existing importer (uninstall.mjs, the test suites)
+// stays green. STATE_PUBLIC / VISIBILITY_PUBLIC / displayOf were private here and are NOT re-exported.
+export {
+  NOT_INSTALLED,
+  UNSUPPORTED_SCHEMA,
+  INVALID_MANIFEST,
+  STUB,
+  FOREIGN,
+  OK,
+  UNKNOWN,
+  DISPLAY_NAMES,
+};
 
 // ── the unified registry ───────────────────────────────────────────────────────
-// One entry per family member. `installed` is the detect.installed spec (env + home-relative default
-// + marker file); `deployed` is the project-relative stamp a deploy writes (kit + memory only);
-// `npm` is the install package (null for the bridges, which are placed by `setup`, not npm);
-// `wrapperCmds` is the deduped roles[].cmd set the `setup` linker creates on PATH (bridges only).
-// Kept in lockstep with the 5 in-repo capability.json by the drift-guard test. The two release skills
-// (release-engineering / release-marketing) are deliberately NOT here — they are not family members
-// (AD-013): no capability.json, not in the kit tarball, not in the role vocabulary.
-export const FAMILY_MEMBERS = [
-  {
-    name: 'agent-workflow-kit',
-    kind: 'composition-root',
-    installed: { env: 'AGENT_WORKFLOW_KIT_DIR', default: '~/.claude/skills/agent-workflow-kit', file: 'SKILL.md' },
-    deployed: { file: 'docs/ai/.workflow-version' },
-    npm: '@sabaiway/agent-workflow-kit',
-    wrapperCmds: [],
-  },
-  {
-    name: 'agent-workflow-memory',
-    kind: 'memory-substrate',
-    installed: { env: 'AGENT_WORKFLOW_MEMORY_DIR', default: '~/.claude/skills/agent-workflow-memory', file: 'SKILL.md' },
-    deployed: { file: 'docs/ai/.memory-version' },
-    npm: '@sabaiway/agent-workflow-memory',
-    wrapperCmds: [],
-  },
-  {
-    name: 'agent-workflow-engine',
-    kind: 'methodology-engine',
-    installed: { env: 'AGENT_WORKFLOW_ENGINE_DIR', default: '~/.claude/skills/agent-workflow-engine', file: 'SKILL.md' },
-    deployed: null,
-    npm: '@sabaiway/agent-workflow-engine',
-    wrapperCmds: [],
-  },
-  {
-    name: 'codex-cli-bridge',
-    kind: 'execution-backend',
-    installed: { env: 'CODEX_CLI_BRIDGE_DIR', default: '~/.claude/skills/codex-cli-bridge', file: 'SKILL.md' },
-    deployed: null,
-    npm: null,
-    wrapperCmds: ['codex-exec', 'codex-review'],
-  },
-  {
-    name: 'antigravity-cli-bridge',
-    kind: 'execution-backend',
-    installed: { env: 'ANTIGRAVITY_CLI_BRIDGE_DIR', default: '~/.claude/skills/antigravity-cli-bridge', file: 'SKILL.md' },
-    deployed: null,
-    npm: null,
-    wrapperCmds: ['agy-run'],
-  },
-];
-
-// A GLOBAL skill (lives under ~/.claude/skills) may be shared by other projects on the host — the
-// uninstaller warns before removing one (there is no cross-project dependency tracking). All current
-// members are global skills; the field is explicit so the warning is data-driven, not hardcoded.
-export const isGlobalSkill = (member) => member.kind !== undefined; // every member is a global skill today
+// FAMILY_MEMBERS (+ isGlobalSkill) is the one authoritative member table. It moved to the
+// dependency-free DATA LEAF family-members.mjs so the npx installer can derive its init-refresh cascade
+// from the table WITHOUT importing this whole status/presenter graph (a leaner npx cold-start path).
+// Re-exported here so every existing importer (uninstall.mjs, the test suites) stays green, and the
+// drift-guard (family-registry.test.mjs) still pins the table to the 5 in-repo capability.json.
+export { FAMILY_MEMBERS, isGlobalSkill } from './family-members.mjs';
+import { FAMILY_MEMBERS } from './family-members.mjs';
 
 // ── pure probes ──────────────────────────────────────────────────────────────────
 // Wrapped marker probe → 'present' (a regular file) | 'absent' (ENOENT / not a regular file) |
@@ -266,62 +247,10 @@ export const surveyProject = (projectDir, deps = {}) => {
 };
 
 // ── report ───────────────────────────────────────────────────────────────────────
-const pad = (s, n) => (s.length >= n ? s : s + ' '.repeat(n - s.length));
-
-// The human (non-JSON) settings render. A dev view — the agent consumes `--json` + renders in plain
-// language (Mode: status). Each area shows its `error` field loudly when one fired.
-const formatSettings = (s) => {
-  const out = ['', 'settings'];
-  if (s.recipes?.error) out.push(`  ${pad('recipes', 14)}error: ${s.recipes.error}`);
-  else {
-    const parts = [];
-    for (const [act, slots] of Object.entries(s.recipes?.activities ?? {})) {
-      for (const [slot, r] of Object.entries(slots)) parts.push(`${act}.${slot}=${r.recipe}`);
-    }
-    out.push(`  ${pad('recipes', 14)}${parts.join(' · ') || '—'}`);
-    if (s.recipes?.detectError) out.push(`  ${pad('', 14)}↳ couldn't check backends (${s.recipes.detectError}); recipes floored at solo`);
-  }
-  if (s.attribution?.error) out.push(`  ${pad('attribution', 14)}error: ${s.attribution.error}`);
-  else out.push(`  ${pad('attribution', 14)}includeCoAuthoredBy effective=${String(s.attribution?.effective)}`);
-  if (s.velocity?.error) out.push(`  ${pad('velocity', 14)}error: ${s.velocity.error}`);
-  else out.push(`  ${pad('velocity', 14)}defaultMode=${String(s.velocity?.defaultMode)} · allow project/local=${s.velocity?.allowEntries?.project}/${s.velocity?.allowEntries?.local}`);
-  return out;
-};
-
-export const formatStatus = (family, project = null, extras = {}) => {
-  const lines = ['agent-workflow family — installed skills (skill axis)', ''];
-  for (const m of family) {
-    const ver = m.version ? `v${m.version}` : '—';
-    lines.push(`  ${pad(m.name, 26)}[${pad(m.manifestState, 16)}] ${pad(ver, 10)} ${m.kind}`);
-    for (const c of m.caveats ?? []) lines.push(`      ↳ ${c}`);
-  }
-  if (extras.bridges) {
-    const WRAP_MARK = { present: '✓', missing: '✗', unknown: '?' };
-    lines.push('', 'execution backends (host)', '');
-    for (const b of extras.bridges) {
-      const w = b.wrappers.map((x) => `${x.cmd} ${WRAP_MARK[x.state] ?? '?'}`).join(', ') || '—';
-      lines.push(`  ${pad(b.display, 20)}${pad(b.readiness, 18)}wrappers: ${w}`);
-    }
-  }
-  if (project) {
-    lines.push('', `project deployment (${project.dir})`, '');
-    if (!project.deployed) {
-      lines.push('  no agent-workflow deployment detected here (no docs/ai, no version stamp).');
-    } else {
-      for (const s of project.stamps) {
-        lines.push(`  ${pad(s.file, 26)}${s.version ?? '—'}`);
-      }
-      lines.push(`  ${pad('docs/ai present', 26)}${project.docsAiPresent ? 'yes' : 'no'}`);
-      if (extras.visibility) {
-        lines.push(`  ${pad('visibility', 26)}${extras.visibility.error ? `error: ${extras.visibility.error}` : extras.visibility.state}`);
-      } else {
-        lines.push(`  ${pad('hidden-mode fence', 26)}${project.hiddenFence ? 'present' : 'absent'}`);
-      }
-    }
-    if (extras.settings) lines.push(...formatSettings(extras.settings));
-  }
-  return lines.join('\n');
-};
+// The direct-CLI human render (formatStatus + formatSettings) was REPLACED by the capability-adaptive
+// presenter pipeline (surface → view-model → renderers, Plan §4.2/§4.5): main() builds the no-leak
+// envelope once, then renders it via toViewModel + render (plain/ansi) or prints it as JSON. ONE data
+// source for both surfaces — the agent-mediated `status` consumes `--json`, the direct CLI renders it.
 
 // ── the no-leak --json envelope ──────────────────────────────────────────────────
 // A machine-readable view with USER-SAFE field names only — NEVER the internal manifestState /
@@ -329,28 +258,8 @@ export const formatStatus = (family, project = null, extras = {}) => {
 // consumes THIS, never the human table verbatim. An envelope-shape test pins its shape so later phases
 // (the settings/visibility block) can't silently break the Phase-2 version consumer.
 
-// internal manifestState → a STABLE, user-safe token (SKILL.md owns the value→plain-language phrasing).
-// Deliberately NOT the internal literals (foreign/stub/…): those must never leak past this boundary.
-const STATE_PUBLIC = {
-  [OK]: 'installed',
-  [NOT_INSTALLED]: 'absent',
-  [FOREIGN]: 'other-tool',
-  [STUB]: 'placeholder',
-  [INVALID_MANIFEST]: 'invalid',
-  [UNSUPPORTED_SCHEMA]: 'unsupported',
-  [UNKNOWN]: 'uncheckable',
-};
-
-// Short, user-facing labels for the version block (kit · memory · engine · codex-bridge · …), so the
-// render is deterministic and the agent never invents a label.
-export const DISPLAY_NAMES = {
-  'agent-workflow-kit': 'kit',
-  'agent-workflow-memory': 'memory',
-  'agent-workflow-engine': 'engine',
-  'codex-cli-bridge': 'codex-bridge',
-  'antigravity-cli-bridge': 'antigravity-bridge',
-};
-const displayOf = (name) => DISPLAY_NAMES[name] ?? name;
+// STATE_PUBLIC (internal→public token map) + DISPLAY_NAMES + displayOf now live in labels.mjs (B1) —
+// imported at the top of this file. They are used below exactly as before.
 
 // ── the settings survey (Phase 3) — read-only, honest, localized-on-error ──────────
 // Each sub-survey returns a small user-safe object OR a single `{ error }` field (a localized message,
@@ -378,8 +287,8 @@ const detectSafe = (deps) => {
 };
 
 // visibility: the THREE honest states from inferVisibility (NOT the single hiddenFence bit) → user-safe
-// words. Never the internal "hidden fence" / marker terms. A git/probe error → a localized error field.
-const VISIBILITY_PUBLIC = { visible: 'visible', hidden: 'hidden', ambiguous: 'unclear' };
+// words (VISIBILITY_PUBLIC, from labels.mjs). Never the internal "hidden fence" / marker terms. A
+// git/probe error → a localized error field.
 export const surveyVisibility = (dir, deps = {}) => {
   try {
     const vis = inferVisibility(deps, resolve(dir));
@@ -467,6 +376,20 @@ export const surveyBridges = (deps = {}) => {
   });
 };
 
+// INV-2 (structural refresh — additive, derived, never parsed from a caveat string). A member is
+// `behind` when it is a refreshable CORE member (memory / engine) carrying a refresh-recommending
+// caveat — surveyFamily attaches caveats ONLY to those two kinds, and today every such caveat is
+// refresh-recommending. `recommend` is composed from the member's npm package in the ONE registry
+// (FAMILY_MEMBERS[].npm), never extracted from the caveat text. The kit (composition-root) + the two
+// bridges (execution-backend) never carry such a caveat, so they derive { behind:false, recommend:null }
+// — gated by the CAVEAT, not by npm-nullness (the kit's npm is non-null; only the bridges are null).
+const REFRESHABLE_KINDS = new Set(['memory-substrate', 'methodology-engine']);
+const npmOf = (name) => FAMILY_MEMBERS.find((m) => m.name === name)?.npm ?? null;
+const refreshOf = (m) => {
+  const behind = REFRESHABLE_KINDS.has(m.kind) && Boolean(m.caveats?.length);
+  return { behind, recommend: behind ? `npx ${npmOf(m.name)}@latest init` : null };
+};
+
 export const buildEnvelope = (family, project = null, extras = {}) => {
   const installed = family.map((m) => {
     const entry = {
@@ -476,6 +399,7 @@ export const buildEnvelope = (family, project = null, extras = {}) => {
       state: STATE_PUBLIC[m.manifestState] ?? STATE_PUBLIC[UNKNOWN],
     };
     if (m.caveats?.length) entry.notes = m.caveats; // plain-language observations (Steps 2.2 / engine)
+    entry.refresh = refreshOf(m); // additive (INV-1): always present; { behind, recommend } (INV-2)
     return entry;
   });
   const envelope = { deploymentHead: EXPECTED_WORKFLOW_VERSION, installed };
@@ -496,27 +420,72 @@ export const buildEnvelope = (family, project = null, extras = {}) => {
 };
 
 // ── CLI ────────────────────────────────────────────────────────────────────────
-const parseArgs = (argv) => {
-  const dirFlag = argv.indexOf('--dir');
-  return {
-    help: argv.includes('--help') || argv.includes('-h'),
-    json: argv.includes('--json'),
-    dir: dirFlag >= 0 ? argv[dirFlag + 1] : undefined,
-  };
+// Parse contract (Plan §4.5, grounded): the old parseArgs SILENTLY ignored unknown args + a missing
+// --dir value. With the explicit format surface added, the parse now rejects LOUDLY (no silent
+// failure): an unknown flag, a `--dir` with no value, and an invalid `--format` (validated by
+// resolveFormat) all throw. `--json` vs `--format=*` precedence is deterministic (last-wins, in
+// surface.mjs). Returns only { dir } — help is handled first, the format/mode comes from the surface.
+const HELP_FLAGS = new Set(['--help', '-h']);
+// --dir and --format carry/consume a value, so they are handled explicitly below — only the valueless
+// flags live in KNOWN_FLAGS.
+const KNOWN_FLAGS = new Set(['--help', '-h', '--json']);
+// Single left-to-right pass (functional reduce, no `let`): EVERY `--dir` must carry a value — a
+// trailing or REPEATED `--dir` with no value rejects loudly, never silently (a first-occurrence-only
+// check let `--dir /p --dir` slip through as a "known flag"). The token right after a `--dir` is its
+// value (skipped), so a path is never mistaken for an unknown flag; the last `--dir` wins.
+export const parseArgs = (argv) => {
+  const { dir } = argv.reduce(
+    (state, a, i) => {
+      if (state.skip) return { dir: state.dir, skip: false }; // this token was the preceding --dir value
+      if (a === '--dir') {
+        const value = argv[i + 1];
+        if (value === undefined || value.startsWith('-')) {
+          throw new Error('[agent-workflow-kit] --dir needs a value: --dir <project>');
+        }
+        return { dir: value, skip: true }; // consume the value; last --dir wins
+      }
+      if (KNOWN_FLAGS.has(a) || a === '--format' || a.startsWith('--format=')) return state;
+      throw new Error(`[agent-workflow-kit] unknown argument: ${a}`);
+    },
+    { dir: undefined, skip: false },
+  );
+  return { dir };
 };
 
-const main = (argv) => {
-  const args = parseArgs(argv);
-  if (args.help) {
-    console.log(`family-registry — read-only view of the agent-workflow family.
+const HELP = `family-registry — read-only view of the agent-workflow family.
 
 Usage:
-  node family-registry.mjs [--dir <project>] [--json]
-    # skill axis always; deploy axis when --dir is given; --json = the no-leak machine envelope
+  node family-registry.mjs [--dir <project>] [--format=<auto|plain|ansi|json>] [--json]
+    # skill axis always; deploy axis when --dir is given.
+    # --format: auto (default — ansi on a TTY, plain otherwise) | plain | ansi | json.
+    #   --json is sugar for --format=json (the no-leak machine envelope). AGENT_WORKFLOW_FORMAT
+    #   sets the default; a flag beats it. Width/color follow the terminal (NO_COLOR / FORCE_COLOR).
 
-Detection only — never writes, never commits, never runs a subscription CLI.`);
+Detection only — never writes, never commits, never runs a subscription CLI.`;
+
+const main = (argv) => {
+  if (argv.some((a) => HELP_FLAGS.has(a))) {
+    console.log(HELP);
     return;
   }
+  // Validate args + resolve the output surface BEFORE any survey work; a bad flag/format → loud exit 1.
+  const args = (() => {
+    try {
+      const parsed = parseArgs(argv);
+      const surface = detectSurface({
+        argv,
+        env: process.env,
+        isTTY: Boolean(process.stdout.isTTY),
+        columns: process.stdout.columns,
+        platform: process.platform,
+      });
+      return { ...parsed, surface };
+    } catch (err) {
+      console.error(err?.message ?? String(err));
+      process.exit(1);
+    }
+  })();
+
   const family = surveyFamily();
   const bridges = surveyBridges();
   const project = args.dir ? surveyProject(args.dir) : null;
@@ -525,7 +494,10 @@ Detection only — never writes, never commits, never runs a subscription CLI.`)
     extras.visibility = surveyVisibility(args.dir);
     extras.settings = surveySettings(args.dir);
   }
-  console.log(args.json ? JSON.stringify(buildEnvelope(family, project, extras), null, 2) : formatStatus(family, project, extras));
+  const envelope = buildEnvelope(family, project, extras);
+  // Two surfaces, one data source: JSON prints the envelope verbatim; plain/ansi render it through the
+  // capability-adaptive presenter pipeline (view-model → renderers). No-leak inherited from the envelope.
+  console.log(args.surface.mode === 'json' ? JSON.stringify(envelope, null, 2) : render(toViewModel(envelope), args.surface));
 };
 
 const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;

package/tools/inject-methodology.mjs

@@ -18,6 +18,14 @@
 // STOP loudly (never a silent fallback) when the engine is needed but absent/invalid.
 //
 // Pure string functions (testable with byte-preservation fixtures); dependency-free, Node >= 18.
+//
+// Canonical-refresh (AD-025): a slot filled BEFORE a clause existed is normally preserved verbatim
+// (reconcile only fills an EMPTY slot). To push a NEW canonical clause to the EXISTING filled base
+// without clobbering a user's customization, reconcileMarkerSlot also REFRESHES a filled slot — but
+// ONLY when its content normalize-matches a KNOWN PRIOR canonical fragment (drift-guarded, append-only
+// per descriptor). A customized slot never matches → preserved verbatim + a read-only upgrade advisory.
+
+import { normalizeCanonical } from './orchestration-config.mjs';
 
 export const START_MARKER = '<!-- workflow:methodology:start -->';
 export const END_MARKER = '<!-- workflow:methodology:end -->';
@@ -57,11 +65,29 @@ export const ORCH_ANCHOR = new RegExp(`^.*${escapeRegExp(END_MARKER)}.*$`, 'm');
 export const EMPTY_SLOT = `${START_MARKER}\n${END_MARKER}`;
 export const ORCH_EMPTY_SLOT = `${ORCH_START_MARKER}\n${ORCH_END_MARKER}`;
 
+// ── known-prior canonical fragments (drift-guarded, APPEND-ONLY per slot) ───────
+// The EXACT content a PREVIOUS release's engine fragment shipped (what a filled slot would carry today).
+// reconcileMarkerSlot refreshes a filled slot to the current engine fragment IFF its content
+// normalize-matches one of these — so the install base gains a new clause without clobbering a
+// customization (which never matches). Any release that CHANGES an engine fragment must FIRST append the
+// OUTGOING content here, so the immediately-previous deployments still match (a drift-guard test pins
+// current-minus-one → new). NEVER edit an existing entry — only append.
+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.',
+];
+export const KNOWN_PRIOR_ORCH_SLOT = [
+  // v1.3.0 — pre-read-at-start orchestration pointer (recipes vocabulary, no orchestration.json clause).
+  '> **Orchestration recipes** — compose plan → execute → review with a named recipe: **Solo** (no backend), **Reviewed** (one backend reviews), **Council** (both review, you synthesize), **Delegated** (a backend executes a bounded sub-task); the orchestrator always commits, a backend is never autonomous. Pick + plan one for this environment with `/agent-workflow-kit recipes` (read-only); the deployed how/why lives in your `docs/ai/` workflow docs.',
+];
+
 // A slot descriptor bundles everything the generic engine needs to operate on ONE marker pair.
 // `leadingBlank` controls whether the inserted empty pair gets a blank separator line above it — the
 // methodology insert keeps it (readability), the orchestration insert omits it to save a cap line
-// (the pair already sits right under the methodology block).
-const METHODOLOGY_DESCRIPTOR = {
+// (the pair already sits right under the methodology block). `knownPriorCanonicals` drives the refresh;
+// `upgradeSignature` + `upgradeAdvice` drive the read-only advisory for a CUSTOMIZED (non-matching) slot
+// that predates the current clause.
+export const METHODOLOGY_DESCRIPTOR = {
   startMarker: START_MARKER,
   endMarker: END_MARKER,
   anchor: METHODOLOGY_ANCHOR,
@@ -69,6 +95,10 @@ const METHODOLOGY_DESCRIPTOR = {
   leadingBlank: true,
   markerName: 'methodology',
   anchorLabel: 'methodology anchor (the "Read it before any code change." Session-Protocols line)',
+  knownPriorCanonicals: KNOWN_PRIOR_METHODOLOGY_SLOT,
+  upgradeSignature: 'Communication',
+  upgradeAdvice:
+    'the workflow-methodology pointer predates the communication-contract clause (deliver the artifact inline, lead with the result) — refresh it to the current canon, or add the clause by hand; the contract still applies.',
 };
 export const ORCHESTRATION_DESCRIPTOR = {
   startMarker: ORCH_START_MARKER,
@@ -78,6 +108,10 @@ export const ORCHESTRATION_DESCRIPTOR = {
   leadingBlank: false,
   markerName: 'orchestration',
   anchorLabel: 'orchestration anchor (the methodology end-marker line)',
+  knownPriorCanonicals: KNOWN_PRIOR_ORCH_SLOT,
+  upgradeSignature: '/agent-workflow-kit set-recipe',
+  upgradeAdvice:
+    'the orchestration-recipes pointer predates the read-at-start clause — add "read `docs/ai/orchestration.json` at session start; set it with /agent-workflow-kit set-recipe", or set your preference now with /agent-workflow-kit set-recipe.',
 };
 
 // ── generic marker-slot engine (descriptor-parameterized) ──────────────────────
@@ -160,16 +194,27 @@ export const ensureMarkerSlot = (text, descriptor) => {
 // Bootstrap/upgrade reconciliation policy (pure): ensure the slot exists, then fill it ONLY IF it
 // is empty (a filled/customized slot is preserved verbatim), enforcing the line cap — all as one step
 // the CLI commits with a single atomic write. On ANY error the INPUT bytes are returned unchanged.
-//   reconciled-inserted — slot was absent, inserted at the anchor, then filled.
-//   reconciled-filled   — slot existed but was empty, now filled.
-//   present-filled      — slot already carried content → preserved verbatim.
-//   error               — malformed slot, 0/>1 anchors, or cap exceeded → input unchanged.
+//   reconciled-inserted  — slot was absent, inserted at the anchor, then filled.
+//   reconciled-filled    — slot existed but was empty, now filled.
+//   reconciled-refreshed — slot was filled with a KNOWN PRIOR canonical → replaced with `fragment`.
+//   present-filled       — slot already carried CUSTOM content → preserved verbatim.
+//   error                — malformed slot, 0/>1 anchors, or cap exceeded → input unchanged.
 export const reconcileMarkerSlot = (text, descriptor, fragment, { maxLines } = {}) => {
   const ensured = ensureMarkerSlot(text, descriptor);
   if (ensured.status === 'error') return { status: 'error', text, error: ensured.error };
   const current = extractMarkerSlot(ensured.text, descriptor);
   const isEmpty = current == null || current.trim() === '';
   if (!isEmpty) {
+    // Canonical-refresh: a slot whose content normalize-matches a known prior canonical is STALE — replace
+    // it with the current `fragment`. A customized slot never matches → preserved verbatim. (`fragment`
+    // is empty for a customized slot — main() only sources it when markerSlotNeedsFill is true.)
+    const priors = descriptor.knownPriorCanonicals ?? [];
+    const matchesPrior = fragment && fragment.trim() !== '' && priors.some((p) => normalizeCanonical(p) === normalizeCanonical(current));
+    if (matchesPrior) {
+      const injected = injectIntoSlot(ensured.text, descriptor, fragment, { maxLines });
+      if (injected.status !== 'injected') return { status: 'error', text, error: injected.error };
+      return { status: 'reconciled-refreshed', text: injected.text };
+    }
     if (maxLines != null && lineCount(ensured.text) > maxLines) {
       return { status: 'error', text, error: `AGENTS.md is ${lineCount(ensured.text)} lines (cap ${maxLines}) — trim the file (a customized ${descriptor.markerName} slot must still fit the cap)` };
     }
@@ -189,7 +234,11 @@ export const markerSlotNeedsFill = (text, descriptor) => {
   const ensured = ensureMarkerSlot(text, descriptor);
   if (ensured.status === 'error') return false;
   const current = extractMarkerSlot(ensured.text, descriptor);
-  return current == null || current.trim() === '';
+  if (current == null || current.trim() === '') return true; // empty → fill
+  // filled-but-STALE (content matches a known prior canonical) → needs a refresh, so main() must
+  // re-source the fragment. A customized slot doesn't match → no source needed (preserved verbatim).
+  const priors = descriptor.knownPriorCanonicals ?? [];
+  return priors.some((p) => normalizeCanonical(p) === normalizeCanonical(current));
 };
 
 // ── methodology-slot exports (delegate to the generic engine, byte-for-byte) ────
@@ -217,6 +266,19 @@ export const methodologyProceduresHint = (text) => {
   return `the methodology pointer has no procedures route — add "${PROCEDURES_POINTER} <activity>" for auto-discovery; the activity procedures are reachable now via ${PROCEDURES_POINTER}.`;
 };
 
+// Generic read-only upgrade advisory (AD-025; the §1.6a/§1.9 reach to CUSTOMIZED filled slots): a slot
+// that is present + FILLED but lacks the descriptor's current-canon `upgradeSignature` (and so could not
+// be canonical-refreshed — its content is customized) gets a one-line note the upgrade flow surfaces.
+// Returns null for an absent / empty / malformed slot, or one that already carries the signature. Pure;
+// never edits the file (a customization is never rewritten — only the user decides).
+export const markerSlotUpgradeHint = (text, descriptor) => {
+  if (!descriptor.upgradeSignature) return null;
+  const content = extractMarkerSlot(text, descriptor);
+  if (content == null || content.trim() === '') return null; // only a FILLED slot
+  if (content.includes(descriptor.upgradeSignature)) return null; // already carries the current clause
+  return descriptor.upgradeAdvice;
+};
+
 // A cap-refusal is a SOFT, reported skip (distinct from a malformed/anchor STOP) — keyed off the
 // stable "(cap N)" substring both cap messages carry, so the dual-slot reconcile can skip the
 // orchestration pointer (loud) while keeping the methodology fill, instead of aborting both.
@@ -317,18 +379,23 @@ const main = async (argv) => {
       console.error(`[inject-methodology] reconcile refused — ${methResult.error}`);
       process.exit(1);
     }
-    const afterMeth = methResult.text; // === text when the methodology slot was already filled
+    const afterMeth = methResult.text; // === text when the methodology slot was already filled (custom)
     const describeMeth = {
       'reconciled-inserted': 'inserted the workflow-methodology pointer at the Session-Protocols anchor and filled it',
       'reconciled-filled': 'filled the empty workflow-methodology pointer',
+      'reconciled-refreshed': 'refreshed the workflow-methodology pointer to the current canon',
       'present-filled': 'workflow-methodology pointer already present',
     }[methResult.status];
-    // Read-only upgrade advisory (AD-019 §3.1a): a pre-existing FILLED methodology pointer that predates
-    // the procedures clause won't be re-rendered (reconcile preserves it verbatim), so surface a hint to
-    // add the procedures route. No mutation — purely a reported note appended to the success report.
-    const proceduresNote = methResult.status === 'present-filled' ? methodologyProceduresHint(afterMeth) : null;
-    const reportNote = () => {
-      if (proceduresNote) console.log(`[inject-methodology] note: ${proceduresNote}`);
+    // Read-only upgrade advisories for a CUSTOMIZED methodology pointer that reconcile preserved verbatim
+    // (a refreshed/filled/inserted slot already carries the current canon, so it gets none): the AD-019
+    // procedures route AND the §1.9 communication-contract clause. No mutation — reported notes only.
+    const notes = [];
+    if (methResult.status === 'present-filled') {
+      const p = methodologyProceduresHint(afterMeth); if (p) notes.push(p);
+      const u = markerSlotUpgradeHint(afterMeth, METHODOLOGY_DESCRIPTOR); if (u) notes.push(u);
+    }
+    const reportNotes = () => {
+      for (const n of notes) console.log(`[inject-methodology] note: ${n}`);
     };
 
     // ── Explicit [fragment.md] binds methodology ONLY → skip the orchestration reconcile ──
@@ -374,8 +441,15 @@ const main = async (argv) => {
         describeOrch = {
           'reconciled-inserted': 'inserted the orchestration-recipes pointer below it and filled it',
           'reconciled-filled': 'filled the empty orchestration-recipes pointer',
+          'reconciled-refreshed': 'refreshed the orchestration-recipes pointer to the current canon',
           'present-filled': 'orchestration-recipes pointer already present',
         }[orchResult.status];
+        // §1.6a advisory: a CUSTOMIZED orchestration pointer preserved verbatim, lacking the read-at-start
+        // clause, gets a read-only nudge (a refreshed/filled slot already carries it).
+        if (orchResult.status === 'present-filled') {
+          const u = markerSlotUpgradeHint(finalText, ORCHESTRATION_DESCRIPTOR);
+          if (u) notes.push(u);
+        }
       }
     }
 
@@ -384,12 +458,12 @@ const main = async (argv) => {
       // Byte-unchanged. Still report a cap-skip (it is not "nothing to do" — a pointer was withheld).
       if (orchSkipped) console.log(`[inject-methodology] reconcile: ${describeMeth}; ${describeOrch}.`);
       else console.log('[inject-methodology] reconcile: both pointers already present and filled — nothing to do (zero-diff).');
-      reportNote();
+      reportNotes();
       return;
     }
     await writeAtomic(finalText);
     console.log(`[inject-methodology] reconcile: ${describeMeth}; ${describeOrch}.`);
-    reportNote();
+    reportNotes();
     return;
   }