@sabaiway/agent-workflow-kit 14.36.0 → 14.37.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 14.37.0 — the first project rules theme, project layout, ships with the writer of a record of what each effective rules file was built from and a read-only check; nothing is laid into a project yet (AD-189)
+
+**The kit now carries default project rules as thematic prose files, starting with project layout, and a command
+line that checks the file agents read still stands for its sources.** This release ships the files' shape, the theme
+registry, the record's writer and the check; the upgrade op that lays the theme into your project comes in a later release,
+so this one writes no rules file into your project.
+
+- **Four files per theme.** `docs/ai/rules/<theme>.md` is the kit's rules, `docs/ai/rules/local/<theme>.md` is
+  yours and wins, `docs/ai/rules/effective/<theme>.md` is what agents read, and
+  `docs/ai/rules/effective/sources.json` records, per theme, the sha256 of the kit, local (or `absent`) and effective
+  files. Rules are plain prose with no keys; with no local file the effective file equals the kit file, with one an
+  agent merges the two by meaning once. No code merges two texts.
+- **The project-layout template** (`references/rules/project-layout.md`): a module is a directory holding its code,
+  tests, mocks, fixtures and command-line entry; its index exports only what is used outside; no README repeats its
+  spec; modules nest by meaning, never by technical layer; a spec's path mirrors its module's; old code keeps its
+  place as a recorded exception.
+- **`node tools/project-rules/rules-cli.mjs --check [--cwd <project>]`** prints one line per theme — `absent`,
+  `current`, `drift` naming every moved file, or `record` with its state — and writes nothing. It exits 0 when every
+  theme is `current` or `absent`, 1 otherwise, every stop line saying `run /agent-workflow-kit upgrade`; 2 is usage.
+  It judges only against the record, never against the bundled template.
+- **`--record --theme <name> --kit <sha256> --local <sha256|absent> --effective <sha256>`** is the merging agent's
+  call: it writes the theme's entry only when the files still hash to the passed digests and the effective file fits
+  the merge, and otherwise exits 1 naming the failed condition, writing nothing.
+
+**Upgrade note.** No step: the module ships, and no rules file reaches a project until the later upgrade op.
+
 ## 14.36.0 — the review lens runs on opus/high by default and its model is a setting; the task tier offer proposes the executor, not codex (AD-188)
 
 **The bundled review lens now takes its model and effort from `docs/ai/vehicles.json`, opus and high unless you set

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow". New to the epic, story and task tier? Run `/agent-workflow-kit tier`. A typed decision with a confidence from Jev? Run `/agent-workflow-kit jev`.
 disable-model-invocation: true
 metadata:
-  version: '14.36.0'
+  version: '14.37.0'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "14.36.0",
+  "version": "14.37.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/rules/project-layout.md

@@ -0,0 +1,41 @@
+---
+type: rules
+lastUpdated: 2026-10-18
+scope: permanent
+staleAfter: never
+owner: kit
+maxLines: 80
+---
+
+# Project layout
+
+Where a file goes is decided by what it means, never by where there is room.
+
+## A module is a directory
+
+A module is a directory holding everything that belongs to it: its code, its tests, its mocks, its
+fixtures and its command-line entry. Tests live inside the module, next to the code they check, never
+in a separate tree.
+
+## The index is the one door
+
+The module's own index file, the one its language uses for that purpose, exports only what is used
+outside the module. Nothing outside reaches past the index into a file of the module.
+
+## The spec is the description
+
+No README repeats the module's spec. The spec describes the module; a README that restates it drifts
+from it.
+
+## Modules nest by meaning
+
+Modules nest by meaning: a slice holds its modules, and a shared layer holds what several slices use.
+Modules never nest by technical layer, so there is no directory of all controllers or all helpers.
+
+## The spec mirrors the module
+
+A spec's path mirrors its module's path, so the name of one gives the place of the other.
+
+## Old code
+
+Old code keeps its place as a recorded exception. New and touched code follows these rules.

package/tools/project-rules/index.mjs

@@ -0,0 +1,3 @@
+// The one door of the project-rules module. Contract: docs/ai/specs/kit/project-rules/index.md.
+export { THEMES } from './themes.mjs';
+export { checkRules } from './rules-check.mjs';

package/tools/project-rules/rules-check.mjs

@@ -0,0 +1,115 @@
+// The read-only check: one verdict per registry theme, judged only against the record. It imports no
+// writer and reads every file through readUnder, so no symlink inside the root is followed. Contract:
+// docs/ai/specs/kit/project-rules/rules-check.md.
+
+import { createHash } from 'node:crypto';
+import { lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { readFileBytesNoFollow } from '../fs-read-nofollow.mjs';
+import { RECORD_PATH, THEMES, themePaths } from './themes.mjs';
+
+const UPGRADE = 'run /agent-workflow-kit upgrade';
+const EDIT_NOTE = 'move your edit to local/, a rebuild drops it';
+const DIGEST = /^[0-9a-f]{64}$/;
+const ROLES = ['kit', 'local', 'effective'];
+
+export const digestOf = (bytes) => createHash('sha256').update(bytes).digest('hex');
+
+const isDigest = (value) => typeof value === 'string' && DIGEST.test(value);
+
+// readUnder(root, rel, deps?) → a readFileBytesNoFollow outcome for root/rel, or foreign or error
+// without a read when a directory on rel's path inside root is a symlink, not a directory, or cannot be
+// inspected; a missing directory ends the walk and the leaf then reads absent.
+export const readUnder = (root, rel, deps = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const parts = rel.split('/');
+  for (let i = 1; i < parts.length; i += 1) {
+    const prefix = parts.slice(0, i).join('/');
+    let st;
+    try {
+      st = lstat(join(root, prefix));
+    } catch (err) {
+      if (err && err.code === 'ENOENT') break;
+      return { outcome: 'error', code: `${prefix} cannot be inspected (${err?.code ?? err})` };
+    }
+    if (st.isSymbolicLink() || !st.isDirectory()) return { outcome: 'foreign', code: `${prefix} is a symlink or not a directory` };
+  }
+  return (deps.read ?? readFileBytesNoFollow)(join(root, rel));
+};
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const sameKeys = (value, keys) => JSON.stringify(Object.keys(value).sort()) === JSON.stringify([...keys].sort());
+
+// parseRecord(text, themes?) → { ok: true, record } | { ok: false, reason }: the record's one schema reader.
+export const parseRecord = (text, themes = THEMES) => {
+  const bad = (reason) => ({ ok: false, reason });
+  let record;
+  try {
+    record = JSON.parse(text);
+  } catch {
+    return bad('not JSON');
+  }
+  if (!isObject(record) || !sameKeys(record, ['schema', 'themes'])) return bad('the keys are not exactly schema and themes');
+  if (record.schema !== 1) return bad(`schema ${JSON.stringify(record.schema)} is not 1`);
+  if (!isObject(record.themes)) return bad('themes is not an object');
+  const names = new Set(themes.map((theme) => theme.name));
+  for (const [name, entry] of Object.entries(record.themes)) {
+    if (!names.has(name)) return bad(`theme ${name} is not in the registry`);
+    if (!isObject(entry) || !sameKeys(entry, ROLES)) return bad(`the entry of ${name} does not hold exactly kit, local and effective`);
+    if (!isDigest(entry.kit) || !isDigest(entry.effective)) return bad(`the entry of ${name} holds a value that is not a sha256`);
+    if (entry.local !== 'absent' && !isDigest(entry.local)) return bad(`the local of ${name} is neither a sha256 nor absent`);
+  }
+  return { ok: true, record };
+};
+
+// readRecord(outcome, themes) → { ok: true, themes } | { ok: false, reason }: an absent record holds no entry.
+export const readRecord = (outcome, themes = THEMES) => {
+  if (outcome.outcome === 'absent') return { ok: true, themes: {} };
+  if (outcome.outcome !== 'ok') return { ok: false, reason: 'it is not a regular file this check can read' };
+  const parsed = parseRecord(outcome.bytes.toString('utf8'), themes);
+  return parsed.ok ? { ok: true, themes: parsed.record.themes } : parsed;
+};
+
+const recordVerdict = (theme, state, detail) =>
+  ({ theme, verdict: 'record', state, line: `${theme}: record (${state}) — ${detail} — ${UPGRADE}` });
+
+const judgeTheme = (theme, paths, files, record) => {
+  if (!record.ok) return recordVerdict(theme, 'unreadable-record', `${paths.record} is unreadable: ${record.reason}`);
+  const unreadable = ROLES.find((role) => !['ok', 'absent'].includes(files[role].outcome));
+  if (unreadable) return recordVerdict(theme, 'unreadable-file', `${paths[unreadable]} is not a regular file this check can read`);
+  const present = (role) => files[role].outcome === 'ok';
+  const entry = record.themes[theme];
+  if (entry === undefined) {
+    const existing = ROLES.find(present);
+    if (existing === undefined) return { theme, verdict: 'absent', line: `${theme}: absent` };
+    return recordVerdict(theme, 'no-entry', `no record entry while ${paths[existing]} exists`);
+  }
+  const missing = ['kit', 'effective'].find((role) => !present(role));
+  if (missing) return recordVerdict(theme, 'missing-file', `${paths[missing]} is missing under its record entry`);
+  const differs = {
+    kit: digestOf(files.kit.bytes) !== entry.kit,
+    local: present('local') ? digestOf(files.local.bytes) !== entry.local : entry.local !== 'absent',
+    effective: digestOf(files.effective.bytes) !== entry.effective,
+  };
+  const moved = ROLES.filter((role) => differs[role])
+    .map((role) => (role === 'effective' ? { role, file: paths[role], note: EDIT_NOTE } : { role, file: paths[role] }));
+  if (moved.length > 0) {
+    const named = moved.map(({ file, note }) => (note ? `${file} (${note})` : file)).join('; ');
+    return { theme, verdict: 'drift', moved, line: `${theme}: drift — moved ${named} — ${UPGRADE}` };
+  }
+  if (!present('local') && !files.kit.bytes.equals(files.effective.bytes)) {
+    return recordVerdict(theme, 'kit-effective-differ', `no local file, yet ${paths.effective} differs from ${paths.kit}`);
+  }
+  return { theme, verdict: 'current', line: `${theme}: current` };
+};
+
+// checkRules(root, deps?) → [{ theme, verdict, line, moved?, state? }] in registry order; writes nothing.
+export const checkRules = (root, deps = {}) => {
+  const themes = deps.themes ?? THEMES;
+  const record = readRecord(readUnder(root, RECORD_PATH, deps), themes);
+  return themes.map(({ name }) => {
+    const paths = themePaths(name);
+    const files = Object.fromEntries(ROLES.map((role) => [role, readUnder(root, paths[role], deps)]));
+    return judgeTheme(name, paths, files, record);
+  });
+};

package/tools/project-rules/rules-cli.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// The command line over the read-only check and the record writer. Contract:
+// docs/ai/specs/kit/project-rules/rules-cli.md. Exit codes: 0 accept; 1 a stop or a refused record; 2 usage.
+
+import { resolve } from 'node:path';
+import { isDirectRun } from '../direct-run.mjs';
+import { checkRules } from './rules-check.mjs';
+import { writeRecord } from './rules-record.mjs';
+
+const USAGE = `project-rules — the effective rule files still stand for their sources.
+
+Usage:
+  node rules-cli.mjs --check [--cwd <project>]
+  node rules-cli.mjs --record --theme <name> --kit <sha256> --local <sha256|absent> --effective <sha256> [--cwd <project>]
+
+--check   one line per theme: current, absent, drift or record; writes nothing.
+--record  the merging agent's call: records the digests of the inputs it read and of the file it wrote.
+
+Exit codes: 0 accept; 1 a stop or a refused record; 2 usage.`;
+
+const MODES = { '--check': [], '--record': ['--theme', '--kit', '--local', '--effective'] };
+const VALUED = new Set(['--cwd', '--theme', '--kit', '--local', '--effective']);
+
+// parseArgs(argv) → { mode, options } | { help: true } | { error }; reads nothing.
+const parseArgs = (argv) => {
+  if (argv.length === 1 && (argv[0] === '--help' || argv[0] === '-h')) return { help: true };
+  let mode = null;
+  const options = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (Object.hasOwn(MODES, arg)) {
+      if (mode !== null) return { error: `${mode} and ${arg} are two modes; one run takes exactly one` };
+      mode = arg;
+    } else if (VALUED.has(arg)) {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith('--')) return { error: `${arg} needs a value` };
+      if (arg in options) return { error: `${arg} is given twice` };
+      options[arg] = value;
+      i += 1;
+    } else {
+      return { error: `unknown argument: ${arg}` };
+    }
+  }
+  if (mode === null) return { error: 'no mode: give --check or --record' };
+  const allowed = new Set(['--cwd', ...MODES[mode]]);
+  const extra = Object.keys(options).find((name) => !allowed.has(name));
+  if (extra) return { error: `${mode} does not take ${extra}` };
+  const absent = MODES[mode].find((name) => !(name in options));
+  if (absent) return { error: `${mode} needs ${absent}` };
+  return { mode, options };
+};
+
+const lines = (list) => (list.length === 0 ? '' : `${list.join('\n')}\n`);
+
+// main(argv, ctx?) → { code, stdout, stderr }; never exits the process.
+export const main = (argv, ctx = {}) => {
+  const parsed = parseArgs(argv);
+  if (parsed.help) return { code: 0, stdout: `${USAGE}\n`, stderr: '' };
+  if (parsed.error) return { code: 2, stdout: '', stderr: `project-rules: ${parsed.error}\n\n${USAGE}\n` };
+  const root = resolve(ctx.cwd ?? process.cwd(), parsed.options['--cwd'] ?? '.');
+  const deps = ctx.deps ?? {};
+  if (parsed.mode === '--check') {
+    const verdicts = checkRules(root, deps);
+    const stops = verdicts.filter(({ verdict }) => verdict !== 'current' && verdict !== 'absent');
+    return { code: stops.length === 0 ? 0 : 1, stdout: lines(verdicts.map(({ line }) => line)), stderr: '' };
+  }
+  const { '--theme': theme, '--kit': kit, '--local': local, '--effective': effective } = parsed.options;
+  const result = writeRecord(root, theme, { kit, local, effective }, deps);
+  if (!result.ok) return { code: 1, stdout: '', stderr: `project-rules: --record refused (${result.condition}) — ${result.message}; nothing written\n` };
+  return { code: 0, stdout: `project-rules: recorded ${theme} in ${result.path}\n`, stderr: '' };
+};
+
+if (isDirectRun(import.meta.url)) {
+  const { code, stdout, stderr } = main(process.argv.slice(2));
+  process.stdout.write(stdout);
+  process.stderr.write(stderr);
+  process.exitCode = code;
+}

package/tools/project-rules/rules-record.mjs

@@ -0,0 +1,78 @@
+// The record's one writer: docs/ai/rules/effective/sources.json states what every effective file was
+// built from, and a merge it cannot vouch for is refused. Contract:
+// docs/ai/specs/kit/project-rules/rules-record.md.
+
+import { lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeDocsAiFileAtomic } from '../atomic-write.mjs';
+import { parseFrontmatter } from '../../references/scripts/check-docs-size.mjs';
+import { digestOf, readRecord, readUnder } from './rules-check.mjs';
+import { RECORD_PATH, THEMES, themePaths } from './themes.mjs';
+
+const ROLES = ['kit', 'local', 'effective'];
+
+// Why the first node on the record's path that lstat cannot inspect, is a symlink or is of the wrong
+// kind fails, or null when the path holds or ends in a missing node.
+const wrongNode = (root, lstat) => {
+  const parts = RECORD_PATH.split('/');
+  for (let i = 1; i <= parts.length; i += 1) {
+    const rel = parts.slice(0, i).join('/');
+    let st;
+    try {
+      st = lstat(join(root, rel));
+    } catch (err) {
+      if (err && err.code === 'ENOENT') return null;
+      return `${rel} cannot be inspected (${err?.code ?? err})`;
+    }
+    const isLeaf = i === parts.length;
+    if (st.isSymbolicLink() || (isLeaf ? !st.isFile() : !st.isDirectory())) return `${rel} is a symlink or not of its kind`;
+  }
+  return null;
+};
+
+// The conditions in the order they are judged; each returns null when it holds, else the refusal.
+const judge = (root, theme, passed, deps) => {
+  const themes = deps.themes ?? THEMES;
+  const fail = (condition, message) => ({ ok: false, condition, message });
+  if (!themes.some(({ name }) => name === theme)) return fail('theme', `${theme} is not a registry theme`);
+  const node = wrongNode(root, deps.lstat ?? lstatSync);
+  if (node !== null) return fail('record-path', node);
+  const recordRead = readUnder(root, RECORD_PATH, deps);
+  if (!['ok', 'absent'].includes(recordRead.outcome)) return fail('record-path', `${RECORD_PATH} is not a regular file`);
+  const record = readRecord(recordRead, themes);
+  if (!record.ok) return fail('unreadable-record', `${RECORD_PATH} is unreadable: ${record.reason}`);
+  const paths = themePaths(theme);
+  const files = Object.fromEntries(ROLES.map((role) => [role, readUnder(root, paths[role], deps)]));
+  const unreadable = ROLES.find((role) => !['ok', 'absent'].includes(files[role].outcome));
+  if (unreadable) return fail('unreadable-file', `${paths[unreadable]} is not a regular file this writer can read`);
+  const missing = ['kit', 'effective'].find((role) => files[role].outcome !== 'ok');
+  if (missing) return fail('missing-file', `${paths[missing]} is missing`);
+  const { kit, local, effective } = { kit: files.kit.bytes, local: files.local.bytes, effective: files.effective.bytes };
+  if (parseFrontmatter(effective.toString('utf8')) === null) return fail('frontmatter', `${paths.effective} carries no frontmatter`);
+  if (digestOf(kit) !== passed.kit) return fail('kit-moved', `${paths.kit} no longer hashes to the passed kit digest`);
+  if (digestOf(effective) !== passed.effective) return fail('effective-moved', `${paths.effective} no longer hashes to the passed effective digest`);
+  if ((local !== undefined) !== (passed.local !== 'absent')) {
+    return fail('local-presence', `${paths.local} ${local === undefined ? 'is absent' : 'exists'} while the passed local is ${passed.local}`);
+  }
+  if (local !== undefined) {
+    if (digestOf(local) !== passed.local) return fail('local-moved', `${paths.local} no longer hashes to the passed local digest`);
+    if (effective.equals(kit) || effective.equals(local)) return fail('effective-equals-input', `${paths.effective} equals one of its inputs, so no merge was written`);
+  } else if (!effective.equals(kit)) {
+    return fail('effective-differs-from-kit', `with no local file ${paths.effective} must equal ${paths.kit}`);
+  }
+  return { ok: true, themes: record.themes };
+};
+
+// writeRecord(root, theme, passed, deps?) → { ok: true, path, entry } | { ok: false, condition, message }.
+export const writeRecord = (root, theme, passed, deps = {}) => {
+  const judged = judge(root, theme, passed, deps);
+  if (!judged.ok) return judged;
+  const entry = { kit: passed.kit, local: passed.local, effective: passed.effective };
+  const body = `${JSON.stringify({ schema: 1, themes: { ...judged.themes, [theme]: entry } }, null, 2)}\n`;
+  try {
+    (deps.write ?? writeDocsAiFileAtomic)(root, RECORD_PATH, body);
+  } catch (err) {
+    return { ok: false, condition: 'write', message: String(err?.message ?? err) };
+  }
+  return { ok: true, path: RECORD_PATH, entry };
+};

package/tools/project-rules/themes.mjs

@@ -0,0 +1,19 @@
+// The theme registry: pure data and pure derivation. Every surface that names a theme or its files
+// reads this list, never a second copy. Contract: docs/ai/specs/kit/project-rules/themes.md.
+
+export const THEMES = Object.freeze([
+  Object.freeze({
+    name: 'project-layout',
+    template: 'references/rules/project-layout.md',
+    readWhen: 'Creating, moving or naming a file, a module or a spec',
+  }),
+]);
+
+export const RECORD_PATH = 'docs/ai/rules/effective/sources.json';
+
+export const themePaths = (name) => Object.freeze({
+  kit: `docs/ai/rules/${name}.md`,
+  local: `docs/ai/rules/local/${name}.md`,
+  effective: `docs/ai/rules/effective/${name}.md`,
+  record: RECORD_PATH,
+});

package/tools/spec-adoption.mjs

@@ -1,5 +1,5 @@
 // spec-adoption.mjs — which of the four adoption states the feature-spec store is in, and whether the layer
-// was declined. Contract: docs/ai/specs/kit/spec-adoption.md. The census and the per-document read are
+// was declined. Contract: docs/ai/specs/kit/spec-layer/spec-adoption.md. The census and the per-document read are
 // spec-check's own exported seam; this module walks nothing of its own. Read-only, Node >= 22.
 
 import { join } from 'node:path';

package/tools/spec-coverage.mjs

@@ -7,7 +7,7 @@
 // contract a REQUIREMENT with a ratchet — a shipped tool no contract governs is a REFUSAL, and the
 // debt of today's uncovered tools may only shrink.
 //
-// The contract this module is built to is `docs/ai/specs/kit/spec-coverage.md`, and it was written
+// The contract this module is built to is `docs/ai/specs/kit/spec-layer/spec-coverage.md`, and it was written
 // BEFORE this file. That order is the point: a contract amended after the code describes whatever
 // the last review happened to find, which makes review an open question with no bounded answer.
 //