5-phase-workflow 3.0.0 → 3.0.1

package/README.md

@@ -92,6 +92,7 @@ Verification runs at the end of `/5:implement` and records a concise result in `
 | `/5:split` / `$5-split` | Split an existing plan into smaller linked plans for separate implementation |
 | `/5:implement` / `$5-implement` | Derive the execution graph, execute steps with agents, and verify inline |
 | `/5:review` / `$5-review` | Review code changes and save findings |
+| `/5:lean-check` / `$5-lean-check` | Check any diff for scope drift and over-engineering — works without a plan |
 | `/5:commit` / `$5-commit` | Create a git commit using the configured commit message template |
 | `/5:address-review-findings` / `$5-address-review-findings` | Decide on review findings interactively, then apply approved fixes and PR comments |
 | `/5:reconfigure` / `$5-reconfigure` | Refresh docs, index, skills, and rules |
@@ -123,6 +124,8 @@ Verification uses a dedicated agent. `/5:implement` runs `verification-agent` at
 
 Review delegates to Claude Code's built-in `code-review` skill (default effort `high`, override with `/5:review {low|medium|high|max}`) and maps its findings into the workflow's findings file. Where that skill is unavailable — Codex, for example — a built-in review agent takes over and triages changed files by risk instead. `/5:address-review-findings` presents each finding one by one with a recommendation, records `fix`/`wont_fix`/`wait` decisions, then coordinates narrower helpers for approved local fixes, PR comment triage, and PR replies so the common path stays compact.
 
+Scope drift is checked, not just discouraged, and not only inside the workflow. The generated `AGENTS.md` carries a simplicity ladder and a "check your own diff before finishing" rule for every session. `/5:lean-check` checks any diff against the request for drift, new dependencies, and over-engineering. On Claude Code, the `dependency-guard` Stop hook makes Claude justify or remove any dependency the uncommitted diff adds, once per session; Codex gets the same rule through its generated instructions. Inside `/5:implement`, executors report what they deliberately skipped and verification reports `SCOPE: passed | drift`.
+
 Reconfiguration uses a compact `.5/reconfigure-manifest.json` to pass refresh decisions to documentation and skill generation helpers without duplicating long detection summaries in prompts.
 
 For Codex installs, the workflow is token-budgeted: exploration, orchestration, and simple executors default to `gpt-5.4-mini` with low reasoning. Complex logic, security-sensitive work, data migrations, public API changes, final verification that needs deeper review, and failed retries escalate to `gpt-5.4` with medium reasoning.

package/bin/install.js

@@ -413,7 +413,8 @@ function getWorkflowManagedFiles() {
       'statusline.js',
       'check-updates.js',
       'check-reconfig.js',
-      'config-guard.js'
+      'config-guard.js',
+      'dependency-guard.js'
     ],
 
     // References: lookup tables and schemas read on-demand by commands
@@ -890,7 +891,7 @@ function cleanupOrphanedFiles(targetPath, dataDir) {
 // Ensure .5/.gitignore exists and contains transient runtime files
 function ensureDotFiveGitignore(dataDir) {
   const gitignorePath = path.join(dataDir, '.gitignore');
-  const entries = ['.update-cache.json', '.migration-v*', '.reconfig-reminder'];
+  const entries = ['.update-cache.json', '.migration-v*', '.reconfig-reminder', '.dependency-guard.json'];
   if (fs.existsSync(gitignorePath)) {
     let content = fs.readFileSync(gitignorePath, 'utf8');
     for (const entry of entries) {
@@ -1009,7 +1010,7 @@ function mergeHookArrays(targetArr, sourceArr) {
 // Hook event keys that contain arrays of hook entries
 const HOOK_ARRAY_KEYS = new Set([
   'PreToolUse', 'PostToolUse', 'SessionStart', 'SessionEnd',
-  'PreCompact', 'PostCompact'
+  'PreCompact', 'PostCompact', 'Stop', 'SubagentStop', 'UserPromptSubmit'
 ]);
 
 // Deep merge for settings.json
@@ -1077,6 +1078,7 @@ function showCommandsHelp(isGlobal) {
     log.info('  $5-split                     - Split plan into smaller plans');
     log.info('  $5-implement                 - Execute implementation + verification');
     log.info('  $5-review                    - Code review');
+    log.info('  $5-lean-check                - Check a diff for scope drift/over-engineering');
     log.info('  $5-commit                    - Create a templated git commit');
     log.info('  $5-address-review-findings   - Decide review findings & PR comments');
     log.info('  $5-configure                 - Interactive project setup');
@@ -1089,6 +1091,7 @@ function showCommandsHelp(isGlobal) {
     log.info('  /5:split                     - Split plan into smaller plans');
     log.info('  /5:implement                 - Execute implementation + verification');
     log.info('  /5:review                    - Code review');
+    log.info('  /5:lean-check                - Check a diff for scope drift/over-engineering');
     log.info('  /5:commit                    - Create a templated git commit');
     log.info('  /5:address-review-findings   - Decide review findings & PR comments');
     log.info('  /5:configure                 - Interactive project setup');
@@ -1306,6 +1309,10 @@ During the planning phase ($5-plan), until the user approves the plan:
 - Do NOT write files outside \`.5/\`
 - Do NOT write source code — only the unified plan and scan cache
 
+## Scope Discipline (replaces the dependency-guard Stop hook)
+
+Before you report any task as done — inside or outside the workflow skills — check the uncommitted diff of dependency manifests (\`package.json\`, \`requirements*.txt\`, \`pyproject.toml\`, \`go.mod\`, \`Cargo.toml\`, \`Gemfile\`, \`composer.json\`, \`pom.xml\`, \`build.gradle\`, \`*.csproj\`). For every added dependency: keep it and name it in your reply if the user asked for it; otherwise remove it with the package manager and use existing code, the standard library, a native platform feature, or an installed dependency instead. For a deeper check, run \`$5-lean-check\`.
+
 ## Configuration
 
 Run \`$5-configure\` after installation to set up your project.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "5-phase-workflow",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "A dev-workflow for Claude Code and Codex",
   "bin": {
     "foifi": "bin/install.js"
   },
   "scripts": {
-    "test": "bash test/verify-install-js.sh && bash test/test-version-compare.sh && bash test/test-check-updates-hook.sh && bash test/test-update-system.sh",
+    "test": "bash test/verify-install-js.sh && bash test/test-version-compare.sh && bash test/test-check-updates-hook.sh && bash test/test-dependency-guard.sh && bash test/test-update-system.sh",
     "test:install": "bash test/verify-install-js.sh",
     "test:hook": "bash test/test-check-updates-hook.sh",
     "test:update": "bash test/test-update-system.sh",

package/src/agents/step-executor-agent.md

@@ -21,7 +21,7 @@ You follow the plan, state entry, and existing codebase patterns. You do not wid
 
 ## Simplicity
 
-Write the minimum that satisfies the component (the "smallest coherent change"): prefer the standard library, a native framework feature, or an already-installed dependency over anything new. Add no new dependency, no abstraction for single-use code, no unrequested flexibility, and no error handling for impossible cases. Follow `Simplicity First` in the project `AGENTS.md`.
+Write the minimum that satisfies the component (the "smallest coherent change"): reuse what already exists in this codebase first, then prefer the standard library, a native framework feature, or an already-installed dependency over anything new. Add no new dependency, no abstraction for single-use code, no unrequested flexibility, and no error handling for impossible cases. Touch only the target file and what it strictly needs (its test, an import site). Follow `Simplicity First` in the project `AGENTS.md`.
 
 End with exactly:
 
@@ -32,6 +32,7 @@ FILES_CREATED: [comma-separated paths]
 FILES_MODIFIED: [comma-separated paths]
 VERIFY: passed | failed | skipped
 DEVIATIONS: none | {brief list}
+SKIPPED: none | {what you deliberately did not build — add when ...}
 ERROR: none | {error description}
 ---END---
 ```

package/src/agents/verification-agent.md

@@ -1,6 +1,6 @@
 ---
 name: verification-agent
-description: Verifies a workflow implementation across completeness, correctness, infrastructure, acceptance criteria, and quality. Used by /5:implement.
+description: Verifies a workflow implementation across completeness, correctness, infrastructure, acceptance criteria, quality, and scope. Used by /5:implement.
 tools: Read, Glob, Grep, Bash
 ---
 
@@ -22,6 +22,7 @@ Read `.5/features/{feature-name}/plan.md` and `.5/config.json` if present. Read
 4. Tests: run the configured test command unless it is `none` or the baseline and component results already prove its status.
 5. Correctness: inspect changed files and executor results to confirm the implementation matches the plan and does not only satisfy file existence. Prefer changed files and targeted imports over broad codebase scanning.
 6. Quality: logic-bearing created or modified components have tests when the project has a test framework.
+7. Scope: run `git status --short` and `git diff HEAD --stat`, and read untracked (`??`) files directly — `git diff HEAD` omits them. Every changed file traces to a planned component (its target, its test, or an import site it needs). Flag files outside the plan, work the plan's Scope marks Out or `[DEFERRED]`, new dependencies no component requires, and abstractions or configurability no acceptance criterion asks for. Report drift only in `SCOPE`; it does not change `STATUS` — the user decides what to revert.
 
 Rerun only the commands whose inputs changed. Do not rerun an identical passing command just to see it pass again.
 
@@ -36,8 +37,9 @@ COMPLETENESS: passed | partial | failed
 INFRASTRUCTURE: passed | failed
 ACCEPTANCE_CRITERIA: satisfied/total
 QUALITY: passed | partial | failed
+SCOPE: passed | drift
 ERRORS: none | {summary}
 ---END_VERIFICATION---
 ```
 
-Keep `ERRORS` to a compact summary. Do not paste command logs or diffs.
+Keep `ERRORS` to a compact summary; list each drift finding there as `drift: {path} — {why}`. Do not paste command logs or diffs.

package/src/commands/5/implement.md

@@ -69,8 +69,9 @@ Run build/test commands from `.5/config.json`. Skip commands set to `none`. Keep
 - The workflow reads the config **file** at `paths.config` itself; do not pass build/test/commit settings inline — baseline (Step 2) and auto-commit (Step 5) are run by this command, not the workflow.
 
 2. Call `Workflow({name: "5-implement", args})`.
-3. When it returns, **merge** (never replace) its `completedComponents` into the existing array and write `state.json` (Step 4). A resumed run reports only the components it ran this invocation. Mark the matching tasks completed with `TaskUpdate`. The workflow does not touch the filesystem itself.
-4. Auto-commit per step (Step 5), then report (Step 6).
+3. If the returned `verification.inline` is `true` (the workflow took the mechanical fast path and no verification agent ran), run the **fast-path scope check** from 3c yourself and set `verification.scope` from it.
+4. When it returns, **merge** (never replace) its `completedComponents` into the existing array and write `state.json` (Step 4). A resumed run reports only the components it ran this invocation. Mark the matching tasks completed with `TaskUpdate`. The workflow does not touch the filesystem itself.
+5. Auto-commit per step (Step 5), then report (Step 6).
 
 > The Workflow path persists only after the workflow returns — if a run is interrupted mid-way, this session's progress is not saved and those components run again on the next `/5:implement`. The executor's smallest-coherent-change contract makes a re-touch safe but not free.
 
@@ -95,7 +96,7 @@ For each step, skipping components already in `completedComponents`:
    - Give each executor only its component block, required `patternRefs`, verify commands, and the inline contract below — do not make it read `step-executor-agent.md`.
 
 ```text
-Implement exactly the assigned component. Read only listed patternRefs ranges/symbols and the target file. Make the smallest coherent change, run assigned verify commands, and stop (STATUS: failed) for missing dependencies, unplanned auth/schema/API changes, or unclear product decisions. If verify fails only from pre-existing unrelated issues, report it under DEVIATIONS with the exact evidence and keep STATUS: success — your change is complete. Do not make more than three attempts on the same failing issue.
+Implement exactly the assigned component. Read only listed patternRefs ranges/symbols and the target file. Make the smallest coherent change — reuse existing codebase code first, then stdlib, native platform features, and installed dependencies; touch only the target file and what it strictly needs (its test, an import site) — run assigned verify commands, and stop (STATUS: failed) for missing dependencies, unplanned auth/schema/API changes, or unclear product decisions. If verify fails only from pre-existing unrelated issues, report it under DEVIATIONS with the exact evidence and keep STATUS: success — your change is complete. Do not make more than three attempts on the same failing issue.
 
 End with:
 ---RESULT---
@@ -104,6 +105,7 @@ FILES_CREATED: [comma-separated paths]
 FILES_MODIFIED: [comma-separated paths]
 VERIFY: passed | failed | skipped
 DEVIATIONS: none | {brief list}
+SKIPPED: none | {what you deliberately did not build — add when ...}
 ERROR: none | {error description}
 ---END---
 ```
@@ -125,10 +127,19 @@ COMPLETENESS: passed | partial | failed
 INFRASTRUCTURE: passed | failed
 ACCEPTANCE_CRITERIA: satisfied/total
 QUALITY: passed | partial | failed
+SCOPE: passed | drift
 ERRORS: none | {summary}
 ---END_VERIFICATION---
 ```
 
+**Fast-path scope check** — the fast path skips `verification-agent`, so run this before Step 4 (on both the Workflow and the prose path):
+
+1. `git status --short` and `git diff HEAD --stat`: every changed file must be a planned target, its test, or an import site it needs. Anything else is drift.
+2. Changed dependency manifests or lockfiles: a dependency no component requires is drift.
+3. `git diff HEAD` on the changed files plus the full contents of untracked (`??`) files — `git diff HEAD` omits files not yet committed — read against the plan's Scope **Out** and `[DEFERRED]` decisions: work the plan excludes, or abstraction/configurability no acceptance criterion asks for, is drift.
+
+Set `SCOPE: passed | drift`. Drift never changes the verification status or `state.json`; it only goes into the report.
+
 ## Step 4: Persist Result
 
 Write `state.json` with the merged `completedComponents`, a one-line `verification` summary condensed from the block above, and `lastUpdated`. Set `status` to `completed` when verification passed; otherwise `failed`, and tell the user to fix the reported issues and rerun `/5:implement {feature-name}` to resume.
@@ -145,4 +156,9 @@ No changed files → skip. Commit error → report it and continue; do not retry
 
 ## Step 6: Report
 
-Report: completed/failed component counts, verification status, path to `state.json`, auto-commit count and any failures, and any failed commands, missing tests, or unmet acceptance criteria. Then stop.
+Report: completed/failed component counts, verification status, path to `state.json`, auto-commit count and any failures, and any failed commands, missing tests, or unmet acceptance criteria. Also list, one line each:
+
+- **Scope:** drift findings from verification, plus files an executor touched outside its planned target (the workflow returns these as `extraFiles`). Suggest `/5:lean-check {feature-name}` when there are any.
+- **Skipped:** every non-`none` `SKIPPED` entry from the executors, so deliberate omissions stay visible.
+
+Then stop.

package/src/commands/5/lean-check.md

@@ -0,0 +1,73 @@
+---
+name: 5:lean-check
+description: Checks any diff for scope drift and over-engineering — changes that do not trace to the request, new dependencies, reinvented code. Works with or without a /5:plan feature.
+allowed-tools: Bash, Read, Glob, Grep, Edit, Write, AskUserQuestion
+argument-hint: [base-branch|feature-name] [what was requested]
+user-invocable: true
+model: sonnet
+---
+
+<role>
+You are a Lean Checker. You find what a change added beyond what was asked and what could be smaller.
+You only hunt scope drift and complexity. Correctness, security, and performance belong to `/5:review`.
+</role>
+
+# Lean Check
+
+## Step 1: Collect the Diff
+
+Resolve a base, then diff the working tree against it — `git diff {base} --stat` and `git diff {base}` cover committed and uncommitted changes together; add untracked files from `git status --short`.
+
+- A base branch argument (`git rev-parse --verify {argument}` succeeds and `.5/features/{argument}/` does not exist): `base = git merge-base {argument} HEAD`.
+- A feature name (`.5/features/{argument}/` exists) or no argument: `base = git merge-base {default-branch} HEAD`, where `{default-branch}` comes from `git symbolic-ref --short refs/remotes/origin/HEAD` (fall back to `main`, then `master`). This includes commits already made by `/5:implement` with `git.autoCommit`. When `HEAD` is the default branch itself, `base = HEAD` (uncommitted changes only).
+- Any other argument is request text for Step 2.
+
+No changes → say `Nothing to check.` and stop.
+
+## Step 2: Establish the Request
+
+Every finding is judged against what was asked. Take the first that exists:
+
+1. Request text passed as an argument.
+2. `.5/features/{feature-name}/plan.md` when a feature name was passed or the current branch matches a feature — use its Scope (In/Out), Acceptance Criteria, `[DEFERRED]` decisions, and Component Checklist target paths.
+3. The request from this conversation.
+
+None of these → ask the user for one sentence describing what the change should do.
+
+## Step 3: Check
+
+Read the diff first; read full files only where a finding needs the surrounding code. Search the codebase before claiming something is reinvented.
+
+Tags, one per finding:
+
+- `drift:` a file or change that does not trace to the request (unrelated refactor, reformatting, a feature nobody asked for, work the plan marks Out or `[DEFERRED]`). Replacement: revert it.
+- `dep:` a new dependency in a manifest or lockfile. Name what already covers it (stdlib, platform, installed dependency), or `needed` if nothing does.
+- `reuse:` re-implements something that already lives in this codebase. Name the existing symbol and path.
+- `stdlib:` / `native:` hand-rolled code the standard library or platform ships. Name the function or feature.
+- `yagni:` abstraction with one implementation, config nobody sets, a layer with one caller, flexibility nobody asked for.
+- `delete:` dead code, unreachable branches, error handling for impossible cases.
+- `shrink:` same logic, fewer lines. Show the shorter form.
+
+Never flag: input validation at trust boundaries, error handling that prevents data loss, security measures, accessibility, one small test for non-trivial logic, or anything the request explicitly asked for.
+
+## Step 4: Report
+
+One line per finding, biggest cut first:
+
+```text
+{file}:L{line}: {tag} {what}. {replacement}.
+```
+
+End with `net: -{N} lines, -{M} dependencies possible.` With no findings, output `Lean already. Ship.` and stop.
+
+## Step 5: Offer to Apply
+
+Ask the user:
+
+- "Apply these cuts?"
+  - Options:
+    1. "Apply all" — apply every finding
+    2. "Only drift and dependencies" — revert unrelated changes and new dependencies, leave the rest
+    3. "No, report only"
+
+When applying: make only the listed changes, revert `drift:` hunks without touching the rest of the file, remove dependencies with the project's package manager (never by editing a lockfile by hand), then run the configured build/test commands from `.5/config.json` (skip any set to `none`) and report the result. Never commit.

package/src/commands/5/plan.md

@@ -114,6 +114,7 @@ Approving a plan means the user wants it built. Branch on the plan format you ch
 
 1. Say what you are about to do, then implement the Component Checklist directly. Make the smallest coherent change per component and follow the patterns named in the plan.
 2. Run the verify commands from `.5/config.json`. Skip any set to `none`.
+   Then check scope: `git status --short` must list only the Component Checklist target paths and what they strictly need (their tests, import sites). Revert anything else before continuing, and tell the user in one line what you deliberately left out (`skipped: X — add when Y`).
 3. Write `.5/features/{name}/state.json`:
 
 ```json

package/src/hooks/dependency-guard.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// Stop hook: when the uncommitted diff adds a dependency, make Claude justify it once
+// before finishing. New dependencies are the most reliable, heuristic-free drift signal.
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// Each extractor returns the dependency identities a manifest declares. The hook compares
+// those sets with HEAD, so config edits and version bumps of existing packages never count.
+const pep508Name = spec => (spec.trim().match(/^([A-Za-z0-9][A-Za-z0-9._-]*)/) || [])[1];
+const normalizePy = name => name && name.toLowerCase().replace(/[_.]+/g, '-');
+const jsonKeys = sections => text => { const json = JSON.parse(text); return sections.flatMap(s => Object.keys(json[s] || {})); };
+const matchAll = (text, re, pick) => [...text.matchAll(re)].map(pick);
+
+function requirementsDeps(text) {
+  return text.split('\n')
+    .map(l => l.replace(/#.*/, '').trim())
+    .filter(l => l && !l.startsWith('-'))
+    .map(l => normalizePy(pep508Name(l)))
+    .filter(Boolean);
+}
+
+// Minimal TOML walk for Cargo.toml, Pipfile, and pyproject.toml (PEP 621, PEP 735, Poetry).
+function tomlDeps(text) {
+  const deps = [];
+  let section = '';
+  let inArray = false;
+  // Collects quoted specs; returns true once the array closes (a `]` outside quotes, not in "pkg[extra]").
+  const arrayLine = line => {
+    matchAll(line, /"([^"]+)"|'([^']+)'/g, m => normalizePy(pep508Name(m[1] || m[2]))).forEach(d => d && deps.push(d));
+    return line.replace(/"[^"]*"|'[^']*'/g, '').includes(']');
+  };
+
+  for (const raw of text.split('\n')) {
+    const line = raw.replace(/\s#.*$/, '').trim();
+    if (inArray) { inArray = !arrayLine(line); continue; }
+    const header = line.match(/^\[\[?([^\]]+)\]\]?$/);
+    if (header) {
+      section = header[1].trim();
+      const dotted = section.match(/(?:^|\.)(?:dependencies|dev-dependencies|build-dependencies)\.([^.]+)$/);
+      if (dotted) deps.push(dotted[1]); // Cargo: [dependencies.serde]
+      continue;
+    }
+    const key = (line.match(/^"?([A-Za-z0-9_.-]+)"?\s*=/) || [])[1];
+    if (!key) continue;
+    const arrayOfSpecs = (section === 'project' && key === 'dependencies') ||
+      section === 'project.optional-dependencies' || section === 'dependency-groups';
+    if (arrayOfSpecs && line.includes('[')) {
+      inArray = !arrayLine(line.slice(line.indexOf('[') + 1));
+    } else if (/(?:^|\.)(?:dependencies|dev-dependencies|build-dependencies|packages|dev-packages)$/.test(section) && key !== 'python') {
+      deps.push(key);
+    }
+  }
+  return deps;
+}
+
+function goModDeps(text) {
+  const deps = [];
+  let inBlock = false;
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (/^require\s*\($/.test(line)) { inBlock = true; continue; }
+    if (inBlock && line === ')') { inBlock = false; continue; }
+    if (line.includes('// indirect')) continue; // pulled in by tooling, not chosen
+    const spec = inBlock ? line : (line.match(/^require\s+(.+)$/) || [])[1];
+    const mod = spec && spec.split(/\s+/)[0];
+    if (mod && !mod.startsWith('//')) deps.push(mod);
+  }
+  return deps;
+}
+
+const EXTRACTORS = [
+  [/^package\.json$/, jsonKeys(['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'])],
+  [/^composer\.json$/, jsonKeys(['require', 'require-dev'])],
+  [/^requirements.*\.txt$/, requirementsDeps],
+  [/^(pyproject\.toml|Pipfile|Cargo\.toml)$/, tomlDeps],
+  [/^go\.mod$/, goModDeps],
+  [/^Gemfile$/, text => matchAll(text, /^\s*gem\s+['"]([^'"]+)['"]/gm, m => m[1])],
+  [/^pom\.xml$/, text => matchAll(text, /<dependency>([\s\S]*?)<\/dependency>/g, m =>
+    [/<groupId>([^<]+)</, /<artifactId>([^<]+)</].map(re => (m[1].match(re) || [])[1] || '?').join(':'))],
+  [/^build\.gradle(\.kts)?$/, text => matchAll(text,
+    /^\s*(?:implementation|api|compileOnly|runtimeOnly|testImplementation|testRuntimeOnly|annotationProcessor|kapt|ksp|classpath)\s*\(?\s*(?:['"]([^'":]+:[^'":]+)|(libs\.[\w.]+))/gm,
+    m => m[1] || m[2])],
+  [/\.csproj$/, text => matchAll(text, /<PackageReference\s+Include="([^"]+)"/gi, m => m[1])]
+];
+
+function git(cwd, args) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+}
+
+function headVersion(root, file) {
+  try { return git(root, ['show', `HEAD:${file}`]); } catch (e) { return null; }
+}
+
+function addedDependencies(root) {
+  const changed = git(root, ['diff', 'HEAD', '--name-only']).split('\n').filter(Boolean);
+  const untracked = git(root, ['ls-files', '--others', '--exclude-standard']).split('\n').filter(Boolean);
+  const found = [];
+
+  for (const file of new Set([...changed, ...untracked])) {
+    const extract = (EXTRACTORS.find(([re]) => re.test(path.basename(file))) || [])[1];
+    const abs = path.join(root, file);
+    if (!extract || !fs.existsSync(abs)) continue;
+    try {
+      const before = headVersion(root, file);
+      const old = new Set(before ? extract(before) : []);
+      extract(fs.readFileSync(abs, 'utf8'))
+        .filter(d => !old.has(d))
+        .forEach(d => found.push(`${d} (${file})`));
+    } catch (e) {
+      // Unparseable manifest (e.g. mid-edit JSON): skip this file, keep checking the others.
+    }
+  }
+  return [...new Set(found)];
+}
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    if (data.stop_hook_active) process.exit(0); // Claude is already continuing because of a Stop hook
+
+    const root = git(data.cwd || process.cwd(), ['rev-parse', '--show-toplevel']).trim(); // git paths are root-relative
+    const deps = addedDependencies(root);
+    if (!deps.length) process.exit(0);
+
+    // Ask once per session and dependency set, so an accepted dependency doesn't nag on every stop.
+    const stateFile = path.join(root, '.5', '.dependency-guard.json');
+    const signature = `${data.session_id || ''}:${deps.slice().sort().join('|')}`;
+    let seen = [];
+    try { seen = JSON.parse(fs.readFileSync(stateFile, 'utf8')).signatures || []; } catch (e) { /* first run */ }
+    if (seen.includes(signature)) process.exit(0);
+    if (fs.existsSync(path.dirname(stateFile))) {
+      fs.writeFileSync(stateFile, JSON.stringify({ signatures: [...seen, signature].slice(-20) })); // concurrent sessions
+    }
+
+    process.stdout.write(JSON.stringify({
+      decision: 'block',
+      reason: `Uncommitted changes add dependencies:\n${deps.map(d => `- ${d}`).join('\n')}\n\n` +
+        'For each one: if the user asked for it or added it themselves, keep it and name it in your reply. ' +
+        'Otherwise remove it with the package manager (never edit a lockfile by hand) and use existing code, ' +
+        'the standard library, a native platform feature, or an installed dependency instead.'
+    }));
+    process.exit(0);
+  } catch (e) {
+    process.exit(0); // Never block on errors (not a git repo, no HEAD, unparseable manifest)
+  }
+});

package/src/settings.json

@@ -37,6 +37,17 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/dependency-guard.js",
+            "timeout": 10
+          }
+        ]
+      }
     ]
   }
 }

package/src/templates/AGENTS.md

@@ -38,11 +38,14 @@ Each phase produces a specific artifact - do not create artifacts belonging to o
 Before writing code, walk this decision hierarchy and stop at the first step that solves the problem:
 
 1. **Does this need to exist at all?** If the requirement is speculative, don't build it (YAGNI).
-2. Does the **language or standard library** already solve it?
-3. Is there a **native platform or framework** feature for it?
-4. Does an **already-installed dependency** cover it? Don't add a new dependency for this.
-5. Can it be a **single, clear expression** instead of a new abstraction?
-6. Only then: write the **minimum viable implementation**.
+2. Does it **already exist in this codebase**? Search before you write — reuse the helper, util, type, or pattern that is already here instead of re-implementing it.
+3. Does the **language or standard library** already solve it?
+4. Is there a **native platform or framework** feature for it?
+5. Does an **already-installed dependency** cover it? Don't add a new dependency for this.
+6. Can it be a **single, clear expression** instead of a new abstraction?
+7. Only then: write the **minimum viable implementation**.
+
+The hierarchy shortens the solution, never the reading: understand the code the change touches before picking a step.
 
 Non-negotiable regardless of the above: security, data integrity, correctness, and accessibility.
 
@@ -53,6 +56,9 @@ Then apply these rules:
 - No flexibility or configurability that was not requested.
 - No error handling for impossible scenarios.
 - If you write 200 lines and it could be 50, rewrite it.
+- Bug fix = root cause, not symptom: find every caller of the function you touch and fix the shared code path once.
+- Large or ambiguous request: build the smallest version that satisfies it and ask about the rest in the same response instead of building it speculatively.
+- When you finish, name what you deliberately left out in one line each (`skipped: X — add when Y`). No essays defending the simplification.
 
 Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
 
@@ -80,6 +86,8 @@ When your changes create orphans:
 
 The test: Every changed line should trace directly to the user's request.
 
+Before you report a task as done, check your own diff (`git status --short` and `git diff --stat`): revert files and changes that do not trace to the request, and remove new dependencies nobody asked for. For a deeper pass, run `/5:lean-check` (Codex: `$5-lean-check`).
+
 ## Goal-Driven Execution
 
 Define success criteria. Loop until verified.

package/src/workflows/5-implement.js

@@ -26,13 +26,14 @@ export const meta = {
 const RESULT_SCHEMA = {
   type: 'object',
   additionalProperties: false,
-  required: ['status', 'verify'],
+  required: ['status', 'verify', 'skipped'],
   properties: {
     status: { enum: ['success', 'failed'] },
     filesCreated: { type: 'array', items: { type: 'string' } },
     filesModified: { type: 'array', items: { type: 'string' } },
     verify: { enum: ['passed', 'failed', 'skipped'] },
     deviations: { type: 'string', description: 'none or a brief list' },
+    skipped: { type: 'string', description: 'none, or what was deliberately not built and when to add it' },
     error: { type: 'string', description: 'none or an error description' }
   }
 }
@@ -40,13 +41,14 @@ const RESULT_SCHEMA = {
 const VERIFICATION_SCHEMA = {
   type: 'object',
   additionalProperties: false,
-  required: ['status', 'completeness', 'infrastructure', 'quality'],
+  required: ['status', 'completeness', 'infrastructure', 'quality', 'scope'],
   properties: {
     status: { enum: ['passed', 'partial', 'failed'] },
     completeness: { enum: ['passed', 'partial', 'failed'] },
     infrastructure: { enum: ['passed', 'failed'] },
     acceptanceCriteria: { type: 'string', description: 'satisfied/total, e.g. "3/3"' },
     quality: { enum: ['passed', 'partial', 'failed'] },
+    scope: { enum: ['passed', 'drift'] },
     commands: {
       type: 'array',
       items: {
@@ -159,11 +161,11 @@ Intent: ${c.description || ''}
 Read only these pattern references (ranges/symbols), plus the target file for modify/rename:
 ${refs}
 
-Rules: smallest coherent change; mirror existing naming/exports/layout/tests; follow any local skill or rule; add no new dependency; no abstraction or error handling beyond what the intent requires. Fix mechanical issues you cause (imports, types, lint). STOP and report failed for missing dependencies, unplanned auth/schema/API/contract changes, or unclear product decisions. If verify fails only from pre-existing unrelated issues, report that as a deviation with the exact evidence — do not mark the component failed. Do not make more than three attempts on the same failing issue.
+Rules: smallest coherent change; reuse what already exists in this codebase before writing new code, then prefer stdlib, native platform features, and installed dependencies; touch only the target file and what it strictly needs (its test, an import site); mirror existing naming/exports/layout/tests; follow any local skill or rule; add no new dependency; no abstraction or error handling beyond what the intent requires. Fix mechanical issues you cause (imports, types, lint). STOP and report failed for missing dependencies, unplanned auth/schema/API/contract changes, or unclear product decisions. If verify fails only from pre-existing unrelated issues, report that as a deviation with the exact evidence — do not mark the component failed. Do not make more than three attempts on the same failing issue.
 
 Then run: ${verify}
 
-Return structured output: status, filesCreated, filesModified, verify, deviations (none or brief), error (none or description). Keep it concise — no logs or diffs unless failed.`
+Return structured output: status, filesCreated, filesModified, verify, deviations (none or brief), skipped (none, or what you deliberately did not build — add when ...), error (none or description). Keep it concise — no logs or diffs unless failed.`
 }
 
 function verifyPrompt(a, results, resumeDone) {
@@ -188,9 +190,9 @@ ${baseline}
 Component results:
 ${summary}
 
-Checks: completeness (every planned component done, acceptance criteria addressed); files exist for create/modify, rename moved correctly, delete removed; build + test pass (reuse the baseline and component results above when they already prove status — rerun only the commands whose inputs changed, not identical passing ones); correctness (inspect changed files, not just existence); quality (logic-bearing changes have tests when a test framework exists). Prefer changed files over broad scanning.
+Checks: completeness (every planned component done, acceptance criteria addressed); files exist for create/modify, rename moved correctly, delete removed; build + test pass (reuse the baseline and component results above when they already prove status — rerun only the commands whose inputs changed, not identical passing ones); correctness (inspect changed files, not just existence); quality (logic-bearing changes have tests when a test framework exists); scope (run \`git status --short\` and \`git diff HEAD --stat\`, and read untracked files directly since \`git diff HEAD\` omits them: every changed file traces to a planned component — its target, its test, or an import site; flag files outside the plan, work the plan's Scope marks Out or [DEFERRED], new dependencies no component requires, and unrequested abstractions — report drift only in scope; it does not change status). Prefer changed files over broad scanning.
 
-Return structured output: status, completeness, infrastructure, acceptanceCriteria ("satisfied/total"), quality, commands[], failures[].`
+Return structured output: status, completeness, infrastructure, acceptanceCriteria ("satisfied/total"), quality, scope, commands[], failures[] (one "drift: {path} — {why}" entry per drift finding).`
 }
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
@@ -294,9 +296,19 @@ const allPassed = allItems.length > 0 && allItems.every(i => i.result && i.resul
 // Non-mechanical when a component was planned as sonnet OR needed a sonnet retry to pass —
 // either signals reasoning-level work that warrants the full verification agent.
 const usedSonnet = components.some(c => (c.model || 'haiku') === 'sonnet') || allItems.some(i => i.escalated)
+// Deterministic scope signal: files an executor touched beyond its planned target(s).
+// Tests and import sites are legitimate, so this is reported for the user, never a failure.
+const extraFiles = allItems.flatMap(i => {
+  const stripDot = f => f.replace(/^\.\//, '')
+  const planned = new Set([i.component.file, i.component.sourceFile].filter(Boolean).map(stripDot))
+  const touched = i.result ? [...(i.result.filesCreated || []), ...(i.result.filesModified || [])].map(stripDot) : []
+  return touched.filter(f => !planned.has(f)).map(f => ({ component: i.component.name, file: f }))
+})
+if (extraFiles.length) log(`scope: ${extraFiles.length} file(s) touched outside planned targets`)
 let verification
 if (allPassed && !usedSonnet) {
   log('all components passed + mechanical (no sonnet, no escalation) — inline verify, no verification agent')
+  // No git access here: /5:implement runs the fast-path scope check itself when it sees inline: true.
   verification = { status: 'passed', completeness: 'passed', infrastructure: 'passed', acceptanceCriteria: 'n/a', quality: 'passed', commands: [], failures: [], inline: true }
 } else {
   if (!allItems.length) log('no components ran this invocation (resume) — verifying the already-completed feature against the plan')
@@ -324,5 +336,6 @@ return {
     items: s.items.map(i => ({ component: i.component.name, file: i.component.file, sourceFile: i.component.sourceFile, escalated: !!i.escalated, result: i.result }))
   })),
   verification,
+  extraFiles,
   status: verification.status === 'passed' ? 'completed' : 'failed'
 }