spec-gen-cli 1.2.6 → 1.2.8

package/examples/cline-workflows/spec-gen-analyze-codebase.md

@@ -0,0 +1,100 @@
+# spec-gen: Analyze Codebase
+
+Run a full static analysis of a project using spec-gen and summarise the results:
+architecture, call graph, top refactoring issues, and duplicate code — no LLM required.
+
+## Step 1: Get the project directory
+
+Ask the user which project to analyse, or confirm we should use the current workspace root.
+
+<ask_followup_question>
+  <question>Which project directory should I analyse?</question>
+  <options>["Current workspace root", "Enter a different path"]</options>
+</ask_followup_question>
+
+## Step 2: Run static analysis
+
+Call analyze_codebase on the chosen directory.
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>analyze_codebase</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+## Step 3: Get the architecture overview
+
+Retrieve the high-level architecture map: clusters, cross-cluster dependencies,
+entry points, and critical hub functions. This is the fastest way to orient
+yourself before diving into details.
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_architecture_overview</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+Present a concise summary:
+- Total files, clusters, edges, cycles, and layer violations
+- Top 3 clusters sorted by file count, with their role (entry_layer / orchestrator /
+  hub_heavy / internal) and which clusters they depend on
+- Global entry points (the public-facing roots of the codebase)
+- Critical hub functions (high fan-in — touch with care)
+
+## Step 4: Summarise the refactor report
+
+Present a concise summary:
+- Project type and detected frameworks
+- File count, function count, internal call count
+- Top 5 refactoring issues (function name, file, issue type, priority score)
+- Detected domains
+
+## Step 5: Show the call graph
+
+Retrieve hub functions, entry points, and any layer violations.
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_call_graph</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+Highlight any hub functions (fanIn ≥ 8) or layer violations detected.
+
+## Step 6: Show duplicate code report
+
+Retrieve the duplicate function analysis (Types 1–3, pure static analysis).
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_duplicate_report</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+Present a concise summary:
+- Overall duplication ratio (e.g. "12% of functions are duplicated")
+- Top 3 clone groups sorted by impact (instances × line count):
+  - Clone type (exact / structural / near) and similarity score
+  - List of instances (file + function name + line range)
+- If no duplicates found, note this as a positive signal
+
+## Step 7: Suggest next steps
+
+Based on the analysis, guide the user through the natural next steps in order:
+1. Call `get_signatures` on the modules that contain the top issues to understand their public API
+2. Call `get_subgraph` on the highest-priority function to map its callers and callees
+3. Call `suggest_insertion_points` with a brief feature description to find where new
+   logic should land — useful before starting any new work on this codebase
+4. If significant duplication was found, suggest consolidating clone groups before refactoring
+5. Suggest running `/spec-gen-plan-refactor` once the user has enough context to act,
+   then `/spec-gen-execute-refactor` to apply the plan
+6. If the project has OpenSpec specs:
+   - Call `list_spec_domains` to discover available spec domains
+   - Call `search_specs` to find requirements by intent — this enables spec-first reasoning
+     (question → requirements → linked source files) rather than code-first exploration
+   - Suggest `/spec-gen-implement-feature` for any new feature work
+     (integrates specs + insertion points + adversarial self-check + drift check)
+   - To enable `search_specs`, run `spec-gen analyze --embed` or `spec-gen analyze --reindex-specs`
+     (requires the embedding server)
+7. If `.claude/antipatterns.md` exists, mention that it is checked automatically
+   by `/spec-gen-implement-feature` during the adversarial self-check step

package/examples/cline-workflows/spec-gen-check-spec-drift.md

@@ -0,0 +1,102 @@
+# spec-gen: Check Spec Drift
+
+Detect code changes that are not reflected in the project's OpenSpec specifications.
+Runs in static mode — no LLM required, no quota consumed.
+
+**Prerequisites**: `spec-gen init` and `spec-gen generate` must have been run at least once
+in the target project.
+
+## Step 1: Get the project directory
+
+Ask the user which project to check, or confirm the current workspace root.
+
+<ask_followup_question>
+  <question>Which project directory should I check for spec drift?</question>
+  <options>["Current workspace root", "Enter a different path"]</options>
+</ask_followup_question>
+
+## Step 2: Run drift detection
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>check_spec_drift</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+If the result contains `{ "error": "..." }`, stop and tell the user what is missing
+(not a git repo / no config / no specs) with the exact remediation command to run.
+
+## Step 3: Present the results
+
+### No drift
+
+If `hasDrift` is false and `issues` is empty:
+
+> ✅ **No spec drift detected.** All changed files are covered by up-to-date specs.
+
+Show `baseRef` and `totalChangedFiles` for context.
+
+### Drift found
+
+Present a summary line first:
+
+```
+Drift detected on $totalChangedFiles changed file(s) vs $baseRef
+Gaps: $gaps · Stale: $stale · Uncovered: $uncovered · Orphaned: $orphanedSpecs
+```
+
+Then a table of issues, sorted by severity (error first):
+
+| Severity | Kind | File | Domain | Spec | Lines changed |
+|---|---|---|---|---|---|
+| ⛔ error | gap | src/auth/login.ts | auth | specs/auth/spec.md | +45/-12 |
+| ⚠️ warning | uncovered | src/billing/invoice.ts | — | — | +120/-0 |
+
+For each issue, show the `suggestion` field on the next line in italic.
+
+## Step 4: Recommend actions
+
+Based on the issue kinds found, guide the user:
+
+### gap (spec exists but is outdated)
+> The spec for **$domain** covers `$filePath` but wasn't updated when the code changed.
+> Run `spec-gen generate --domains $domain` to regenerate it, or edit the spec manually
+> if the change is minor.
+
+### stale (spec references deleted/moved code)
+> The **$domain** spec references code that no longer exists. Either the file was deleted
+> or its structure changed significantly. Run `spec-gen generate --domains $domain` to
+> rebuild the spec from the current state of the code.
+
+### uncovered (new file with no spec)
+> `$filePath` has no matching spec. If this file introduces new domain logic, run
+> `spec-gen generate` so that spec-gen can infer a spec from it. If it is a utility
+> or test helper, it may not need a spec.
+
+### orphaned-spec (spec references non-existent files)
+> A spec references files that no longer exist. The spec may need to be deleted or its
+> `source-files` header updated. Review the spec at `$specPath` manually.
+
+## Step 5: Offer to drill down
+
+If there are `gap` or `stale` issues, offer to show the signatures of the affected files
+so the user can see exactly what changed in the public API:
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_signatures</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "filePattern": "$AFFECTED_FILE"}</arguments>
+</use_mcp_tool>
+
+## Step 6: Suggest next steps
+
+Present the following options and let the user choose:
+
+1. **Regenerate specs for affected domains** — run `spec-gen generate --domains <list>`
+   (fastest fix for `gap` and `stale` issues)
+2. **Review and edit specs manually** — appropriate for minor changes where the
+   existing spec is mostly correct
+3. **Install the pre-commit hook** — run `spec-gen drift --install-hook` so drift is
+   caught automatically before every commit
+4. **Run `/spec-gen-plan-refactor` then `/spec-gen-execute-refactor`** — if the drift
+   reveals structural issues in the changed files

package/examples/cline-workflows/spec-gen-execute-refactor.md

@@ -0,0 +1,194 @@
+# spec-gen: Execute Refactor
+
+Apply the refactoring plan produced by `/spec-gen-plan-refactor`. This workflow
+reads `.spec-gen/refactor-plan.md` at the start and re-reads it before each
+change to stay on track — especially important with small or limited models.
+
+**Prerequisites**: run `/spec-gen-plan-refactor` first and confirm the plan.
+
+## Step 1: Read the plan
+
+Read `.spec-gen/refactor-plan.md` from the project directory.
+
+If the file does not exist, stop immediately:
+> "No refactor plan found at `.spec-gen/refactor-plan.md`. Please run
+> `/spec-gen-plan-refactor` first to generate a plan."
+
+Extract and display a summary:
+- Target function, file, and line range
+- Strategy and risk score
+- Number of changes planned
+- Test command
+- Acceptance criteria
+
+Ask the user to confirm before proceeding.
+
+## Step 2: Establish a green baseline
+
+Confirm the test suite is passing. Use the test command from the plan.
+
+**If tests are already failing, stop and tell the user.** Do not proceed with
+refactoring on a red baseline — the failures must be fixed first or the user
+must explicitly acknowledge them.
+
+If a coverage tool is available, run it on the target file and compare against
+the coverage baseline in the plan.
+
+| Coverage on files to touch | Recommendation |
+|---|---|
+| ≥ 70% lines | Safe to refactor — proceed |
+| 40–69% lines | Caution — write characterisation tests for the affected functions before starting |
+| < 40% lines | **Stop.** Strongly recommend writing tests first. Refactoring untested code hides regressions. |
+| 0% (no tests at all) | **Block.** Do not refactor. Propose writing a minimal test harness first, then restart the workflow. |
+
+If coverage is below 40%, tell the user:
+> "Coverage on the target file is X%. Refactoring without test coverage risks
+> introducing silent regressions. I recommend writing tests for the affected
+> functions before proceeding. Would you like me to suggest test cases based on
+> the function signatures, or do you want to proceed at your own risk?"
+
+Only continue past this point with explicit user confirmation.
+
+**Large file warning**: If the target function spans more than 300 lines:
+> "This function is X lines long. Small models (< 13B parameters) may lose
+> code when editing files of this size in a single pass. Recommended approach:
+> apply Change 1 from the plan (smallest extraction) first to reduce the target
+> below 200 lines before the main refactor."
+
+## Step 3: Set the restore point
+
+Verify the working tree is clean, then note the restore point:
+
+```bash
+git status            # must show: nothing to commit, working tree clean
+git log --oneline -1  # note this commit hash — your restore point
+```
+
+If there are uncommitted changes, stop and ask the user to commit or stash them
+first. A clean tree guarantees that `git checkout HEAD -- <file>` will fully
+restore any file to its pre-edit state.
+
+Fill in the `Restore point` section of `.spec-gen/refactor-plan.md` with the
+current commit hash.
+
+## Step 4: Apply changes (one at a time)
+
+**Before each change**, re-read `.spec-gen/refactor-plan.md` to confirm:
+- Which change you are on
+- Exactly what to extract, where to put it, and which call sites to update
+
+**Editing tool rule**: Always prefer a targeted edit tool (`replace_in_file`,
+`str_replace_based_edit`, `apply_diff`, or equivalent) over a full-file
+rewrite tool (`write_to_file`). Only use `write_to_file` if the file is under
+100 lines in total. If a change seems to require `write_to_file` on a larger
+file, stop and split it into smaller targeted edits instead.
+
+**Model capability note**: If using a small model (Mistral Small, Phi, Gemma,
+or any model under 13B parameters), enforce an additional constraint: each edit
+must touch a contiguous block of at most 50 lines. If the intended change
+exceeds this, split it into multiple smaller extractions and apply them one
+by one.
+
+For each change in the plan:
+
+1. **Read the source file** around the lines to extract (do not rely on memory).
+
+2. **Apply the edit**:
+   - Extract or move the identified block
+   - Place it in the target file and target class specified in the plan
+   - If the target file is new, create it with only the extracted code
+   - Update all call sites listed in the plan
+
+3. **Verify the diff** before running tests:
+   ```bash
+   git diff --stat   # only the expected files should appear
+   git diff          # scan deleted lines (-) and confirm each removal is
+                     # intentional — moved to a new function or file,
+                     # not silently dropped.
+                     # If deleted lines >> added lines with no new file
+                     # created, code was likely lost — abort immediately.
+   ```
+
+4. **Run the test suite** (use the command from the plan). If any test fails,
+   restore the file right away:
+   ```bash
+   git checkout HEAD -- <file>
+   ```
+   Do NOT accumulate broken state before restoring.
+
+5. **Mark the change as done** in `.spec-gen/refactor-plan.md` by appending
+   `✅` to the change heading, then proceed to the next one.
+
+Repeat until all changes in the plan are marked ✅.
+
+## Step 5: Verify improvement
+
+Re-analyse to confirm the priority score dropped for the refactored function.
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>analyze_codebase</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "force": true}</arguments>
+</use_mcp_tool>
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_refactor_report</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+Check each acceptance criterion from the plan:
+- Priority score dropped below the target
+- Function is no longer in the top-5 list
+- Full test suite passes
+
+If not, investigate why and iterate (add a new change to the plan if needed).
+
+Run the full test suite one final time to confirm the refactored state is clean.
+
+## Step 6 (optional — requires spec-gen generate to have been run)
+
+**Important**: this step proposes irreversible changes (deletions, renames).
+Do not apply anything without explicit user confirmation at each sub-step.
+
+### 6a. Dead code: orphan functions
+
+Check for functions not covered by any spec requirement.
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_mapping</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "orphansOnly": true}</arguments>
+</use_mcp_tool>
+
+Present the orphan list (kind `function` or `class` only). For each one, check:
+- Is it exported and potentially consumed by external code?
+- Is it re-exported from an index file?
+- Was it simply missed by the LLM in Stage 3?
+
+Only after the user has reviewed and confirmed each entry, propose deletion or
+a documentation comment marking it as intentionally uncovered.
+
+**Do not delete anything without the user explicitly approving each function.**
+
+### 6b. Naming alignment: spec vocabulary vs actual names
+
+Find functions whose names diverge from the business vocabulary in the spec.
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_mapping</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+Build a table of mismatches (requirement name vs function name) and present it
+to the user for review before touching any code:
+
+| Current name | Proposed name | File | Confidence |
+|---|---|---|---|
+
+Only renames with `confidence: "llm"` should be proposed automatically.
+Flag `confidence: "heuristic"` entries for manual verification first.
+
+**Wait for explicit user approval of the full rename table before applying
+any change. Apply renames one file at a time and run tests after each.**

package/examples/cline-workflows/spec-gen-implement-feature.md

@@ -0,0 +1,238 @@
+# spec-gen: Implement Feature
+
+Plan and implement a new feature with full architectural context:
+architecture overview → OpenSpec requirements → insertion points → implementation → drift check.
+
+No code is written until Step 6. Steps 1–5 are read-only analysis.
+
+## Step 1: Get the project directory and feature description
+
+Ask the user:
+
+<ask_followup_question>
+  <question>Which project directory and what feature should I implement?</question>
+  <options>["Current workspace root", "Enter a different path"]</options>
+</ask_followup_question>
+
+Also ask for a brief description of the feature if not already provided (1–3 sentences).
+Store it as `$FEATURE_DESCRIPTION`.
+
+If `.claude/antipatterns.md` exists in the project, read it and store as `$ANTIPATTERNS`.
+This list will be cross-checked at Step 5b.
+
+## Step 2: Get the architecture overview
+
+Orient yourself before touching any code.
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_architecture_overview</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+From the result, note:
+- Which cluster(s) the feature most likely belongs to (based on role and name)
+- Critical hub functions to avoid touching unnecessarily (high fan-in → high blast radius)
+- Existing entry points — the feature may need to hook in at one of them
+
+If analysis data is missing (`{ "error": "..." }`), run `analyze_codebase` first:
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>analyze_codebase</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+Then retry `get_architecture_overview`.
+
+## Step 2.5: Stack inventory (conditional)
+
+Based on the feature description and architecture overview results, call the relevant inventory tool(s) before reading any source file. Skip if the feature clearly involves none of these areas.
+
+| Feature involves | Tool |
+|---|---|
+| Data models / ORM / database / tables | `get_schema_inventory` |
+| HTTP routes / API / endpoints | `get_route_inventory` |
+| Config / env vars / secrets | `get_env_vars` |
+| UI components | `get_ui_components` |
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_schema_inventory</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+Use results to ground the implementation plan in existing schemas/routes — don't re-create what already exists.
+
+---
+
+## Step 2.6: Audit spec coverage of the target domain
+
+Run a parity audit to check if the domain you're about to touch has spec gaps.
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>audit_spec_coverage</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+From the result, check:
+- `staleDomains` — if the target domain appears here, its spec is outdated.
+  Recommend running `spec-gen generate --domains $DOMAIN` before implementing.
+- `hubGaps` — uncovered hub functions. If the feature touches one of these,
+  add it to the adversarial check in Step 5b (high blast radius + no spec = risk).
+
+If both are clean, continue to Step 3 without action.
+
+## Step 3: Search the OpenSpec specifications (if available)
+
+Discover which spec domains exist, then search for requirements relevant to the feature.
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>list_spec_domains</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+If domains are found, search the specs semantically:
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>search_specs</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "query": "$FEATURE_DESCRIPTION", "limit": 5}</arguments>
+</use_mcp_tool>
+
+From the results, extract:
+- Existing requirements that relate to the feature (note their `id` for drift tracking)
+- Any constraints or acceptance criteria already documented
+- The `linkedFiles` — these are the source files already mapped to those requirements
+  (will be highlighted in the diagram viewer)
+
+If `search_specs` returns an index-not-found error, fall back to reading the spec file
+directly: `openspec/specs/<domain>/spec.md`.
+
+If no spec exists yet, note it — the feature will be "uncovered" and `check_spec_drift`
+will flag it after implementation. That is expected: propose running `spec-gen generate`
+after the feature lands.
+
+## Step 4: Find insertion points
+
+Identify the best functions and files to extend or hook into.
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>suggest_insertion_points</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "query": "$FEATURE_DESCRIPTION", "limit": 5}</arguments>
+</use_mcp_tool>
+
+For each candidate, present:
+- Rank, name, file, role, strategy, reason
+- Whether it appears in the relevant cluster identified in Step 2
+
+Then pick the top 1–2 candidates and inspect their call neighbourhood:
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_subgraph</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "functionName": "$TOP_CANDIDATE", "direction": "both", "format": "mermaid"}</arguments>
+</use_mcp_tool>
+
+Show the Mermaid diagram so the user can confirm the chosen insertion point is correct.
+
+## Step 5: Read the skeleton of the target file(s)
+
+Get a noise-stripped structural view of the file(s) you will modify.
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_function_skeleton</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "filePath": "$TARGET_FILE"}</arguments>
+</use_mcp_tool>
+
+Use the skeleton to:
+- Confirm the insertion strategy (extend existing function vs. add new function)
+- Identify the exact line range where new code will be added
+- Spot any existing error handling or type patterns to follow
+
+Ask the user to confirm the implementation approach before writing any code:
+
+> "I plan to [extend / add / hook into] `$TOP_CANDIDATE` in `$TARGET_FILE` by [brief description].
+> Does this match your intent?"
+
+## Step 5b: Adversarial self-check
+
+Before writing any code, state explicitly what could break with this approach.
+If `$ANTIPATTERNS` was loaded in Step 1, include any applicable patterns.
+
+> "Risk check on `$TOP_CANDIDATE`:
+> - `$CALLER_A` and `$CALLER_B` depend on this function — verify their assumptions hold after the change.
+> - `$EDGE_CASE` is not covered by the current test suite — add it in Step 6.
+> - [if antipatterns apply] AP-NNN (`$PATTERN_NAME`) — `$RULE` — applies here because `$REASON`."
+
+This is not a gate — do not wait for user input. It is a mandatory self-check
+that must appear in the output before the first line of code is written.
+
+## Step 6: Implement the feature
+
+Apply the changes incrementally:
+
+1. **Add new types / interfaces first** (if needed) — separate commit
+2. **Implement the core logic** at the chosen insertion point
+3. **Update callers** if the insertion requires updating call sites
+4. **Add or update tests** — at minimum one test covering the new behaviour
+5. **Run the test suite** to confirm nothing is broken
+
+Follow existing code style (naming conventions, error handling, import style) observed
+in the skeleton from Step 5.
+
+## Step 7: Check spec drift
+
+After implementing, verify the feature is covered by specs (or flag missing coverage).
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>check_spec_drift</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+### If drift is detected
+
+Present the issues table (see `/spec-gen-check-spec-drift` for format).
+
+For `uncovered` issues on the new files: this is expected if no spec existed.
+Offer to run `spec-gen generate` to create/update the spec:
+
+> "The new file `$NEW_FILE` has no matching spec. Run `spec-gen generate` to infer
+> one from the implementation, or edit the spec manually if the domain spec already
+> partially covers it."
+
+For `gap` issues on existing specs: the new code changed the public API of a covered
+domain. Run `spec-gen generate --domains $DOMAIN` to regenerate.
+
+### If no drift
+
+> ✅ All changed files are covered by up-to-date specs.
+
+## Step 8: Summarise
+
+Present a brief implementation summary:
+
+- **Feature**: $FEATURE_DESCRIPTION
+- **Files changed**: list with line counts
+- **Insertion point**: $TOP_CANDIDATE in $TARGET_FILE (role: $ROLE, strategy: $STRATEGY)
+- **Tests**: N added / N updated
+- **Spec drift**: ✅ clean / ⚠️ N issues (remediation: …)
+
+Suggest follow-up actions if applicable:
+- Regenerate specs (`spec-gen generate`)
+- Re-run analysis to update call graph (`analyze_codebase`)
+- If the feature touches a hub function, suggest `/spec-gen-plan-refactor` to
+  track growing complexity
+
+## Absolute constraints
+
+- **No code written before Step 6** — analysis and user confirmation come first
+- Always confirm the insertion point with the user before implementing
+- Step 5b adversarial self-check is mandatory — never skip it
+- Run tests after implementation — never skip
+- Run `check_spec_drift` as the final verification step