@sabaiway/agent-workflow-kit 14.10.0 → 14.12.0

package/tools/checker-gates-read.mjs

@@ -0,0 +1,156 @@
+// checker-gates-read.mjs — the READ-ONLY leaf of the kit-owned checker gates: the frozen candidate
+// table, the precondition probes, the declaration read and the one derivation the declare verb and
+// the profile-gap detector both call. Governing contract: docs/ai/specs/kit/tier/checker-gates/
+// (part checker-gates-read). No CLI (refuseDirectRun); nothing here writes.
+import { lstatSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { CHECKER_CLAIM, classifyCheckerClaim, dqUnsafePath } from './checker-claim.mjs';
+import { refuseDirectRun } from './direct-run.mjs';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { GATES_REL, KIT_CHECKER_CLAIMS, coverageDeclarationDefects, validateDeclaration } from './gates-declaration.mjs';
+import { escapeForLine, isLineUnsafe } from './source-size-core.mjs';
+
+const DEPLOYMENT_CHAIN = ['.', 'docs', 'docs/ai'];
+const NOT_APPLICABLE_CODES = new Set(['ENOENT', 'ENOTDIR']);
+const OK = 'ok';
+const ABSENT = 'absent';
+const FOREIGN = 'foreign';
+const SYMLINK_CLASS = 'symlink';
+const GIT_DIR = Object.freeze({ rel: '.git', kinds: ['directory', 'file'], what: 'a directory or a regular gitfile' });
+const STORE_ROOT = Object.freeze({ rel: 'docs/ai/specs/index.md', kinds: ['file'], what: 'a regular file' });
+const COVERAGE_SCOPE = Object.freeze({ rel: 'docs/ai/spec-coverage.json', kinds: ['file'], what: 'a regular file' });
+
+export const CANDIDATE_STATES = Object.freeze({
+  declared: 'declared',
+  idTaken: 'id-taken',
+  probeUnreadable: 'probe-unreadable',
+  notApplicable: 'not-applicable',
+  offered: 'offered',
+  withheld: 'withheld',
+});
+
+const lstatOf = (deps) => deps.lstatSync ?? lstatSync;
+
+export const isDeployed = (root, deps) => {
+  try {
+    return DEPLOYMENT_CHAIN.every((path, index) => {
+      const stat = lstatOf(deps)(resolve(root, path));
+      if (stat.isSymbolicLink()) return false;
+      return index < DEPLOYMENT_CHAIN.length - 1 || stat.isDirectory();
+    });
+  } catch {
+    return false;
+  }
+};
+
+const kindAt = (path, lstat) => {
+  try {
+    const stat = lstat(path);
+    if (stat.isSymbolicLink()) return { kind: SYMLINK_CLASS };
+    if (stat.isDirectory()) return { kind: 'directory' };
+    return { kind: stat.isFile() ? 'file' : 'other' };
+  } catch (error) {
+    if (NOT_APPLICABLE_CODES.has(error?.code)) return { kind: ABSENT };
+    return { unreadable: String(error?.code ?? error?.message ?? error) };
+  }
+};
+
+// A probe answers {} when its checker runs by design over the tree, else the state and its detail.
+const requiring = (...requirements) => (root, deps) => {
+  const judged = requirements.map((requirement) => ({ requirement, ...kindAt(resolve(root, requirement.rel), lstatOf(deps)) }));
+  const unreadable = judged.find((item) => item.unreadable !== undefined);
+  if (unreadable) {
+    return { state: CANDIDATE_STATES.probeUnreadable, detail: `${unreadable.requirement.rel}: ${unreadable.unreadable}` };
+  }
+  const missing = judged.find(({ requirement, kind }) => !requirement.kinds.includes(kind));
+  if (missing) return { state: CANDIDATE_STATES.notApplicable, detail: `${missing.requirement.rel} is not ${missing.requirement.what}` };
+  return {};
+};
+
+const candidate = (id, title, probe) => Object.freeze({ id, title, probe });
+
+export const CHECKER_GATE_CANDIDATES = Object.freeze([
+  candidate('control-bytes', 'No raw control byte in the work tree', requiring(GIT_DIR)),
+  candidate('plan-shape', 'Plans in flight keep the structural planning shape', requiring()),
+  candidate('spec-check', 'Feature-spec store structure — the whole store', requiring(STORE_ROOT)),
+  candidate(
+    'spec-coverage',
+    'No work without a specification — every in-scope tool is governed by a contract, or named in the shrink-only debt',
+    requiring(COVERAGE_SCOPE, STORE_ROOT),
+  ),
+]);
+
+const claimOf = (id) => KIT_CHECKER_CLAIMS.find((claim) => claim.id === id);
+
+const refusal = (name, detail) => (detail === undefined ? { refusal: name } : { refusal: name, detail: String(detail) });
+
+const attempt = (read) => {
+  try {
+    return { value: read() };
+  } catch (error) {
+    return { error };
+  }
+};
+
+const readDeclaration = (root, deps) => {
+  const read = readRegularFileNoFollow(resolve(root, GATES_REL), deps);
+  if (read.outcome === ABSENT) return refusal('declaration-absent');
+  if (read.outcome === FOREIGN) {
+    return read.className === SYMLINK_CLASS ? refusal('declaration-symlink') : refusal('declaration-not-regular', read.className);
+  }
+  if (read.outcome !== OK) return refusal('declaration-unreadable', read.code);
+  const parsed = attempt(() => JSON.parse(read.content));
+  if (parsed.error) return refusal('declaration-malformed', parsed.error.message);
+  const validated = attempt(() => validateDeclaration(parsed.value));
+  if (validated.error) return refusal('declaration-invalid', validated.error.message);
+  const gates = validated.value;
+  const defects = coverageDeclarationDefects(gates, root);
+  if (defects.length > 0) return refusal('declaration-coverage-defect', defects[0].message);
+  return { declaration: Object.hasOwn(parsed.value, '_README') ? { readme: parsed.value._README, gates } : { gates } };
+};
+
+const claimState = ({ id, screen }, gates, root) => {
+  const claimed = gates.some((gate) => {
+    const claim = classifyCheckerClaim(screen, gate.cmd, root);
+    return claim === CHECKER_CLAIM.CANONICAL || claim === CHECKER_CLAIM.ELSEWHERE;
+  });
+  if (claimed) return { state: CANDIDATE_STATES.declared };
+  const taken = gates.find((gate) => gate.id === id);
+  return taken ? { state: CANDIDATE_STATES.idTaken, detail: taken.cmd } : {};
+};
+
+const toolPathOf = ({ basename, screen }, deps) => join(deps.kitToolsDir ?? dirname(screen.canonical), basename);
+const isUnrenderable = (path) => dqUnsafePath(path) || isLineUnsafe(path);
+
+const judgeCandidate = ({ id, title, probe }, rendered, gates, root, deps) => {
+  const claimed = claimState(claimOf(id), gates, root);
+  if (claimed.state) return claimed;
+  const probed = probe(root, deps);
+  if (probed.state) return probed;
+  if (rendered.unrenderable) return { state: CANDIDATE_STATES.withheld };
+  return { state: CANDIDATE_STATES.offered, entry: JSON.stringify({ id, title, cmd: rendered.cmd }) };
+};
+
+const shapeOf = (id, { state, entry = null, detail }) => (detail === undefined ? { id, state, entry } : { id, state, entry, detail });
+
+export const judgeCheckerGates = (root, deps = {}) => {
+  if (!isDeployed(root, deps)) return refusal('no-deployment');
+  const loaded = readDeclaration(root, deps);
+  if (loaded.refusal) return loaded;
+  const rendered = CHECKER_GATE_CANDIDATES.map(({ id }) => {
+    const claim = claimOf(id);
+    const path = toolPathOf(claim, deps);
+    return isUnrenderable(path) ? { unrenderable: path } : { cmd: `node "${path}" ${claim.tail}` };
+  });
+  const judged = CHECKER_GATE_CANDIDATES.map((entry, index) => judgeCandidate(entry, rendered[index], loaded.declaration.gates, root, deps));
+  const firstWithheld = judged.findIndex(({ state }) => state === CANDIDATE_STATES.withheld);
+  const named = (item, index) => (index === firstWithheld
+    ? { ...item, detail: `the kit path cannot be rendered into a command: ${escapeForLine(rendered[index].unrenderable)}` }
+    : item);
+  return {
+    declaration: loaded.declaration,
+    candidates: CHECKER_GATE_CANDIDATES.map(({ id }, index) => shapeOf(id, named(judged[index], index))),
+  };
+};
+
+refuseDirectRun(import.meta.url);

package/tools/checker-gates.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// checker-gates.mjs — the declare verb of the kit-owned checker gates: previews the candidates the
+// read leaf judges and, on --apply, writes the offered ones add-only into docs/ai/gates.json.
+// Governing contract: docs/ai/specs/kit/tier/checker-gates/ (part checker-gates-verb).
+// main(argv, deps) returns, never exits, never asks.
+import { resolve } from 'node:path';
+import { assertDocsAiDeployment, writeDocsAiFileAtomic } from './atomic-write.mjs';
+import { safeLine } from './carriers.mjs';
+import { CANDIDATE_STATES, judgeCheckerGates } from './checker-gates-read.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { GATES_REL, coverageDeclarationDefects, validateDeclaration } from './gates-declaration.mjs';
+import { TRUST_CHAIN_DISCLOSURE, placeEntries } from './gates-init.mjs';
+
+const LF = String.fromCharCode(10);
+const ARGV_OFFSET = 2;
+const EXIT_SUCCESS = 0;
+const EXIT_REFUSAL = 1;
+const EXIT_USAGE = 2;
+const CWD_FLAG = '--cwd';
+const APPLY_FLAG = '--apply';
+const ONLY_FLAG = '--only';
+const HELP_FLAGS = new Set(['--help', '-h']);
+const APPLIED = 'applied';
+const INDENT = '  ';
+const JSON_INDENT = 2;
+const NOUN = 'a gate declaration';
+
+export const OUTCOME_LINES = Object.freeze({
+  candidate: (id, word, detail) => `${id}: ${word}${detail ? ` — ${safeLine(detail)}` : ''}`,
+  entry: (json) => `${INDENT}entry: ${json}`,
+  disclosure: () => TRUST_CHAIN_DISCLOSURE,
+  refusal: (name, detail) => `checker-gates: refused — ${name}${detail ? `: ${safeLine(detail)}` : ''}`,
+  usage: (problem) => `usage: checker-gates.mjs --cwd DIR [--apply] [--only ID]... — ${safeLine(problem)}`,
+  onlyNotOffered: (ids, offered) => `${ONLY_FLAG} names ids not offered: ${ids.join(', ')} (offered: ${offered.join(', ') || 'none'})`,
+  help: () => [
+    'checker-gates.mjs --cwd DIR [--apply] [--only ID]...',
+    'Previews the kit-owned checker gates the project in DIR can declare; writes nothing by default.',
+    '--apply writes the offered entries into docs/ai/gates.json, add-only; --only ID narrows the write.',
+    'Exit codes: 0 done, 1 one named refusal, 2 usage.',
+  ].join(LF),
+});
+
+const result = (code, stdout = '', stderr = '') => ({ code, stdout, stderr });
+const refuse = (name, detail) => result(EXIT_REFUSAL, '', OUTCOME_LINES.refusal(name, detail));
+const causeOf = (error) => String(error?.message ?? error);
+
+const parseArgs = (argv) => {
+  if (argv.length === 1 && HELP_FLAGS.has(argv[0])) return { help: true };
+  const options = { only: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (flag === CWD_FLAG) {
+      if (options.cwd !== undefined) return { problem: `${CWD_FLAG} given twice` };
+      if (value === undefined || value.startsWith('-')) return { problem: `${CWD_FLAG} needs a directory` };
+      options.cwd = value;
+      index += 1;
+    } else if (flag === APPLY_FLAG) {
+      if (options.apply) return { problem: `${APPLY_FLAG} given twice` };
+      options.apply = true;
+    } else if (flag === ONLY_FLAG) {
+      if (value === undefined || value.startsWith('-')) return { problem: `${ONLY_FLAG} needs a gate id` };
+      if (!options.only.includes(value)) options.only.push(value);
+      index += 1;
+    } else {
+      return { problem: `unknown argument ${flag}` };
+    }
+  }
+  if (options.cwd === undefined) return { problem: `${CWD_FLAG} is required` };
+  return { cwd: options.cwd, apply: Boolean(options.apply), only: options.only };
+};
+
+export const mergeCheckerGates = (loaded, selected, root) => {
+  const readme = Object.hasOwn(loaded, 'readme') ? { _README: loaded.readme } : {};
+  const merged = { ...readme, gates: placeEntries(loaded.gates, selected, root) };
+  validateDeclaration(merged);
+  const defects = coverageDeclarationDefects(merged.gates, root);
+  if (defects.length > 0) return { refusal: 'coverage-defect', detail: defects[0].message };
+  return { merged, body: `${JSON.stringify(merged, null, JSON_INDENT)}${LF}` };
+};
+
+const renderLines = (candidates) => {
+  const disclose = candidates.some(({ state }) => state === CANDIDATE_STATES.offered || state === APPLIED);
+  const lines = candidates.flatMap(({ id, state, entry, detail }) => (state === CANDIDATE_STATES.offered
+    ? [OUTCOME_LINES.candidate(id, state, detail), OUTCOME_LINES.entry(entry)]
+    : [OUTCOME_LINES.candidate(id, state, detail)]));
+  return disclose ? [OUTCOME_LINES.disclosure(), ...lines] : lines;
+};
+
+const writeSelected = (root, judged, selected, deps) => {
+  const merge = mergeCheckerGates(judged.declaration, selected.map(({ entry }) => JSON.parse(entry)), root);
+  if (merge.refusal) return { refusal: refuse(merge.refusal, merge.detail) };
+  try {
+    writeDocsAiFileAtomic(root, GATES_REL, merge.body, deps, { noun: NOUN, rel: GATES_REL });
+  } catch (error) {
+    return { refusal: refuse('write-failed', causeOf(error)) };
+  }
+  const written = new Set(selected.map(({ id }) => id));
+  return { candidates: judged.candidates.map((item) => (written.has(item.id) ? { ...item, state: APPLIED, entry: null } : item)) };
+};
+
+const runVerb = (options, deps) => {
+  const root = resolve(options.cwd);
+  try {
+    assertDocsAiDeployment(root, deps, { noun: NOUN, rel: GATES_REL });
+  } catch (error) {
+    return refuse('no-deployment', causeOf(error));
+  }
+  const judged = judgeCheckerGates(root, deps);
+  if (judged.refusal) return refuse(judged.refusal, judged.detail);
+  const offered = judged.candidates.filter(({ state }) => state === CANDIDATE_STATES.offered);
+  const offeredIds = offered.map(({ id }) => id);
+  const unknown = options.only.filter((id) => !offeredIds.includes(id));
+  if (unknown.length > 0) return result(EXIT_USAGE, '', OUTCOME_LINES.usage(OUTCOME_LINES.onlyNotOffered(unknown, offeredIds)));
+  const selected = options.only.length > 0 ? offered.filter(({ id }) => options.only.includes(id)) : offered;
+  if (!options.apply || selected.length === 0) return result(EXIT_SUCCESS, renderLines(judged.candidates).join(LF));
+  const written = writeSelected(root, judged, selected, deps);
+  if (written.refusal) return written.refusal;
+  return result(EXIT_SUCCESS, renderLines(written.candidates).join(LF));
+};
+
+export const main = (argv, deps = {}) => {
+  const parsed = parseArgs(argv);
+  if (parsed.help) return result(EXIT_SUCCESS, OUTCOME_LINES.help());
+  if (parsed.problem) return result(EXIT_USAGE, '', OUTCOME_LINES.usage(parsed.problem));
+  return runVerb(parsed, deps);
+};
+
+if (isDirectRun(import.meta.url)) {
+  const outcome = main(process.argv.slice(ARGV_OFFSET));
+  if (outcome.stdout) console.log(outcome.stdout);
+  if (outcome.stderr) console.error(outcome.stderr);
+  process.exitCode = outcome.code;
+}

package/tools/direct-run.mjs

@@ -65,6 +65,10 @@ export const LIBRARY_ONLY_MODULES = Object.freeze({
   'review-roster.mjs': '/agent-workflow-kit recipes',
   'review-roster-resolve.mjs': '/agent-workflow-kit recipes',
   'set-recipe-roster.mjs': '/agent-workflow-kit set-recipe',
+  // The read half of the tier offer: the upgrade's step-3 `tier` item runs the offer that uses it.
+  'reference-profile.mjs': '/agent-workflow-kit upgrade',
+  // The read half of the checker-gates verb: the same step-3 `tier` item runs the verb that uses it.
+  'checker-gates-read.mjs': '/agent-workflow-kit upgrade',
 });
 
 // The frozen refusal line. One line, names the module, names the command.

package/tools/doc-parity.mjs

@@ -330,8 +330,8 @@ read only from the surface anchored between the doc's advisor-matrix begin/end m
 elsewhere in the doc can neither stand in for it nor mask its drift, and a drifted header inside the
 anchor fails closed rather than falling through to another table.
 
---check exits 0/1 as a gate (declare it in docs/ai/gates.json by hand). --json prints the structured
-result. Default prints the per-binding report.
+--check exits 0/1 as a gate over the kit's own package, the gate a kit maintainer runs. --json prints
+the structured result. Default prints the per-binding report.
 
 Read-only: never writes, never commits, spawns nothing. Exit codes: 0 pass (or plain report); 1 drift
 (under --check) or error; 2 usage.`;

package/tools/gates-declaration.mjs

@@ -9,6 +9,7 @@
 import { readFileSync, lstatSync, realpathSync } from 'node:fs';
 import { join, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { CHECKER_CLAIM, checkerClaimTool, classifyCheckerClaim } from './checker-claim.mjs';
 import { fail, loadConfig, CONFIG_REL } from './orchestration-config.mjs';
 import { isCoverageProducerGate } from './coverage-producer.mjs';
 import { matchesSourceSizeGate } from './source-size-core.mjs';
@@ -224,8 +225,21 @@ export const isReviewDependentGate = (gate, projectDir) =>
 // "does this declaration verify the PROJECT?" through the review-dependent predicate alone read a
 // matrix of nothing but that gate as project verification. Three surfaces asked it, each knowing a
 // different half; this is the one home, so a future kit checker is added once.
+// KIT_CHECKER_CLAIMS is the one statement of the four declarable kit checkers' basenames, tails and
+// canonical paths (docs/ai/specs/kit/tier/checker-gates/, part checker-claim-tail).
+const kitCheckerClaim = (id, basename, tail) => Object.freeze({
+  id, basename, tail, screen: checkerClaimTool(basename, fileURLToPath(new URL(`./${basename}`, import.meta.url)), tail),
+});
+export const KIT_CHECKER_CLAIMS = Object.freeze([
+  kitCheckerClaim('control-bytes', 'control-bytes.mjs', '--check'),
+  kitCheckerClaim('plan-shape', 'plan-shape-cli.mjs', '--check --in-flight'),
+  kitCheckerClaim('spec-check', 'spec-check-cli.mjs', '--all'),
+  kitCheckerClaim('spec-coverage', 'spec-coverage-cli.mjs', '--check'),
+]);
+
 export const isKitOwnedCheckerGate = (gate, projectDir) =>
-  isReviewDependentGate(gate, projectDir) || matchesSourceSizeGate(gate.cmd, projectDir);
+  isReviewDependentGate(gate, projectDir) || matchesSourceSizeGate(gate.cmd, projectDir)
+  || KIT_CHECKER_CLAIMS.some(({ screen }) => classifyCheckerClaim(screen, gate.cmd, projectDir) === CHECKER_CLAIM.CANONICAL);
 
 // ── the pregate subset derivation (#66 / Decision 7 — ONE home for producer and factory) ─────
 

package/tools/gates-init.mjs

@@ -4,9 +4,9 @@
 // explicitly-consenting prose (the init/bootstrap flows and the gates.md consent-fill section) —
 // it is NOT a routable mode token, it sits OUTSIDE every velocity allowlist tier (a
 // consent-per-run writer is never pre-approved), and the shipped gates.json TEMPLATE stays EMPTY
-// (AD-021/AD-038): a populated declaration is per-entry maintainer consent recorded through this
-// preview, never auto-seeding. ONE lifecycle contract: this preview runs at INIT; at UPGRADE the
-// only gates.json writer is the consented legacy migration.
+// (AD-021/AD-038): a populated declaration is per-entry maintainer consent recorded through a
+// consented writer (this preview among them), never auto-seeding. This preview runs at INIT; at UPGRADE step 3's
+// run-list changes entries only through the consented legacy migration and, under `tier`, checker-gates.mjs.
 //
 // What it offers (the derivation invariants, test-pinned) — CLOSED-WORLD since AD-052: an entry
 // is offered only when every axis is proven safe by MEMBERSHIP in a finite, test-guarded set,

package/tools/profile-gaps.mjs

@@ -1,5 +1,8 @@
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { CANDIDATE_STATES, isDeployed, judgeCheckerGates } from './checker-gates-read.mjs';
+import { CONFIG_REL, validateConfig } from './orchestration-config.mjs';
+import { TIER_TARGETS } from './reference-profile.mjs';
 import {
   RULES_REGIONS,
   extractRegionBy,
@@ -11,6 +14,13 @@ import {
 } from './rules-regions.mjs';
 
 const GAP_ID = 'story-sessions-section';
+const SLOTS_ID = 'epic-task-slots';
+const STORE_ID = 'epic-store-seeded';
+const STORE_PATH = 'docs/ai/epics';
+const CHECKER_GATES_ID = 'checker-gates-declared';
+const TIER_PREVIEW_PATH = fileURLToPath(new URL('./tier-preview.mjs', import.meta.url));
+const CHECKER_GATES_PATH = fileURLToPath(new URL('./checker-gates.mjs', import.meta.url));
+const UNDECIDED_STATES = [CANDIDATE_STATES.idTaken, CANDIDATE_STATES.probeUnreadable, CANDIDATE_STATES.withheld];
 const STORY_ID = 'story-sessions';
 const TEMPLATE_CANON = 'template';
 const ENCODING = 'utf8';
@@ -28,6 +38,15 @@ const REASONS = Object.freeze({
   fileAbsent: 'file-absent',
   fileSymlink: 'file-symlink',
   fileUnreadable: 'file-unreadable',
+  noDeployment: 'no-deployment',
+  configAbsent: 'config-absent',
+  configSymlink: 'config-symlink',
+  configUnreadable: 'config-unreadable',
+  configMalformed: 'config-malformed',
+  configInvalid: 'config-invalid',
+  storeNotDirectory: 'store-not-directory',
+  storeSymlink: 'store-symlink',
+  storeUnreadable: 'store-unreadable',
 });
 const TEMPLATE_REGIONS = RULES_REGIONS.filter(({ canon }) => canon === TEMPLATE_CANON);
 const STORY_REGION = RULES_REGIONS.find(({ id }) => id === STORY_ID);
@@ -81,6 +100,73 @@ const detectStorySessions = ({ root, deps }) => {
   return { verdict: VERDICTS.absent };
 };
 
+const parseConfig = (bytes) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(decodeUtf8Strict(bytes));
+  } catch (error) {
+    return error instanceof SyntaxError ? { reason: REASONS.configMalformed } : { reason: REASONS.configUnreadable };
+  }
+  try {
+    return { config: validateConfig(parsed) };
+  } catch {
+    return { reason: REASONS.configInvalid };
+  }
+};
+
+export const readTierConfig = (root, deps) => {
+  const path = resolve(root, CONFIG_REL);
+  try {
+    const stat = deps.lstatSync(path);
+    if (stat.isSymbolicLink()) return { reason: REASONS.configSymlink };
+    if (!stat.isFile()) return { reason: REASONS.configUnreadable };
+  } catch (error) {
+    return { reason: error?.code === MISSING_FILE_CODE ? REASONS.configAbsent : REASONS.configUnreadable };
+  }
+  let bytes;
+  try {
+    bytes = deps.readFileSync(path);
+  } catch {
+    return { reason: REASONS.configUnreadable };
+  }
+  return parseConfig(bytes);
+};
+
+const detectSlots = ({ root, deps }) => {
+  if (!isDeployed(root, deps)) return reportUndecidable(REASONS.noDeployment);
+  const read = readTierConfig(root, deps);
+  if (read.reason) return reportUndecidable(read.reason);
+  const declared = TIER_TARGETS.every(({ activity, slot }) => Object.hasOwn(read.config[activity] ?? {}, slot));
+  return { verdict: declared ? VERDICTS.present : VERDICTS.absent };
+};
+
+const detectStore = ({ root, deps }) => {
+  if (!isDeployed(root, deps)) return reportUndecidable(REASONS.noDeployment);
+  let stat;
+  try {
+    stat = deps.lstatSync(resolve(root, STORE_PATH));
+  } catch (error) {
+    if (error?.code === MISSING_FILE_CODE) return { verdict: VERDICTS.absent };
+    return reportUndecidable(REASONS.storeUnreadable);
+  }
+  if (stat.isSymbolicLink()) return reportUndecidable(REASONS.storeSymlink);
+  if (!stat.isDirectory()) return reportUndecidable(REASONS.storeNotDirectory);
+  return { verdict: VERDICTS.present };
+};
+
+const detectCheckerGates = ({ root, deps }) => {
+  const judged = judgeCheckerGates(root, deps);
+  if (judged.refusal) return reportUndecidable(judged.refusal);
+  if (judged.candidates.some(({ state }) => state === CANDIDATE_STATES.offered)) return { verdict: VERDICTS.absent };
+  const undecided = judged.candidates.find(({ state }) => UNDECIDED_STATES.includes(state));
+  return undecided ? reportUndecidable(undecided.state) : { verdict: VERDICTS.present };
+};
+
+const tierPreview = (root) => buildInsertPreview(root, TIER_PREVIEW_PATH);
+
 export const PROFILE_GAPS = Object.freeze([
   Object.freeze({ id: GAP_ID, detect: detectStorySessions, apply: (root) => buildInsertPreview(root) }),
+  Object.freeze({ id: SLOTS_ID, detect: detectSlots, apply: tierPreview }),
+  Object.freeze({ id: STORE_ID, detect: detectStore, apply: tierPreview }),
+  Object.freeze({ id: CHECKER_GATES_ID, detect: detectCheckerGates, apply: (root) => buildInsertPreview(root, CHECKER_GATES_PATH) }),
 ]);

package/tools/reference-profile.mjs

@@ -0,0 +1,69 @@
+// reference-profile.mjs — the READ-ONLY leaf over the running kit's reference profile and a
+// project's decline record: the frozen epic/task target table, the shipped profile reader, the
+// decline record reader and the currency rule. Governing contract: docs/ai/specs/kit/tier/tier-offer/.
+// No CLI (refuseDirectRun); every read goes through injected deps; nothing here writes.
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { refuseDirectRun } from './direct-run.mjs';
+
+const PROFILE_PATH = fileURLToPath(new URL('../references/reference-profile.json', import.meta.url));
+const DECLINES_REL = 'docs/ai/profile-declines.json';
+const PROFILE_KEYS = ['items', 'lineage', 'name', 'schema'];
+const ITEM_KEYS = ['has', 'id', 'story'];
+const RECORD_KEYS = ['declined', 'schema'];
+const SCHEMA = 1;
+const OK = 'ok';
+const ABSENT = 'absent';
+const SYMLINK_CLASS = 'symlink';
+
+const target = (activity, slot, candidates) => Object.freeze({ activity, slot, candidates: Object.freeze(candidates) });
+
+export const TIER_TARGETS = Object.freeze([
+  target('epic', 'author', ['subagent', 'solo']),
+  target('epic', 'review', ['reviewed', 'solo']),
+  target('task', 'author', ['delegated', 'subagent', 'solo']),
+  target('task', 'execute', ['delegated', 'subagent', 'solo']),
+]);
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const hasKeys = (value, keys) => isPlainObject(value) && Object.keys(value).sort().join() === keys.join();
+const isText = (value) => typeof value === 'string' && value.length > 0;
+const parseJson = (text) => {
+  try {
+    return { value: JSON.parse(text) };
+  } catch {
+    return null;
+  }
+};
+
+const isProfile = (value) => hasKeys(value, PROFILE_KEYS) && value.schema === SCHEMA
+  && isText(value.name) && isText(value.lineage) && Array.isArray(value.items)
+  && value.items.every((item) => hasKeys(item, ITEM_KEYS) && isText(item.id) && isText(item.story) && isText(item.has));
+
+const isRecord = (value) => hasKeys(value, RECORD_KEYS) && value.schema === SCHEMA && isPlainObject(value.declined)
+  && Object.entries(value.declined).every(([id, lineage]) => id.length > 0 && typeof lineage === 'string');
+
+export const readShippedProfile = (deps = {}) => {
+  const read = readRegularFileNoFollow(deps.profilePath ?? PROFILE_PATH, deps);
+  if (read.outcome !== OK) return { refusal: 'profile-unreadable' };
+  const parsed = parseJson(read.content);
+  if (parsed === null || !isProfile(parsed.value)) return { refusal: 'profile-malformed' };
+  return { profile: parsed.value };
+};
+
+export const readDeclines = (root, deps = {}) => {
+  const read = readRegularFileNoFollow(join(root, DECLINES_REL), deps);
+  if (read.outcome === ABSENT) return { absent: true };
+  if (read.outcome !== OK) {
+    return { refusal: read.className === SYMLINK_CLASS ? 'declines-symlink' : 'declines-unreadable' };
+  }
+  const parsed = parseJson(read.content);
+  if (parsed === null || !isRecord(parsed.value)) return { refusal: 'declines-malformed' };
+  return { declined: parsed.value.declined };
+};
+
+export const isDeclineCurrent = (declined, id, lineage) =>
+  isPlainObject(declined) && Object.hasOwn(declined, id) && declined[id] === lineage;
+
+refuseDirectRun(import.meta.url);