@alexandrealvaro/agentic 0.2.0-beta.1 → 0.3.0-beta.1

package/README.md

@@ -43,6 +43,42 @@ A short TUI shows the detected mode, agent, and feature signals (frontend / `.cl
 
 If your project already has an `AGENTS.md` (or `CLAUDE.md`), the installer appends a managed `Skills installed by agentic` section bracketed by `<!-- agentic-managed-skills:start -->` / `:end -->` markers. User content outside those markers is byte-preserved; re-runs update only the managed block.
 
+## Updating an existing project
+
+To pull upstream kit changes into a project that already has agentic skills installed:
+
+```bash
+cd your-project
+npx @alexandrealvaro/agentic@beta update
+```
+
+`update` is a separate command from `init` (clearer intent) and runs a three-way diff against a state file the kit writes at install time:
+
+* `.claude/agentic-state.json` — for Claude Code installs.
+* `.agents/agentic-state.json` — for Codex installs.
+
+These state files are committed to your repo so the whole team shares one view of what skill version is in place. They record kit version, per-skill version, and the SHA of every shipped file at the time of last install. The three-way diff uses those SHAs to distinguish *user-edited* files from *kit-changed* files and acts accordingly:
+
+| File state | Action |
+| --- | --- |
+| New file in the kit | install |
+| Kit unchanged, you didn't touch it | report unchanged |
+| Kit unchanged, you edited it | keep your edits |
+| Kit changed, you didn't touch it | silent update |
+| Kit changed, you also edited it | prompt with diff (default: skip) |
+| Skill removed from the kit or de-selected | prompt before removing your file (default: keep) |
+
+Useful flags:
+
+* `--dry-run` — print the action plan without writing anything. Always start here when you're not sure what will happen.
+* `--force` — overwrite user-edited files on conflict (non-interactive default: no). Escape hatch when you genuinely want kit-side content to win.
+* `--agent claude-code | codex | both` — restrict the update to one agent.
+* `--yes` — non-interactive, accepts defaults (skip on conflict, keep orphans). Combine with `--force` if you want overwrites in CI.
+
+If the project was installed with a kit version older than v0.3 (no state file present), the first `update` falls back to today's byte-compare behavior, then writes the state file so subsequent runs use the three-way diff.
+
+The `agentic-review` skill writes the assembled WORKFLOW §10 handoff to `.agentic/reviews/<ISO-timestamp>-<scope>.md` before delegating to the fresh-context reviewer (Claude Code) or before instructing you to `/clear` and paste (Codex). These files are ephemeral audit artifacts — add `.agentic/reviews/` to your `.gitignore`.
+
 For persistent install:
 
 ```bash
@@ -100,10 +136,14 @@ your-project/
 │   │   └── NNNN-<title>.md
 │   └── tasks/
 │       └── NNNN-<slug>.md
+├── .agentic/
+│   └── reviews/                (gitignored — ephemeral §10 review handoffs)
 ├── .claude/                    (Claude Code targets)
+│   ├── agentic-state.json      (kit install state — committed)
 │   ├── skills/agentic-*/SKILL.md
 │   └── agents/fresh-context-reviewer.md
 └── .agents/                    (Codex targets, cc-sdd convention)
+    ├── agentic-state.json      (kit install state — committed)
     └── skills/agentic-*/{SKILL.md, agents/openai.yaml}
 ```
 

package/WORKFLOW.md

@@ -49,7 +49,20 @@ Avoid putting implementation code in docs unless it's executable, generated, or
 
 The split is simple. **Docs are for the *why*** — decisions, not history. Git tracks history; docs explain the reasoning that won't survive otherwise. **Code is for the *what*** — clean naming and small units make logic self-evident, and the more your code does this work, the less your docs need to.
 
-Comments are exceptions. They justify *why* a non-obvious choice was made — never *what* the line does. No commented-out code, and no orphan `TODO` or `FIXME`: every deferred item references an issue, ADR, or explicit follow-up.
+Comments are exceptions. They justify *why* a non-obvious choice was made — never *what* the line does. No commented-out code, and no orphan `TODO` or `FIXME`: every deferred item references a tracked work item — a GitHub Issue or a per-task file under `doc/tasks/NNNN-*.md`.
+
+### Documentation Discipline
+
+Eight rules apply to every document the agent or the human writes in the project. They are framed against the failure modes the kit has actually seen — bloated `AGENTS.md`, README pages that drift into changelogs, decision artifacts diluted by speculation.
+
+1. **Definitions and decisions only.** Documentation captures what is true now and the decisions that brought it there. Speculation, history, and unfounded plans are out. A deferred decision is in scope when it is *recorded* — an accepted ADR or a task file is fundamentação; "we might do X later" without a record is speculation and is cut.
+2. **No dates, version stamps, `DRAFT` markers, or changelogs in narrative documents.** Applies to `README.md`, `AGENTS.md` / `CLAUDE.md`, `ARCHITECTURE.md`, `DESIGN.md`, specs, and any prose page. **Decision-record artifacts are exempt** — ADRs under `doc/adr/` (Nygard `Status` lifecycle requires a date) and tasks under `doc/tasks/` (append-only `Notes` log is the auditability surface). Use git history for narrative-doc evolution; keep the dated lifecycle inside the artifacts that need it.
+3. **No emoji anywhere.** Not in docs, code, source comments, commit messages, PR bodies, or skill outputs. Severity tags use plain words (`Blocker / Concern / Note`); status uses words (`accepted / superseded`); structural cues use Markdown.
+4. **Business context first.** Every document opens with *why* — the problem, the constraint, the user — before *what* and *how*. The first paragraph answers "what would break if this document didn't exist".
+5. **One scope per document. No duplication.** If two documents would say the same thing, link instead of copying. The canonical location owns the content; everywhere else references it.
+6. **Code is the primary documentation of behavior.** Comments justify *why* a non-obvious choice was made — never restate *what* the line does. If the comment is needed to explain *what*, rename or refactor.
+7. **No commented-out code; no orphan `TODO` / `FIXME` in source.** Every deferred item references a tracked work item — a GitHub Issue, or a per-task file under `doc/tasks/NNNN-*.md` (the kit's file-based tracking surface). The trace must be addressable from the source line.
+8. **Tests are living documentation of behavior.** Test names and assertions should read as the spec they enforce. When the spec changes, the test changes; when the test changes, the spec it documents must already have changed.
 
 ## 3. Format by Evidence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexandrealvaro/agentic",
-  "version": "0.2.0-beta.1",
+  "version": "0.3.0-beta.1",
   "description": "Bootstrap and audit AGENTS.md, ARCHITECTURE.md, ADRs, skills, and subagents for engineering production code with LLMs",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
   },
   "scripts": {
     "start": "node bin/agentic.js",
-    "test": "node bin/agentic.js --help && node bin/agentic.js init --help && node --test test/*.test.js",
+    "test": "node bin/agentic.js --help && node bin/agentic.js init --help && node bin/agentic.js update --help && node --test test/*.test.js",
     "prepublishOnly": "npm test"
   },
   "keywords": [

package/src/commands/init.js

@@ -1,8 +1,17 @@
 import * as p from '@clack/prompts';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
 import { detectAgents, detectFeatures, detectMode } from '../lib/detect.js';
 import { installSkills } from '../lib/install.js';
+import { saveState, loadState } from '../lib/state.js';
 import { updateRootDoc } from '../lib/rootdoc.js';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(
+  readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf8')
+);
+
 const VALID_AGENTS = ['claude-code', 'codex'];
 const AGENT_FLAG_VALUES = ['claude-code', 'codex', 'both'];
 
@@ -206,13 +215,17 @@ export async function initCommand(opts) {
   for (const agent of agents) {
     const agentSkills = skillsForAgent(agent, optedSkills);
     for (const s of agentSkills) installedSkillSet.add(s);
-    const { actions } = await installSkills({
+    const previousStates = { [agent]: loadState(cwd, agent) };
+    const { actions, nextStates } = await installSkills({
       cwd,
       agents: [agent],
       skills: agentSkills,
       confirmReplace,
+      previousStates,
+      kitVersion: pkg.version,
     });
     allActions.push(...actions);
+    saveState(cwd, agent, nextStates[agent]);
   }
 
   const skillDisplayOrder = [

package/src/commands/update.js

@@ -0,0 +1,251 @@
+import * as p from '@clack/prompts';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { detectAgents, detectFeatures } from '../lib/detect.js';
+import { installSkills, removeOrphanSkills } from '../lib/install.js';
+import { loadState, saveState } from '../lib/state.js';
+import { updateRootDoc } from '../lib/rootdoc.js';
+import { CONDITIONAL_SKILLS, REQUIRED_SKILLS } from './init.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(
+  readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf8')
+);
+
+const VALID_AGENTS = ['claude-code', 'codex'];
+const AGENT_FLAG_VALUES = ['claude-code', 'codex', 'both'];
+
+const AGENT_LABEL = {
+  'claude-code': 'Claude Code',
+  codex: 'Codex',
+};
+
+const ACTION_SYMBOL = {
+  created: '+',
+  updated: '~',
+  replaced: '~',
+  unchanged: '·',
+  kept: '·',
+  skipped: '!',
+  removed: '-',
+  'orphan-kept': '?',
+};
+
+const ROOT_DOC_LABEL = {
+  appended: '+ ',
+  updated: '~ ',
+  unchanged: '· ',
+  skipped: '! ',
+  absent: '',
+};
+
+function resolveAgents(flagValue, detectedAgents, previousAgents) {
+  if (flagValue === 'both') return ['claude-code', 'codex'];
+  if (flagValue) return [flagValue];
+  if (previousAgents.length > 0) return previousAgents;
+  if (detectedAgents.length > 0) return detectedAgents;
+  return ['claude-code'];
+}
+
+function pickConditionalAuto(features, targetAgents) {
+  return CONDITIONAL_SKILLS.filter(
+    (s) => s.autoIf(features) && s.agents.some((a) => targetAgents.includes(a))
+  ).map((s) => s.name);
+}
+
+function skillsForAgent(agent, optedSkills) {
+  const conditional = optedSkills.filter((skillName) => {
+    const def = CONDITIONAL_SKILLS.find((s) => s.name === skillName);
+    return def && def.agents.includes(agent);
+  });
+  return [...REQUIRED_SKILLS, ...conditional];
+}
+
+function previousAgentsFromStates(cwd) {
+  const out = [];
+  for (const agent of VALID_AGENTS) {
+    const state = loadState(cwd, agent);
+    if (state) out.push(agent);
+  }
+  return out;
+}
+
+function previouslyOptedConditional(previousStates, currentAgents) {
+  const opted = new Set();
+  for (const agent of currentAgents) {
+    const prev = previousStates[agent];
+    if (!prev) continue;
+    for (const skill of Object.keys(prev.skills ?? {})) {
+      if (CONDITIONAL_SKILLS.some((s) => s.name === skill)) {
+        opted.add(skill);
+      }
+    }
+  }
+  return [...opted];
+}
+
+export async function updateCommand(opts) {
+  if (opts.agent && !AGENT_FLAG_VALUES.includes(opts.agent)) {
+    throw new Error(
+      `invalid agent "${opts.agent}". Use one of: ${AGENT_FLAG_VALUES.join(', ')}`
+    );
+  }
+
+  const cwd = process.cwd();
+  const interactive = process.stdout.isTTY && !opts.yes && !opts.agent;
+  const dryRun = Boolean(opts.dryRun);
+  const force = Boolean(opts.force);
+
+  const detectedAgents = detectAgents(cwd);
+  const features = detectFeatures(cwd);
+  const previousAgents = previousAgentsFromStates(cwd);
+
+  const agents = resolveAgents(opts.agent, detectedAgents, previousAgents);
+  const previousStates = {};
+  for (const agent of agents) {
+    previousStates[agent] = loadState(cwd, agent);
+  }
+
+  const previousOpted = previouslyOptedConditional(previousStates, agents);
+  const autoOpted = pickConditionalAuto(features, agents);
+  const defaultOpted = previousOpted.length ? previousOpted : autoOpted;
+
+  let optedSkills;
+  if (interactive) {
+    p.intro(`agentic update${dryRun ? ' (dry-run)' : ''}${force ? ' (force)' : ''}`);
+    const previousLine = previousAgents.length
+      ? previousAgents.map((a) => AGENT_LABEL[a]).join(', ')
+      : 'none — first update on a legacy install';
+    p.note(
+      `Previous install: ${previousLine}\n` +
+        `Updating for: ${agents.map((a) => AGENT_LABEL[a]).join(' + ')}\n` +
+        `Kit version: ${pkg.version}`,
+      'Update plan'
+    );
+
+    const conditionalOptions = CONDITIONAL_SKILLS.filter((s) =>
+      s.agents.some((a) => agents.includes(a))
+    ).map((s) => ({
+      value: s.name,
+      label: s.name,
+      hint: s.autoIf(features) ? s.hintWhenAuto : s.hintWhenManual,
+    }));
+
+    if (conditionalOptions.length > 0) {
+      const picked = await p.multiselect({
+        message: 'Optional skills (toggle to include or exclude):',
+        options: conditionalOptions,
+        initialValues: defaultOpted,
+        required: false,
+      });
+      if (p.isCancel(picked)) {
+        p.cancel('Cancelled.');
+        return;
+      }
+      optedSkills = picked;
+    } else {
+      optedSkills = [];
+    }
+  } else {
+    optedSkills = defaultOpted;
+  }
+
+  const confirmReplace = interactive
+    ? async (question) => {
+        const answer = await p.confirm({ message: question, initialValue: false });
+        if (p.isCancel(answer)) return false;
+        return answer;
+      }
+    : async () => Boolean(force);
+
+  const confirmRemove = interactive
+    ? async (question) => {
+        const answer = await p.confirm({ message: question, initialValue: false });
+        if (p.isCancel(answer)) return false;
+        return answer;
+      }
+    : async () => Boolean(force);
+
+  const installedSkillSet = new Set();
+  const allActions = [];
+  const nextStates = {};
+
+  for (const agent of agents) {
+    const agentSkills = skillsForAgent(agent, optedSkills);
+    for (const s of agentSkills) installedSkillSet.add(s);
+
+    const orphanResult = await removeOrphanSkills({
+      cwd,
+      agent,
+      previousState: previousStates[agent],
+      currentSkills: agentSkills,
+      confirmRemove,
+      dryRun,
+    });
+    allActions.push(...orphanResult.actions);
+
+    const result = await installSkills({
+      cwd,
+      agents: [agent],
+      skills: agentSkills,
+      confirmReplace,
+      previousStates: { [agent]: previousStates[agent] ?? null },
+      kitVersion: pkg.version,
+      dryRun,
+      force,
+    });
+    allActions.push(...result.actions);
+    nextStates[agent] = result.nextStates[agent];
+  }
+
+  if (!dryRun) {
+    for (const agent of agents) {
+      saveState(cwd, agent, nextStates[agent]);
+    }
+  }
+
+  const skillDisplayOrder = [
+    ...REQUIRED_SKILLS,
+    ...CONDITIONAL_SKILLS.map((s) => s.name),
+  ].filter((s) => installedSkillSet.has(s));
+
+  const confirmAppend = interactive
+    ? async (path) => {
+        const answer = await p.confirm({
+          message: `Append a managed "Skills installed by agentic" section to ${path}? (existing content preserved)`,
+          initialValue: true,
+        });
+        if (p.isCancel(answer)) return false;
+        return answer;
+      }
+    : async () => true;
+
+  const rootDocAction = !dryRun
+    ? await updateRootDoc({
+        cwd,
+        skills: skillDisplayOrder,
+        confirmAppend,
+      })
+    : { type: 'absent', path: null };
+
+  const lines = allActions.map((a) => {
+    const sym = ACTION_SYMBOL[a.type] ?? '?';
+    return `${sym} [${a.agent}] ${a.path}`;
+  });
+  if (rootDocAction.type !== 'absent') {
+    lines.push(`${ROOT_DOC_LABEL[rootDocAction.type]}${rootDocAction.path}`);
+  }
+
+  if (interactive) {
+    p.note(lines.join('\n') || '(no changes)', dryRun ? 'Plan' : 'Result');
+    const closing = dryRun
+      ? 'Dry-run only — nothing written. Re-run without --dry-run to apply.'
+      : `Updated to ${pkg.version}. State saved at .claude/agentic-state.json / .agents/agentic-state.json.`;
+    p.outro(closing);
+  } else {
+    for (const line of lines) {
+      process.stderr.write(`${line}\n`);
+    }
+  }
+}

package/src/index.js

@@ -3,6 +3,7 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { initCommand } from './commands/init.js';
+import { updateCommand } from './commands/update.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(
@@ -24,5 +25,14 @@ export async function run(argv) {
     .option('-y, --yes', 'skip confirmation prompts (non-interactive)')
     .action(initCommand);
 
+  program
+    .command('update')
+    .description('Pull upstream kit changes into an installed project (three-way diff against the saved state)')
+    .option('-a, --agent <agent>', 'restrict update to a specific agent: claude-code | codex | both')
+    .option('-y, --yes', 'skip confirmation prompts (non-interactive)')
+    .option('--dry-run', 'preview the action plan without writing any files')
+    .option('--force', 'overwrite user-edited files on conflict (non-interactive default: no)')
+    .action(updateCommand);
+
   await program.parseAsync(argv);
 }

package/src/lib/install.js

@@ -1,10 +1,13 @@
+import { createHash } from 'node:crypto';
 import {
   copyFileSync,
   existsSync,
   mkdirSync,
   readFileSync,
   readdirSync,
+  rmSync,
   statSync,
+  unlinkSync,
 } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { basename, dirname, join, relative } from 'node:path';
@@ -26,6 +29,12 @@ const AGENT_LAYOUT = {
   },
 };
 
+export function agentLayout(agent) {
+  const layout = AGENT_LAYOUT[agent];
+  if (!layout) throw new Error(`unknown agent "${agent}"`);
+  return layout;
+}
+
 function walkSkill(srcRoot) {
   const out = [];
   function walk(dir, prefix) {
@@ -55,94 +64,290 @@ function loadManifest(srcRoot) {
   return { subagents: Array.isArray(raw.subagents) ? raw.subagents : [] };
 }
 
+function sha256Of(path) {
+  return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+
 function sameFile(a, b) {
   if (!existsSync(b)) return false;
   return readFileSync(a).equals(readFileSync(b));
 }
 
+function targetForRel(rel, layout, targetRoot, cwd, subagentSet) {
+  if (subagentSet.has(rel)) {
+    if (!layout.agentsDir) return null;
+    return join(cwd, layout.agentsDir, basename(rel));
+  }
+  return join(targetRoot, rel);
+}
+
+function resolveSkillSource(agent, skill) {
+  const layout = agentLayout(agent);
+  const srcRoot = join(KIT_ROOT, layout.sourceDir, skill);
+  if (!existsSync(srcRoot)) {
+    throw new Error(
+      `skill "${skill}" not found for agent "${agent}" (expected at ${srcRoot})`
+    );
+  }
+  const manifest = loadManifest(srcRoot);
+  const subagentSet = new Set(manifest.subagents);
+  const walked = walkSkill(srcRoot);
+  const walkedRels = new Set(walked.map(({ rel }) => rel));
+  for (const declared of subagentSet) {
+    if (!walkedRels.has(declared)) {
+      throw new Error(
+        `manifest at ${join(srcRoot, MANIFEST_FILE)} declares subagent "${declared}" but no such file exists in the skill source`
+      );
+    }
+  }
+  return { layout, srcRoot, subagentSet, walked };
+}
+
+function planFile({
+  src,
+  rel,
+  target,
+  relForReport,
+  prevSha,
+  force,
+}) {
+  const sourceSha = sha256Of(src);
+  if (!existsSync(target)) {
+    return { type: 'create', sourceSha };
+  }
+  const targetSha = sha256Of(target);
+
+  if (sourceSha === targetSha) {
+    return { type: 'unchanged', sourceSha };
+  }
+
+  if (prevSha === undefined || prevSha === null) {
+    return { type: 'legacy-divergent', sourceSha, targetSha };
+  }
+
+  if (sourceSha === prevSha) {
+    // kit unchanged since last install; differ vs. target → user edited; keep
+    return { type: 'user-edited-keep', sourceSha };
+  }
+
+  if (targetSha === prevSha) {
+    // user untouched; kit changed → silent update
+    return { type: 'kit-changed-update', sourceSha };
+  }
+
+  // both changed → conflict
+  if (force) return { type: 'conflict-force', sourceSha };
+  return { type: 'conflict-prompt', sourceSha, targetSha };
+}
+
 /**
- * Install one or more skills for one or more agents.
+ * Install one or more skills for one or more agents, with optional state-aware
+ * three-way diff against the prior install.
+ *
+ * Legacy contract (no state): default-skip on divergent files, prompt via
+ * confirmReplace. Matches v0.2 behavior.
+ *
+ * State-aware contract (previousStates supplied): three-way diff using the
+ * previous source SHA, target SHA, current source SHA. See ADR-0009.
  *
  * @param {object} opts
- * @param {string} opts.cwd  Target project root.
- * @param {string[]} opts.agents  e.g. ['claude-code', 'codex'].
- * @param {string[]} opts.skills  Skill names, e.g. ['agentic-bootstrap'].
+ * @param {string} opts.cwd
+ * @param {string[]} opts.agents
+ * @param {string[]} opts.skills
  * @param {(question: string) => Promise<boolean>} [opts.confirmReplace]
- *   Async callback used when a target file already exists with different
- *   content. Default: skip without asking (safe non-interactive default).
+ *   Callback for divergent files (legacy path or three-way conflict). Default: skip.
+ * @param {Record<string, object|null>} [opts.previousStates]
+ *   Per-agent previous state from src/lib/state.js. Missing/null entries fall
+ *   back to legacy byte-compare.
+ * @param {string} [opts.kitVersion]
+ *   Stamped into the returned nextStates as kitVersion and per-skill version.
+ * @param {boolean} [opts.dryRun]
+ *   If true, no files are written. Actions reflect what would happen.
+ * @param {boolean} [opts.force]
+ *   If true, three-way conflicts overwrite without prompting.
  *
- * @returns {Promise<{ actions: Array<{type: 'created'|'replaced'|'unchanged'|'skipped', path: string}> }>}
+ * @returns {Promise<{ actions: Array<{type, path, agent}>, nextStates: Record<string, object> }>}
  */
 export async function installSkills({
   cwd,
   agents,
   skills,
   confirmReplace = async () => false,
+  previousStates = {},
+  kitVersion = null,
+  dryRun = false,
+  force = false,
 }) {
   const actions = [];
+  const nextStates = {};
 
   for (const agent of agents) {
-    const layout = AGENT_LAYOUT[agent];
-    if (!layout) {
-      throw new Error(`unknown agent "${agent}"`);
-    }
+    const prev = previousStates[agent] ?? null;
+    const nextSkills = {};
 
     for (const skill of skills) {
-      const srcRoot = join(KIT_ROOT, layout.sourceDir, skill);
-      if (!existsSync(srcRoot)) {
-        throw new Error(
-          `skill "${skill}" not found for agent "${agent}" (expected at ${srcRoot})`
-        );
-      }
-
+      const { layout, srcRoot, subagentSet, walked } = resolveSkillSource(agent, skill);
       const targetRoot = join(cwd, layout.skillsDir, skill);
-      const manifest = loadManifest(srcRoot);
-      const subagentSet = new Set(manifest.subagents);
-      const walked = walkSkill(srcRoot);
-      const walkedRels = new Set(walked.map(({ rel }) => rel));
-      for (const declared of subagentSet) {
-        if (!walkedRels.has(declared)) {
-          throw new Error(
-            `manifest at ${join(srcRoot, MANIFEST_FILE)} declares subagent "${declared}" but no such file exists in the skill source`
-          );
-        }
-      }
+      const prevSkill = prev?.skills?.[skill] ?? null;
+      const prevByPath = new Map(
+        (prevSkill?.files ?? []).map((f) => [f.path, f.sourceSha])
+      );
+      const skillFiles = [];
 
       for (const { src, rel } of walked) {
         if (rel === MANIFEST_FILE) continue;
 
-        let target;
-        if (subagentSet.has(rel)) {
-          if (!layout.agentsDir) continue;
-          target = join(cwd, layout.agentsDir, basename(rel));
-        } else {
-          target = join(targetRoot, rel);
-        }
+        const target = targetForRel(rel, layout, targetRoot, cwd, subagentSet);
+        if (!target) continue;
         const relForReport = relative(cwd, target);
+        const prevSha = prevByPath.has(relForReport)
+          ? prevByPath.get(relForReport)
+          : null;
+
+        const decision = planFile({
+          src,
+          rel,
+          target,
+          relForReport,
+          prevSha,
+          force,
+        });
 
-        if (existsSync(target)) {
-          if (sameFile(src, target)) {
-            actions.push({ type: 'unchanged', path: relForReport });
-            continue;
+        let actionType;
+        let writeFile = false;
+
+        switch (decision.type) {
+          case 'create':
+            actionType = 'created';
+            writeFile = true;
+            break;
+          case 'unchanged':
+            actionType = 'unchanged';
+            break;
+          case 'kit-changed-update':
+            actionType = 'updated';
+            writeFile = true;
+            break;
+          case 'user-edited-keep':
+            actionType = 'kept';
+            break;
+          case 'conflict-force':
+            actionType = 'replaced';
+            writeFile = true;
+            break;
+          case 'conflict-prompt': {
+            const replace = await confirmReplace(
+              `${relForReport}: kit and your edits both changed since last install. Overwrite?`
+            );
+            if (replace) {
+              actionType = 'replaced';
+              writeFile = true;
+            } else {
+              actionType = 'skipped';
+            }
+            break;
           }
-          const replace = await confirmReplace(
-            `Replace ${relForReport}? (target differs from the kit version)`
-          );
-          if (!replace) {
-            actions.push({ type: 'skipped', path: relForReport });
-            continue;
+          case 'legacy-divergent': {
+            const replace = await confirmReplace(
+              `Replace ${relForReport}? (target differs from the kit version)`
+            );
+            if (replace) {
+              actionType = 'replaced';
+              writeFile = true;
+            } else {
+              actionType = 'skipped';
+            }
+            break;
           }
+          default:
+            throw new Error(`unhandled plan decision: ${decision.type}`);
+        }
+
+        if (writeFile && !dryRun) {
           mkdirSync(dirname(target), { recursive: true });
           copyFileSync(src, target);
-          actions.push({ type: 'replaced', path: relForReport });
-        } else {
-          mkdirSync(dirname(target), { recursive: true });
-          copyFileSync(src, target);
-          actions.push({ type: 'created', path: relForReport });
         }
+
+        actions.push({ type: actionType, path: relForReport, agent });
+        skillFiles.push({ path: relForReport, sourceSha: decision.sourceSha });
+      }
+
+      nextSkills[skill] = {
+        version: kitVersion ?? prevSkill?.version ?? null,
+        files: skillFiles,
+      };
+    }
+
+    nextStates[agent] = {
+      schemaVersion: 1,
+      kitVersion: kitVersion ?? prev?.kitVersion ?? null,
+      agent,
+      skills: nextSkills,
+    };
+  }
+
+  return { actions, nextStates };
+}
+
+/**
+ * Identify and optionally remove orphan skills — skills present in the prior
+ * state but absent from the current opted skill list. Default keep.
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd
+ * @param {string} opts.agent
+ * @param {object|null} opts.previousState
+ * @param {string[]} opts.currentSkills
+ * @param {(question: string) => Promise<boolean>} [opts.confirmRemove]
+ * @param {boolean} [opts.dryRun]
+ *
+ * @returns {Promise<{ actions: Array<{type, path, agent}>, removedSkills: string[] }>}
+ */
+export async function removeOrphanSkills({
+  cwd,
+  agent,
+  previousState,
+  currentSkills,
+  confirmRemove = async () => false,
+  dryRun = false,
+}) {
+  const actions = [];
+  const removedSkills = [];
+  if (!previousState?.skills) return { actions, removedSkills };
+
+  const layout = agentLayout(agent);
+  const currentSet = new Set(currentSkills);
+
+  for (const [skill, entry] of Object.entries(previousState.skills)) {
+    if (currentSet.has(skill)) continue;
+    const remove = await confirmRemove(
+      `Remove orphan skill "${skill}" for ${agent}? (no longer in your install set)`
+    );
+    if (!remove) {
+      for (const f of entry.files) {
+        actions.push({ type: 'orphan-kept', path: f.path, agent });
+      }
+      continue;
+    }
+
+    for (const f of entry.files) {
+      const abs = join(cwd, f.path);
+      if (existsSync(abs) && !dryRun) {
+        unlinkSync(abs);
+      }
+      actions.push({ type: 'removed', path: f.path, agent });
+    }
+    // Try to drop the empty skill directory under skillsDir/<skill>.
+    const skillDir = join(cwd, layout.skillsDir, skill);
+    if (!dryRun && existsSync(skillDir)) {
+      try {
+        rmSync(skillDir, { recursive: true, force: true });
+      } catch {
+        // best-effort cleanup
       }
     }
+    removedSkills.push(skill);
   }
 
-  return { actions };
+  return { actions, removedSkills };
 }

package/src/lib/state.js

@@ -0,0 +1,80 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const SCHEMA_VERSION = 1;
+export const STATE_FILE = 'agentic-state.json';
+
+export const STATE_DIRS = {
+  'claude-code': '.claude',
+  codex: '.agents',
+};
+
+export function statePath(cwd, agent) {
+  const dir = STATE_DIRS[agent];
+  if (!dir) throw new Error(`unknown agent "${agent}"`);
+  return join(cwd, dir, STATE_FILE);
+}
+
+export function emptyState(agent, kitVersion) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    kitVersion,
+    agent,
+    skills: {},
+  };
+}
+
+export function loadState(cwd, agent) {
+  const path = statePath(cwd, agent);
+  if (!existsSync(path)) return null;
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    throw new Error(`malformed state at ${path}: ${err.message}`);
+  }
+  if (typeof raw.schemaVersion !== 'number') {
+    throw new Error(`state at ${path} missing schemaVersion`);
+  }
+  if (raw.schemaVersion > SCHEMA_VERSION) {
+    throw new Error(
+      `state at ${path} has schemaVersion ${raw.schemaVersion}; this kit only knows ${SCHEMA_VERSION}. Upgrade the kit.`
+    );
+  }
+  if (raw.agent && raw.agent !== agent) {
+    throw new Error(
+      `state at ${path} declares agent "${raw.agent}" but expected "${agent}"`
+    );
+  }
+  return {
+    schemaVersion: raw.schemaVersion,
+    kitVersion: raw.kitVersion ?? null,
+    agent,
+    skills: raw.skills ?? {},
+  };
+}
+
+export function saveState(cwd, agent, state) {
+  const path = statePath(cwd, agent);
+  mkdirSync(dirname(path), { recursive: true });
+  const ordered = orderState(state);
+  writeFileSync(path, JSON.stringify(ordered, null, 2) + '\n');
+}
+
+function orderState(state) {
+  const skills = {};
+  for (const skillName of Object.keys(state.skills).sort()) {
+    const entry = state.skills[skillName];
+    const files = [...entry.files].sort((a, b) => a.path.localeCompare(b.path));
+    skills[skillName] = {
+      version: entry.version,
+      files: files.map((f) => ({ path: f.path, sourceSha: f.sourceSha })),
+    };
+  }
+  return {
+    schemaVersion: state.schemaVersion,
+    kitVersion: state.kitVersion,
+    agent: state.agent,
+    skills,
+  };
+}

package/src/skills/claude-code/agentic-adr/SKILL.md

@@ -60,3 +60,10 @@ Stop after writing. Do **not** flip status to `accepted` — that requires user
 ## Output contract
 
 A single new file at `doc/adr/<NNNN>-<short-slug>.md`. Status `proposed`. No existing ADRs modified. No invented content.
+
+ADRs are decision-record artifacts and are **exempt** from the no-dates rule (Documentation Discipline §2): the `**Status:**` lifecycle and `**Date:**` field are required for Nygard supersession ordering. The remaining Documentation Discipline rules (`WORKFLOW.md` §2) apply at write time:
+
+- No emoji anywhere in the file.
+- `Context` is the business-context-first section — the *forces* and *problem* before the *decision*.
+- One scope: one decision per ADR. If the user's request implies multiple decisions, ask which one to write first; the others become follow-up ADRs.
+- No speculation. `Decision` is a directive ("We will…"); rejected paths go in `Alternatives Considered`, not the body.

package/src/skills/claude-code/agentic-architecture/SKILL.md

@@ -102,3 +102,11 @@ Currently-binding decisions. Link each to `doc/adr/`.
 ## Output contract
 
 A single `ARCHITECTURE.md` at the repo root. Every line locks a binding pattern. ADR candidates flagged in the response, not written. In audit mode: drift list only, no file written.
+
+`ARCHITECTURE.md` is a narrative document, so the Documentation Discipline rules in `WORKFLOW.md` §2 apply at write time:
+
+- No emoji anywhere in the file.
+- No dates, version stamps, `DRAFT` markers, or changelog blocks. Architecture is the current binding pattern; the lifecycle of "when did this become true" lives in ADRs and git history.
+- `Overview` is the business-context-first paragraph — *what the system does* and *what would break without it* before layers and patterns.
+- One scope: system-level patterns and boundaries. Per-decision rationale lives in ADRs; per-project operations live in `AGENTS.md`. Link, do not copy.
+- No speculation. If a layer has no observed signal, write `<TODO: not yet wired>` once; do not propose patterns that aren't already in the code.

package/src/skills/claude-code/agentic-audit/SKILL.md

@@ -34,6 +34,21 @@ If the user names an artifact (`AGENTS.md`, `ARCHITECTURE.md`, ADRs), audit only
 * Status field — every ADR has one of `proposed | accepted | deprecated | superseded by ADR-NNNN`.
 * Superseded chains — every "superseded by ADR-NNNN" target exists.
 
+### Documentation discipline drift (`WORKFLOW.md` §2 / ADR-0008)
+
+Audit narrative documents — `README.md`, `AGENTS.md` / `CLAUDE.md`, `ARCHITECTURE.md`, `DESIGN.md`, any prose page under `doc/` that is not a decision-record artifact under `doc/adr/` or `doc/tasks/`:
+
+* Emoji — any present? Rule 3 forbids emoji anywhere (docs, code, comments, commits, skill outputs).
+* Dates / version stamps / `DRAFT` markers / changelog blocks in narrative documents — Rule 2 forbids these. Decision-record artifacts under `doc/adr/` and `doc/tasks/` are exempt.
+* Business context first — does the first paragraph answer *why* the document exists, before *what* and *how*? Rule 4.
+* Scope duplication — does the document copy material that is canonically owned by another file (`AGENTS.md` repeating `ARCHITECTURE.md` patterns; `README.md` re-stating ADR rationale)? Rule 5 requires linking, not copying.
+* Speculation — phrases like "we might", "in the future", "could be added", or roadmaps without an ADR / task reference. Rule 1 forbids unfounded plans.
+
+Source code (sample, not exhaustive — flag findings, not every match):
+
+* Orphan `TODO` / `FIXME` — Rule 7. A reference to a GitHub Issue or a `doc/tasks/NNNN-*.md` task file makes it not orphan.
+* Commented-out code blocks — Rule 7. Removed code lives in git history.
+
 ## Step 3 — Output
 
 One line per finding, formatted:
@@ -42,7 +57,7 @@ One line per finding, formatted:
 [file or section]: spec says X, code says Y. Suggested resolution: change spec / change code / discuss.
 ```
 
-Group by artifact. If a category has no drift, print one line: `AGENTS.md — no drift.` etc. If an audited artifact does not exist, say so explicitly rather than reporting zero findings.
+Group by artifact. If a category has no drift, print one line: `AGENTS.md — no drift.` etc. If an audited artifact does not exist, say so explicitly rather than reporting zero findings. The Documentation discipline drift category groups its own findings under `Documentation discipline — <category>: ...`.
 
 If something the user says contradicts what the code shows, surface the conflict. Don't silently trust the user; don't silently trust the code.
 

package/src/skills/claude-code/agentic-bootstrap/SKILL.md

@@ -151,3 +151,11 @@ Real traps. Each one should map to an incident or to specific code.
 ## Output contract
 
 A single `AGENTS.md` at the repo root, ≤150 lines, every line operational. No "External Resources" section. No appended Universal Agent Behavior block — that lives in the `agentic-philosophy` skill. No meta-prose explaining gaps. In audit mode: a drift list, no file written.
+
+`AGENTS.md` is a narrative document, so the Documentation Discipline rules in `WORKFLOW.md` §2 apply at write time:
+
+- No emoji anywhere in the file.
+- No dates, version stamps, `DRAFT` markers, or changelog blocks. Stack versions are facts (`Node ≥18`); release timelines are not.
+- `Project Overview` is the business-context-first paragraph — *why* the project exists before *what* it does.
+- One scope: this file is the operational guide for agents. Do not duplicate `ARCHITECTURE.md` patterns or ADR rationale here; link instead.
+- No speculation. If a section has no signal, write `<TODO: not yet wired>` once; do not narrate "this could be added later".

package/src/skills/claude-code/agentic-design/SKILL.md

@@ -61,3 +61,11 @@ If the source has tokens DESIGN.md doesn't document, list those too as additions
 ## Output contract
 
 A single `DESIGN.md` at the repo root. YAML frontmatter uses W3C `$value`/`$type` shape. Markdown body has one section per token group present in the source. No invented tokens. No "External Resources" section. In audit mode: a drift list, no file written.
+
+`DESIGN.md` is a narrative document, so the Documentation Discipline rules in `WORKFLOW.md` §2 apply at write time:
+
+- No emoji anywhere — including the Markdown body's do's and don'ts.
+- No dates, version stamps, `DRAFT` markers, or changelog blocks. Token revisions live in git history; DESIGN.md is the current visual contract.
+- The Markdown body opens with the *why* of each token group — the visual constraint or product principle — before listing rules.
+- One scope: visual contract. Component anatomy and interaction patterns belong elsewhere; link, do not copy.
+- No speculation. If a group has no source token, mark `<TODO: not yet wired>` and move on.

package/src/skills/claude-code/agentic-philosophy/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: agentic-philosophy
-description: Universal agent behavior — think before coding, ground in real patterns, prefer simplicity, make surgical changes, define verifiable goals, verify before claiming done. Auto-invokes on non-trivial changes, refactors, debugging, "think before coding", "ground before coding", "verify done", "before implementing", or whenever the task is ambiguous enough that guardrails matter.
+description: Universal agent behavior and documentation discipline — think before coding, ground in real patterns, prefer simplicity, make surgical changes, define verifiable goals, verify before claiming done, and write documentation that captures only definitions and decisions. Auto-invokes on non-trivial changes, refactors, debugging, "think before coding", "ground before coding", "verify done", "before implementing", on documentation work — "writing docs", "writing readme", "writing architecture", "writing adr", "writing task", "audit docs" — or whenever the task is ambiguous enough that guardrails matter.
 ---
 
 # /agentic-philosophy
 
-Six behaviors apply to every non-trivial change. Bias toward caution over speed; for trivial diffs, use judgment.
+Six behaviors apply to every non-trivial change. Bias toward caution over speed; for trivial diffs, use judgment. A separate Documentation Discipline section at the end applies to every document the agent writes.
 
 ## Think Before Coding
 
@@ -86,3 +86,18 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 - For UI/runtime changes, exercise the feature in a browser.
 - Can't verify it? Say so. Don't claim success.
 - Never bypass gates (`--no-verify`, skipped hooks, deleted failing tests).
+
+## Documentation Discipline
+
+**Every document the agent writes obeys these eight rules.** The canonical source is `WORKFLOW.md` §2. ADR-0008 records the decision and its reconciliations.
+
+1. **Definitions and decisions only.** Capture what is true now and the decisions that brought it there. No speculation, no history, no unfounded plans. A deferred decision is in scope when it is *recorded* — an accepted ADR or a task file is fundamentação; "we might do X later" without a record is speculation and is cut.
+2. **No dates, version stamps, `DRAFT` markers, or changelogs in narrative documents.** Applies to `README.md`, `AGENTS.md` / `CLAUDE.md`, `ARCHITECTURE.md`, `DESIGN.md`, specs, and any prose page. **Decision-record artifacts are exempt** — ADRs under `doc/adr/` keep their `**Status:**` and `**Date:**` fields (Nygard supersession requires ordering); tasks under `doc/tasks/` keep their `**Created:**` field and append-only dated `Notes` log. Outside those artifacts, use git history.
+3. **No emoji anywhere.** Not in docs, code, source comments, commit messages, PR bodies, or skill outputs. Severity and status use words; structural cues use Markdown.
+4. **Business context first.** Open every document with *why* — the problem, the constraint, the user — before *what* and *how*. The first paragraph must answer "what would break if this document didn't exist".
+5. **One scope per document. No duplication.** If two documents would say the same thing, link instead of copying. The canonical location owns the content; everywhere else references it.
+6. **Code is the primary documentation of behavior.** Comments justify *why* a non-obvious choice was made — never restate *what*. If the comment is needed to explain *what*, rename or refactor.
+7. **No commented-out code; no orphan `TODO` / `FIXME` in source.** Every deferred item references a tracked work item — a GitHub Issue, or a per-task file under `doc/tasks/NNNN-*.md`. The trace must be addressable from the source line.
+8. **Tests are living documentation of behavior.** Test names and assertions read as the spec they enforce. Spec changes drive test changes; never the reverse.
+
+When generating or auditing a document, walk this list before declaring done.

package/src/skills/claude-code/agentic-review/SKILL.md

@@ -31,16 +31,22 @@ The reviewer subagent will get **only** what you assemble here. No conversation
 
 Build the handoff as a single message: a short framing paragraph (what's being reviewed, what spec applies), followed by the diff and the spec slice. No prose summary of what you think the diff does — the reviewer reads the diff itself.
 
-## Step 2 — Delegate to the subagent
+## Step 2 — Persist the handoff to disk
 
-Invoke the bundled `fresh-context-reviewer` subagent via the `Task` tool. Pass the assembled handoff as the prompt. The subagent has read-only tools (`Read, Glob, Grep, Bash`) and no write access — it cannot accidentally modify the code under review.
+Write the assembled handoff to `.agentic/reviews/<ISO-timestamp>-<scope-slug>.md` at the repo root. The path encodes both the moment of review and a short slug for the scope (`branch-vs-main`, `pr-42`, `commit-abc1234`, `working-tree`). Create the directory if it does not exist. The file is the audit trail — the user can read it later, replay the review against an updated diff, or share it with a teammate.
 
-## Step 3 — Surface findings
+This directory is ephemeral; advise the user to add `.agentic/reviews/` to their `.gitignore` if it is not already. Handoffs are per-review artifacts, not committed history.
 
-Relay the subagent's findings to the user verbatim, grouped by severity (Blocker / Concern / Note). Do **not** add commentary defending the code. Do **not** synthesize an "approve" verdict — §10 frames the reviewer as adversarial; approval is the user's call after weighing the findings.
+## Step 3 — Delegate to the subagent
+
+Invoke the bundled `fresh-context-reviewer` subagent via the `Task` tool. Pass the assembled handoff as the prompt — the same content you wrote to disk. The subagent has read-only tools (`Read, Glob, Grep, Bash`) and no write access; it cannot accidentally modify the code under review.
+
+## Step 4 — Surface findings
+
+Relay the subagent's findings to the user verbatim, grouped by severity (Blocker / Concern / Note). Do **not** add commentary defending the code. Do **not** synthesize an "approve" verdict — §10 frames the reviewer as adversarial; approval is the user's call after weighing the findings. Reference the persisted handoff path in your reply so the user can audit what was sent.
 
 If the subagent reports zero findings across all severities, say so explicitly ("no issues found in <range>"). Empty results are real signal, not a gap.
 
 ## Output contract
 
-A structured findings list grouped Blocker / Concern / Note, each finding `file:line: <emoji> <severity>: <problem>. <fix>.`. No "approve" verdict, no defending of the code, no rewrite of the diff. Empty result is reported explicitly.
+A structured findings list grouped Blocker / Concern / Note, each finding `file:line: <severity>: <problem>. <fix>.`. The path of the persisted handoff under `.agentic/reviews/` is reported alongside. No "approve" verdict, no defending of the code, no rewrite of the diff. Empty result is reported explicitly.

package/src/skills/claude-code/agentic-review/agents/fresh-context-reviewer.md

@@ -37,9 +37,7 @@ Group findings by severity:
 - **Concern** — worth a follow-up task. Real issue, not blocking the current change.
 - **Note** — informational, no action expected. Includes "no issues found in this section".
 
-Each finding: one line, `file:line: <emoji> <severity>: <problem>. <fix>.`
-
-Use `🚨` for Blocker, `⚠️` for Concern, `ℹ️` for Note.
+Each finding: one line, `file:line: <severity>: <problem>. <fix>.` Severity is the literal word `Blocker`, `Concern`, or `Note`.
 
 End with a one-line bottom-line: `Ship as-is`, `Ship with the Concerns logged as follow-up tasks`, or `Don't ship until Blockers resolved`.
 

package/src/skills/claude-code/agentic-task/SKILL.md

@@ -91,3 +91,11 @@ All Acceptance Criteria checked, plus:
 ## Output contract
 
 A single new file at `doc/tasks/<NNNN>-<short-slug>.md`. Status `proposed`. Notes empty. No existing tasks modified. No invented values.
+
+Task files are decision-record artifacts and are **exempt** from the no-dates rule (Documentation Discipline §2): the `**Created:**` field anchors the task in time and the append-only `Notes` log is dated per entry by design. The remaining Documentation Discipline rules (`WORKFLOW.md` §2) apply at write time:
+
+- No emoji anywhere in the file.
+- `Context` is the business-context-first section — *why this task exists* and *what would break without it* before *Acceptance Criteria*.
+- One scope: one task per file. If the user's request implies multiple deliverables, ask which to write first; the others become follow-up tasks.
+- No speculation. Acceptance criteria must be measurable; do not list aspirational items ("loads in under 2s", not "fast enough").
+- `Notes` is append-only and dated per entry — that is the auditability primitive, not a violation of Rule 2.

package/src/skills/codex/agentic-adr/SKILL.md

@@ -50,4 +50,10 @@ Stop after writing. Do NOT flip status to accepted — that requires user review
 
 <output_contract>
 A single new file at `doc/adr/<NNNN>-<short-slug>.md`. Status proposed. No existing ADRs modified. No invented content.
+
+ADRs are decision-record artifacts and are exempt from the no-dates rule (Documentation Discipline §2): `**Status:**` and `**Date:**` are required for Nygard supersession ordering. Remaining Documentation Discipline rules (`WORKFLOW.md` §2) apply at write time:
+- No emoji anywhere in the file.
+- `Context` is the business-context-first section — *forces* and *problem* before the *decision*.
+- One scope: one decision per ADR.
+- No speculation. `Decision` is a directive; rejected paths go in `Alternatives Considered`.
 </output_contract>

package/src/skills/codex/agentic-architecture/SKILL.md

@@ -85,4 +85,11 @@ Currently-binding decisions. Link each to `doc/adr/`.
 
 <output_contract>
 A single `ARCHITECTURE.md` at the repo root. Every line locks a binding pattern. ADR candidates flagged in the response, not written. In audit mode: drift list only, no file written.
+
+`ARCHITECTURE.md` is a narrative document, so the Documentation Discipline rules in `WORKFLOW.md` §2 apply at write time:
+- No emoji anywhere in the file.
+- No dates, version stamps, `DRAFT` markers, or changelog blocks. Architecture is the current binding pattern; lifecycle lives in ADRs and git history.
+- `Overview` is the business-context-first paragraph — *what the system does* and *what would break without it* before layers and patterns.
+- One scope: system-level patterns and boundaries. Per-decision rationale lives in ADRs; per-project operations live in `AGENTS.md`. Link, do not copy.
+- No speculation. If a layer has no observed signal, write `<TODO: not yet wired>` once; do not propose patterns absent from the code.
 </output_contract>

package/src/skills/codex/agentic-audit/SKILL.md

@@ -29,10 +29,21 @@ ADR drift (if `doc/adr/` exists):
 - Status field — every ADR has one of `proposed | accepted | deprecated | superseded by ADR-NNNN`.
 - Superseded chains — every "superseded by ADR-NNNN" target exists.
 
+Documentation discipline drift (`WORKFLOW.md` §2 / ADR-0008). Audit narrative documents — `README.md`, `AGENTS.md` / `CLAUDE.md`, `ARCHITECTURE.md`, `DESIGN.md`, any prose page under `doc/` that is not a decision-record artifact under `doc/adr/` or `doc/tasks/`:
+- Emoji — any present? Rule 3 forbids emoji anywhere (docs, code, comments, commits, skill outputs).
+- Dates / version stamps / `DRAFT` markers / changelog blocks in narrative documents — Rule 2 forbids these. Decision-record artifacts under `doc/adr/` and `doc/tasks/` are exempt.
+- Business context first — does the first paragraph answer *why* the document exists, before *what* and *how*? Rule 4.
+- Scope duplication — does the document copy material that is canonically owned by another file? Rule 5 requires linking, not copying.
+- Speculation — phrases like "we might", "in the future", "could be added", or roadmaps without an ADR / task reference. Rule 1 forbids unfounded plans.
+
+Source code (sample, not exhaustive — flag findings, not every match):
+- Orphan `TODO` / `FIXME` — Rule 7. A reference to a GitHub Issue or a `doc/tasks/NNNN-*.md` task file makes it not orphan.
+- Commented-out code blocks — Rule 7. Removed code lives in git history.
+
 Step 3 — output. One line per finding, formatted:
 `[file or section]: spec says X, code says Y. Suggested resolution: change spec / change code / discuss.`
 
-Group by artifact. If a category has no drift, print one line: `AGENTS.md — no drift.` etc. If an audited artifact does not exist, say so explicitly rather than reporting zero findings.
+Group by artifact. If a category has no drift, print one line: `AGENTS.md — no drift.` etc. If an audited artifact does not exist, say so explicitly rather than reporting zero findings. The Documentation discipline drift category groups findings under `Documentation discipline — <category>: ...`.
 
 If something the user says contradicts what the code shows, surface the conflict. Don't silently trust the user; don't silently trust the code.
 </instructions>

package/src/skills/codex/agentic-bootstrap/SKILL.md

@@ -135,4 +135,11 @@ Real traps. Each one should map to an incident or to specific code.
 
 <output_contract>
 A single `AGENTS.md` at the repo root, ≤150 lines, every line operational. No "External Resources" section. No appended Universal Agent Behavior block — that lives in the `agentic-philosophy` skill. No meta-prose explaining gaps. In audit mode: a drift list, no file written.
+
+`AGENTS.md` is a narrative document, so the Documentation Discipline rules in `WORKFLOW.md` §2 apply at write time:
+- No emoji anywhere in the file.
+- No dates, version stamps, `DRAFT` markers, or changelog blocks. Stack versions are facts (`Node ≥18`); release timelines are not.
+- `Project Overview` is the business-context-first paragraph — *why* the project exists before *what* it does.
+- One scope: this file is the operational guide for agents. Do not duplicate `ARCHITECTURE.md` patterns or ADR rationale here; link instead.
+- No speculation. If a section has no signal, write `<TODO: not yet wired>` once; do not narrate "this could be added later".
 </output_contract>

package/src/skills/codex/agentic-design/SKILL.md

@@ -45,4 +45,11 @@ If the source has tokens DESIGN.md doesn't document, list those as additions. If
 
 <output_contract>
 A single `DESIGN.md` at the repo root. YAML frontmatter uses W3C `$value`/`$type` shape. Markdown body has one section per token group present in the source. No invented tokens. No "External Resources" section. In audit mode: a drift list, no file written.
+
+`DESIGN.md` is a narrative document, so the Documentation Discipline rules in `WORKFLOW.md` §2 apply at write time:
+- No emoji anywhere — including do's and don'ts.
+- No dates, version stamps, `DRAFT` markers, or changelog blocks. Token revisions live in git history; DESIGN.md is the current visual contract.
+- The Markdown body opens with the *why* of each token group — the visual constraint or product principle — before listing rules.
+- One scope: visual contract. Component anatomy and interaction patterns live elsewhere; link, do not copy.
+- No speculation. If a group has no source token, mark `<TODO: not yet wired>` and move on.
 </output_contract>

package/src/skills/codex/agentic-philosophy/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: agentic-philosophy
-description: Universal agent behavior — think before coding, ground in real patterns, prefer simplicity, make surgical changes, define verifiable goals, verify before claiming done. Auto-invokes on non-trivial changes, refactors, debugging, "think before coding", "ground before coding", "verify done", "before implementing", or whenever the task is ambiguous enough that guardrails matter.
+description: Universal agent behavior and documentation discipline — think before coding, ground in real patterns, prefer simplicity, make surgical changes, define verifiable goals, verify before claiming done, and write documentation that captures only definitions and decisions. Auto-invokes on non-trivial changes, refactors, debugging, "think before coding", "ground before coding", "verify done", "before implementing", on documentation work — "writing docs", "writing readme", "writing architecture", "writing adr", "writing task", "audit docs" — or whenever the task is ambiguous enough that guardrails matter.
 ---
 
 <background_information>
-Six behaviors apply to every non-trivial change. Bias toward caution over speed; for trivial diffs, use judgment.
+Six behaviors apply to every non-trivial change. Bias toward caution over speed; for trivial diffs, use judgment. A separate Documentation Discipline block applies to every document the agent writes.
 </background_information>
 
 <instructions>
@@ -19,6 +19,19 @@ Six behaviors apply to every non-trivial change. Bias toward caution over speed;
 **Goal-Driven Execution.** Define success criteria. Loop until verified. Transform vague tasks into verifiable goals ("Add validation" → "Write tests for invalid inputs, then make them pass"). Before modifying a file, list which tests cover it; run, modify, run; if none, write one first. For multi-step tasks, state a brief plan with a verify step per item.
 
 **Verify Before Claiming Done.** Type-check and tests verify code, not feature. For UI/runtime changes, exercise in a browser. Can't verify? Say so — don't claim success. Never bypass gates (`--no-verify`, skipped hooks, deleted failing tests).
+
+**Documentation Discipline.** Every document the agent writes obeys eight rules. Canonical source: `WORKFLOW.md` §2. Decision: ADR-0008.
+
+1. **Definitions and decisions only.** What is true now, plus the decisions that brought it there. No speculation, no history, no unfounded plans. A deferred decision is in scope when *recorded* — an accepted ADR or a task file is fundamentação; "we might do X later" without a record is cut.
+2. **No dates, version stamps, `DRAFT` markers, or changelogs in narrative documents.** Applies to `README.md`, `AGENTS.md` / `CLAUDE.md`, `ARCHITECTURE.md`, `DESIGN.md`, specs, prose pages. **Decision-record artifacts are exempt** — ADRs under `doc/adr/` keep `**Status:**` / `**Date:**`; tasks under `doc/tasks/` keep `**Created:**` and the append-only dated `Notes` log. Outside those, use git history.
+3. **No emoji anywhere.** Not in docs, code, source comments, commit messages, PR bodies, or skill outputs. Severity and status use words; structural cues use Markdown.
+4. **Business context first.** Open with *why* — the problem, the constraint, the user — before *what* and *how*. First paragraph answers "what would break if this document didn't exist".
+5. **One scope per document. No duplication.** Link instead of copying. The canonical location owns the content; everywhere else references it.
+6. **Code is the primary documentation of behavior.** Comments justify *why* a non-obvious choice was made — never restate *what*. If the comment explains *what*, rename or refactor.
+7. **No commented-out code; no orphan `TODO` / `FIXME` in source.** Every deferred item references a tracked work item — a GitHub Issue, or a per-task file under `doc/tasks/NNNN-*.md`. The trace must be addressable from the source line.
+8. **Tests are living documentation of behavior.** Test names and assertions read as the spec they enforce. Spec changes drive test changes; never the reverse.
+
+Walk this list before declaring any documentation task done.
 </instructions>
 
 <output_contract>

package/src/skills/codex/agentic-review/SKILL.md

@@ -25,7 +25,7 @@ Step 1 — assemble the handoff. The fresh session will get only what you print
 - Relevant task file under `doc/tasks/` — if the diff or recent commit messages reference `Task NNNN`, read its Acceptance Criteria and Plan.
 - Recent commit messages for the range (`git log <range> --format=%B`).
 
-Step 2 — print the handoff inline. Format the message exactly as below so the user can copy it as a single block. Do not summarize what you think the diff does.
+Step 2 — write the handoff to disk. Save the assembled handoff at `.agentic/reviews/<ISO-timestamp>-<scope-slug>.md` at the repo root. Create the directory if missing. The slug encodes the scope (`branch-vs-main`, `pr-42`, `commit-abc1234`, `working-tree`). The file body is exactly the block below — no prose summary of what you think the diff does, the reviewer reads the diff itself.
 
 ```
 === AGENTIC-REVIEW HANDOFF ===
@@ -41,7 +41,7 @@ Review focus, in priority order:
 
 Skip formatting, naming opinions, stylistic preferences. Skip praise.
 
-Output: group findings by severity (Blocker / Concern / Note). Each finding one line: `file:line: <emoji> <severity>: <problem>. <fix>.` Use 🚨 / ⚠️ / ℹ️.
+Output: group findings by severity (Blocker / Concern / Note). Each finding one line: `file:line: <severity>: <problem>. <fix>.` Severity is the literal word `Blocker`, `Concern`, or `Note` — no emoji.
 
 End with a one-line bottom-line: "Ship as-is", "Ship with the Concerns logged as follow-up tasks", or "Don't ship until Blockers resolved". Do NOT synthesize an "approve" verdict.
 
@@ -54,15 +54,24 @@ End with a one-line bottom-line: "Ship as-is", "Ship with the Concerns logged as
 === END HANDOFF ===
 ```
 
-Step 3 — instruct the user. After printing the handoff, output exactly this and stop:
+Advise the user to add `.agentic/reviews/` to their `.gitignore` if it is not already — handoffs are ephemeral per-review artifacts, not committed history.
+
+Step 3 — instruct the user. After writing the handoff, output exactly this and stop:
 
 ```
-Copy the handoff above. Run `/clear` to drop the current context. Paste the handoff into the empty session. Codex will produce the structured findings.
+Handoff saved at <path>.
+
+Load it into a fresh Codex session:
+
+  cat <path> | pbcopy        # macOS
+  xclip -selection clipboard < <path>   # Linux
+
+Then in Codex: run `/clear`, paste from the clipboard, send. Codex will produce the structured findings.
 ```
 
 Do not proceed past this point in the current session.
 </instructions>
 
 <output_contract>
-One inline message containing the assembled handoff (review instructions + diff + spec slice), followed by a short instruction telling the user to /clear and paste. No file is written. The current session does not produce findings — the fresh session does, after the user re-loads the handoff. This honors WORKFLOW §10 by enforcing context isolation through `/clear` rather than via a subagent primitive Codex lacks.
+A handoff file at `.agentic/reviews/<ISO-timestamp>-<scope-slug>.md`, plus a short instruction telling the user how to load it into a fresh Codex session via `/clear` and paste. The current session does not produce findings — the fresh session does, after the user re-loads the handoff. This honors WORKFLOW §10 by enforcing context isolation through `/clear` rather than via a subagent primitive Codex lacks; the persisted file replaces the chat-scroll copy step that previously made the round-trip fragile.
 </output_contract>

package/src/skills/codex/agentic-task/SKILL.md

@@ -79,4 +79,11 @@ All Acceptance Criteria checked, plus:
 
 <output_contract>
 A single new file at `doc/tasks/<NNNN>-<short-slug>.md`. Status proposed. Notes empty. No existing tasks modified. No invented values.
+
+Task files are decision-record artifacts and are exempt from the no-dates rule (Documentation Discipline §2): `**Created:**` and the dated `Notes` log are required by design. Remaining Documentation Discipline rules (`WORKFLOW.md` §2) apply at write time:
+- No emoji anywhere in the file.
+- `Context` is the business-context-first section — *why this task exists* before *Acceptance Criteria*.
+- One scope: one task per file.
+- No speculation. Acceptance criteria must be measurable; do not list aspirational items.
+- `Notes` is append-only and dated per entry — that is the auditability primitive, not a violation of Rule 2.
 </output_contract>