@sabaiway/agent-workflow-kit 1.10.0 → 1.12.0

package/tools/uninstall.test.mjs

@@ -0,0 +1,372 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { join, resolve } from 'node:path';
+import {
+  buildPlan,
+  executePlan,
+  formatPlan,
+  parseArgs,
+  SAFE_REMOVE,
+  MANAGED_MARKER,
+  REPORT_ONLY,
+  STOP,
+  UNINSTALL_STOP,
+} from './uninstall.mjs';
+import { OK } from './family-registry.mjs';
+
+// ── synthetic family rows (the surveyFamily shape) ─────────────────────────────
+const row = (name, kind, over = {}) => ({
+  name, kind, installed: true, skillDir: `/skills/${name}`, manifestState: OK, version: '1.0.0', ...over,
+});
+
+const KIT = row('agent-workflow-kit', 'composition-root');
+const MEMORY = row('agent-workflow-memory', 'memory-substrate');
+const ENGINE = row('agent-workflow-engine', 'methodology-engine');
+const CODEX = row('codex-cli-bridge', 'execution-backend');
+const ANTIGRAVITY = row('antigravity-cli-bridge', 'execution-backend');
+
+const find = (items, surface, member) => items.find((i) => i.surface === surface && (member ? i.member === member : true));
+
+// A path-keyed mock fs. `symlinks` maps a path → its (absolute) link target; `files` maps path →
+// contents; `dirs` is a set of present directories. realpath is identity (no symlinked bindir here).
+const mockFs = ({ symlinks = {}, files = {}, dirs = [], manifests = {} } = {}) => {
+  const enoent = (p) => Object.assign(new Error(`ENOENT: ${p}`), { code: 'ENOENT' });
+  const present = (p) => p in symlinks || p in files || dirs.includes(p);
+  return {
+    exists: (p) => present(p),
+    stat: (p) => ({ isFile: () => p in files, isDirectory: () => dirs.includes(p) }),
+    lstat: (p) => {
+      if (p in symlinks) return { isSymbolicLink: () => true, isFile: () => false };
+      if (present(p)) return { isSymbolicLink: () => false, isFile: () => p in files };
+      throw enoent(p);
+    },
+    readlink: (p) => { if (p in symlinks) return symlinks[p]; throw enoent(p); },
+    readFile: (p) => { if (p in files) return files[p]; throw enoent(p); },
+    realpath: (p) => p,
+    readManifest: (skillDir) => { if (skillDir in manifests) return manifests[skillDir]; throw enoent(skillDir); },
+  };
+};
+
+const CODEX_MANIFEST = {
+  name: 'codex-cli-bridge', kind: 'execution-backend',
+  roles: {
+    execute: { cmd: 'codex-exec', source: 'bin/codex-exec.sh' },
+    review: { cmd: 'codex-review', source: 'bin/codex-review.sh' },
+  },
+};
+
+// ── buildPlan: SKILL axis ──────────────────────────────────────────────────────
+
+describe('buildPlan — skill axis', () => {
+  it('plans a proven-managed composition-root for removal, with no shared-global warning', () => {
+    const { items } = buildPlan({ family: [KIT] }, mockFs());
+    const skill = find(items, 'skill');
+    assert.equal(skill.class, SAFE_REMOVE);
+    assert.equal(skill.path, '/skills/agent-workflow-kit');
+    assert.equal(skill.warn, null);
+  });
+
+  it('warns that a shared global (memory/engine/bridge) may be used by other projects', () => {
+    const { items } = buildPlan({ family: [MEMORY, ENGINE] }, mockFs());
+    assert.match(find(items, 'skill', 'agent-workflow-memory').warn, /GLOBAL skill/);
+    assert.match(find(items, 'skill', 'agent-workflow-engine').warn, /GLOBAL skill/);
+  });
+
+  it('STOPs (never removes) a present-but-not-ours skill dir', () => {
+    const foreign = row('agent-workflow-kit', 'composition-root', { manifestState: 'foreign' });
+    const skill = find(buildPlan({ family: [foreign] }, mockFs()).items, 'skill');
+    assert.equal(skill.class, STOP);
+    assert.match(skill.reason, /not provably ours/);
+  });
+
+  it('skips a member that is not installed', () => {
+    const { items } = buildPlan({ family: [row('agent-workflow-engine', 'methodology-engine', { installed: false, skillDir: null, manifestState: 'not-installed' })] }, mockFs());
+    assert.equal(items.length, 0);
+  });
+
+  it('limits to a single member when `member` is given', () => {
+    const { items } = buildPlan({ family: [KIT, MEMORY, ENGINE], member: 'agent-workflow-memory' }, mockFs());
+    assert.deepEqual(items.map((i) => i.member), ['agent-workflow-memory']);
+  });
+});
+
+// ── buildPlan: bridge wrappers ─────────────────────────────────────────────────
+
+describe('buildPlan — bridge wrappers', () => {
+  const bindir = '/home/u/.local/bin';
+  const skillDir = '/skills/codex-cli-bridge';
+
+  it('reverses a wrapper symlink that points at our source (managed-marker)', () => {
+    const fs = mockFs({
+      manifests: { [skillDir]: CODEX_MANIFEST },
+      symlinks: {
+        [join(bindir, 'codex-exec')]: join(skillDir, 'bin/codex-exec.sh'),
+        [join(bindir, 'codex-review')]: join(skillDir, 'bin/codex-review.sh'),
+      },
+    });
+    const { items } = buildPlan({ family: [CODEX], bindir }, fs);
+    const wrappers = items.filter((i) => i.surface === 'wrapper');
+    assert.equal(wrappers.length, 2);
+    assert.ok(wrappers.every((w) => w.class === MANAGED_MARKER));
+    assert.equal(find(wrappers, 'wrapper').expectedSrc, join(skillDir, 'bin/codex-exec.sh'));
+  });
+
+  it('STOPs on a foreign wrapper symlink (points elsewhere) — never removed', () => {
+    const fs = mockFs({
+      manifests: { [skillDir]: CODEX_MANIFEST },
+      symlinks: {
+        [join(bindir, 'codex-exec')]: '/somewhere/else/codex-exec',
+        [join(bindir, 'codex-review')]: join(skillDir, 'bin/codex-review.sh'),
+      },
+    });
+    const wrappers = buildPlan({ family: [CODEX], bindir }, fs).items.filter((i) => i.surface === 'wrapper');
+    assert.equal(wrappers.find((w) => w.path.endsWith('codex-exec')).class, STOP);
+    assert.equal(wrappers.find((w) => w.path.endsWith('codex-review')).class, MANAGED_MARKER);
+  });
+
+  it('emits no wrapper item when the link is absent', () => {
+    const fs = mockFs({ manifests: { [skillDir]: CODEX_MANIFEST } }); // no symlinks present
+    const wrappers = buildPlan({ family: [CODEX], bindir }, fs).items.filter((i) => i.surface === 'wrapper');
+    assert.equal(wrappers.length, 0);
+  });
+});
+
+// ── buildPlan: project deploy axis ─────────────────────────────────────────────
+
+describe('buildPlan — project deploy axis', () => {
+  const dir = '/proj';
+  const project = { dir, deployed: true, docsAiPresent: true, hiddenFence: true, stamps: [] };
+
+  const projectFs = (extra = {}) => mockFs({
+    files: {
+      [join(dir, '.git/hooks/pre-commit')]: '#!/usr/bin/env bash\n# myproj:install-git-hooks.mjs\nset -e\n',
+      [join(dir, '.claude/settings.json')]: '{ "includeCoAuthoredBy": false }',
+      ...extra.files,
+    },
+    dirs: [join(dir, 'docs/ai'), join(dir, 'docs/plans'), ...(extra.dirs ?? [])],
+  });
+
+  it('plans the hidden fence + marker hook as managed-marker reversals', () => {
+    const { items } = buildPlan({ family: [], project, projectDir: dir }, projectFs());
+    assert.equal(find(items, 'fence').class, MANAGED_MARKER);
+    assert.equal(find(items, 'hook').class, MANAGED_MARKER);
+  });
+
+  it('reports (never removes) an UNMARKED pre-commit hook', () => {
+    const fs = mockFs({ files: { [join(dir, '.git/hooks/pre-commit')]: '#!/bin/sh\necho mine\n' } });
+    const hook = find(buildPlan({ family: [], project: { ...project, hiddenFence: false }, projectDir: dir }, fs).items, 'hook');
+    assert.equal(hook.class, REPORT_ONLY);
+  });
+
+  it('reports the settings.json includeCoAuthoredBy edit (never auto-edits)', () => {
+    const settings = buildPlan({ family: [], project, projectDir: dir }, projectFs()).items.find((i) => i.surface === 'settings');
+    assert.equal(settings.class, REPORT_ONLY);
+  });
+
+  it('reports docs/ai, AGENTS.md, CLAUDE.md, docs/plans as never-deleted', () => {
+    const fs = projectFs({ files: { [join(dir, 'AGENTS.md')]: 'x', [join(dir, 'CLAUDE.md')]: 'x' } });
+    const docs = buildPlan({ family: [], project, projectDir: dir }, fs).items.filter((i) => i.surface === 'docs');
+    const paths = docs.map((d) => d.path).sort();
+    assert.deepEqual(paths, [join(dir, 'AGENTS.md'), join(dir, 'CLAUDE.md'), join(dir, 'docs/ai'), join(dir, 'docs/plans')].sort());
+    assert.ok(docs.every((d) => d.class === REPORT_ONLY));
+  });
+
+  it('formatPlan prints rm + git rm guidance for the report-only set', () => {
+    const plan = buildPlan({ family: [], project, projectDir: dir }, projectFs());
+    const out = formatPlan(plan);
+    assert.match(out, /KEEP \(do by hand\)/);
+    assert.match(out, /git rm -r --cached/);
+  });
+});
+
+// ── executePlan: guarded mutation ──────────────────────────────────────────────
+
+describe('executePlan — guarded', () => {
+  const okClassify = (reg) => ({ installed: true, manifestState: OK, skillDir: `/skills/${reg.name}` });
+
+  const spyDeps = (over = {}) => {
+    const calls = { removeTree: [], unlink: [], unhide: [], rmFile: [] };
+    return {
+      calls,
+      deps: {
+        classify: over.classify ?? okClassify,
+        removeTree: (p) => { calls.removeTree.push(p); return 'removed'; },
+        unlink: (p) => { calls.unlink.push(p); return 'unlinked'; },
+        hideFootprint: (opts) => { calls.unhide.push(opts); return { action: 'unhidden' }; },
+        rmFile: (p) => { calls.rmFile.push(p); },
+        // fs for the wrapper preflight inspect (report 'ours') + the hook marker re-check (present + marked).
+        lstat: () => ({ isSymbolicLink: () => true, isFile: () => false }),
+        readlink: (p) => p.replace('/home/u/.local/bin/codex-exec', '/skills/codex-cli-bridge/bin/codex-exec.sh'),
+        realpath: (p) => p,
+        exists: () => true,
+        readFile: () => '#!/usr/bin/env bash\n# myproj:install-git-hooks.mjs\nset -e\n',
+        ...over.deps,
+      },
+    };
+  };
+
+  const fullPlan = () => ({
+    projectDir: '/proj',
+    items: [
+      { surface: 'skill', member: 'agent-workflow-kit', path: '/skills/agent-workflow-kit', class: SAFE_REMOVE },
+      { surface: 'wrapper', member: 'codex-cli-bridge', path: '/home/u/.local/bin/codex-exec', expectedSrc: '/skills/codex-cli-bridge/bin/codex-exec.sh', class: MANAGED_MARKER },
+      { surface: 'fence', path: '/proj/.git/info/exclude', class: MANAGED_MARKER },
+      { surface: 'hook', path: '/proj/.git/hooks/pre-commit', class: MANAGED_MARKER },
+      { surface: 'docs', path: '/proj/docs/ai', class: REPORT_ONLY },
+    ],
+  });
+
+  it('--dry-run mutates nothing', () => {
+    const { calls, deps } = spyDeps();
+    const r = executePlan(fullPlan(), { dryRun: true }, deps);
+    assert.equal(r.applied, false);
+    assert.deepEqual([calls.removeTree, calls.unlink, calls.unhide, calls.rmFile], [[], [], [], []]);
+  });
+
+  it('without --yes mutates nothing (awaiting consent)', () => {
+    const { calls, deps } = spyDeps();
+    const r = executePlan(fullPlan(), {}, deps);
+    assert.equal(r.applied, false);
+    assert.equal(calls.removeTree.length, 0);
+  });
+
+  it('with --yes applies the auto-removable set and never touches report-only', () => {
+    const { calls, deps } = spyDeps();
+    const r = executePlan(fullPlan(), { yes: true }, deps);
+    assert.equal(r.applied, true);
+    assert.deepEqual(calls.removeTree, ['/skills/agent-workflow-kit']);
+    assert.deepEqual(calls.unlink, ['/home/u/.local/bin/codex-exec']);
+    // The fence is unhidden once for real (mutate) after being validated by a dry-run unhide (preflight).
+    assert.ok(calls.unhide.some((o) => o.dryRun === true), 'fence validated by a dry-run unhide in preflight');
+    assert.ok(calls.unhide.some((o) => !o.dryRun), 'fence unhidden for real in the mutate phase');
+    assert.deepEqual(calls.rmFile, ['/proj/.git/hooks/pre-commit']);
+    assert.equal(r.unhidden, true);
+    assert.equal(r.hookRemoved, true);
+    assert.equal(r.reported.length, 1); // the docs item, untouched
+  });
+
+  it('preflight STOPs (zero mutation) when a skill dir is no longer provably ours', () => {
+    const { calls, deps } = spyDeps({ classify: () => ({ installed: true, manifestState: 'foreign', skillDir: '/skills/agent-workflow-kit' }) });
+    assert.throws(() => executePlan(fullPlan(), { yes: true }, deps), (err) => err.code === UNINSTALL_STOP);
+    assert.deepEqual([calls.removeTree, calls.unlink], [[], []]); // nothing mutated
+  });
+
+  it('preflight STOPs (zero mutation) when a wrapper turned foreign', () => {
+    const { calls, deps } = spyDeps({ deps: { readlink: () => '/somewhere/foreign' } });
+    assert.throws(() => executePlan(fullPlan(), { yes: true }, deps), (err) => err.code === UNINSTALL_STOP);
+    assert.equal(calls.removeTree.length, 0);
+  });
+
+  it('a wrapper that merely VANISHED is benign — teardown proceeds (no abort)', () => {
+    const enoent = () => { throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' }); };
+    const { calls, deps } = spyDeps({ deps: { lstat: (p) => (p.endsWith('codex-exec') ? enoent() : { isSymbolicLink: () => true, isFile: () => false }) } });
+    const r = executePlan(fullPlan(), { yes: true }, deps);
+    assert.equal(r.applied, true);
+    assert.deepEqual(calls.removeTree, ['/skills/agent-workflow-kit']); // skill still removed
+  });
+
+  it('refuses (zero mutation) when the pre-commit hook lost OUR marker since the plan', () => {
+    const { calls, deps } = spyDeps({ deps: { readFile: () => '#!/bin/sh\n# the user rewrote this hook\n' } }); // no marker
+    assert.throws(() => executePlan(fullPlan(), { yes: true }, deps), (err) => err.code === UNINSTALL_STOP);
+    assert.deepEqual([calls.removeTree, calls.rmFile], [[], []]); // nothing mutated
+  });
+
+  const planWithStop = () => ({
+    projectDir: '/proj',
+    items: [
+      { surface: 'skill', member: 'agent-workflow-kit', path: '/skills/agent-workflow-kit', class: SAFE_REMOVE },
+      { surface: 'wrapper', member: 'codex-cli-bridge', path: '/home/u/.local/bin/codex-exec', class: STOP, reason: 'foreign symlink' },
+    ],
+  });
+
+  it('a plan-time STOP (a not-ours surface) is reported + LEFT; the teardown still removes what IS ours (per-item, not global-abort)', () => {
+    const { calls, deps } = spyDeps();
+    const r = executePlan(planWithStop(), { yes: true }, deps);
+    assert.equal(r.applied, true);
+    assert.deepEqual(calls.removeTree, ['/skills/agent-workflow-kit']); // ours removed
+    assert.deepEqual(calls.unlink, []); // the foreign wrapper (STOP) is never touched
+    assert.ok(r.reported.some((i) => i.class === STOP), 'the STOP surface is surfaced, not silently dropped');
+  });
+
+  it('--dry-run never mutates, even with a STOP present', () => {
+    const { calls, deps } = spyDeps();
+    const r = executePlan(planWithStop(), { dryRun: true }, deps);
+    assert.equal(r.applied, false);
+    assert.deepEqual([calls.removeTree, calls.unlink], [[], []]);
+  });
+
+  it('a malformed fence is caught by the preflight dry-run unhide → abort before any mutation (codex #2)', () => {
+    const { calls, deps } = spyDeps({ deps: { hideFootprint: (opts) => { if (opts.dryRun) throw new Error('malformed managed block'); return { action: 'unhidden' }; } } });
+    assert.throws(() => executePlan(fullPlan(), { yes: true }, deps), (err) => err.code === UNINSTALL_STOP);
+    assert.deepEqual([calls.removeTree, calls.unlink, calls.rmFile], [[], [], []]); // fence threw in preflight → nothing mutated
+  });
+});
+
+// ── formatPlan: report-only guidance (codex #4) ─────────────────────────────────
+
+describe('formatPlan — report-only guidance', () => {
+  it('settings.json gets EDIT guidance (remove the key), never `rm`', () => {
+    const plan = { projectDir: '/proj', items: [{ surface: 'settings', path: '/proj/.claude/settings.json', class: REPORT_ONLY, reason: 'x' }] };
+    const out = formatPlan(plan);
+    assert.match(out, /edit .*settings\.json.* remove the "includeCoAuthoredBy"/);
+    assert.ok(!/rm -rf .*settings\.json/.test(out), 'settings.json is never rm-ed');
+  });
+
+  it('paths are shell-quoted in the printed rm/git-rm commands', () => {
+    const plan = { projectDir: '/p', items: [{ surface: 'docs', path: '/p/docs/ai', class: REPORT_ONLY, reason: 'x' }] };
+    const out = formatPlan(plan);
+    assert.match(out, /rm -rf '\/p\/docs\/ai'/);
+    assert.match(out, /git rm -r --cached '\/p\/docs\/ai'/);
+  });
+});
+
+// ── buildPlan: an underivable bridge manifest → STOP, not a silent half-removal (codex #3) ──────────
+
+describe('buildPlan — underivable bridge', () => {
+  it('emits a STOP for the skill (not SAFE_REMOVE) when deriveLinks throws on the bridge manifest', () => {
+    const throwingFs = {
+      readManifest: () => { throw new Error('corrupt manifest'); },
+    };
+    const codex = row('codex-cli-bridge', 'execution-backend');
+    const items = buildPlan({ family: [codex], bindir: '/home/u/.local/bin' }, throwingFs).items;
+    const skill = items.find((i) => i.surface === 'skill');
+    assert.equal(skill.class, STOP);
+    assert.ok(!items.some((i) => i.surface === 'skill' && i.class === SAFE_REMOVE));
+    assert.ok(!items.some((i) => i.surface === 'wrapper'));
+  });
+});
+
+// ── parseArgs: strict validation (codex #6) ─────────────────────────────────────
+
+describe('parseArgs — strict', () => {
+  it('accepts a clean whole-family teardown', () => {
+    const a = parseArgs(['--dir', '/proj', '--dry-run']);
+    assert.equal(a.bad, null);
+    assert.equal(a.dir, '/proj');
+    assert.equal(a.dryRun, true);
+    assert.equal(a.member, undefined);
+  });
+
+  it('accepts a valid <member>', () => {
+    assert.equal(parseArgs(['agent-workflow-memory', '--yes']).bad, null);
+    assert.equal(parseArgs(['agent-workflow-memory']).member, 'agent-workflow-memory');
+  });
+
+  it('rejects an unknown flag (a typo cannot silently slip past)', () => {
+    assert.match(parseArgs(['--yes', '--frce']).bad, /unknown option/);
+  });
+
+  it('rejects an unknown member name', () => {
+    assert.match(parseArgs(['memory']).bad, /unknown member "memory"/);
+  });
+
+  it('rejects --dir / --bindir without a value', () => {
+    assert.match(parseArgs(['--dir']).bad, /--dir requires/);
+    assert.match(parseArgs(['--dir', '--yes']).bad, /--dir requires/);
+    assert.match(parseArgs(['--bindir']).bad, /--bindir requires/);
+  });
+
+  it('rejects more than one positional', () => {
+    assert.match(parseArgs(['agent-workflow-kit', 'agent-workflow-memory']).bad, /at most one/);
+  });
+});

package/references/planning.md

@@ -1,105 +0,0 @@
-# Planning Workflow
-
-Source of truth for **how plans are written, stored, executed, and torn down**. Overrides the generic `writing-plans` skill — if both trigger, this one wins. Runtime series status (which plan is Current / Pending) lives in `docs/plans/queue.md`.
-
----
-
-## 1. Plan vocabulary
-
-Strict four-level hierarchy, used in plan files (`docs/plans/*.md`) and in verbal summaries:
-
-- **Plan** — top-level container = the plan file itself. One file = one Plan. A series of related plans is not grouped under any wrapper noun; refer to them as "Plan 1 of N", "the next plan". Series order lives in `queue.md` (§3).
-- **Phase** — a large block inside the Plan. Exactly one execution session. Ends with its own verification block. `## Phase 1: …`, `## Phase 2: …`.
-- **Step** — an atomic change inside a Phase. Numbered `<phase>.<step>`: `### 1.1. …`. One Step → one logical commit.
-- **Substep** — optional split of a complex Step. Lettered: `**1.2.a**`, `**1.2.b**`. Use only when a Step cannot be one command.
-
-Reserve the word "task" for the todo list and `active_plan.md` — not for plan structure.
-
-## 2. Plan directory & lifecycle
-
-Plan files are **ephemeral, machine-local scratch space**, gitignored (`.gitignore` contains `docs/plans/`).
-
-**Lifecycle:** Creation (untracked file) → Execution (Phases 1..N-1) → mandatory **Phase N: Cleanup** (§4) → Post-deletion (only `changelog.md` + ADRs remain). Plans are **NEVER committed** — full stop. Even if a plan looks load-bearing (referenced by an ADR), inline the load-bearing content into a persistent doc and delete the plan file.
-
-**Forbidden:** `git add` of any plan file; plan-file paths in committed docs; leaving plan files on disk after Cleanup. If the user says "commit the plan" — ask back: "the plan is ephemeral — what exactly should I inline into `decisions.md` / `changelog.md`?".
-
-## 3. Series & queue.md
-
-A **series** = 2+ related plans that share a roadmap. The index lives at `docs/plans/queue.md` (gitignored, machine-local):
-
-```markdown
-## Series: <name>
-
-### Current
-- **Plan N / M** — <slug> — <one-line description>
-
-### Pending
-- **Plan N+1 / M** — <slug or TBD> — <description>
-
-### Done
-- **Plan K / M** — <slug> — done YYYY-MM-DD. Outputs: <pointers>.
-```
-
-`queue.md` is initialised when the **first** plan of a series is written, not during its Cleanup — without an upfront index the execution agent has no map of the series. Each plan's Cleanup then marks itself Done (with outputs) and promotes the next plan to Current. A single, unrelated plan does not need a series entry.
-
-## 4. Required Cleanup phase
-
-Every Plan MUST end with a final **Phase N: Cleanup** — the last numbered Phase. Without it the Plan is not done.
-
-Minimum content:
-
-- **Migrate outputs** → `docs/ai/decisions.md` (AD-XXX), `changelog.md`, `known_issues.md` (Issue-XXX), `current_state.md`, `pages/<page>.md`.
-- **Inline cross-references** — `grep -rn "<plan-slug>" docs/` must be empty. Every pointer is rewritten inline or removed.
-- **Update `queue.md`** — if part of a series, mark Done + promote next.
-- **Delete the plan file** — `rm docs/plans/<slug>.md`.
-- **Verification** — `grep -rn "<slug>" .` empty; `ls docs/plans/<slug>.md` → No such file; docs cap-validator green.
-
-If a Plan is aborted mid-flight, Cleanup still runs — partial outputs land in `known_issues.md`, then the file is deleted.
-
-## 5. All work in plans
-
-Anything required for the task is a **Step inside the Plan**. Nothing "before the plan", "between plans", or "don't forget" — those evaporate at execution time because the execution agent reads only the plan file, not chat scrollback. Every dependency, check, and install is its own Step or Substep. The final "Next steps" section contains **only user-actionable** items.
-
-## 6. Plan-then-execute split
-
-Default workflow for non-trivial features (multi-file change, new service + hook + UI, architectural choices): write a **self-contained Plan** and stop. Implementation runs in a fresh session via the `executing-plans` skill.
-
-- Triggers: any feature, refactor, or change touching more than ~1 file, or non-obvious architectural choices.
-- Does NOT apply to typos, one-line fixes, doc-only edits, or pure "where is X" research — those run inline.
-- The Plan must be readable cold by a fresh agent: file paths, contracts, execution order, verification, gotchas — all inside the file.
-
-This split is a token-efficiency strategy: exploration context stays out of the execution window.
-
-### Session-continuity heuristic (split vs continue)
-
-The volume trigger above (files / LoC / tokens) is necessary but not sufficient. The deeper question is whether the planning context is the execution **payload** or **noise**:
-
-- **Split** (fresh session) when planning exploration was *broad fan-out* — many files skimmed, sub-agent dumps, wide searches to *locate* things. That context is noise for execution; discard it.
-- **Continue** in the current session when ALL hold: (1) exploration was *targeted-deep* — you read the exact files to be created/modified/copied, so execution would just re-read them; (2) no new heavy exploration is needed to execute; (3) the context budget is healthy (far from the window limit / Lost-in-the-Middle).
-- When continuing, each Phase's Verification block is a natural checkpoint. If different Phases need different cold context, continue only through the warm Phases, then split.
-
-## 7. Plan-document structure
-
-```
-# Plan: <human-readable title>
-
-## Context              ← why this Plan exists, current state, why now (reads cold)
-## Approach             ← chosen design + an explicit "What we are NOT doing"
-## Phase 1: <name>
-   ### 1.1. <step>      ← exact paths + commands
-## Phase 2: <name>
-   ...
-## Phase N: Cleanup     ← mandatory (§4)
-## Critical files       ← table: file → change kind (new / modify / delete / move)
-## Reuse                ← pointers to existing patterns/snippets to copy, not re-derive
-## Verification         ← full check sequence (mechanical + behavioural)
-## Next steps           ← user-actionable only (§5)
-```
-
-## 8. Self-review checklist (before finalizing a Plan)
-
-- Every Step has exact file paths and exact commands.
-- Every recommendation that used to live outside the Plan is now a Step (§5).
-- Vocabulary is strict (§1); the Plan ends with **Phase N: Cleanup** (§4).
-- If part of a series: `queue.md` is initialised / updated (§3).
-- No `git add <plan>` and no "commit the plan" wording in the final report.

package/tools/methodology-slot.md

@@ -1 +0,0 @@
-> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`. Full vocabulary, lifecycle, and the plan-then-execute split live in the project's **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5.