diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index c843e9f..a735dcc 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -7,7 +7,7 @@ "plugins": [ { "name": "deepgrade", - "description": "9-phase planning with an adversarial verifier-first audit gate, plan-linked troubleshooting, and documentation generation.", + "description": "Six-stage AI-Native SDLC planning (intent.md, spec.md, plan.md, review.md) with an adversarial verifier-first design gate, plan-linked troubleshooting, and documentation generation.", "category": "development", "tags": [ "planning", diff --git a/CHANGELOG.md b/CHANGELOG.md index a4d79f5..22962bc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,32 @@ ## Unreleased +### BREAKING + +- **`/deepgrade:plan` runs Anthropic's AI-Native SDLC playbook.** Nine phases + become six stages, Plan, Design, Build, Test, Deploy, Maintain, each + committing one artifact the next stage reads: `intent.md`, `spec.md` (plus + `audit.md` from the verifier gate), `plan.md` (the build plan: files, order, + risks, proof, verification), `test-plan.md`, `review.md`, and a new + `intent.md` proposed from incidents. All artifacts live in the plan folder; + `docs/specs/{name}.md`, `brainstorm.md`, `approach.md`, and `confidence.md` + are no longer written (the confidence brief is spec.md's Evidence section). + `status.json` moves to schema 2 with the six stage keys and per-stage + `started`/`completed` timestamps; a schema-1 plan is migrated on resume by a + fixed name map and its old artifacts are read where they are. Anything that + parsed the old phase names or artifact names breaks. +- **The audit score is gone.** The design gate keeps the canary, the evidence + validator, the criterion registry, and the rubric-free pass; the 8-dimension + 1-5 score, `/40` totals, bands, `score_history`, and the score clause in the + review waiver are removed. plan-auditor returns criterion verdicts only. +- New: `intent {name}` runs Stage 1 only and stops, so a non-engineer can + capture intent for a product owner to accept. Deploy adds a diff-versus-plan + check (unplanned and untouched files, intent constraints against the code) + that must be acknowledged in plan.md before release, and the skill never runs + a release command: it prepares and asks a named human. Troubleshoot proposes + a Draft intent for SEV1/SEV2 or recurring incidents linked to a plan. + plan-status prints intent-to-spec, spec-to-plan, plan-to-release elapsed. + ### Changed - **`/deepgrade:plan` is a skill.** The 1,710-line command is now `skills/plan/SKILL.md` (a 319-line router) plus one file per phase under diff --git a/README.md b/README.md index 3eac1ae..b537aab 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ marketplace, one release, install any subset: | Plugin | What it does | Who installs it | | ------ | ------------ | --------------- | -| [`deepgrade`](plugins/deepgrade/) | 9-phase planning with an adversarial verifier-first audit gate, plan-linked troubleshooting, documentation generation | Developers living in `docs/plans/` daily | +| [`deepgrade`](plugins/deepgrade/) | Six-stage AI-Native SDLC planning (intent, spec, plan, test, release, maintain) with an adversarial verifier-first design gate, plan-linked troubleshooting, documentation generation | Developers living in `docs/plans/` daily | | [`deepgrade-readiness`](plugins/deepgrade-readiness/) | AI-readiness scan: 52 checks, 9 categories, composite letter grade A+ to F, generated scaffolding | Consultants and leads grading many repos | | [`deepgrade-audit`](plugins/deepgrade-audit/) | Severity-graded codebase audits, security scans, delta/KPI tracking, characterization tests, generated CI gates | Engineering managers doing due diligence | | [`deepgrade-guard`](plugins/deepgrade-guard/) | Always-on safety hooks: force-push and DB-deploy blocking, migration protection, change/test tracking, session summaries | Everyone — recommended universal co-install | diff --git a/interop.md b/interop.md index c4f7161..b5adedc 100644 --- a/interop.md +++ b/interop.md @@ -27,9 +27,9 @@ Format rules (the sweep depends on them): | docs/audit/readability/readability-report.md | plugins/deepgrade-readiness/agents/readiness-report-generator.md | plugins/deepgrade-audit/commands/codebase-audit.md, plugins/deepgrade-audit/agents/delta-scanner.md, plugins/deepgrade/skills/documentation/references/spec-template.md | | docs/audit/deepgrade-report.md | plugins/deepgrade-audit/agents/deepgrade-report-generator.md | plugins/deepgrade/scripts/dg-session-start.js | | docs/audit/risk-assessment.md | plugins/deepgrade-audit/agents/risk-assessor.md | plugins/deepgrade/agents/plan-scaffolder.md, plugins/deepgrade/agents/plan-auditor.md, plugins/deepgrade/commands/quick-plan.md, plugins/deepgrade/skills/documentation/SKILL.md, plugins/deepgrade/skills/documentation/references/spec-template.md | -| docs/audit/dependency-map.md | plugins/deepgrade-audit/agents/dependency-mapper.md | plugins/deepgrade/agents/plan-scaffolder.md, plugins/deepgrade/agents/plan-auditor.md, plugins/deepgrade/commands/quick-plan.md, plugins/deepgrade/skills/plan/phases/phase-7-impact-review.md, plugins/deepgrade/skills/documentation/references/spec-template.md | +| docs/audit/dependency-map.md | plugins/deepgrade-audit/agents/dependency-mapper.md | plugins/deepgrade/agents/plan-scaffolder.md, plugins/deepgrade/agents/plan-auditor.md, plugins/deepgrade/commands/quick-plan.md, plugins/deepgrade/skills/plan/stages/stage-3-build.md, plugins/deepgrade/skills/documentation/references/spec-template.md | | docs/audit/feature-inventory.md | plugins/deepgrade-audit/agents/feature-scanner.md | plugins/deepgrade/commands/quick-plan.md, plugins/deepgrade/skills/documentation/SKILL.md, plugins/deepgrade/skills/documentation/references/spec-template.md | -| docs/audit/integration-scan.md | plugins/deepgrade-audit/agents/integration-scanner.md | plugins/deepgrade/agents/plan-auditor.md, plugins/deepgrade/commands/quick-plan.md, plugins/deepgrade/skills/plan/phases/phase-7-impact-review.md, plugins/deepgrade/skills/documentation/references/spec-template.md | +| docs/audit/integration-scan.md | plugins/deepgrade-audit/agents/integration-scanner.md | plugins/deepgrade/agents/plan-auditor.md, plugins/deepgrade/commands/quick-plan.md, plugins/deepgrade/skills/plan/stages/stage-3-build.md, plugins/deepgrade/skills/documentation/references/spec-template.md | | docs/audit/audit-progress.md | plugins/deepgrade-audit/commands/codebase-audit.md | plugins/deepgrade-readiness/agents/baseline-scanner.md | ## The readability-score.json schema diff --git a/plugins/deepgrade/.claude-plugin/plugin.json b/plugins/deepgrade/.claude-plugin/plugin.json index e59e654..5aa6de7 100644 --- a/plugins/deepgrade/.claude-plugin/plugin.json +++ b/plugins/deepgrade/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "deepgrade", "version": "7.1.0", - "description": "DeepGrade planning: 9-phase idea-to-handoff planning with an adversarial verifier-first audit gate, plan-linked troubleshooting, and documentation generation. Stack-agnostic.", + "description": "DeepGrade planning: six-stage AI-Native SDLC planning (intent, spec, plan, test, release, maintain) with an adversarial verifier-first design gate, plan-linked troubleshooting, and documentation generation. Stack-agnostic.", "author": { "name": "Kyle Whynot", "url": "https://github.com/krwhynot" diff --git a/plugins/deepgrade/GUIDE.md b/plugins/deepgrade/GUIDE.md index 103adae..83266b9 100644 --- a/plugins/deepgrade/GUIDE.md +++ b/plugins/deepgrade/GUIDE.md @@ -12,8 +12,9 @@ > A reference for the deepgrade planning plugin: structured planning with an adversarial audit gate, plan-linked troubleshooting, and documentation generation. -DeepGrade's planning core walks an idea through nine phases from brainstorm to -handoff, with an adversarial audit gate in the middle: a fresh, isolated +DeepGrade's planning core walks an idea through the six stages of Anthropic's +AI-Native SDLC playbook, Plan, Design, Build, Test, Deploy, Maintain, each +committing one artifact the next stage reads, with an adversarial design gate: a fresh, isolated plan-auditor judges every plan against falsifiable criteria, its evidence is re-validated byte-for-byte by `scripts/dg-evidence-validate.js`, and a seeded canary defect (`scripts/dg-canary.js`) proves the audit can actually see @@ -45,9 +46,9 @@ methodology reference lives in the monorepo's --- ### `/deepgrade:plan` -**What it does:** Walks you through a 9-phase guided planning workflow: Brainstorm, Research, Pre-Plan, Plan, Audit, Build, Impact Review, Test, and Handoff. +**What it does:** Walks you through the six-stage playbook: Plan (intent.md), Design (spec.md plus the verifier gate), Build (plan.md, code, impact review), Test, Deploy (review.md, release authorization), Maintain (incidents become new intents). `intent {name}` captures intent only and stops. **When to use it:** For any significant initiative -- migrations, new features, refactoring projects. This is the full workflow. -**What it produces:** `docs/plans/YYYY-MM-DD-{name}/` folder with manifest, status, brainstorm, approach, research, audit, specs, and more. +**What it produces:** `docs/plans/YYYY-MM-DD-{name}/` with manifest, status, intent.md, research, spec.md, audit.md, plan.md, impact-review.md, test-plan.md, review.md. **Example:** ``` /deepgrade:plan worldpay-canada @@ -58,7 +59,7 @@ methodology reference lives in the monorepo's ### `/deepgrade:quick-plan` **What it does:** One-shot plan generation from a vague objective. Analyzes the codebase and produces a phased technical plan targeting 32+/40 on audit dimensions. -**When to use it:** For smaller changes where the full 9-phase workflow is overkill. +**When to use it:** For smaller changes where the full six-stage workflow is overkill. **What it produces:** `docs/specs/{plan-name}.md` **Example:** ``` @@ -165,7 +166,7 @@ methodology reference lives in the monorepo's Skills are persistent knowledge that loads automatically when relevant — reference books the plugin carries in its back pocket. -**plan** -- The `/deepgrade:plan` workflow itself. `SKILL.md` is a router (identity, lifecycle, workspace layout, Step 0 intent detection) and each of the nine phases lives in its own file under `phases/`, read when the phase is entered. Split this way so the later phases survive context compaction in long planning sessions instead of being silently dropped with the rest of a 1,700-line command. +**plan** -- The `/deepgrade:plan` workflow itself. `SKILL.md` is a router (identity, lifecycle, workspace layout, Step 0 intent detection and schema migration) and each of the six stages lives in its own file under `stages/`, with artifact templates under `templates/`, read when the phase is entered. Split this way so the later phases survive context compaction in long planning sessions instead of being silently dropped with the rest of a 1,700-line command. **troubleshoot** -- The `/deepgrade:troubleshoot` workflow: a router holding identity, timeline logging, plan detection, and Step 0 knowledge-base lookup, with the incident pre-flow, the four phases, multi-agent mode, and the knowledge-base write-back in one file each under `phases/`, read on entry. diff --git a/plugins/deepgrade/README.md b/plugins/deepgrade/README.md index 7c3674d..02c59ab 100644 --- a/plugins/deepgrade/README.md +++ b/plugins/deepgrade/README.md @@ -1,7 +1,8 @@ # DeepGrade (planning core) -DeepGrade's planning plugin: a 9-phase idea-to-handoff planning workflow with an -adversarial, verifier-first audit gate, plan-linked troubleshooting, and +DeepGrade's planning plugin: a six-stage idea-to-release workflow on Anthropic's +AI-Native SDLC playbook (intent.md, spec.md, plan.md, review.md) with an +adversarial, verifier-first design gate, plan-linked troubleshooting, and documentation generation. Stack-agnostic. Works on any codebase. This is one of four DeepGrade plugins in the @@ -30,7 +31,7 @@ Verify inside a Claude Code session: | Command | Description | | ------- | ----------- | -| `/deepgrade:plan` | 9-phase structured planning workflow | +| `/deepgrade:plan` | Six-stage playbook workflow: Plan, Design, Build, Test, Deploy, Maintain | | `/deepgrade:quick-plan` | Lightweight plan for small changes | | `/deepgrade:plan-status` | Check plan progress and phase status | | `/deepgrade:plan-export` | Export a plan as a portable package | diff --git a/plugins/deepgrade/agents/plan-auditor.md b/plugins/deepgrade/agents/plan-auditor.md index c5a815f..a6e6215 100644 --- a/plugins/deepgrade/agents/plan-auditor.md +++ b/plugins/deepgrade/agents/plan-auditor.md @@ -1,11 +1,11 @@ --- name: plan-auditor description: | - Use this agent to audit any technical plan, spec, or proposal. Evaluates - the plan across 8 dimensions: completeness, risk, timeline, rollback, - dependencies, team capacity, testing strategy, and go/no-go criteria. - Produces a structured audit report with a leadership-ready summary. - Called by /deepgrade:quick-audit. + Use this agent to audit any technical plan, spec, or proposal. Verifies a + plan against the criterion registry with evidence, reviewing completeness, + risk, timeline, rollback, dependencies, team capacity, testing strategy, and + go/no-go criteria. Produces a structured audit report with a leadership-ready + summary. Called by /deepgrade:quick-audit. model: opus color: purple tools: Read, Grep, Glob, Bash, Write, Agent, Skill @@ -29,8 +29,8 @@ gap you find, you suggest what should be added. -Read the provided plan document(s). Score it across 8 dimensions. Identify gaps, -risks, and strengths. Produce an audit report. Output location is determined by +Read the provided plan document(s). Verify it against the criterion registry with +evidence. Identify gaps, risks, and strengths. Produce an audit report. Output location is determined by the calling command (plan folder, conversation, or docs/audit/). If the plan references files in the codebase, read those files to verify claims. @@ -48,7 +48,7 @@ silently proceed, and do not treat this list as advisory. NEVER read: the Phase 4 generation transcript or any record of how the plan was written NEVER read: the generator's rationale, self-assessment, or claims about its own coverage NEVER read: scores, verdicts or audit.md files from a previous iteration of this plan -NEVER read: the pass threshold, band table, or any statement of what total is required +NEVER read: the pass threshold or any statement of which verdicts are required NEVER read: the plan author's identity, seniority, or team The fourth is the one that feels harmless and is not. A grader told what the @@ -57,38 +57,10 @@ ambiguity stops resolving neutrally and starts resolving toward the wanted answe You are not told where the cut is. Report what you find and let the caller apply it. - -Rate each dimension 1-5 (1 = missing/critical gaps, 5 = thorough/no gaps): - -RUBRIC CALIBRATION (applies to ALL dimensions): -Before scoring, the auditor MUST: -1. List the evidence found for this dimension -2. Map evidence to the rubric criteria below -3. Select the rubric level that matches the evidence -4. Output reasoning BEFORE the score - -Per-dimension rubric anchors: - 5/5: Section is thorough with quantified evidence, file paths verified, - measurable criteria defined. No reasonable reviewer would find a gap. - Example: "Success = 0% failure rate measured over 30 days (see metrics/billing.csv)" - 4/5: Section is present with solid evidence but one minor gap. - Example: "Success criteria defined but not all are measurable" - 3/5: Section exists but has notable gaps. Stated without evidence. - Example: "Problem described as 'important' without quantified impact" - 2/5: Section exists but is critically incomplete or unsupported. - Example: "Timeline says '2-3 months' with no breakdown by phase" - 1/5: Section is absent or is a solution disguised as a problem statement. - Example: No rollback section exists at all - -SCORING FORMAT (required for each dimension): -``` -Dimension N: [Name] -Evidence found: - - [item 1 with source reference] - - [item 2 with source reference] -Rubric match: [which level and why] -Score: X/5 -``` + +The 8 dimensions below organise the specialist review. They are lenses for finding +gaps and locating evidence, not things to be rated: every conclusion is expressed as +a per-criterion verdict (MET / UNMET / N_A) with evidence, never as a number. EVIDENCE REQUIREMENT (applies to ALL dimensions): Every finding MUST include: @@ -99,7 +71,7 @@ Every finding MUST include: - For gaps: reference WHERE in the plan the content should appear - For strengths: quote or reference the specific plan text - If a finding cannot cite any evidence, it MUST be tagged [UNVERIFIED] - and placed in a separate section. It does NOT count toward the score. + and placed in a separate section. It does NOT support any verdict. Reference the deepgrade:self-audit-knowledge skill for claim tier definitions and failure mode taxonomy. Map each finding to Tier A/B/C alongside the confidence level: @@ -177,24 +149,13 @@ Plan audit failure mode flags (append where applicable): - Is the expand/migrate/contract phasing explicit? - What does "done" look like for each phase? -Scoring guidance for methodology selection: - 5/5: Every deliverable has appropriate methodology assigned, separate test - authorship for AI code, database changes use expand/contract, AI failure - modes checked. Evidence: methodology table in spec with rationale. - 4/5: Methodologies assigned but one is suboptimal (e.g., unit tests for - refactoring when characterization would be more appropriate). - 3/5: Generic "unit tests" or "integration tests" without methodology selection. - Testing exists but isn't tailored to the type of change. - 2/5: Testing mentioned but no methodology or strategy. "We'll write tests." - 1/5: No testing strategy defined. - ## 8. Team & Resources (WHO does this?) - Is the team identified (names, roles, or at least headcount)? - Is the skill set required documented? - What happens to other work during this project? - Is there a single accountable owner? - What happens if a key person leaves mid-project? - + ## Step 1: Read the Plan @@ -244,28 +205,28 @@ codebase files + the deterministic pre-check results from Step 2. **Dimensions:** 1 (Problem Definition), 2 (Architecture & Design), 3 (Phasing) **Context:** Plan text + referenced source files + existing patterns in codebase **Focus:** Is the design sound? Does it follow existing patterns? Is the phase order right? -**Output:** Scores for dimensions 1-3 with evidence, strengths, and gaps. +**Output:** Findings for dimensions 1-3 with evidence, strengths, and gaps. ### Subagent 2: Risk Reviewer (Opus) **Dimensions:** 4 (Risk Assessment), 5 (Rollback & Safety) **Context:** Plan text + docs/audit/risk-assessment.md + docs/audit/integration-scan.md **Focus:** What could go wrong? Can we undo it? Are mitigations sufficient? -**Output:** Scores for dimensions 4-5 with evidence. Also generates the Top 5 Risks table. +**Output:** Findings for dimensions 4-5 with evidence. Also generates the Top 5 Risks table. ### Subagent 3: Execution Reviewer (Sonnet) **Dimensions:** 6 (Timeline & Effort), 8 (Team & Resources) **Context:** Plan text + docs/audit/dependency-map.md + project structure **Focus:** Is the timeline realistic? Who does the work? What about capacity? -**Output:** Scores for dimensions 6 and 8 with evidence. +**Output:** Findings for dimensions 6 and 8 with evidence. ### Subagent 4: Quality Reviewer (Sonnet) **Dimensions:** 7 (Testing & Validation) **Context:** Plan text + existing test files in codebase + test framework detection **Focus:** How do we prove this works? Are characterization tests planned? -**Output:** Score for dimension 7 with evidence. +**Output:** Findings for dimension 7 with evidence. ### Subagent 5: Gap Verifier (Opus) -**Dimensions:** None (produces structured gap artifacts, not dimension scores) +**Dimensions:** None (produces structured gap artifacts) **Context:** Available plan artifacts (see input modes below) + spec **Focus:** Systematic gap detection using 4 matrices + 15 lint rules **Output:** 4 structured artifacts: @@ -318,17 +279,17 @@ MODE DETECTION: If only a spec file is provided -> LITE MODE Log which mode was selected in the audit output. -CRITICAL: The Gap Verifier does NOT score dimensions. It produces structured -tables that expose gaps the dimension scoring might miss. A plan can score at the -top of every dimension and still have several gaps in the Coverage Matrix — which -is why the gaps, not the score, are what the caller acts on. +CRITICAL: The Gap Verifier does NOT review by dimension. It produces structured +tables that expose gaps the dimension review might miss. A plan can look clean under +every dimension and still have several gaps in the Coverage Matrix — which is why +the per-criterion verdicts and gaps are what the caller acts on. WHY 5 AGENTS: A single agent reviewing all dimensions gravitates toward the first type of issue it finds (anchoring bias). Splitting into specialists means each domain gets deep, focused attention. The Gap Verifier is separate because structural gap detection (traceability, scenarios, assumptions) uses a -fundamentally different methodology than dimension scoring. A plan can score -strongly on every dimension and still have critical gaps in coverage or assumptions. +fundamentally different methodology than dimension review. A plan can look strong +under every dimension and still have critical gaps in coverage or assumptions. MODEL SELECTION: Architecture and Risk use Opus (deep reasoning about tradeoffs and failure scenarios). Execution and Quality use Sonnet (more mechanical @@ -346,8 +307,8 @@ After receiving all 5 subagent outputs: 5. Track stats: X candidate gaps -> Y confirmed, Z dropped Cross-reference between specialists: -- If Risk Reviewer found a risk but Architecture Reviewer scored that dimension - 5/5, investigate the contradiction +- If Risk Reviewer found a risk but Architecture Reviewer reported no gap in + that dimension, investigate the contradiction - If Quality Reviewer flagged missing tests but the plan mentions them in a section the Quality Reviewer didn't read, drop the false positive @@ -369,26 +330,6 @@ Based on the audit, define: - NO-GO conditions (what would stop this project) - CONDITIONAL-GO (proceed with specific modifications) -## Step 6.5: Calibration Check - -Before writing the final report, verify scoring consistency: - -1. Review all 8 dimension scores and their reasoning -2. Check for contradictions: - - If reasoning says "all criteria met" but score is 3/5: investigate - - If reasoning says "section absent" but score is 2/5: should be 1/5 - - If two dimensions have identical evidence quality but different scores: reconcile -3. Check for anchoring bias: - - If all scores cluster within 1 point (e.g., all 3s and 4s): verify each independently - - If first dimension scored high and rest follow: re-evaluate later dimensions -4. Record calibration metadata in the report: - ``` - ## Calibration - - Contradictions found and resolved: X - - Score adjustments after calibration: Y - - Score range: [min]-[max] (spread of N) - ``` - ## Step 7: Write the Audit Report Write the audit report to the location specified by the calling command. @@ -464,27 +405,25 @@ the `command` you ran and its `exit_code` alongside the quote. A command that ex non-zero does not support a `MET`. -## Overall Score: [X/40] +## Verdict Summary + +- MET: X +- UNMET: Y +- N_A: Z + +UNMET criteria (one line each — id, and where in the plan the missing content +should appear): + +| Criterion | Location expected | Gap | +|-----------|-------------------|-----| +| LINT-NN | [section or artifact:line] | [one-line description] | -Report the total and stop. Do not band it, interpret it, or state whether the plan +Report the counts and the UNMET list and stop. Do not state whether the plan passes. You have not been told where the cut is, and that is deliberate: a grader -told the score its subject needs tends to produce a justification for reaching it -rather than a measurement. The caller owns the threshold and applies it after you -return. If you find yourself reasoning about whether a total is "enough", that is -the bias this withholding exists to prevent — report the number and the gaps. - -## Scorecard - -| Dimension | Score | Confidence | Key Strength | Key Gap | -|-----------|-------|-----------|-------------|---------| -| 1. Problem Definition | X/5 | HIGH/MED/LOW | [strength + evidence ref] | [gap or "None"] | -| 2. Architecture & Design | X/5 | HIGH/MED/LOW | [strength + evidence ref] | [gap or "None"] | -| 3. Phasing & Sequencing | X/5 | HIGH/MED/LOW | [strength + evidence ref] | [gap or "None"] | -| 4. Risk Assessment | X/5 | HIGH/MED/LOW | [strength + evidence ref] | [gap or "None"] | -| 5. Rollback & Safety | X/5 | HIGH/MED/LOW | [strength + evidence ref] | [gap or "None"] | -| 6. Timeline & Effort | X/5 | HIGH/MED/LOW | [strength + evidence ref] | [gap or "None"] | -| 7. Testing & Validation | X/5 | HIGH/MED/LOW | [strength + evidence ref] | [gap or "None"] | -| 8. Team & Resources | X/5 | HIGH/MED/LOW | [strength + evidence ref] | [gap or "None"] | +told what its subject needs tends to produce a justification for reaching it rather +than a measurement. The caller owns the gate and applies it after you return. If you +find yourself reasoning about whether the verdicts are "enough", that is the bias +this withholding exists to prevent — report the verdicts and the gaps. ## Detailed Findings @@ -582,7 +521,7 @@ Rule and Description columns verbatim from `docs/planning-techniques/lint-regist | HIGH [B] (Verified) | X | Direct evidence from plan text or codebase | | MEDIUM [B] (Inferred) | X | Indirect evidence, likely correct | | LOW [C] (Speculated) | X | Agent judgment, verify with author | -| UNVERIFIED | X | No evidence found, excluded from scoring | +| UNVERIFIED | X | No evidence found, excluded from verdicts | ## Verification Statistics - Candidate findings generated: X @@ -596,7 +535,7 @@ Rule and Description columns verbatim from `docs/planning-techniques/lint-regist - Be constructive, not destructive. Every gap should have a suggestion. - Verify claims against the actual codebase when possible. -- Score honestly. A plan with no timeline is a 1/5 on dimension 6, period. +- Verdict honestly. A plan with no timeline is UNMET on every timeline criterion, period. - Do not assume the plan author is wrong. They may know things not in the doc. Flag as "[VERIFY WITH AUTHOR]" when uncertain. - The audit report should be useful to both the plan author AND leadership. diff --git a/plugins/deepgrade/commands/help.md b/plugins/deepgrade/commands/help.md index 6bf34b5..353b10c 100644 --- a/plugins/deepgrade/commands/help.md +++ b/plugins/deepgrade/commands/help.md @@ -9,11 +9,11 @@ works on React/TypeScript, C#/.NET, Python, Rust, and Go projects. ## Commands -### Planning (the 9-phase guided workflow) +### Planning (the six-stage playbook workflow) | Command | What It Does | |---------|-------------| -| `/deepgrade:plan` | Start or resume a guided plan. 9 phases: Brainstorm, Research, Pre-Plan, Plan, Audit, Build, Impact Review, Test, Handoff. | +| `/deepgrade:plan` | Start or resume a guided plan on the AI-Native SDLC playbook. Six stages: Plan (intent.md), Design (spec.md + verifier gate), Build (plan.md), Test, Deploy (review.md), Maintain. `intent {name}` captures intent only. | | `/deepgrade:plan-status` | Show all active plans or detailed status of one plan with staleness checks. | | `/deepgrade:plan-export` | Export a plan as a self-contained zip. Includes all docs, redacts secrets, adds CLAUDE.md for vanilla Claude Code bootstrap. | @@ -31,7 +31,7 @@ works on React/TypeScript, C#/.NET, Python, Rust, and Go projects. | | `/deepgrade:plan` | `/deepgrade:quick-plan` | |--|-----------|-----------------| -| **What** | Guided 9-phase workflow | One-shot plan generation | +| **What** | Guided six-stage workflow | One-shot plan generation | | **Phases** | All 9 (Brainstorm through Handoff) | Phase 4 (Plan) only | | **Asks questions?** | Yes, walks you through interactively | No, takes objective and generates immediately | | **Creates plan folder?** | Yes: `docs/plans/2026-03-07-{name}/` | No, just writes `docs/specs/{name}.md` | @@ -185,11 +185,11 @@ Don't know which format? Just say "I need to document X" and the skill will reco 6. `/deepgrade-audit:codebase-delta` after changes to verify improvement 7. `/deepgrade-audit:codebase-security` periodically -**For planning any new work (the 9-phase guided workflow):** +**For planning any new work (the six-stage playbook workflow):** ``` /deepgrade:plan {name} ``` -Walks you through: Brainstorm -> Research -> Pre-Plan -> Plan -> Audit -> Build -> Impact Review -> Test -> Handoff +Walks you through: Plan (intent.md) -> Design (spec.md, gate) -> Build (plan.md, code) -> Test -> Deploy (review.md) -> Maintain All artifacts go to `docs/plans/{date}-{name}/`. Check progress with `/deepgrade:plan-status`. diff --git a/plugins/deepgrade/commands/plan-export.md b/plugins/deepgrade/commands/plan-export.md index 6a1339f..a487542 100644 --- a/plugins/deepgrade/commands/plan-export.md +++ b/plugins/deepgrade/commands/plan-export.md @@ -70,8 +70,10 @@ Copy everything from the plan homebase: cp -r "$PLAN_DIR"/* "$EXPORT_DIR/plans/${PLAN_NAME}/" ``` -This includes: brainstorm.md, approach.md, audit.md, impact-review.md, -test-plan.md, research/, troubleshooting/, manifest.md, status.json. +This includes: intent.md, spec.md, audit.md, evidence/, plan.md, impact-review.md, +test-plan.md, review.md, research/, changes/, troubleshooting/, manifest.md, status.json. +(A plan started before 8.0.0 has brainstorm.md and approach.md instead of +intent.md and spec.md; copy whatever is present.) ## Step 4: Copy Referenced Project Documents @@ -167,9 +169,9 @@ VERIFICATION RULE: ## Referenced Files ({N} total) | # | File Path | Phase Referenced | Found? | Notes | |---|-----------|----------------|--------|-------| -| 1 | {path} | brainstorm | [CHECK] | | -| 2 | {path} | research | [CHECK] | | -| 3 | {path} | plan | [CHECK] | | +| 1 | {path} | plan (intent) | [CHECK] | | +| 2 | {path} | plan (research) | [CHECK] | | +| 3 | {path} | design (spec) | [CHECK] | | [every file path mentioned in any plan document] MATCH SUMMARY: @@ -318,14 +320,15 @@ Suggested next steps: {context-aware based on phase + verification results}" ## Plan Summary -{Auto-generated from brainstorm.md: problem statement, goals, current phase} +{Auto-generated from intent.md: problem, proposed outcome, current stage} ## Key Documents in This Package | Document | Purpose | Path | |----------|---------|------| | manifest.md | Index of all plan files and project docs | docs/plans/{name}/manifest.md | -| brainstorm.md | Problem definition and goals | docs/plans/{name}/brainstorm.md | -| approach.md | Scope, risks, and approach | docs/plans/{name}/approach.md | +| intent.md | Problem, proposed outcome, constraints | docs/plans/{name}/intent.md | +| spec.md | Requirements, design, evidence, delivery | docs/plans/{name}/spec.md | +| plan.md | Build plan: files, order, risks, proof | docs/plans/{name}/plan.md | | status.json | Machine-readable progress | docs/plans/{name}/status.json | | codebase-verification.md | File/function reference checklist | docs/plans/{name}/codebase-verification.md | | redaction-log.md | What secrets were removed | docs/plans/{name}/redaction-log.md | @@ -380,11 +383,13 @@ Package contents: CLAUDE.md <- Auto-loads in vanilla Claude Code manifest.md <- Plan index status.json <- Current progress - brainstorm.md <- Problem + goals - approach.md <- Scope + risks - [audit.md] <- Plan audit (if exists) + intent.md <- Problem + proposed outcome + spec.md <- Requirements + design + evidence + [audit.md] <- Design gate result (if exists) + [plan.md] <- Build plan (if exists) [impact-review.md] <- Impact review (if exists) [test-plan.md] <- Test plan (if exists) + [review.md] <- Release review (if exists) research/ <- Research findings + cleaned source docs [troubleshooting/] <- Debug logs (if any) referenced-docs/ <- Copies of all linked project docs diff --git a/plugins/deepgrade/commands/plan-status.md b/plugins/deepgrade/commands/plan-status.md index ce95c65..b22471a 100644 --- a/plugins/deepgrade/commands/plan-status.md +++ b/plugins/deepgrade/commands/plan-status.md @@ -48,14 +48,17 @@ with open(sys.argv[1]) as f: fi # Count files per subdirectory - BRAINSTORM=$([ -f "$d/brainstorm.md" ] && echo "done" || echo "-") + # Artifact names follow the playbook (8.0.0). A schema-1 plan still has + # brainstorm.md/approach.md; count either so old folders do not read as empty. + INTENT=$({ [ -f "$d/intent.md" ] || [ -f "$d/brainstorm.md" ]; } && echo "done" || echo "-") RESEARCH=$(ls "$d/research/" 2>/dev/null | wc -l) - APPROACH=$([ -f "$d/approach.md" ] && echo "done" || echo "-") - PLAN=$([ -f "$d/plan.md" ] && echo "done" || echo "-") + SPEC=$({ [ -f "$d/spec.md" ] || [ -f "$d/approach.md" ]; } && echo "done" || echo "-") AUDIT=$([ -f "$d/audit.md" ] && echo "done" || echo "-") + PLAN=$([ -f "$d/plan.md" ] && echo "done" || echo "-") TEST=$([ -f "$d/test-plan.md" ] && echo "done" || echo "-") + REVIEW=$([ -f "$d/review.md" ] && echo "done" || echo "-") - echo "$NAME | phase: $PHASE | brainstorm: $BRAINSTORM | research: $RESEARCH files | approach: $APPROACH | plan: $PLAN | audit: $AUDIT | test: $TEST" + echo "$NAME | stage: $PHASE | intent: $INTENT | research: $RESEARCH files | spec: $SPEC | audit: $AUDIT | plan: $PLAN | test: $TEST | review: $REVIEW" done ``` @@ -65,29 +68,34 @@ Present as a summary table. For each plan, recommend the next action. Read docs/plans/{date}-{name}/status.json. +If `schema_version` is 1, map the old phase names to stages before reporting +(brainstorm+research -> plan; pre_plan+plan+audit -> design; build+impact_review +-> build; test -> test; handoff -> deploy) and say the plan predates 8.0.0. + Show: -1. Phase-by-phase status with freshness indicators -2. Any STALE or WARNING phases (check file hashes) -3. Build progress (if in build phase): tickets done/total/blocked -4. Audit score (if audit complete) -5. Recommended next action with reasoning +1. Stage-by-stage status with freshness indicators +2. Any STALE or WARNING stages (check file hashes) +3. Build progress (if in build stage): tickets done/total/blocked +4. Design gate result (PASS / NOT PASS, unmet criteria count) if audit.md exists +5. Playbook metrics from the stage timestamps: intent -> spec, spec -> plan, + plan -> release elapsed; plan match from review.md if present +6. Recommended next action with reasoning ``` Plan: worldpay-canada Created: 2026-03-07 -Current Phase: 6 - Build (in_progress) -Audit Score: 31/40 (YELLOW) +Current Stage: 3 - Build (in_progress) +Design gate: PASS (0 unmet criteria, canary found) +Intent -> spec: 2d 4h Spec -> plan: 1d 1h Plan -> release: pending -| # | Phase | Status | Freshness | File | -|---|-------|--------|-----------|------| -| 1 | Brainstorm | Complete | Fresh | brainstorm.md | -| 2 | Research | Complete | Warning | research/findings.md | -| 3 | Pre-Plan | Complete | Fresh | approach.md | -| 4 | Plan | Complete | Fresh | plan.md | -| 5 | Audit | Complete | Fresh | audit.md (31/40 YELLOW) | -| 6 | Build | In Progress | - | 2/24 tickets done, 1 blocked | -| 7 | Test | Not Started | - | - | -| 8 | Handoff | Not Started | - | - | +| # | Stage | Status | Freshness | Artifact | +|---|-------|--------|-----------|----------| +| 1 | Plan | Complete | Warning | intent.md (Accepted by J. Ortiz), research/findings.md | +| 2 | Design | Complete | Fresh | spec.md (Approved), audit.md (PASS) | +| 3 | Build | In Progress | - | plan.md (Approved); 2/24 tickets done, 1 blocked | +| 4 | Test | Not Started | - | - | +| 5 | Deploy | Not Started | - | - | +| 6 | Maintain | Not Started | - | - | Warning: Research findings may be stale (related files in CreditCard/ changed). Consider re-running research if current build work affects payment code. diff --git a/plugins/deepgrade/skills/plan/SKILL.md b/plugins/deepgrade/skills/plan/SKILL.md index f635fa0..529a01f 100644 --- a/plugins/deepgrade/skills/plan/SKILL.md +++ b/plugins/deepgrade/skills/plan/SKILL.md @@ -1,43 +1,47 @@ --- name: plan -description: Start or resume a guided plan. Walks you through 9 phases from idea to handoff, with AI assistance at every step. Produces documents by default; codebase writes require your approval. Pass a plan name to start new or resume existing. Optionally pass source material with 'from'. Use when the user asks to plan a feature, start or resume a plan, or take an idea through brainstorm, research, audit, build, and handoff. -argument-hint: "[plan-name] [from docs/path or 'idea: description']" +description: Start or resume a guided plan that runs the AI-Native SDLC loop. Six stages, Plan, Design, Build, Test, Deploy, Maintain, each committing one artifact the next stage reads (intent.md, spec.md, plan.md, test results, review.md, new intent). Human approval at every gate; codebase writes require your approval. Pass a plan name to start or resume, 'intent {name}' to capture intent only, or source material with 'from'. Use when the user asks to plan a feature, capture an intent, start or resume a plan, or take an idea through design, build, test, and release. +argument-hint: "[plan-name | intent plan-name] [from docs/path or 'idea: description']" allowed-tools: Read, Write, Grep, Glob, Bash, Task --- -You are a planning and implementation assistant. You guide engineers through -a structured 9-phase workflow that takes ANY starting input (vague idea, docs -folder, Jira ticket, existing spec) and produces a complete, audited, -executable plan with implementation support. +You are a planning and implementation assistant. You guide people through +Anthropic's AI-Native SDLC loop: six stages that take ANY starting input (vague +idea, docs folder, ticket, incident, existing spec) and leave a committed +artifact behind at each stage. The chain of artifacts is the audit trail: +who asked, what was produced, who approved. You are BOTH a planning tool AND an implementation helper. You produce documents automatically. You assist with code changes only on explicit approval. + +Hard rules, in every stage: +1. Human gates are real gates. Never advance past one without the recorded approval. +2. Nothing is implemented without an approved plan.md. When implementation departs + from it, update plan.md in the same commit. +3. Verify your own work before asking a human to review it. +4. Never cross the production gate. Prepare the release, then stop and ask. USE PARALLEL AGENTS WHENEVER POSSIBLE. -Anthropic's research shows multi-agent with parallel subagents outperforms -single-agent by 90%+ and reduces time by up to 90% for complex tasks. - -RULE: If a phase has 2+ tasks that don't depend on each other, +RULE: If a stage has 2+ tasks that don't depend on each other, run them as parallel subagents. Do NOT run them sequentially. -When to parallelize (by phase): -- Phase 2 (Research): 3 tracks are independent -> 3 parallel subagents -- Phase 5 (Audit): 5 specialists are independent -> 5 parallel subagents (already done) -- Phase 6 (Build): Independent tickets -> batch into parallel groups -- Phase 7 (Impact): 5 check dimensions -> 3 parallel subagents +When to parallelize (by stage): +- Stage 1 (Plan): the 3 research tracks are independent -> 3 parallel subagents +- Stage 2 (Design): the design gate's 5 audit specialists -> 5 parallel subagents +- Stage 3 (Build): independent tickets -> batches; impact review's 3 check groups -> 3 subagents +- Stage 5 (Deploy): diff-versus-plan check runs in its own fresh subagent When NOT to parallelize: -- Phase 1 (Brainstorm): Interactive with user, must be sequential -- Phase 3 (Pre-Plan): Depends on research, must be sequential -- Phase 4 (Plan): Depends on scope lock, must be sequential -- Phase 8 (Test): Tests may have execution order dependencies -- Phase 9 (Handoff): Single synthesis step +- Stage 1 intent interview: interactive with the originator, sequential +- Stage 2 scope lock and spec authoring: depends on research, sequential +- Stage 4 (Test): tests may have execution-order dependencies +- Stage 6 (Maintain): triage is a human decision -Subagent delegation rules (from Anthropic's 8 principles): +Subagent delegation rules: 1. Give each subagent a SPECIFIC, scoped objective (not vague instructions) 2. Define what THIS subagent covers vs what OTHER subagents cover 3. Specify the output format and file path @@ -46,6 +50,8 @@ Subagent delegation rules (from Anthropic's 8 principles): 6. Use Sonnet for workers, keep orchestration in the current agent 7. Store subagent outputs to filesystem (prevents context loss) 8. After all subagents complete, synthesize and cross-reference findings +9. Every subagent has a functional name, a defined scope, and a visible report; + no silent background work Scaling rules: - 1-2 independent tasks: just run them (overhead of subagents isn't worth it) @@ -54,19 +60,19 @@ Scaling rules: -9 phases, each answering exactly ONE question: - -| # | Phase | Question | Gate | -|---|-------|----------|------| -| 1 | Brainstorm | What problem are we solving? | User confirmation | -| 2 | Research | What is true about our situation? | Auto (tool decides "enough") | -| 3 | Pre-Plan | What should be in scope? | User confirmation (scope lock) | -| 4 | Plan | How will we execute? | User confirmation | -| 5 | Audit | What is weak or missing? | Evaluator-optimizer loop + human review | -| 6 | Build | Execute + track progress | Per-action approval for code | -| 7 | Impact Review | What else does this change affect? | User confirmation | -| 8 | Test | Does it work safely? | Hard pass/fail gate | -| 9 | Handoff | What happens next? | Readiness check | +Six stages. Each reads the previous artifact and commits its own. + +| # | Stage | Question | Reads | Produces | Gate | +|---|-------|----------|-------|----------|------| +| 1 | Plan | What is wanted, why, under which constraints? | idea, docs, ticket, incident | intent.md | product owner sets Status: Accepted | +| 2 | Design | What exactly will be built, and does the spec hold up? | intent.md | spec.md, audit.md | verifier gate PASS + human review, Status: Approved | +| 3 | Build | How is it implemented, and what did the change touch? | spec.md | plan.md, code, impact-review.md | plan.md approved before code; impact review confirmed | +| 4 | Test | Does it work safely? | code, plan.md | test-plan.md, results | automated tier passes, manual tier confirmed | +| 5 | Deploy | Does the diff match the plan, and who authorizes release? | diff, plan.md, intent.md | review.md | diff-versus-plan acknowledged; a named human authorizes release | +| 6 | Maintain | What did production teach us? | incidents, metrics | new intent.md | on-call triage; never auto-accepted | + +The agent does the generating, verifying, and mechanical work. Humans keep +the judgment calls. Stage 6 is the steady state; it never "completes". @@ -75,57 +81,66 @@ Four tiers of approval: 2. DOCUMENT WRITE (no approval): write to docs/plans/{date}-{name}/ 3. CODEBASE WRITE (approval required): test files, code scaffolds, generated code 4. SIDE-EFFECT COMMANDS (approval required): git operations, package installs, builds +Release to production is not a tier. The skill never runs it. -The plan folder is a HOMEBASE that contains plan-specific files and a manifest -linking to all related documents. Actual project documents (specs, ADRs, PRDs, -audits) live in standard project docs/ locations where developers expect them. +The plan folder is the HOMEBASE. Every stage artifact lives in it, named as +the playbook names them, so a reader can follow the chain from intent to +release without leaving the folder. -PLAN FOLDER (homebase): docs/plans/YYYY-MM-DD-{plan-name}/ +PLAN FOLDER: docs/plans/YYYY-MM-DD-{plan-name}/ manifest.md <- Human-readable index linking to ALL related files - status.json <- Machine-readable progress, staleness, resume state - brainstorm.md <- Phase 1 (plan-specific, lives here) - approach.md <- Phase 3 (plan-specific, lives here) - confidence.md <- Phase 3 (created), Phase 5 (reinforced) - audit.md <- Phase 5 (plan-specific, lives here) - impact-review.md <- Phase 7 (plan-specific, lives here) - test-plan.md <- Phase 8 (plan-specific, lives here) - research/ <- Phase 2 (plan-specific, lives here) + status.json <- Machine-readable progress, timestamps, resume state (schema 2) + intent.md <- Stage 1: problem, outcome, affected users/systems, constraints, open questions + research/ <- Stage 1 research tracks findings.md reference-data.json intake/ <- Cleaned source docs + spec.md <- Stage 2: requirements, design, standards, gotchas, evidence, verification plan, delivery + audit.md <- Stage 2 gate: criterion verdicts, gap outputs, canary and evidence results + evidence/ <- Stage 2 gate: one record per criterion, committed with audit.md + plan.md <- Stage 3: files that change, order of work, risks, proof, verification, parallelization changes/ <- Immutable change records (CR-001, CR-002, ...) - troubleshooting/ <- /deepgrade:troubleshoot logs linked to this plan + impact-review.md <- Stage 3 exit: cross-cutting findings, integration edges, traceability + test-plan.md <- Stage 4: test matrix, two-tier verification + review.md <- Stage 5: diff-versus-plan, constraint check, findings, release checklist, authorization + troubleshooting/ <- Stage 6: /deepgrade:troubleshoot logs linked to this plan + +TEMPLATES: ${CLAUDE_SKILL_DIR}/templates/intent.md, spec.md, plan.md, review.md. +Read the template when creating the artifact; keep its headings. PROJECT DOCUMENTS (standard locations, linked from manifest): - docs/specs/{plan-name}.md <- Phase 4 spec - docs/adr/ADR-{topic}.md <- ADRs created during plan - docs/prd/{feature}.md <- PRDs created during plan + docs/adr/ADR-{topic}.md <- ADRs created during design + docs/prd/{feature}.md <- PRDs created during design CODEBASE (on approval only): - Test files in project test directories <- Phase 7 golden master tests - Code scaffolds in source directories <- Phase 6 generated code + Test files in project test directories <- Stage 4 + Code in source directories <- Stage 3 -The manifest.md links everything together with creation dates: +manifest.md template: ```markdown # Plan: {Name} Created: {date} -Status: Phase {N} - {name} +Status: Stage {N} - {name} Owner: {name} -## Plan Files (this folder) -- [Brainstorm](brainstorm.md) - {date} -- [Approach](approach.md) - {date} -- [Confidence Brief](confidence.md) - {date} (reinforced: {date}) -- [Research](research/findings.md) - {date} -- [Audit](audit.md) - {date} -- [Impact Review](impact-review.md) - {date} -- [Test Plan](test-plan.md) - {date} +## Artifacts (this folder) +| File | Stage | Status | Date | +|------|-------|--------|------| +| [Intent](intent.md) | 1 | Draft/Accepted | {date} | +| [Research](research/findings.md) | 1 | | {date} | +| [Spec](spec.md) | 2 | Draft/Approved | {date} | +| [Audit](audit.md) | 2 | PASS/NOT PASS | {date} | +| [Build plan](plan.md) | 3 | Draft/Approved | {date} | +| [Impact review](impact-review.md) | 3 | | {date} | +| [Test plan](test-plan.md) | 4 | | {date} | +| [Review](review.md) | 5 | Authorized by {name} | {date} | ## Project Documents (in docs/) -- [Spec: {name}](../../docs/specs/{plan-name}.md) - {date} -- [ADR: {topic}](../../docs/adr/ADR-{topic}.md) - {date} +| Document | Type | Path | Created | +|----------|------|------|---------| +| (none yet) | | | | ## Change Records | CR | Date | Summary | @@ -133,8 +148,9 @@ Owner: {name} | (none yet) | | | ## Codebase Files -- {path to test files} - {date} -- {path to generated code} - {date} +| File | Type | Created | +|------|------|---------| +| (none yet) | | | ``` @@ -142,19 +158,21 @@ Owner: {name} ## Step 0: Detect Intent and Create/Resume Workspace Parse $ARGUMENTS: +- If the first word is `intent` -> INTENT-ONLY mode: run Stage 1, commit intent.md, + ask for acceptance, then STOP. Say so up front. Use this when the originator is + capturing an idea and design is someone else's decision. - If a plan folder matching the name exists in docs/plans/ -> RESUME (read status.json) -- If "from" keyword present -> NEW plan with source material -- If just a name -> NEW plan from scratch +- If "from" keyword present -> NEW plan with source material (a docs folder, a ticket, + a troubleshooting log) +- If just a name -> NEW plan from an idea For NEW plans: ```bash TODAY=$(date +%Y-%m-%d) PLAN_NAME="{name}" PLAN_DIR="docs/plans/${TODAY}-${PLAN_NAME}" -mkdir -p "$PLAN_DIR/research/intake" - -# Also ensure standard doc directories exist -mkdir -p docs/specs docs/adr docs/prd docs/audit docs/test-plans +mkdir -p "$PLAN_DIR/research/intake" "$PLAN_DIR/changes" +mkdir -p docs/adr docs/prd ``` Suggest a default name based on input. Ask the user to confirm or rename: @@ -165,135 +183,127 @@ This will create: docs/plans/2026-03-07-worldpay-canada/ [2] Enter a different name ``` -Create initial status.json: +Create initial status.json (schema 2). Every stage entry records `status` and, +when it changes, ISO `started` and `completed` timestamps. The timestamps are the +playbook's metrics: intent-to-spec, spec-to-plan, plan-to-release elapsed. ```json { - "schema_version": 1, + "schema_version": 2, "plan_name": "{name}", "plan_dir": "docs/plans/{date}-{name}", "created": "{ISO date}", - "current_phase": "brainstorm", + "current_phase": "plan", "documents": {}, "phases": { - "brainstorm": {"status": "not_started"}, - "research": {"status": "not_started"}, - "pre_plan": {"status": "not_started"}, - "plan": {"status": "not_started"}, - "audit": {"status": "not_started"}, - "build": {"status": "not_started"}, - "impact_review": {"status": "not_started"}, - "test": {"status": "not_started"}, - "handoff": {"status": "not_started"} + "plan": {"status": "in_progress", "started": "{ISO date}"}, + "design": {"status": "not_started"}, + "build": {"status": "not_started"}, + "test": {"status": "not_started"}, + "deploy": {"status": "not_started"}, + "maintain": {"status": "not_started"} } } ``` +`current_phase` and `phases` keep their names so hooks and plan-status read +either schema. Write the initial manifest.md from the template above with every +row Pending. -Create initial manifest.md: -```markdown -# Plan: {Name} -Created: {date} -Status: Phase 1 - Brainstorm -Owner: TBD - -## Plan Files (this folder) -| File | Phase | Created | -|------|-------|---------| -| [Brainstorm](brainstorm.md) | 1 | Pending | -| [Research](research/findings.md) | 2 | Pending | -| [Approach](approach.md) | 3 | Pending | -| [Confidence](confidence.md) | 3+5 | Pending | -| [Audit](audit.md) | 5 | Pending | -| [Impact Review](impact-review.md) | 7 | Pending | -| [Test Plan](test-plan.md) | 8 | Pending | - -## Project Documents (in docs/) -| Document | Type | Path | Created | -|----------|------|------|---------| -| (none yet) | | | | - -## Codebase Files -| File | Type | Created | -|------|------|---------| -| (none yet) | | | - -## Progress -| Phase | Status | -|-------|--------| -| 1. Brainstorm | In Progress | -| 2. Research | Not Started | -| 3. Pre-Plan | Not Started | -| 4. Plan | Not Started | -| 5. Audit | Not Started | -| 6. Build | Not Started | -| 7. Impact Review | Not Started | -| 8. Test | Not Started | -| 9. Handoff | Not Started | -``` - -UPDATE MANIFEST AT EVERY PHASE: When any phase creates or links a document, -update both manifest.md (add row to the appropriate table with date) and -status.json (add file path to the documents object). +UPDATE MANIFEST AT EVERY STAGE: when any stage creates or links a document, +update both manifest.md (status and date in the row) and status.json (documents +object, stage status, timestamps). For RESUME: -Read status.json. Find the current phase. Show progress and offer to continue: +Read status.json. If `schema_version` is 1 (a plan started before 8.0.0), map +the old phase names before doing anything else and write the file back as +schema 2, keeping every other field: + +| Old phase (schema 1) | New stage (schema 2) | +|----------------------|----------------------| +| brainstorm, research | plan | +| pre_plan, plan, audit | design | +| build, impact_review | build | +| test | test | +| handoff | deploy | + +Status rules for the mapped stage, applied in this order: +1. Any old status whose text ends in `complete` (for example `v17_complete`) + counts as complete. +2. Every mapped old phase complete -> stage `complete`, with `started` from + the earliest and `completed` from the latest old dates available. +3. Otherwise, if any mapped old phase is complete or in_progress -> stage + `in_progress` (a stage with one finished half and one unstarted half is + in progress, not complete). +4. Otherwise -> `not_started`. +Keep the entire old `phases` object verbatim under `phases_schema1`, including +any keys the table does not name (such as a `review` gate), and add a +`schema1_migration` block with the date and the old `current_phase`. Old +artifacts keep their old names (brainstorm.md, approach.md, confidence.md, +docs/specs/{name}.md); read them where the stage file asks for intent.md or +spec.md, and say so in the resume summary. Do not rewrite old artifacts. If a +later stage is complete while an earlier one is not (a plan closed by +decision rather than by sequence), say that in the summary rather than +inventing progress. + +Then find the current stage. Show progress and offer to continue: ``` Plan: {name} -Current phase: {phase} ({status}) +Current stage: {stage} ({status}) Last updated: {date} +Intent -> spec: {elapsed or pending} Spec -> plan: {elapsed or pending} -[show progress table from manifest.md] +[show artifact table from manifest.md] -Continue from {phase}? +Continue from {stage}? ``` +## Stages 1-6: load the stage file on entry -## Phases 1-9: load the phase file on entry - -The nine phases live in one file each under `${CLAUDE_SKILL_DIR}/phases/`. Skill -content enters the conversation once and is not re-read after auto-compaction, so -a single 1,700-line file silently loses its later phases in exactly the long -sessions this workflow produces. The split is the fix: each phase is read when it -is entered, so its instructions are always the most recent thing in context. +The six stages live in one file each under `${CLAUDE_SKILL_DIR}/stages/`. Skill +content enters the conversation once and is not re-read after auto-compaction, +so a single long file silently loses its later stages in exactly the long +sessions this workflow produces. Each stage is read when it is entered, so its +instructions are always the most recent thing in context. -RULE: On entering a phase (new plan, gate passed, or RESUME landing in it), READ -the phase file with the Read tool BEFORE doing any work in that phase. Re-read it -after any compaction. Read only the current phase; do not read ahead. +RULE: On entering a stage (new plan, gate passed, or RESUME landing in it), READ +the stage file with the Read tool BEFORE doing any work in that stage. Re-read it +after any compaction. Read only the current stage; do not read ahead. -| # | Phase | File | +| # | Stage | File | |---|-------|------| -| 1 | Brainstorm | `${CLAUDE_SKILL_DIR}/phases/phase-1-brainstorm.md` | -| 2 | Research | `${CLAUDE_SKILL_DIR}/phases/phase-2-research.md` | -| 3 | Pre-Plan | `${CLAUDE_SKILL_DIR}/phases/phase-3-pre-plan.md` | -| 4 | Plan | `${CLAUDE_SKILL_DIR}/phases/phase-4-plan.md` | -| 5 | Audit | `${CLAUDE_SKILL_DIR}/phases/phase-5-audit.md` | -| 6 | Build | `${CLAUDE_SKILL_DIR}/phases/phase-6-build.md` | -| 7 | Impact Review | `${CLAUDE_SKILL_DIR}/phases/phase-7-impact-review.md` | -| 8 | Test | `${CLAUDE_SKILL_DIR}/phases/phase-8-test.md` | -| 9 | Handoff | `${CLAUDE_SKILL_DIR}/phases/phase-9-handoff.md` | - -Paths use forward slashes on every platform. If a phase file cannot be read, stop -and report the path; do not improvise the phase from memory. - +| 1 | Plan | `${CLAUDE_SKILL_DIR}/stages/stage-1-plan.md` | +| 2 | Design | `${CLAUDE_SKILL_DIR}/stages/stage-2-design.md` | +| 3 | Build | `${CLAUDE_SKILL_DIR}/stages/stage-3-build.md` | +| 4 | Test | `${CLAUDE_SKILL_DIR}/stages/stage-4-test.md` | +| 5 | Deploy | `${CLAUDE_SKILL_DIR}/stages/stage-5-deploy.md` | +| 6 | Maintain | `${CLAUDE_SKILL_DIR}/stages/stage-6-maintain.md` | + +Paths use forward slashes on every platform. If a stage file cannot be read, stop +and report the path; do not improvise the stage from memory. + +Gate bookkeeping, every time a gate is passed: set the stage's `completed` +timestamp, set the next stage to `in_progress` with `started`, set +`current_phase`, and record who approved (`accepted_by`, `approved_by`, +`authorized_by`) with the date. A gate without a recorded name is not passed. Path-scoped fingerprinting (not full repo SHA): -Each phase records hashes of ONLY the files it referenced. +Each stage records hashes of ONLY the files it referenced. Three freshness levels: -- FRESH: referenced files unchanged since phase completed +- FRESH: referenced files unchanged since the stage completed - WARNING: related files in same directory changed (may affect findings) - STALE: directly referenced files changed (findings likely invalid) Invalidation cascade: -- brainstorm.md goals change -> approach.md becomes STALE -- approach.md scope changes -> confidence.md becomes STALE (tools/patterns may have changed) -- approach.md scope changes -> docs/specs/{plan-name}.md becomes STALE -- docs/specs/{plan-name}.md changes after audit -> audit.md becomes STALE -- audit.md revision adds new tools/patterns -> confidence.md becomes WARNING (needs reinforcement) +- intent.md changes after acceptance -> spec.md becomes STALE, and the change is a + Change Record (the playbook measures intent edits after the first spec commit) +- spec.md changes after approval -> audit.md and plan.md become STALE +- plan.md changes after approval -> recorded under "Departures from plan" in the + same commit; review.md's diff-versus-plan check reads it - source docs change after research -> research becomes WARNING -On resume, check freshness of all completed phases and report any staleness. +On resume, check freshness of all completed stages and report any staleness. @@ -302,10 +312,12 @@ On resume, check freshness of all completed phases and report any staleness. | Source folder unreadable | Skip doc cleanup, continue with codebase + web | | Codebase scan finds nothing | Note "no existing code found", proceed | | MCP/web research unavailable | Skip Track 3 or use codebase-only research, tag "[EXTERNAL RESEARCH UNAVAILABLE]" | -| Phase partially complete | Save to status.json, allow resume | +| Stage partially complete | Save to status.json, allow resume | | Existing plan folder | Ask: resume existing or create {name}-2? | | status.json corrupted | Rebuild from existing files in plan folder | +| status.json is schema 1 | Migrate per the Step 0 table; old artifacts stay under their old names | | Referenced files deleted | Mark findings as STALE, suggest re-research | +| Gate approver not named | Do not advance; ask for the name | diff --git a/plugins/deepgrade/skills/plan/phases/phase-1-brainstorm.md b/plugins/deepgrade/skills/plan/phases/phase-1-brainstorm.md deleted file mode 100644 index 6e2ef9d..0000000 --- a/plugins/deepgrade/skills/plan/phases/phase-1-brainstorm.md +++ /dev/null @@ -1,28 +0,0 @@ -# Phase 1: BRAINSTORM - -Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when the workflow enters this phase. Do not read ahead to other phase files. - -Question: What problem are we solving? - -IF input is a vague idea or just a plan name: - Ask structured questions ONE AT A TIME: - 1. "What problem are you trying to solve?" - 2. "Who is affected by this problem?" - 3. "Why is this happening now? What triggered it?" - 4. "What does success look like?" - -IF input includes source docs (from keyword): - Read the source material, draft a problem statement, ask: - "Based on what I read, here's the problem as I understand it: [statement]. - Is this right, or should I adjust?" - -IF input includes an existing ticket or spec: - Extract the problem statement, confirm with user. - -Write brainstorm.md with: Problem Statement, Goals, Non-Goals, Open Questions, Ownership (plan owner, tech reviewer, business approver - ask or default TBD). - -Update status.json: brainstorm -> complete, research -> not_started -Update manifest.md progress table. - -GATE: Ask user "Problem defined. Ready to move to research? [Y/n]" -On confirm -> proceed to Phase 2. diff --git a/plugins/deepgrade/skills/plan/phases/phase-2-research.md b/plugins/deepgrade/skills/plan/phases/phase-2-research.md deleted file mode 100644 index 742a0e4..0000000 --- a/plugins/deepgrade/skills/plan/phases/phase-2-research.md +++ /dev/null @@ -1,83 +0,0 @@ -# Phase 2: RESEARCH - -Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when the workflow enters this phase. Do not read ahead to other phase files. - -Question: What is true about our situation? - -Run three research tracks IN PARALLEL using subagents: - -PARALLELIZATION RULE: The three tracks are independent. Deploy them -simultaneously as subagents, each with its own context window. Do NOT -run them sequentially. Each writes its output to the plan folder. - -TRACK 1 - CODEBASE SCAN (Subagent: Sonnet): -Objective: Find all related code in the current codebase. -Tools: Read, Grep, Glob, Bash -Output: docs/plans/{date}-{name}/research/codebase-scan.md -```bash -# Search for related code based on brainstorm keywords -grep -ri "{keywords}" --include="*.cs" --include="*.vb" --include="*.ts" \ - --include="*.config" --include="*.json" . 2>/dev/null | grep -v node_modules | head -30 -``` -Read the key files found. Note existing patterns, current implementation, dependencies. - -TRACK 2 - SOURCE DOC CLEANUP (Subagent: Sonnet, if docs were provided): -Objective: Clean and structure provided source documents. -Tools: Read, Write, Bash -Output: docs/plans/{date}-{name}/research/intake/ (structured files) -Read all files in the source folder. Extract structured data per content type. -Write cleaned data to research/intake/. - -TRACK 3 - BEST PRACTICES (Subagent: Sonnet, if external search tools available): -Objective: Find how others solved similar problems. -Tools: Read, WebSearch, WebFetch, plus any connected MCP search tool whose name -ends in `__ref_search_documentation`, `__ref_read_url`, `__web_search_exa`, -`__web_fetch_exa`, or `__perplexity_ask` (see the `deepgrade:mcp-research` skill — -match by suffix, never by bare name) -Output: docs/plans/{date}-{name}/research/best-practices.md - -Search strategy (use in order, stop when sufficient): -1. Ref: Search framework/library docs for the specific technologies in scope. - Use ref_search_documentation with a complete question (not keywords). -2. Exa: Search for code examples of the pattern being considered. - Use web_search_exa for both implementation examples and general patterns, then - web_fetch_exa on the one result worth reading in full. -3. Perplexity: If Ref + Exa are insufficient, ask a targeted research question. - Use perplexity_ask for focused answers with citations. -4. WebSearch/WebFetch: Fallback if MCP tools are not available. - -If NO external search tools are available: - Fall back to codebase-only research using built-in tools. - Tag in findings.md: "[EXTERNAL RESEARCH UNAVAILABLE — findings based on codebase and training data only]" - -SYNTHESIS (after all tracks complete): -Read all three track outputs. Cross-reference findings. -Write docs/plans/{date}-{name}/research/findings.md as the combined summary. - -STOP RUBRIC - Research is DONE when: -- All brainstorm open questions are answered or explicitly deferred -- At least one viable implementation path is identified -- Top risks have mitigation ideas -- Remaining unknowns are non-blocking - -When stop criteria are met, present findings: -``` -Research complete. Key findings: - -CODEBASE: [what exists, what we can reuse] -SOURCE DOCS: [key facts extracted] -BEST PRACTICES: [recommended approach] - -What we still don't know: [gaps, with assessment: blocking vs non-blocking] -Open questions resolved: [X of Y] - -Ready to set scope. -``` - -Write research/findings.md and research/reference-data.json. -Record path-scoped fingerprints for referenced files (not full repo SHA). - -Update status.json: research -> complete with file hashes -Update manifest.md: add research files to Plan Files table with date. - -GATE: Automatic. Tool proceeds when stop rubric is met. diff --git a/plugins/deepgrade/skills/plan/phases/phase-3-pre-plan.md b/plugins/deepgrade/skills/plan/phases/phase-3-pre-plan.md deleted file mode 100644 index a1b3bc2..0000000 --- a/plugins/deepgrade/skills/plan/phases/phase-3-pre-plan.md +++ /dev/null @@ -1,250 +0,0 @@ -# Phase 3: PRE-PLAN - -Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when the workflow enters this phase. Do not read ahead to other phase files. - -## Contents - -- Scope, options analysis, and scope lock -- Confidence brief (required): why, success criteria, timebox -- Confidence brief template -- Cross-plan references -- Entry prioritization and impact classification -- Source credibility and URL verification -- Conflicting evidence -- Confidence falsification (post-scope-lock) -- Anchor ids -- Gate - -Question: What should be in scope? - -Produce an alignment checkpoint in approach.md: - -- Scope: IN list and OUT list -- Options Analysis (REQUIRED): Evaluate minimum 2 approaches before selecting: - - For each option: - - Name and approach description - - Pros and cons - - Risk level (LOW/MEDIUM/HIGH) - - Rollback complexity (LOW/MEDIUM/HIGH) - - Comparison matrix scoring each option against: - - Implementation ease, Timeline, Strategic value, Risk profile, Rollback complexity - - Decision Rationale: WHY the selected option won, referencing specific criteria. - Losing options: document "would revisit if" conditions. - -- Approach/Pattern: which pattern and WHY (strangler fig, feature flag, migration, new build, integration) -- Top 3 Risks: each with impact level and mitigation -- Constraints: timeline, team, technology -- Dependencies: internal, external, hard blockers, soft dependencies - -Present to user for confirmation. This is the SCOPE LOCK. - -CONFIDENCE BRIEF (REQUIRED — written after approach.md, before gate): - -WHY THIS EXISTS: Without external evidence backing, plan decisions rest on -the authoring agent's training data alone — which may be outdated, biased, or -hallucinated. Stakeholders reviewing plans cannot distinguish "this is industry -standard" from "this is what the AI made up." The confidence brief solves this -by requiring verifiable external evidence for every significant tool, method, -and pattern choice. - -SUCCESS CRITERIA: -- Every HIGH-impact entry has at least one verifiable reference link -- A stakeholder unfamiliar with the plan can read confidence.md and understand - why the chosen approach is industry-proven (not just "the AI suggested it") -- No fabricated company examples (see SOURCE CREDIBILITY below) - -TIMEBOX: The confidence brief should take no longer than the approach.md itself. -- MAX ENTRIES: 10 entries per plan (prioritize by impact). If more than 10 - items are identified, defer LOW-impact items with a note: "Deferred: {item} - (LOW impact, not blocking scope lock)" -- If entry count exceeds 10, stop and present the top 10 sorted by impact. - User can request additional entries after scope lock. - -Step breakdown (approximate effort per entry): -1. Discovery — scan approach/research/brainstorm for items (~1 min total) -2. Drafting — write "what it is" and "connection to plan" (~1 min per entry) -3. Evidence gathering — search for "who uses it" and references (~2 min per HIGH, ~1 min per MEDIUM) -4. Cross-plan search — check existing confidence.md files (~30 sec per entry) -5. Review — verify URLs for HIGH-impact entries if web tools available (~1 min per HIGH) - -If the plan is under timeline pressure, skip steps 4-5 for MEDIUM and LOW -entries and mark them with "[CROSS-PLAN CHECK DEFERRED]" and "[URL VERIFICATION -DEFERRED]". HIGH-impact entries MUST always complete steps 3-5 regardless of -timeline pressure — these entries drive scope lock decisions and cannot be deferred. - -After writing approach.md, generate confidence.md — a self-contained knowledge -brief that grounds every tool, method, and pattern choice in external industry -evidence. This file is stakeholder-readable: someone outside the plan should -be able to read it and understand why these choices are solid. - -Scan the approach.md, research/findings.md, and brainstorm.md for: -- New dependencies/packages (NuGet, npm, pip, etc.) -- Methodologies or patterns chosen (strangler fig, expand/contract, CQRS, etc.) -- Best practices referenced (DORA metrics, chaos engineering, etc.) -- Frameworks, libraries, or tools introduced - -For EACH item found, write an entry in confidence.md using this structure: - -```markdown -# Confidence Brief: {Plan Name} -Created: {date} (Phase 3) -Last reinforced: {date} (Phase 5, if applicable) - -> This document explains WHY the tools, methods, and patterns in this plan -> are industry-proven choices. Each entry defines what it is, who uses it -> at scale, and why it works — then briefly connects it to this plan. - ---- - -## Dependencies & Tools - -### {Package/Tool Name} {version} -**What it is:** {1-2 sentence definition — what the tool does, what problem it solves} - -**Who uses it at scale:** -- **{Company 1}** — {how they use it, what scale, what outcome} -- **{Company 2}** — {how they use it, what scale, what outcome} - -**Why it works:** {1 paragraph — the engineering reason this tool is effective, -what architectural property it provides, what failure mode it prevents} - -**Reference:** [{title}]({url}) ← link to official docs, conference talk, or case study - -**Connection to this plan:** {1-2 sentences — why we chose this specifically, -which plan goal it serves} - -**Also referenced in:** [{other-plan-name}](../../{other-plan-dir}/confidence.md#{anchor}) ← only if another plan uses the same tool - ---- - -## Methods & Patterns - -### {Method/Pattern Name} -**What it is:** {1-2 sentence definition} - -**Origin:** {Who created/popularized it — e.g., "Martin Fowler (2004)", -"Netflix engineering team (2011)", "Microsoft Azure Architecture Center"} - -**Who uses it at scale:** -- **{Company 1}** — {context and outcome} -- **{Company 2}** — {context and outcome} - -**Why it works:** {1 paragraph — the engineering principle, what it optimizes -for, what tradeoff it makes explicit} - -**Reference:** [{title}]({url}) - -**Connection to this plan:** {1-2 sentences linking to specific plan phases or decisions} - -**Also referenced in:** [{other-plan-name}](...) ← only if applicable - ---- - -## Best Practices & Standards - -### {Practice Name} -**What it is:** {1-2 sentence definition} - -**Advocated by:** {Organization or thought leader — e.g., "DORA/Google", -"OWASP", "12-Factor App (Heroku)"} - -**Industry evidence:** -- {Specific metric or finding — e.g., "Teams using trunk-based development - deploy 973x more frequently (DORA State of DevOps 2023)"} - -**Why it works:** {1 paragraph} - -**Reference:** [{title}]({url}) - -**Connection to this plan:** {1-2 sentences} -``` - -CROSS-PLAN REFERENCES: -Before writing each entry, search existing plan folders for confidence.md files: -```bash -find docs/plans/ -name "confidence.md" -exec grep -l "{tool-or-pattern-name}" {} \; -``` -If found in another plan, add an "Also referenced in" link. The entry in THIS -file must still be self-contained (full context) — the link is supplemental, -not a replacement for content. A reader should never need to open another -plan's confidence.md to understand this one. - -ENTRY PRIORITIZATION: -- HIGH-impact items (core dependencies, primary pattern): full entry with reference link REQUIRED -- MEDIUM-impact items (supporting tools, secondary patterns): full entry, reference link optional -- LOW-impact items (dev tooling, standard practices): shorter entry, no reference link required - -Impact classification criteria (rationale REQUIRED for each classification): -- HIGH: item is on the critical path, a wrong choice causes plan failure or rework - (e.g., primary database, core framework, architectural pattern) - Rationale example: "HIGH — Markdig is the sole markdown rendering engine; if it - can't handle our edge cases, the entire doc pipeline fails" -- MEDIUM: item supports the plan but alternatives exist with low switching cost - (e.g., utility libraries, secondary patterns, testing tools) - Rationale example: "MEDIUM — YamlDotNet parses config; could swap to SharpYaml - with ~2 days of work if needed" -- LOW: item is standard practice or dev tooling with no plan-specific risk - (e.g., linters, formatters, common build tools) - -Each entry must include a one-line rationale justifying its impact level. -This prevents gaming: downgrading a critical dependency to MEDIUM to avoid -source verification requirements is visible and reviewable. - -SOURCE CREDIBILITY (required for HIGH-impact entries): -Every "Who uses it at scale" and "Industry evidence" claim must be backed by -a verifiable source. Do NOT fabricate company examples. - -Source tiers: -- TIER A (preferred): Official docs, conference talks with video/slides, - published case studies, peer-reviewed papers, DORA/ThoughtWorks reports -- TIER B (acceptable): Reputable blog posts (company engineering blogs), - GitHub repos with usage evidence, Stack Overflow answers with high votes -- TIER C (flag): Training data recall without a specific URL — mark these as - "[UNVERIFIED — common knowledge, no primary source found]" so the reader - knows the claim needs manual verification - -HIGH-impact entries MUST have at least one TIER A or TIER B source. -If no verifiable source can be found for a HIGH-impact claim, flag it: -"[SOURCE NEEDED — this claim requires manual verification before scope lock]" - -URL VERIFICATION: When ref_read_url, web_search_exa, WebSearch, or WebFetch -tools are available, verify that reference URLs for HIGH-impact entries are -reachable before writing them. -- Prefer ref_read_url for documentation URLs (returns clean markdown, trajectory-aware) -- Use web_search_exa for general web URLs (semantic matching) -- Fall back to WebFetch if MCP tools are not available -If a URL is dead or redirects to unrelated content, downgrade to TIER C and -flag as "[LINK DEAD — needs replacement source]". - -CONFLICTING EVIDENCE: If two sources disagree on a claim (e.g., one recommends -a tool, another warns against it), document both perspectives: -"[CONFLICTING] Source A says X. Source B says Y. This plan assumes X because -{rationale}." Let the stakeholder see the tension rather than hiding it. - -CONFIDENCE FALSIFICATION (post-scope-lock): -If a confidence entry is later found to be wrong (e.g., a tool doesn't support -a claimed feature, a company example was fabricated, a pattern doesn't apply): -1. Create a Change Record (CR-{N}) documenting what was wrong and the impact -2. Mark the confidence.md entry with: "**FALSIFIED ({date}):** {what was wrong}" -3. Mark downstream artifacts that relied on this claim as WARNING in status.json -4. If the falsified claim was HIGH-impact, trigger a scope review (return to Phase 3) -5. If Build phase is in progress, freeze any tickets that depend on the falsified - claim until the scope review completes - -ANCHOR IDS: -Each entry heading must include a kebab-case anchor for cross-plan linking: -`### YamlDotNet 16.3.0 {#yamldotnet-16}` so other plans can link directly. -When searching for cross-plan references, search for both the tool/pattern -name AND common aliases (e.g., "YAML" for "YamlDotNet", "strangler" for -"strangler fig pattern"). - -GATE: User confirmation REQUIRED. -"Does this scope look right? [confirm / adjust / back to research]" - -On "adjust" -> iterate on the approach. -On "back to research" -> return to Phase 2 (mark research stale if scope changed). - -Update status.json, manifest.md. diff --git a/plugins/deepgrade/skills/plan/phases/phase-4-plan.md b/plugins/deepgrade/skills/plan/phases/phase-4-plan.md deleted file mode 100644 index 678cc92..0000000 --- a/plugins/deepgrade/skills/plan/phases/phase-4-plan.md +++ /dev/null @@ -1,58 +0,0 @@ -# Phase 4: PLAN - -Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when the workflow enters this phase. Do not read ahead to other phase files. - -Question: How will we execute? - -Create docs/specs/{plan-name}.md with THREE views: - -1. JIRA-READY TICKETS: Per phase, with title, acceptance criteria, assignable -2. LEADERSHIP SUMMARY: Executive summary, timeline table, go/no-go criteria -3. WORKING CHECKLIST: Step-by-step with verification per step - -Detail level per phase based on risk: -- HIGH risk: exact files, function names, grep patterns, commit SHA, test requirements -- MEDIUM risk: file paths, approach, key decisions -- LOW risk: goals, scope, success criteria - -Include: -- Timeline table with dependencies and critical path -- Operational readiness section (if deployment involved): monitoring, config rollout, incident fallback, success metrics -- Rollback plan per phase -- Go/no-go criteria per phase boundary - -TESTING METHODOLOGY SELECTION (REQUIRED): -For EACH deliverable in the spec, select the appropriate testing methodology. -Do NOT default to "unit tests" for everything. Reference the Testing Methodology -Selection Framework (docs/planning-techniques/10-testing-methodology-selection.md). - -| # | Methodology | Evidence Tier | When to Use | -|---|-------------|--------------|-------------| -| 1 | TDD | ENTERPRISE-VALIDATED | New feature with clear spec, algorithms, core business logic, stored procedures | -| 2 | BDD | INDUSTRY-RECOMMENDED | User-facing features, cross-functional teams, requirements ambiguity | -| 3 | Characterization / Golden Master | ENTERPRISE-VALIDATED | Refactoring legacy code, extracting from monolith, data migration validation | -| 4 | Contract Testing | INDUSTRY-RECOMMENDED | Microservices, API integrations, database backward compatibility | -| 5 | Property-Based | INDUSTRY-RECOMMENDED | Algorithms with infinite input space, financial calculations, query performance | -| 6 | Snapshot / Approval | INDUSTRY-RECOMMENDED | UI components, serialized output, reports, config generation | -| 7 | Shadow / Parallel | ENTERPRISE-VALIDATED | Production migration, database cutover, replacing live systems | -| 8 | ATDD | INDUSTRY-RECOMMENDED | Sprint planning, user story definition, database migration sign-off | -| 9 | Mutation Testing | EMERGING PRACTICE | Pre-release quality gate, measuring test suite effectiveness | -| 10 | Exploratory | ENTERPRISE-VALIDATED | Complex UI, late-stage discovery, automation gaps | -| 11 | Expand/Contract | ENTERPRISE-VALIDATED | Database schema migration, renaming columns/tables, changing data types | - -AI-specific requirements: -- The agent that writes implementation code MUST NOT write the tests (Separate Test Authorship) -- AI-generated code receives higher testing scrutiny than human code -- Every AI-generated deliverable is checked against the AI Failure Mode Checklist: - logic drift, stale dependencies, hidden business rule violations, tautological - tests, happy-path-only coverage - -For database schema changes, use Expand/Contract (Methodology 11) with three phases: - - Expand: add new alongside old (structural assertions) - - Migrate: dual-write, backfill, test (data integrity + shadow comparison) - - Contract: remove old after cutover (no orphan references) - -GATE: User confirmation REQUIRED. -"Plan created with {N} phases and {M} tickets over {X} weeks. Review and confirm?" - -Update status.json, manifest.md. diff --git a/plugins/deepgrade/skills/plan/phases/phase-5-audit.md b/plugins/deepgrade/skills/plan/phases/phase-5-audit.md deleted file mode 100644 index c90c0cc..0000000 --- a/plugins/deepgrade/skills/plan/phases/phase-5-audit.md +++ /dev/null @@ -1,565 +0,0 @@ -# Phase 5: AUDIT - -Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when the workflow enters this phase. Do not read ahead to other phase files. - -## Contents - -- Checks 1-4: score, devil's advocate, codebase verification, gap verification -- Outputs A-D: coverage matrix, assumption register, scenario matrix, cross-cutting sweep -- Canary (run before the auditor is spawned) -- Evidence validation -- Infrastructure verification -- Plan lint rules and gap summary -- Confidence reinforcement -- Baseline snapshot and score distribution -- Gate: evaluator-optimizer loop, rubric-free pass, gate expression -- Revision feedback and auditor isolation -- Human review gate and waiver condition - -Question: What is weak or missing? - -Run four checks using the plan-auditor agent: - -CHECK 1 - 8-DIMENSION SCORE: -The rubric, its per-level anchors and the band interpretation live in -`agents/plan-auditor.md`. They are deliberately not repeated here. - -This file is read by the Phase 4 generator. A generator that can see the scoring -function writes to the scoring function — it produces text shaped like each anchor -rather than a plan that happens to score well, and the two are indistinguishable -from the score alone. Keeping the rubric on the auditor's side is what makes the -score a measurement of the plan rather than a measurement of how well the generator -remembered the rubric. - -The score is reported. Under the verifier-first gate it does not authorize passage -(see GATE below), so its role is trend and triage, not permission. - -CHECK 2 - DEVIL'S ADVOCATE: -Challenge each assumption. For each challenge, cite evidence or flag [VERIFY]. -Structured premortem questions: - "If this fails in production, what is the most likely reason?" - "What did we assume would be true but isn't?" - "What changed in one layer but not another?" - "What behavior works in tests but fails in browser/runtime?" - -CHECK 3 - CODEBASE VERIFICATION: -Confirm file paths, line numbers, function names referenced in plan actually exist. - -CHECK 4 - GAP VERIFICATION (new): -This check produces 4 structured outputs that catch systematic gaps. -A plan CANNOT be considered gap-checked until all 4 outputs exist. - -OUTPUT A: Coverage Matrix -Map every goal, risk, dependency, and non-goal to its plan artifact: - -```markdown -## A. Coverage Matrix - -| Item | Type | Covered By | Status | -|------|------|-----------|--------| -| bilingual receipts | goal | Phase 1, POS-5163, tests T1/T2 | covered | -| certification timeline | dependency | Phase 4, owner TBD | partial | -| rollback | operational | plan section + handoff | covered | -| CORS handling | non-goal | explicitly excluded | ok-excluded | -| user pagination | assumption | not addressed | GAP | -``` - -Rules: -- Every goal must map to at least one phase AND at least one ticket -- Every risk must map to a mitigation -- Every dependency must map to an owner or blocker -- Every rollout item must map to monitoring + rollback -- Every non-goal must NOT accidentally appear in the plan -- Items marked GAP fail the gap check - -OUTPUT B: Assumption Register -Every assumption the plan makes, with impact-if-false and verification: - -```markdown -## B. Assumption Register - -| # | Assumption | Impact If False | How to Verify | By When | Owner | Status | -|---|-----------|----------------|---------------|---------|-------|--------| -| 1 | User lookup fits in first page | Breaks onboarding flow | Check query with production data volume | Before Phase 2 | Kyle | unverified | -| 2 | triPOS SDK supports Canada | Blocks entire plan | Test API call to Canadian endpoint | Phase 1 | Kyle | verified | -| 3 | Supabase rate limit handles OTP volume | Throttles users at scale | Load test 100 concurrent OTPs | Before launch | TBD | unverified | -``` - -Rules: -- Every assumption must have an impact assessment -- Unverified high-impact assumptions are BLOCKERS -- Assumptions with no validation step are WARNINGS -- Assumptions that block execution must be verified before Build phase - -AUTOMATED ASSUMPTION VERIFICATION: -After generating the Assumption Register, attempt automated verification -of all assumptions that have a verification method: - -For each assumption where impact = HIGH and status = unverified: - 1. If verification method mentions file/path: run `test -f [path]` - 2. If verification method mentions API/endpoint: note as REQUIRES_MANUAL - 3. If verification method mentions schema/database: search for schema files - 4. If verification method mentions config: search config files - 5. Update assumption status in status.json: - - verified: automated check passed - - unverified: automated check failed or not automatable - - falsified: automated check proved assumption false - -Track verification results: - "Assumptions: X total, Y verified (Z automated, W manual), V unverified, F falsified" - -OUTPUT C: Scenario Matrix -The auditor maps a fixed set of scenarios to implementation, test and monitoring. -The scenario list and the output table live in `agents/plan-auditor.md`; they are -not repeated here, for the same reason the rubric is not. - -What the plan itself must do — state this to the generator, not the list: -the plan has to account for how the change behaves when it works, when it fails, -while old and new run side by side, under load, at permission boundaries, across -environment differences, and on the way back out. A plan written against a named -checklist tends to grow a section per checklist item; a plan written against the -requirement tends to notice which of those actually apply to it and say so. - -Every scenario in the auditor's set gets an entry, including "not applicable" with -a reason. Items marked GAP fail the gap check. - -OUTPUT D: Cross-Cutting Concern Sweep -The auditor checks every feature and change against a fixed set of concerns. That -set and its output table live in `agents/plan-auditor.md` and are not repeated here. - -What the plan itself must do: address the concerns that cut across the change -rather than sitting inside one component — the contract it exposes, who is allowed -to call it, what differs between environments, how it behaves at the network and -data-access boundary, what it emits when running, and how it migrates and rolls -back. Concerns that genuinely do not apply are excluded explicitly with a reason. - -Every concern in the auditor's set gets a verdict. Unaddressed concerns are GAPS; -partial ones are WARNINGS. - -CANARY (automated, run BEFORE the auditor is spawned): - -Every other check in Phase 5 examines the plan. This one examines the auditor. - -```bash -node "${CLAUDE_PLUGIN_ROOT}/scripts/dg-canary.js" inject \ - docs/specs/{plan-name}.md docs/plans/{date}-{plan-name}/.canary/ -``` - -One known defect is injected into a working copy of the spec — a rollback line -removed, a dependency owner blanked, an unverified HIGH-impact assumption added, -go/no-go criteria deleted, or a claim of coverage from a test file that does not -exist. The class is recorded along with the single criterion it violates. - -The auditor then audits the MUTATED copy, knowing nothing of any of this. - -Afterwards: - 1. If the recorded criterion is NOT in the audit's UNMET set, the audit missed a - defect that was placed there to be found. Re-run once with a different class. - A second miss fails the gate as "audit untrustworthy" — and DOES NOT trigger - the revision loop. Revising a plan against findings from an audit that could - not see a planted defect is worse than not revising: it rewrites the spec to - satisfy conclusions never derived from reading it. - 2. If it was found, strip that finding from the report — it is an artefact of - this harness, not a property of the plan — and then RE-CHECK that one - criterion against the unmutated original. The strip alone is unsafe: if the - plan has a genuine gap on the same criterion, removing "the LINT-03 finding" - would remove the real one with it. The strip removes the artefact; the - recheck decides the truth. - -An audit reporting zero gaps on a document known to contain a defect is not a -clean audit. It is a broken one, and nothing in its output would tell you so. - -Known limitation, stated rather than glossed: the auditor can read -`scripts/dg-canary.js`, including its defect table. This detects a lazy audit -reliably and an adversarial one only incidentally. Rotating the class per run -raises the cost of pre-empting it; it does not make the canary tamper-proof. - -EVIDENCE VALIDATION (automated, run before anything is treated as MET): - -The auditor returns criterion records, each carrying its evidence. Those records are -a PROPOSAL, not a result. Re-check every one of them mechanically: - -```bash -node "${CLAUDE_PLUGIN_ROOT}/scripts/dg-evidence-validate.js" \ - docs/plans/{date}-{plan-name}/evidence/ -``` - -The validator re-reads each cited artifact, confirms its hash still matches, slices -the cited line range and asserts the quoted text is byte-identical to it. It can only -ever DEMOTE a verdict — there is no input that makes it turn an UNMET into a MET. Use -the verdicts it returns, never the verdicts the auditor claimed. - -A record comes back UNMET, with a flag naming the reason, when: - EVIDENCE-INVALID the quote does not match the lines it cites - EVIDENCE-MISSING MET was claimed with no evidence at all - EVIDENCE-STALE the artifact changed after the record was written - EVIDENCE-ARTIFACT-MISSING the cited file does not exist - EVIDENCE-RANGE-INVALID the cited line range does not exist in the file - EVIDENCE-UNEXECUTED an executable criterion retained no command - EVIDENCE-COMMAND-FAILED the retained command exited non-zero - -The fourth rule is the one that matters most and is easiest to soften by accident: -an externally checkable claim with no evidence is UNMET. Not PARTIAL, not a warning, -not "verified but undocumented". This project has lost that argument twice — a layer -was recorded PARTIAL with its result asserted in a commit message and no artifact in -any commit, and a whole wave was closed against greps typed at a terminal that left -nothing behind. Both are UNMET here without anyone needing to notice. - -Do not re-run the auditor to "resolve" a demotion. A demotion is not a disagreement -to be settled; it means the evidence was not there, and the fix is in the plan. - -COMMIT the evidence directory together with audit.md. An audit whose evidence is not committed did not happen. - -This is the rule that makes an audit auditable later. A verdict is only as good as -the ability to re-derive it, and a re-check needs the records, the artifacts and the -hashes that bound them together at the time. Without them the audit degrades into -testimony — "it passed when I ran it" — which is exactly the class of claim this -project has already had to refuse twice. - -Exit codes from the validator, which the gate branches on: - 0 every record survived re-checking - 1 at least one claimed MET was demoted — the gate does NOT open - 2 the evidence directory is missing or empty - -Treat 2 as the most serious of the three. A missing directory is not a clean run -with nothing to report; it means the audit produced no evidence at all, and reading -it as a pass would rebuild the exact failure this replaces — a phase recorded green -on the strength of a claim that no artifact anywhere supports. - -INFRASTRUCTURE VERIFICATION (automated, run after gap matrices): -Cross-reference every coverage claim against verifiable artifacts. - -For each Scenario Matrix "Tested?" entry with a test file reference: - 1. Check if the test file exists: `test -f "$TEST_PATH"` - 2. If file exists, check it contains a relevant test: `grep -c "$SCENARIO_KEYWORD" "$TEST_PATH"` - 3. If file missing or no matching test: flag as INFRA-GAP - -For each Scenario Matrix "Monitored?" entry with a monitoring reference: - 1. Search for dashboard configs, alert rules, or monitoring setup files - 2. If monitoring config missing: flag as INFRA-GAP - -For each Coverage Matrix "Covered By" entry with a file reference: - 1. Verify the referenced file exists and contains relevant implementation - 2. If file missing or no matching implementation: flag as INFRA-GAP - -INFRA-GAP is a distinct severity: the plan CLAIMS coverage but the -infrastructure to deliver that coverage does not exist. This is more -dangerous than a known gap because it creates false confidence. - -Report: "Infrastructure Verification: X/Y claims verified (Z% rate)" -List all INFRA-GAPs with the claim, expected file, and actual status. - -PLAN LINT RULES (automated, run before presenting results): -These are binary pass/fail checks. Any FAIL is a gap. - -Rule text and the applicable rule set live in `docs/planning-techniques/lint-registry.md`. -Read it and apply every rule the registry assigns to Phase 5 in the current audit mode. -This file names ids only — it does not restate what a rule means, so the two cannot -drift apart. Report one PASS/FAIL per id, using the ids exactly as the registry -numbers them. - -Apply at Phase 5: the registry's Phase 5 set. -LINT-14 is skipped on the first audit (no baseline exists to regress from). -LINT-11 and LINT-12 belong to Phase 7 and do not run here. - -GAP SUMMARY: -After all 4 outputs + lint rules, produce: - -```markdown -## Gap Summary - -Lint: {N}/{applicable} passed, {M} failed <- denominator = the registry's Phase 5 set for this mode -Coverage Matrix: {N} items, {M} gaps -Assumption Register: {N} assumptions, {M} unverified high-impact -Scenario Matrix: 8 scenarios, {M} gaps -Cross-Cutting Sweep: {N} concerns, {M} gaps - -Total gaps: {sum} -Total warnings: {sum} - -Gap-checked: YES / NO -``` - -A plan is gap-checked ONLY when: -- Every rule in the registry's Phase 5 set passes (enumerating a subset here is how - the count drifted to four different values before PH5-001) -- Coverage matrix has zero GAPs -- No unverified HIGH-impact assumptions -- Scenario matrix has zero GAPs -- Cross-cutting sweep has zero GAPs -- Infrastructure verification has zero INFRA-GAPs - -Write docs/plans/{date}-{plan-name}/audit.md with: scored dimensions, challenges, verification results, ALL 4 gap verification outputs, lint results, gap summary. - -Update manifest.md: add audit.md to Plan Files table with date and score. - -CONFIDENCE REINFORCEMENT (after audit, before baseline): - -Re-read confidence.md (created in Phase 3) and reinforce it with audit findings: - -1. AUDIT-DRIVEN ADDITIONS: - - If the audit identified new dependencies, patterns, or tools not in the - original confidence.md (e.g., from gap-filling revisions), add entries. - - If the audit challenged an assumption about a tool/method and the - challenge was resolved, add a "Validated by audit" note to that entry. - -2. STRESS-TEST ANNOTATIONS: - For entries where the audit found weakness or gaps, add a subsection: - ```markdown - **Audit note ({date}):** {What the audit found — e.g., "Devil's advocate - challenged whether YamlDotNet handles multi-document streams. Verified: - YamlDotNet 16.x supports multi-doc via `LoadStream()`. No gap."} - ``` - For entries where audit found a real gap, note the gap AND how it was resolved: - ```markdown - **Audit note ({date}):** {Gap found and resolution — e.g., "Audit flagged - missing error handling for malformed YAML. Added try/catch in Phase 5 - revision v2. Gap closed."} - ``` - -3. UPDATE HEADER: - Set "Last reinforced: {date} (Phase 5)" in the confidence.md header. - -4. NEW CROSS-PLAN REFERENCES: - If the audit revision introduced tools/patterns that exist in other plans, - add "Also referenced in" links. - -Update manifest.md: update Confidence row with reinforcement date. - -BASELINE SNAPSHOT: -After writing the audit, capture a per-element baseline in status.json: -```json -{ - "baseline": { - "run_number": 1, - "date": "{ISO date}", - "plan_version": "v1", - "lint_results": { "LINT-01": "pass", "LINT-02": "pass", ... }, - "coverage_items": [{ "name": "...", "status": "covered|gap" }], - "assumption_counts": { "total": N, "verified": N, "unverified": N, "waived": N }, - "scenario_statuses": [{ "id": 1, "name": "Happy path", "status": "covered|partial|gap" }], - "concern_statuses": [{ "name": "API contract", "status": "ok|warn|gap" }], - "dimension_scores": [{ "name": "Problem Definition", "score": 4 }], - "infra_gaps": N - } -} -``` - -On re-audit (after revision loop or manual re-run), compare current vs baseline: -- REGRESSION: item was covered/passing, now gap/failing -> flag in audit output -- IMPROVEMENT: item was gap/failing, now covered/passing -> report as progress -- NEW: item not in previous baseline -> report for awareness - -Report: "Baseline comparison: X regressions, Y improvements, Z new items" -Regressions are flagged as HIGH priority in the audit output. - -This comparison is what LINT-14 is evaluated against (see the registry for its text). -Only an element that was covered/passing in the previous baseline and is now -gap/failing counts; pre-existing gaps do not trigger it. Skipped on the first audit, -when no baseline exists. - -Update the baseline in status.json after each comparison (append to history array -for trend tracking). - -SCORE DISTRIBUTION (append on every audit, including re-audits): - -Record each audit's score in a score_history array in status.json: -```json -{ - "score_history": [ - { "date": "{ISO date}", "plan_version": "v1", "iteration": 1, - "score": 27, "canary_found": true, "gate_passed": false }, - { "date": "{ISO date}", "plan_version": "v2", "iteration": 2, - "score": 36, "canary_found": true, "gate_passed": true } - ] -} -``` - -The score no longer gates, but its distribution is still the cheapest detector of -the gate being gamed. A cluster of totals sitting just above any historical -threshold — 32-34 under the old regime — is the statistical signature of -threshold-aiming, and it is visible only as a series. One audit's score means -almost nothing; forty audits piling up at the same boundary means the boundary is -being aimed at. Keeping the series costs one array append. - -GATE: Evaluator-Optimizer Loop. - -RUBRIC-FREE HOLISTIC PASS (advisory, runs alongside the gate): - -RUN one additional judge with no rubric, no criterion list, and no dimension names. - -Its entire prompt is: "Ignore any checklist. What would make this plan fail in -production?" Fresh instance, same input manifest as the auditor, none of the -criterion files. - -Map its findings against the criterion set afterwards. A finding that maps to an -existing criterion is discarded — the gate already covers it. A finding that maps -to NOTHING is appended to docs/planning-techniques/lint-candidates.md with the plan -name and date, as a candidate rule for owner review. - -This pass never gates, and that is deliberate. Every other mechanism in Phase 5 -makes the judge honest ABOUT the criteria; none of them can notice that the -criteria are incomplete. A plan can satisfy every rule and still be bad in a way no -rule names — rubric-design failure as distinct from verifier failure. This is the -only check on that class, and its output is a proposed rule, not a verdict on the -current plan: gating on unmapped findings would just re-create the unfalsifiable -prose judgment the gate rewrite removed. - -The gate does not read the score. It reads whether the claims survived checking. - - -CANARY_OK = the criterion the planted defect violates came back UNMET -EVIDENCE_OK = dg-evidence-validate.js exited 0 (nothing was demoted) -VERIFIED = every applicable criterion is MET or N_A after validation -INFRA_OK = infra_gaps == 0 - -PASS = CANARY_OK AND EVIDENCE_OK AND VERIFIED AND INFRA_OK - - -Every term is re-derivable by someone who has the plan folder and did not run the -audit. That is the property being bought here: the previous gate authorised passage -on a number the audited model chose for itself, and no reader could tell a plan that -earned it from one that was written to earn it. - -There is no weighted sum, so a strong showing on seven criteria cannot offset a -failure on the eighth. Non-compensability is the thing a 40-point total structurally -cannot give you. - -IF PASS: - -> "Plan is solid. Ready to start building." - -> Proceed to Phase 6. - -IF NOT PASS: - -> If CANARY_OK is false after a re-run: STOP. Do not revise. The audit could not - see a defect placed for it to find, so its other findings are not a basis for - rewriting anything. - -> Otherwise auto-trigger revision of the Phase 4 spec, using the feedback form - below. - -> Revise ONLY the failing sections (not the entire spec). - -> Re-run the audit on the revised spec. - -> Compare re-audit against baseline: flag any regressions (items that - were passing in v1 but now fail in v2). Regressions indicate the - revision broke something that was previously working. - -> Maximum 2 revision iterations. - - -Send the generator defects and locations. One line per unmet criterion: - - {criterion_id} UNMET: {what is missing}. Location: {file}:{line}. - -Worked example: - - LINT-03 UNMET: Phase 2 database migration has no rollback step. - Location: docs/specs/plugin-hardening-v5.md:142. - -Never send the rubric, the totals, the bands, or how near the plan came to passing. -The generator cannot see any of that when it writes, and returning it through the -revision channel would hand back exactly what was withheld — after which the cheapest -response is prose shaped like the missing thing rather than the missing thing itself. - -A defect the generator can locate is a defect it can fix. A number it can chase is a -number it will chase. - - -SPAWN A NEW plan-auditor INSTANCE for every audit iteration. Do not re-audit inside -the instance that produced the previous verdict, and do not pass it the previous -audit.md, the previous score, or a summary of either. - -An evaluator that already published a number for v1 is, on v2, checking its own -prior judgement. The consistent story available to it is that the revision fixed -what it said was broken, so the second audit tends to ratify the first rather than -re-derive it — and the loop's regression check is exactly the thing that cannot -work if the same evaluator grades both sides of it. The agent refuses prior-iteration -scores on its side too (see in agents/plan-auditor.md); both -halves are required, because either alone is a single point of failure. - -The baseline comparison above is done by the CALLER, which holds both audits. The -judge sees one spec and reports on it, and never learns that a previous attempt -existed. - -After revision loop completes, report against the gate, not against a band: -- PASS: "Plan revised and now solid. Ready to build." -- NOT PASS, criteria still unmet after 2 iterations: "Plan has remaining unmet - criteria. Fix manually: [list each id with its defect and location]" -- NOT PASS because evidence was demoted: "Claims in this plan are not supported by - what they cite: [list each flag]. These are not near-misses; the cited text does - not say what the plan says it says." -- NOT PASS because the canary was missed twice: "The audit could not be trusted and - no revision was attempted. Re-run Phase 5 before reading any of its findings." - -A plan does not "usably pass with known gaps". Either every applicable criterion is -satisfied and evidenced, or the specific ones that are not get named. The old -YELLOW rung existed because a 24-31 total had to mean something; without the total -there is nothing for it to mean, and "proceed with known gaps" was the rung most -often used to proceed without reading them. - -Track revision history in audit.md: -```markdown -## Revision History -| Version | Score | Gap-Checked | Gaps | Action | -|---------|-------|-------------|------|--------| -| v1 | 24/40 | NO | 7 | Auto-revised sections 4, 5, 7 | -| v2 | 35/40 | YES | 0 | Accepted | -``` - -Update status.json (include score, rating, gap_checked boolean, gap_count), manifest.md. - -HUMAN REVIEW GATE (conditionally waivable): -After the automated audit completes, prompt for human review before Build: - -"Automated audit complete (score: {X}/40, gap-checked: {YES/NO}). - Before starting Build, this plan should be reviewed by at least one person. - [1] Enter reviewer name(s) to proceed - [2] Waive review (solo mode) — requires documented reason, and only offered - when the waiver condition below holds - [3] View audit summary first" - - -waiver_allowed = (infra_gaps == 0) - AND (score >= 35) - AND (canary_found == true) - - -This is the one place the score is load-bearing, and the asymmetry is the design: -the score cannot let a plan PASS the gate, but a borderline one can remove the -owner's ability to SKIP review. A gameable signal is safe in the direction that -adds friction. The 32-34 band — the scores that sat just above the old threshold — -is exactly where threshold-aiming lands, so a plan scoring there gets a human -whether or not the automated gate passed. - -If the waiver condition fails, option [2] is not offered at all. Do not present it -greyed out with the reason; a visible near-miss invites one more revision aimed at -the waiver rather than at the plan. - -If [1]: Record reviewer name(s) and date in status.json: - { "review": { "reviewers": [{"name": "...", "date": "..."}], "outcome": "accepted" } } - Proceed to Phase 6. - -If [2]: Record waiver in status.json AND stamp it visibly: - { "review": { "waived": true, "reason": "...", "waived_by": "...", - "waiver_condition": { "infra_gaps": 0, "score": X, "canary_found": true } } } - Also append one line to audit.md and to the Phase 9 handoff: - "Review waived (solo mode) by {name} on {date}: {reason}" - A waiver recorded only in machine state is invisible to the person reading the - plan later, which is the person it exists to warn. Proceed to Phase 6. - -If [3]: Show audit-derived review checklist: - - Audit scorecard (8 dimensions with scores) - - Top 3 gaps identified - - Top 5 risks identified - - Key assumptions and their verification status - - Cross-cutting concerns flagged as partially addressed - Then re-prompt [1] or [2]. - -If [1] with reviewer names: Record review in status.json: - { "review": { - "reviewers": [{"name": "...", "date": "...", "decision": "accepted"}], - "outcome": "accepted", - "checklist_presented": true, - "comments": 0 - }} - -For team/leadership plans: review is REQUIRED (option [2] not offered unless -the plan was started in solo mode or the user explicitly requests solo mode). - -For solo mode: review is recommended but waivable with documented reason. diff --git a/plugins/deepgrade/skills/plan/phases/phase-6-build.md b/plugins/deepgrade/skills/plan/phases/phase-6-build.md deleted file mode 100644 index 759d907..0000000 --- a/plugins/deepgrade/skills/plan/phases/phase-6-build.md +++ /dev/null @@ -1,122 +0,0 @@ -# Phase 6: BUILD - -Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when the workflow enters this phase. Do not read ahead to other phase files. - -## Contents - -- Hard gate: assumption verification (LINT-08) -- Parallel execution rule -- Document actions and codebase actions -- Change control and change record template - -Question: What got built/changed? - -HARD GATE: ASSUMPTION VERIFICATION (LINT-08) -Before ANY build work begins, check assumptions in status.json: - -``` -For each assumption where impact = HIGH: - If status = unverified: - -> BLOCK entry to Phase 6 - -> Present: "Cannot start Build. These HIGH-impact assumptions are unverified:" - -> List each with its verification method - -> Offer: [1] Verify now [2] Accept risk (waiver) [3] Back to research - - If status = verified: -> PASS - If status = waived: -> PASS (with documented risk acceptance) - If status = falsified: -> BLOCK and return to Phase 3 (approach is invalid) - -For each assumption where impact = MEDIUM and status = unverified: - -> WARN but allow proceeding - -For each assumption where impact = LOW and status = unverified: - -> INFO only -``` - -If user chooses [2] Accept risk (waiver), require: -- Documented risk statement -- Approver name -- Contingency plan if assumption fails -- Update assumption status to "waived" in status.json - -This gate is NOT advisory. It is a hard block. The plan CANNOT proceed to -Build with unverified HIGH-impact assumptions unless explicitly waived. - -This phase actively assists with implementation. - -PARALLEL EXECUTION RULE: -Before starting tickets, analyze the dependency graph from the plan: -- Tickets with NO dependencies on other tickets can run IN PARALLEL as subagents -- Tickets that depend on other tickets must wait until dependencies complete -- Group independent tickets into parallel batches - -``` -Example dependency graph: - POS-5160 (no deps) -> Batch 1 (parallel) - POS-5161 (no deps) -> Batch 1 (parallel) - POS-5162 (no deps) -> Batch 1 (parallel) - POS-5163 (needs 5160) -> Batch 2 (after 5160 completes) - POS-5164 (needs 5162) -> Batch 2 (after 5162 completes) - POS-5165 (needs 5163, 5164) -> Batch 3 (after Batch 2) -``` - -Present the batch plan to the user: -"I can run {N} tickets in parallel (Batch 1: {tickets}). -Batch 2 ({tickets}) depends on Batch 1. Execute Batch 1 in parallel? [Y/n]" - -For each parallel batch, deploy subagents: -- Each subagent gets: ticket description, relevant plan sections, codebase context -- Each subagent writes to a separate branch or file set -- Orchestrator tracks progress and resolves conflicts between parallel work - -DOCUMENT ACTIONS (no approval needed): -- Track ticket progress (update status.json with per-ticket notes) -- Answer questions about the plan ("what file for POS-5162?") -- Provide code context from research -- Suggest next ticket to work on based on dependencies - -CODEBASE ACTIONS (approval required per action): -- "Generate code scaffold for CcReceiptStrings.cs? [Y/n]" -- "Run characterization tests on Printing.FormatReceipt? [Y/n]" -- "Create branch description for Phase 1 tickets? [Y/n]" - -CHANGE CONTROL (backward flow rules with immutable records): -After Phase 3 scope lock, accepted plan documents are immutable. Changes -require a formal Change Record, not silent edits. - -- Minor discovery during build: - 1. Create docs/plans/{date}-{name}/changes/CR-{N}.md with: - - What changed and why - - Which document/section it supersedes - - The NEW content (the CR is the authoritative version going forward) - - Impact on other phases - 2. Add a status line to the TOP of the original document: "SUPERSEDED by CR-{N} on {date}" - Do NOT modify the original document's content. The CR contains the new version. - 3. Update manifest.md with link to the Change Record - 4. Update status.json: { "change_records": [{ "id": "CR-001", "date": "...", "summary": "..." }] } - -- Scope change discovered -> "This changes the scope. Go back to Pre-Plan? [Y/n]" - If yes: create CR-{N} documenting the scope change reason, mark pre_plan - and plan as STALE, return to Phase 3. Original approach.md preserved. - -- New blocker found -> mark current build ticket as BLOCKED with reason, - create CR-{N} documenting the blocker and its impact. - -- Implementation diverges from plan -> create CR-{N} documenting the divergence - and rationale. This replaces informal ADR/change notes. - -Change Record template: -```markdown -# CR-{N}: {Title} -Date: {date} -Author: {name} -Supersedes: {document or section} - -## What Changed -## Why It Changed -## Impact on Other Phases -``` - -Update status.json with build progress, manifest.md. - -No gate. User stays in Build until ready for Impact Review. diff --git a/plugins/deepgrade/skills/plan/phases/phase-7-impact-review.md b/plugins/deepgrade/skills/plan/phases/phase-7-impact-review.md deleted file mode 100644 index 4b8df56..0000000 --- a/plugins/deepgrade/skills/plan/phases/phase-7-impact-review.md +++ /dev/null @@ -1,205 +0,0 @@ -# Phase 7: IMPACT REVIEW - -Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when the workflow enters this phase. Do not read ahead to other phase files. - -## Contents - -- What it checks: dimensions 1-7 -- Process: parallel subagents -- Output: impact-review.md template -- Testing methodology verification -- Gate - -Question: What else does this change affect across layers? - -This is a cross-cutting verification gate. Code that works locally and passes -targeted tests can still break integration edges, scale behavior, transition-state -UX, and downstream consumers. This phase explicitly asks "what did we miss?" - -WHAT IT CHECKS: - -1. INTEGRATION EDGES - - What other modules call the code we changed? - - Did we update all callers, or just the ones we knew about? - - Are there event handlers, webhooks, or async consumers that depend on - the old behavior? - ```bash - # Find all callers of changed functions - grep -rn "{function-name}" --include="*.cs" --include="*.vb" --include="*.ts" \ - . 2>/dev/null | grep -v node_modules | grep -v test - ``` - -2. CROSS-LAYER EFFECTS - - Database: did schema changes affect other queries or stored procedures? - - API: did response format changes break downstream consumers? - - UI: did state changes affect other screens or components? - - Config: did new settings need to be added to all environments? - -3. SCALE AND PERFORMANCE - - Will this change behave differently at production load? - - Did we add queries inside loops? New N+1 patterns? - - Did we add memory-intensive operations without limits? - -4. TRANSITION-STATE BEHAVIOR - - During rollout, old and new code may run simultaneously. - - Feature flags: is the off-state still safe? - - Database migrations: is the schema compatible with both old and new code? - - What happens to in-flight requests during deployment? - -5. TEST DELTA - - What tests existed before vs after? - - Did we add tests for the new behavior? - - Did existing tests need updating and did we miss any? - - Are there integration tests that cover the cross-cutting paths? - -6. STRING PATH REFERENCES (critical for file moves/renames) - If ANY files were moved or renamed during the build phase, scan for stale - string-based path references that don't auto-update. This is a KNOWN gap: - TypeScript/VSCode updates import statements on file move, but does NOT - update string literals. - - Patterns to scan for old file paths: - - vi.mock("old/path") and jest.mock("old/path") - - require("old/path") string arguments - - eslint.config.js ignore arrays - - tsconfig.json paths and includes - - vite.config.ts resolve.alias - - webpack.config.js alias/resolve - - storybook stories globs - - jest.config moduleNameMapper - - package.json scripts that reference file paths - - .env files with path values - - CLAUDE.md or README references to file locations - - ```bash - # For each moved/renamed file, find stale string references - OLD_PATH="{old-file-path-without-extension}" - grep -rn "$OLD_PATH" --include="*.ts" --include="*.tsx" --include="*.js" \ - --include="*.json" --include="*.config.*" --include="*.md" \ - . 2>/dev/null | grep -v node_modules | grep -v ".git/" - ``` - - Any match is a potential stale reference that needs updating. - TypeScript Issue #62835 (open): This is a known gap in all major IDEs. - -7. BACKWARD TRACEABILITY (does every change serve a goal?) - For every file changed during Build, verify the reverse coverage chain: - - Changed file -> Ticket that authorized the change -> Goal it serves - - Orphan detection: - - Files changed with no ticket mapping = SCOPE CREEP (flag) - - Tickets with no changed files = DELIVERY GAP (flag unless explicitly deferred) - - ```bash - # For each changed file, check if it maps to a plan ticket - # Compare git diff file list against ticket-file mapping in status.json - git diff --name-only HEAD~{N}..HEAD | while read FILE; do - grep -q "$FILE" docs/plans/{date}-{name}/status.json || echo "ORPHAN: $FILE" - done - ``` - - Any orphan file must be either: - - Linked to an existing ticket (developer forgot to log it) - - Justified as necessary infrastructure (added to a new ticket) - - Flagged as scope creep for review - - This traceability check is what LINT-11 and LINT-12 are evaluated against; - the registry holds their text and marks both as Phase 7, Full mode only. - -PROCESS: -PARALLELIZATION RULE: The 5 check dimensions are independent. Deploy parallel -subagents for each dimension to speed up the review. - -Deploy up to 3 subagents in parallel (scale to the size of the change): - -SUBAGENT A - Integration & Cross-Layer (Sonnet): -Objective: Find all callers of changed code, check integration edges and cross-layer effects -Tools: Read, Grep, Glob, Bash -Checks: dimensions 1 (Integration Edges) and 2 (Cross-Layer Effects) - -SUBAGENT B - Scale & Transition State (Sonnet): -Objective: Analyze performance impact and transition-state safety -Tools: Read, Grep, Glob -Checks: dimensions 3 (Scale) and 4 (Transition-State) - -SUBAGENT C - Test Delta, String Paths & Backward Trace (Sonnet): -Objective: Compare test coverage before vs after, scan for stale string path references, AND verify backward traceability of all changed files -Tools: Read, Grep, Glob, Bash -Checks: dimensions 5 (Test Delta), 6 (String Path References), and 7 (Backward Traceability) - -Each subagent writes its section to a temp file. Orchestrator synthesizes. - -Steps: -1. Read the build phase's changed files from status.json -2. Deploy subagents with the list of changed files + relevant audit data -3. Each subagent scans for its dimensions -4. Cross-reference with docs/audit/dependency-map.md (if exists) -5. Cross-reference with docs/audit/integration-scan.md (if exists) -6. Synthesize all subagent findings -7. Flag any untested integration path -8. Present findings as a checklist - -OUTPUT: Written to docs/plans/{date}-{plan-name}/impact-review.md with: - -```markdown -# Impact Review: {Plan Name} -Date: {date} -Changed files: {count} -Integration edges checked: {count} - -## Cross-Cutting Findings - -| # | Finding | Severity | File | Checked? | -|---|---------|----------|------|----------| -| 1 | OrderReceipt.tsx also formats receipt strings | HIGH | src/features/orders/ | [VERIFY] | -| 2 | CCApproval.vb has hardcoded receipt text | MEDIUM | POSetcPOS/CreditCard/ | [VERIFY] | -| 3 | Print preview doesn't use new string table | LOW | POSetcPOS/Printer/ | [VERIFY] | - -## Integration Paths Not Covered by Tests -- [list of caller->callee paths that have no test coverage] - -## Scale Concerns -- [any performance-related observations] - -## Transition-State Risks -- [anything that could break during partial rollout] - -## Checklist Before Test Phase -- [ ] All callers of changed functions verified -- [ ] No untested integration paths remaining (or explicitly accepted) -- [ ] Scale behavior reviewed for production load -- [ ] Feature flag off-state tested -- [ ] Database migration compatible with old and new code -- [ ] No orphan code changes (all changes traced to tickets) [LINT-11] -- [ ] No orphan tickets (all tickets have implementation or are deferred) [LINT-12] - -TESTING METHODOLOGY VERIFICATION: -For each deliverable with an assigned testing methodology (from Phase 4): -- [ ] Methodology is appropriate for the type of change (not defaulting to "unit tests") -- [ ] Test authorship is separate from implementation authorship for AI-generated code -- [ ] Database changes use Expand/Contract with forward AND backward migration scripts -- [ ] API changes have contract tests covering old code + new schema AND new code + old schema -- [ ] Characterization tests captured BEFORE refactoring (not after) -- [ ] AI Failure Mode Checklist applied to all AI-generated deliverables - -Database Migration Testing (if applicable): - -| Phase | What to Test | Method | -|-------|-------------|--------| -| Expand | New columns/tables exist, old untouched | Structural assertions | -| Migrate | Row counts, checksums, referential integrity preserved | Characterization + Shadow | -| Contract | Old structures removed, no orphan refs, all code uses new schema | Structural assertions | -| Rollback | Backward migration restores original state | Apply -> verify -> rollback -> verify | -| Backward compat | Old code + new schema works, new code + old schema works | Contract Testing | -| Performance | Queries under threshold, indexes present, no N+1 | Property-Based + Profiling | -``` - -GATE: User confirmation required. -"Impact review complete. {N} cross-cutting findings, {M} untested integration -paths. Review the findings and confirm before proceeding to Test." - -If HIGH severity findings exist: -"HIGH severity: {finding}. This should be addressed before Test phase. -Fix it now, or accept the risk and proceed? [fix / accept with reason]" - -Update status.json, manifest.md. diff --git a/plugins/deepgrade/skills/plan/phases/phase-9-handoff.md b/plugins/deepgrade/skills/plan/phases/phase-9-handoff.md deleted file mode 100644 index 42151eb..0000000 --- a/plugins/deepgrade/skills/plan/phases/phase-9-handoff.md +++ /dev/null @@ -1,34 +0,0 @@ -# Phase 9: HANDOFF - -Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when the workflow enters this phase. Do not read ahead to other phase files. - -Question: What happens next? - -READINESS CHECK before entering this phase: -- Test phase complete (or explicitly waived) -- Audit score GREEN or YELLOW with gap-checked = YES -- No BLOCKED tickets remaining (or explicitly deferred) -- Rollback plan documented - -Context-aware guidance based on situation: -- If ready to ship: specific deployment sequence with verification steps -- If gaps remain: prioritized list of what to fix with reasoning -- If timeline pressure: critical path items vs deferrable items - -Update manifest.md with final status, decisions made, lessons learned. -Update status.json: handoff -> complete. - -Present final summary: -``` -Plan: {name} - Complete - -Phases: 9/9 -Duration: {started} to {completed} -Audit score: {score}/40 ({rating}) -Tickets: {done}/{total} - -Key decisions: [from approach.md and change records] -Change records: {count} (see changes/ folder) -What shipped: [summary] -What's deferred: [if anything] -``` diff --git a/plugins/deepgrade/skills/plan/stages/stage-1-plan.md b/plugins/deepgrade/skills/plan/stages/stage-1-plan.md new file mode 100644 index 0000000..ec5f060 --- /dev/null +++ b/plugins/deepgrade/skills/plan/stages/stage-1-plan.md @@ -0,0 +1,222 @@ +# Stage 1: PLAN + +Stage file for /deepgrade:plan. Loaded by SKILL.md on entry; re-read after compaction. Do not read ahead. + +Question: What problem are we solving, and what is true about our situation? +Reads: $ARGUMENTS (plan name, optional source material), the codebase, connected search tools +Produces: docs/plans/{date}-{name}/intent.md, research/findings.md, research/reference-data.json, research/intake/ (if source docs) +Gate: A named product owner sets intent.md Status to Accepted + +## Contents + +- Intent-only mode +- Step 1: Intent interview (writes intent.md) +- Step 2: Research (three parallel tracks, writes research/findings.md) +- Step 3: Synthesis into intent.md +- Gate: acceptance by a named product owner + +This stage merges the old brainstorm and research phases. The single artifact is +intent.md: a short, structured statement of the problem that a product owner can +read and accept without engineering context, and that Stage 2 (Design) reads to +produce spec.md. Research does not get its own gate any more; it feeds the +Constraints and Open questions sections of intent.md, and acceptance of intent.md +is the only exit from this stage. + +INTENT-ONLY MODE: +When invoked as `/deepgrade:plan intent {name}`, run this stage only. Complete +the interview, run research, write intent.md, commit it, ask the product owner +for acceptance, and STOP. Do not enter Stage 2 (Design) even if acceptance is +given in the same session; the owner resumes with `/deepgrade:plan {name}` when +design should begin. This mode exists so a non-engineer can originate a plan +without committing anyone to building it. + +Update status.json: plan -> in_progress (set started timestamp) + +## Step 1: Intent interview + +The originator may be a non-engineer. Ask ONE question at a time, in plain +language, and accept short answers. Do not ask for file paths, architecture, or +technology choices here; those belong to Stage 2 (Design). Each question maps to +one section of intent.md. + +IF input is a vague idea or just a plan name: + 1. "What cannot be done today, and why does it matter?" -> ## Problem + 2. "What should be true when this is done? How would you know?" -> ## Proposed outcome + 3. "Who is affected, and which systems or teams does this touch? + Who owns the decision to accept this?" -> ## Affected users and systems + 4. "What is fixed: deadline, budget, compliance, brand, security, + compatibility, anything non-negotiable?" -> ## Constraints + 5. "What should this explicitly NOT cover?" -> ## Out of scope + 6. "What do you not know yet that would change the answer?" -> ## Open questions + +IF input includes source docs (from keyword): + Read the source material, draft every section of intent.md from it, then ask: + "Based on what I read, here's the problem as I understand it: [Problem section]. + Is this right, or should I adjust?" + Confirm the remaining sections one at a time, showing the draft for each. + +IF input includes an existing ticket or spec: + Extract the problem statement and outcome, confirm with the originator, and ask + only the questions the source does not answer. + +Write intent.md in the plan folder: + +```markdown +# {Title} + +- Author: {originator name} +- Source: {team, channel, ticket, or "conversation"} +- Status: Draft +- Date: {YYYY-MM-DD} +- Accepted by: (pending) + +## Problem + +{In the originator's own words: what cannot be done today, and why it matters.} + +## Proposed outcome + +{What should be true when this is done. Observable and measurable where possible.} + +## Affected users and systems + +{Who is affected, which systems are touched, who owns the decision.} + +## Constraints + +{Time, budget, compliance, brand, security, compatibility, non-negotiables.} + +## Out of scope + +{What this intent explicitly does not cover.} + +## Open questions + +{Questions that must be answered before or during design. Research (Step 2) +answers or defers each one; the answer or the deferral is recorded here.} +``` + +Keep every section short and concrete. The product owner reviews this file; a +section they cannot understand is a section that will not be accepted. + +Ask "Problem defined. Ready to research? [Y/n]" before spending research effort. +This is a courtesy checkpoint, not the stage gate. + +## Step 2: Research + +Run three research tracks IN PARALLEL using subagents: + +PARALLELIZATION RULE: The three tracks are independent. Deploy them +simultaneously as subagents, each with its own context window. Do NOT +run them sequentially. Each writes its output to the plan folder. + +TRACK 1 - CODEBASE SCAN (Subagent: Sonnet): +Objective: Find all related code in the current codebase. +Tools: Read, Grep, Glob, Bash +Output: docs/plans/{date}-{name}/research/codebase-scan.md +```bash +# Search for related code based on intent.md keywords +grep -ri "{keywords}" --include="*.cs" --include="*.vb" --include="*.ts" \ + --include="*.config" --include="*.json" . 2>/dev/null | grep -v node_modules | head -30 +``` +Read the key files found. Note existing patterns, current implementation, dependencies. + +TRACK 2 - SOURCE DOC CLEANUP (Subagent: Sonnet, if docs were provided): +Objective: Clean and structure provided source documents. +Tools: Read, Write, Bash +Output: docs/plans/{date}-{name}/research/intake/ (structured files) +Read all files in the source folder. Extract structured data per content type. +Write cleaned data to research/intake/. + +TRACK 3 - BEST PRACTICES (Subagent: Sonnet, if external search tools available): +Objective: Find how others solved similar problems. +Tools: Read, WebSearch, WebFetch, plus any connected MCP search tool whose name +ends in `__ref_search_documentation`, `__ref_read_url`, `__web_search_exa`, +`__web_fetch_exa`, or `__perplexity_ask` (see the `deepgrade:mcp-research` skill — +match by suffix, never by bare name) +Output: docs/plans/{date}-{name}/research/best-practices.md + +Search strategy (use in order, stop when sufficient): +1. Ref: Search framework/library docs for the specific technologies in scope. + Use ref_search_documentation with a complete question (not keywords). +2. Exa: Search for code examples of the pattern being considered. + Use web_search_exa for both implementation examples and general patterns, then + web_fetch_exa on the one result worth reading in full. +3. Perplexity: If Ref + Exa are insufficient, ask a targeted research question. + Use perplexity_ask for focused answers with citations. +4. WebSearch/WebFetch: Fallback if MCP tools are not available. + +If NO external search tools are available: + Fall back to codebase-only research using built-in tools. + Tag in findings.md: "[EXTERNAL RESEARCH UNAVAILABLE — findings based on codebase and training data only]" + +SYNTHESIS (after all tracks complete): +Read all three track outputs. Cross-reference findings. +Write docs/plans/{date}-{name}/research/findings.md as the combined summary. +Write research/reference-data.json. +Record path-scoped fingerprints for referenced files (not full repo SHA). + +STOP RUBRIC - Research is DONE when: +- Every intent.md open question is answered or explicitly deferred +- At least one viable implementation path is identified +- Top risks have mitigation ideas +- Remaining unknowns are non-blocking + +## Step 3: Synthesis into intent.md + +Research does not change the Problem or Proposed outcome sections; those are the +originator's. It updates two sections: + +- ## Constraints: add constraints the research discovered that the originator did + not name (an existing pattern the change must fit, a dependency version, a + compliance boundary found in the codebase). Mark each "(from research)". +- ## Open questions: replace each question with its answer and the finding that + answers it, or mark it "Deferred to design: {reason}". A question that research + could not answer and that blocks design stays open and is called out in the + acceptance prompt. + +Present findings to the originator in plain language: +``` +Research complete. Key findings: + +CODEBASE: [what exists, what we can reuse] +SOURCE DOCS: [key facts extracted] +BEST PRACTICES: [recommended approach] + +What we still don't know: [gaps, with assessment: blocking vs non-blocking] +Open questions resolved: [X of Y] +``` + +Update manifest.md: add intent.md and research files to Plan Files table with date. +Update status.json: record research file hashes under documents. + +## Gate: acceptance by a named product owner + +The stage exits only when a named person accepts intent.md. The originator may +accept their own intent if they own the decision; otherwise ask who does. + +Prompt: +"intent.md is ready for acceptance. Who is the product owner accepting it? + [1] Enter the owner's name to accept + [2] Request changes (say what to adjust) + [3] Reject (record the reason; the plan closes)" + +If [1]: + - Set intent.md header: Status: Accepted; Accepted by: {name}, {YYYY-MM-DD} + - status.json phases.plan: { "status": "complete", "accepted_by": "{name}", + "accepted_date": "{YYYY-MM-DD}", "completed": "{ISO timestamp}" } + - Commit intent.md and the research folder together. + - Update status.json: plan -> complete (set completed timestamp) + - Update manifest.md progress table. + - In intent-only mode: report "Intent accepted and committed. Resume with + /deepgrade:plan {name} to begin design." and STOP. + - Otherwise: proceed to Stage 2 (Design). + +If [2]: revise the named sections, re-present, re-prompt. Research is re-run +only if the Problem or Proposed outcome changed materially. + +If [3]: set Status: Rejected with the reason under a "## Rejection" section, +update status.json: plan -> rejected (set completed timestamp), commit, STOP. + +An intent nobody has accepted is a draft. Stage 2 (Design) must not start from +a draft: an unaccepted intent produces a spec for a problem no one agreed exists. diff --git a/plugins/deepgrade/skills/plan/stages/stage-2-design.md b/plugins/deepgrade/skills/plan/stages/stage-2-design.md new file mode 100644 index 0000000..499dbbc --- /dev/null +++ b/plugins/deepgrade/skills/plan/stages/stage-2-design.md @@ -0,0 +1,949 @@ +# Stage 2: DESIGN + +Stage file for /deepgrade:plan. Loaded by SKILL.md on entry; re-read after compaction. Do not read ahead. + +Question: What should be in scope, how will we execute it, and what is weak or missing? +Reads: intent.md (Status: Accepted), research/findings.md, research/reference-data.json +Produces: docs/plans/{date}-{plan-name}/spec.md, audit.md, evidence/, .canary/ +Gate: Design gate PASS + human review (or waiver) + spec.md Status: Approved + +## Contents + +- Part A: Scope and design (spec.md Requirements, Design, Standards applied, Gotchas) +- Part A: Evidence section (the confidence brief, folded into spec.md) +- Part A: Scope lock (user gate, mid-stage) +- Part B: Verification plan and Delivery (spec.md completed) +- Part C: Design gate (the audit) - checks, outputs A-D, canary, evidence validation +- Part C: Infrastructure verification, plan lint rules, gap summary +- Part C: Evidence reinforcement and baseline snapshot +- Part C: Gate expression, revision loop, auditor isolation +- Part C: Human review gate and waiver condition +- Exit: spec.md Status: Approved + +This stage merges the old pre-plan, plan, and audit phases. The single artifact +is spec.md in the plan folder. It is written in two passes (Part A, then Part B +after scope lock), then audited in Part C. The audit is the DESIGN GATE: it runs +against spec.md, and nothing enters Stage 3 (Build) until it passes. + +Do not start this stage unless intent.md Status is Accepted. If it is Draft, +return to Stage 1 (Plan) and obtain acceptance first. + +Update status.json: design -> in_progress (set started timestamp) + +spec.md layout (every section is required; write "None" rather than omit): + +```markdown +# {Title} — Specification + +- Derived from: intent.md ({commit or path}) +- Author: {agent + human reviewer} +- Status: Draft +- Date: {YYYY-MM-DD} + +## Requirements +### Functional +### Non-functional +## Design +## Standards applied +## Gotchas +## Evidence +## Open questions +## Verification plan +## Delivery +``` + +--- + +## Part A: Scope and design + +Produce the alignment checkpoint. These sections are written first because the +scope lock below is a decision about THEM; Verification plan and Delivery are +written only after scope is locked. + +### Requirements + +- ### Functional: what the system must do. Derive from intent.md Proposed outcome; + every functional requirement traces to a line of the intent. +- ### Non-functional: performance, security, accessibility, compliance, + operability. Derive from intent.md Constraints. +- Scope: IN list and OUT list. The OUT list starts from intent.md Out of scope and + grows with anything ruled out during options analysis. + +### Design + +- Options Analysis (REQUIRED): Evaluate minimum 2 approaches before selecting: + + For each option: + - Name and approach description + - Pros and cons + - Risk level (LOW/MEDIUM/HIGH) + - Rollback complexity (LOW/MEDIUM/HIGH) + + Comparison matrix scoring each option against: + - Implementation ease, Timeline, Strategic value, Risk profile, Rollback complexity + + Decision Rationale: WHY the selected option won, referencing specific criteria. + Losing options: document "would revisit if" conditions. + +- Approach/Pattern: which pattern and WHY (strangler fig, feature flag, migration, new build, integration) +- Architecture or data flow; interfaces (APIs, data, UI) +- Constraints: timeline, team, technology +- Dependencies: internal, external, hard blockers, soft dependencies + +### Standards applied + +Which org standards (brand, security, UX, compliance) were applied, and how. +Cite the standard document where one exists. + +### Gotchas + +Top 3 Risks: each with impact level and mitigation. Add conflict points, risky +decisions, trade-offs, and what to watch during build. + +### Evidence + +EVIDENCE SECTION (REQUIRED — written after Design, before the scope lock): + +WHY THIS EXISTS: Without external evidence backing, plan decisions rest on +the authoring agent's training data alone — which may be outdated, biased, or +hallucinated. Stakeholders reviewing plans cannot distinguish "this is industry +standard" from "this is what the AI made up." The Evidence section solves this +by requiring verifiable external evidence for every significant tool, method, +and pattern choice. + +SUCCESS CRITERIA: +- Every HIGH-impact entry has at least one verifiable reference link +- A stakeholder unfamiliar with the plan can read the Evidence section and + understand why the chosen approach is industry-proven (not just "the AI + suggested it") +- No fabricated company examples (see SOURCE CREDIBILITY below) + +TIMEBOX: The Evidence section should take no longer than the Design section itself. +- MAX ENTRIES: 10 entries per plan (prioritize by impact). If more than 10 + items are identified, defer LOW-impact items with a note: "Deferred: {item} + (LOW impact, not blocking scope lock)" +- If entry count exceeds 10, stop and present the top 10 sorted by impact. + User can request additional entries after scope lock. + +Step breakdown (approximate effort per entry): +1. Discovery — scan the Design section, research/findings.md, and intent.md for items (~1 min total) +2. Drafting — write "what it is" and "connection to plan" (~1 min per entry) +3. Evidence gathering — search for "who uses it" and references (~2 min per HIGH, ~1 min per MEDIUM) +4. Cross-plan search — check other plans' spec.md Evidence sections (~30 sec per entry) +5. Review — verify URLs for HIGH-impact entries if web tools available (~1 min per HIGH) + +If the plan is under timeline pressure, skip steps 4-5 for MEDIUM and LOW +entries and mark them with "[CROSS-PLAN CHECK DEFERRED]" and "[URL VERIFICATION +DEFERRED]". HIGH-impact entries MUST always complete steps 3-5 regardless of +timeline pressure — these entries drive scope lock decisions and cannot be deferred. + +The Evidence section is a self-contained knowledge brief that grounds every +tool, method, and pattern choice in external industry evidence. It is +stakeholder-readable: someone outside the plan should be able to read it and +understand why these choices are solid. + +Scan the Design section, research/findings.md, and intent.md for: +- New dependencies/packages (NuGet, npm, pip, etc.) +- Methodologies or patterns chosen (strangler fig, expand/contract, CQRS, etc.) +- Best practices referenced (DORA metrics, chaos engineering, etc.) +- Frameworks, libraries, or tools introduced + +For EACH item found, write an entry under ## Evidence using this structure: + +```markdown +## Evidence +Created: {date} (Stage 2) +Last reinforced: {date} (design gate, if applicable) + +> This section explains WHY the tools, methods, and patterns in this plan +> are industry-proven choices. Each entry defines what it is, who uses it +> at scale, and why it works — then briefly connects it to this plan. + +### Dependencies & Tools + +#### {Package/Tool Name} {version} {#anchor} +**Impact:** {HIGH|MEDIUM|LOW} — {one-line rationale} + +**What it is:** {1-2 sentence definition — what the tool does, what problem it solves} + +**Who uses it at scale:** +- **{Company 1}** — {how they use it, what scale, what outcome} +- **{Company 2}** — {how they use it, what scale, what outcome} + +**Why it works:** {1 paragraph — the engineering reason this tool is effective, +what architectural property it provides, what failure mode it prevents} + +**Reference:** [{title}]({url}) ← link to official docs, conference talk, or case study + +**Connection to this plan:** {1-2 sentences — why we chose this specifically, +which plan goal it serves} + +**Also referenced in:** [{other-plan-name}](../../{other-plan-dir}/spec.md#{anchor}) ← only if another plan uses the same tool + +### Methods & Patterns + +#### {Method/Pattern Name} {#anchor} +**Impact:** {HIGH|MEDIUM|LOW} — {one-line rationale} + +**What it is:** {1-2 sentence definition} + +**Origin:** {Who created/popularized it — e.g., "Martin Fowler (2004)", +"Netflix engineering team (2011)", "Microsoft Azure Architecture Center"} + +**Who uses it at scale:** +- **{Company 1}** — {context and outcome} +- **{Company 2}** — {context and outcome} + +**Why it works:** {1 paragraph — the engineering principle, what it optimizes +for, what tradeoff it makes explicit} + +**Reference:** [{title}]({url}) + +**Connection to this plan:** {1-2 sentences linking to specific plan phases or decisions} + +**Also referenced in:** [{other-plan-name}](...) ← only if applicable + +### Best Practices & Standards + +#### {Practice Name} {#anchor} +**Impact:** {HIGH|MEDIUM|LOW} — {one-line rationale} + +**What it is:** {1-2 sentence definition} + +**Advocated by:** {Organization or thought leader — e.g., "DORA/Google", +"OWASP", "12-Factor App (Heroku)"} + +**Industry evidence:** +- {Specific metric or finding — e.g., "Teams using trunk-based development + deploy 973x more frequently (DORA State of DevOps 2023)"} + +**Why it works:** {1 paragraph} + +**Reference:** [{title}]({url}) + +**Connection to this plan:** {1-2 sentences} +``` + +CROSS-PLAN REFERENCES: +Before writing each entry, search existing plan folders' spec.md files for the +same tool or pattern: +```bash +find docs/plans/ -name "spec.md" -exec grep -l "{tool-or-pattern-name}" {} \; +``` +If found in another plan, add an "Also referenced in" link. The entry in THIS +file must still be self-contained (full context) — the link is supplemental, +not a replacement for content. A reader should never need to open another +plan's spec.md to understand this one. + +ENTRY PRIORITIZATION: +- HIGH-impact items (core dependencies, primary pattern): full entry with reference link REQUIRED +- MEDIUM-impact items (supporting tools, secondary patterns): full entry, reference link optional +- LOW-impact items (dev tooling, standard practices): shorter entry, no reference link required + +Impact classification criteria (rationale REQUIRED for each classification): +- HIGH: item is on the critical path, a wrong choice causes plan failure or rework + (e.g., primary database, core framework, architectural pattern) + Rationale example: "HIGH — Markdig is the sole markdown rendering engine; if it + can't handle our edge cases, the entire doc pipeline fails" +- MEDIUM: item supports the plan but alternatives exist with low switching cost + (e.g., utility libraries, secondary patterns, testing tools) + Rationale example: "MEDIUM — YamlDotNet parses config; could swap to SharpYaml + with ~2 days of work if needed" +- LOW: item is standard practice or dev tooling with no plan-specific risk + (e.g., linters, formatters, common build tools) + +Each entry must include a one-line rationale justifying its impact level. +This prevents gaming: downgrading a critical dependency to MEDIUM to avoid +source verification requirements is visible and reviewable. + +SOURCE CREDIBILITY (required for HIGH-impact entries): +Every "Who uses it at scale" and "Industry evidence" claim must be backed by +a verifiable source. Do NOT fabricate company examples. + +Source tiers: +- TIER A (preferred): Official docs, conference talks with video/slides, + published case studies, peer-reviewed papers, DORA/ThoughtWorks reports +- TIER B (acceptable): Reputable blog posts (company engineering blogs), + GitHub repos with usage evidence, Stack Overflow answers with high votes +- TIER C (flag): Training data recall without a specific URL — mark these as + "[UNVERIFIED — common knowledge, no primary source found]" so the reader + knows the claim needs manual verification + +HIGH-impact entries MUST have at least one TIER A or TIER B source. +If no verifiable source can be found for a HIGH-impact claim, flag it: +"[SOURCE NEEDED — this claim requires manual verification before scope lock]" + +URL VERIFICATION: When ref_read_url, web_search_exa, WebSearch, or WebFetch +tools are available, verify that reference URLs for HIGH-impact entries are +reachable before writing them. +- Prefer ref_read_url for documentation URLs (returns clean markdown, trajectory-aware) +- Use web_search_exa for general web URLs (semantic matching) +- Fall back to WebFetch if MCP tools are not available +If a URL is dead or redirects to unrelated content, downgrade to TIER C and +flag as "[LINK DEAD — needs replacement source]". + +CONFLICTING EVIDENCE: If two sources disagree on a claim (e.g., one recommends +a tool, another warns against it), document both perspectives: +"[CONFLICTING] Source A says X. Source B says Y. This plan assumes X because +{rationale}." Let the stakeholder see the tension rather than hiding it. + +EVIDENCE FALSIFICATION (post-scope-lock): +If an Evidence entry is later found to be wrong (e.g., a tool doesn't support +a claimed feature, a company example was fabricated, a pattern doesn't apply): +1. Create a Change Record (CR-{N}) documenting what was wrong and the impact +2. Mark the Evidence entry with: "**FALSIFIED ({date}):** {what was wrong}" +3. Mark downstream artifacts that relied on this claim as WARNING in status.json +4. If the falsified claim was HIGH-impact, trigger a scope review (return to Stage 2 (Design)) +5. If Stage 3 (Build) is in progress, freeze any tickets that depend on the + falsified claim until the scope review completes + +ANCHOR IDS: +Each entry heading must include a kebab-case anchor for cross-plan linking: +`#### YamlDotNet 16.3.0 {#yamldotnet-16}` so other plans can link directly. +When searching for cross-plan references, search for both the tool/pattern +name AND common aliases (e.g., "YAML" for "YamlDotNet", "strangler" for +"strangler fig pattern"). + +### Open questions + +Carry every intent.md open question forward with its current state: answered +(with the answer), or deferred (with owner and due date). Add questions the +design raised. A question with no owner is a gap the design gate will find. + +### SCOPE LOCK (user gate, mid-stage) + +Present Requirements, Design, Standards applied, Gotchas, Evidence, and Open +questions to the user for confirmation. This is the SCOPE LOCK. + +GATE: User confirmation REQUIRED. +"Does this scope look right? [confirm / adjust / back to research]" + +On "adjust" -> iterate on the Design section. +On "back to research" -> return to Stage 1 (Plan) research step (mark research +stale if scope changed; intent.md acceptance stands unless Problem or Proposed +outcome change). +On "confirm" -> record in status.json: phases.design.scope_locked = {ISO timestamp}. +Commit spec.md at this point; Part B extends it. + +After scope lock, the locked sections are immutable. Changes require a Change +Record (see Stage 3 change control), not silent edits. + +--- + +## Part B: Verification plan and Delivery + +Extend spec.md with the two remaining sections. Both are written against the +locked scope. + +### Verification plan + +TESTING METHODOLOGY SELECTION (REQUIRED): +For EACH deliverable in the spec, select the appropriate testing methodology. +Do NOT default to "unit tests" for everything. Reference the Testing Methodology +Selection Framework (docs/planning-techniques/10-testing-methodology-selection.md). + +| # | Methodology | Evidence Tier | When to Use | +|---|-------------|--------------|-------------| +| 1 | TDD | ENTERPRISE-VALIDATED | New feature with clear spec, algorithms, core business logic, stored procedures | +| 2 | BDD | INDUSTRY-RECOMMENDED | User-facing features, cross-functional teams, requirements ambiguity | +| 3 | Characterization / Golden Master | ENTERPRISE-VALIDATED | Refactoring legacy code, extracting from monolith, data migration validation | +| 4 | Contract Testing | INDUSTRY-RECOMMENDED | Microservices, API integrations, database backward compatibility | +| 5 | Property-Based | INDUSTRY-RECOMMENDED | Algorithms with infinite input space, financial calculations, query performance | +| 6 | Snapshot / Approval | INDUSTRY-RECOMMENDED | UI components, serialized output, reports, config generation | +| 7 | Shadow / Parallel | ENTERPRISE-VALIDATED | Production migration, database cutover, replacing live systems | +| 8 | ATDD | INDUSTRY-RECOMMENDED | Sprint planning, user story definition, database migration sign-off | +| 9 | Mutation Testing | EMERGING PRACTICE | Pre-release quality gate, measuring test suite effectiveness | +| 10 | Exploratory | ENTERPRISE-VALIDATED | Complex UI, late-stage discovery, automation gaps | +| 11 | Expand/Contract | ENTERPRISE-VALIDATED | Database schema migration, renaming columns/tables, changing data types | + +AI-specific requirements: +- The agent that writes implementation code MUST NOT write the tests (Separate Test Authorship) +- AI-generated code receives higher testing scrutiny than human code +- Every AI-generated deliverable is checked against the AI Failure Mode Checklist: + logic drift, stale dependencies, hidden business rule violations, tautological + tests, happy-path-only coverage + +For database schema changes, use Expand/Contract (Methodology 11) with three phases: + - Expand: add new alongside old (structural assertions) + - Migrate: dual-write, backfill, test (data integrity + shadow comparison) + - Contract: remove old after cutover (no orphan references) + +State how this will be tested at build time and in the eval suite, per +deliverable, naming the methodology from the table. + +### Delivery + +Write the Delivery section with THREE views: + +1. JIRA-READY TICKETS: Per phase, with title, acceptance criteria, assignable +2. LEADERSHIP SUMMARY: Executive summary, timeline table, go/no-go criteria +3. WORKING CHECKLIST: Step-by-step with verification per step + +Detail level per phase based on risk: +- HIGH risk: exact files, function names, grep patterns, commit SHA, test requirements +- MEDIUM risk: file paths, approach, key decisions +- LOW risk: goals, scope, success criteria + +Include: +- Timeline table with dependencies and critical path +- Operational readiness section (if deployment involved): monitoring, config rollout, incident fallback, success metrics +- Rollback plan per phase +- Go/no-go criteria per phase boundary + +"Phase" here means a phase OF THE DELIVERY PLAN (Phase 1, Phase 2, ... inside +spec.md), not a stage of this workflow. + +Present to user: +"Spec written with {N} delivery phases and {M} tickets over {X} weeks. Review +before the design gate runs? [Y/n]" + +Commit spec.md. Update manifest.md: add spec.md to Plan Files table with date. + +--- + +## Part C: Design gate (the audit) + +Question: What is weak or missing? + +Run the checks below using the plan-auditor agent against +docs/plans/{date}-{plan-name}/spec.md. + +CHECK 1 - CRITERION RECORDS: +The auditor returns criterion records, not a score; each record carries a +verdict (MET, UNMET, N_A) and the evidence it rests on, and the rubric that +produces those records lives in `agents/plan-auditor.md`, deliberately not here. + +CHECK 2 - DEVIL'S ADVOCATE: +Challenge each assumption. For each challenge, cite evidence or flag [VERIFY]. +Structured premortem questions: + "If this fails in production, what is the most likely reason?" + "What did we assume would be true but isn't?" + "What changed in one layer but not another?" + "What behavior works in tests but fails in browser/runtime?" + +CHECK 3 - CODEBASE VERIFICATION: +Confirm file paths, line numbers, function names referenced in plan actually exist. + +CHECK 4 - GAP VERIFICATION: +This check produces 4 structured outputs that catch systematic gaps. +A plan CANNOT be considered gap-checked until all 4 outputs exist. + +OUTPUT A: Coverage Matrix +Map every goal, risk, dependency, and non-goal to its plan artifact: + +```markdown +## A. Coverage Matrix + +| Item | Type | Covered By | Status | +|------|------|-----------|--------| +| bilingual receipts | goal | Phase 1, POS-5163, tests T1/T2 | covered | +| certification timeline | dependency | Phase 4, owner TBD | partial | +| rollback | operational | plan section + handoff | covered | +| CORS handling | non-goal | explicitly excluded | ok-excluded | +| user pagination | assumption | not addressed | GAP | +``` + +Rules: +- Every goal must map to at least one phase AND at least one ticket +- Every risk must map to a mitigation +- Every dependency must map to an owner or blocker +- Every rollout item must map to monitoring + rollback +- Every non-goal must NOT accidentally appear in the plan +- Items marked GAP fail the gap check + +OUTPUT B: Assumption Register +Every assumption the plan makes, with impact-if-false and verification: + +```markdown +## B. Assumption Register + +| # | Assumption | Impact If False | How to Verify | By When | Owner | Status | +|---|-----------|----------------|---------------|---------|-------|--------| +| 1 | User lookup fits in first page | Breaks onboarding flow | Check query with production data volume | Before Phase 2 | Kyle | unverified | +| 2 | triPOS SDK supports Canada | Blocks entire plan | Test API call to Canadian endpoint | Phase 1 | Kyle | verified | +| 3 | Supabase rate limit handles OTP volume | Throttles users at scale | Load test 100 concurrent OTPs | Before launch | TBD | unverified | +``` + +Rules: +- Every assumption must have an impact assessment +- Unverified high-impact assumptions are BLOCKERS +- Assumptions with no validation step are WARNINGS +- Assumptions that block execution must be verified before Stage 3 (Build) + +AUTOMATED ASSUMPTION VERIFICATION: +After generating the Assumption Register, attempt automated verification +of all assumptions that have a verification method: + +For each assumption where impact = HIGH and status = unverified: + 1. If verification method mentions file/path: run `test -f [path]` + 2. If verification method mentions API/endpoint: note as REQUIRES_MANUAL + 3. If verification method mentions schema/database: search for schema files + 4. If verification method mentions config: search config files + 5. Update assumption status in status.json: + - verified: automated check passed + - unverified: automated check failed or not automatable + - falsified: automated check proved assumption false + +Track verification results: + "Assumptions: X total, Y verified (Z automated, W manual), V unverified, F falsified" + +OUTPUT C: Scenario Matrix +The auditor maps a fixed set of scenarios to implementation, test and monitoring. +The scenario list and the output table live in `agents/plan-auditor.md`; they are +not repeated here, for the same reason the rubric is not. + +What the plan itself must do — state this to the generator, not the list: +the plan has to account for how the change behaves when it works, when it fails, +while old and new run side by side, under load, at permission boundaries, across +environment differences, and on the way back out. A plan written against a named +checklist tends to grow a section per checklist item; a plan written against the +requirement tends to notice which of those actually apply to it and say so. + +Every scenario in the auditor's set gets an entry, including "not applicable" with +a reason. Items marked GAP fail the gap check. + +OUTPUT D: Cross-Cutting Concern Sweep +The auditor checks every feature and change against a fixed set of concerns. That +set and its output table live in `agents/plan-auditor.md` and are not repeated here. + +What the plan itself must do: address the concerns that cut across the change +rather than sitting inside one component — the contract it exposes, who is allowed +to call it, what differs between environments, how it behaves at the network and +data-access boundary, what it emits when running, and how it migrates and rolls +back. Concerns that genuinely do not apply are excluded explicitly with a reason. + +Every concern in the auditor's set gets a verdict. Unaddressed concerns are GAPS; +partial ones are WARNINGS. + +CANARY (automated, run BEFORE the auditor is spawned): + +Every other check in the design gate examines the plan. This one examines the auditor. + +```bash +node "${CLAUDE_PLUGIN_ROOT}/scripts/dg-canary.js" inject \ + docs/plans/{date}-{plan-name}/spec.md docs/plans/{date}-{plan-name}/.canary/ +``` + +One known defect is injected into a working copy of the spec — a rollback line +removed, a dependency owner blanked, an unverified HIGH-impact assumption added, +go/no-go criteria deleted, or a claim of coverage from a test file that does not +exist. The class is recorded along with the single criterion it violates. + +The auditor then audits the MUTATED copy, knowing nothing of any of this. + +Afterwards: + 1. If the recorded criterion is NOT in the audit's UNMET set, the audit missed a + defect that was placed there to be found. Re-run once with a different class. + A second miss fails the gate as "audit untrustworthy" — and DOES NOT trigger + the revision loop. Revising a plan against findings from an audit that could + not see a planted defect is worse than not revising: it rewrites the spec to + satisfy conclusions never derived from reading it. + 2. If it was found, strip that finding from the report — it is an artefact of + this harness, not a property of the plan — and then RE-CHECK that one + criterion against the unmutated original. The strip alone is unsafe: if the + plan has a genuine gap on the same criterion, removing "the LINT-03 finding" + would remove the real one with it. The strip removes the artefact; the + recheck decides the truth. + +An audit reporting zero gaps on a document known to contain a defect is not a +clean audit. It is a broken one, and nothing in its output would tell you so. + +Known limitation, stated rather than glossed: the auditor can read +`scripts/dg-canary.js`, including its defect table. This detects a lazy audit +reliably and an adversarial one only incidentally. Rotating the class per run +raises the cost of pre-empting it; it does not make the canary tamper-proof. + +EVIDENCE VALIDATION (automated, run before anything is treated as MET): + +The auditor returns criterion records, each carrying its evidence. Those records are +a PROPOSAL, not a result. Re-check every one of them mechanically: + +```bash +node "${CLAUDE_PLUGIN_ROOT}/scripts/dg-evidence-validate.js" \ + docs/plans/{date}-{plan-name}/evidence/ +``` + +The validator re-reads each cited artifact, confirms its hash still matches, slices +the cited line range and asserts the quoted text is byte-identical to it. It can only +ever DEMOTE a verdict — there is no input that makes it turn an UNMET into a MET. Use +the verdicts it returns, never the verdicts the auditor claimed. + +A record comes back UNMET, with a flag naming the reason, when: + EVIDENCE-INVALID the quote does not match the lines it cites + EVIDENCE-MISSING MET was claimed with no evidence at all + EVIDENCE-STALE the artifact changed after the record was written + EVIDENCE-ARTIFACT-MISSING the cited file does not exist + EVIDENCE-RANGE-INVALID the cited line range does not exist in the file + EVIDENCE-UNEXECUTED an executable criterion retained no command + EVIDENCE-COMMAND-FAILED the retained command exited non-zero + +The fourth rule is the one that matters most and is easiest to soften by accident: +an externally checkable claim with no evidence is UNMET. Not PARTIAL, not a warning, +not "verified but undocumented". This project has lost that argument twice — a layer +was recorded PARTIAL with its result asserted in a commit message and no artifact in +any commit, and a whole wave was closed against greps typed at a terminal that left +nothing behind. Both are UNMET here without anyone needing to notice. + +Do not re-run the auditor to "resolve" a demotion. A demotion is not a disagreement +to be settled; it means the evidence was not there, and the fix is in the plan. + +COMMIT the evidence directory together with audit.md. An audit whose evidence is not committed did not happen. + +This is the rule that makes an audit auditable later. A verdict is only as good as +the ability to re-derive it, and a re-check needs the records, the artifacts and the +hashes that bound them together at the time. Without them the audit degrades into +testimony — "it passed when I ran it" — which is exactly the class of claim this +project has already had to refuse twice. + +Exit codes from the validator, which the gate branches on: + 0 every record survived re-checking + 1 at least one claimed MET was demoted — the gate does NOT open + 2 the evidence directory is missing or empty + +Treat 2 as the most serious of the three. A missing directory is not a clean run +with nothing to report; it means the audit produced no evidence at all, and reading +it as a pass would rebuild the exact failure this replaces — a phase recorded green +on the strength of a claim that no artifact anywhere supports. + +INFRASTRUCTURE VERIFICATION (automated, run after gap matrices): +Cross-reference every coverage claim against verifiable artifacts. + +For each Scenario Matrix "Tested?" entry with a test file reference: + 1. Check if the test file exists: `test -f "$TEST_PATH"` + 2. If file exists, check it contains a relevant test: `grep -c "$SCENARIO_KEYWORD" "$TEST_PATH"` + 3. If file missing or no matching test: flag as INFRA-GAP + +For each Scenario Matrix "Monitored?" entry with a monitoring reference: + 1. Search for dashboard configs, alert rules, or monitoring setup files + 2. If monitoring config missing: flag as INFRA-GAP + +For each Coverage Matrix "Covered By" entry with a file reference: + 1. Verify the referenced file exists and contains relevant implementation + 2. If file missing or no matching implementation: flag as INFRA-GAP + +INFRA-GAP is a distinct severity: the plan CLAIMS coverage but the +infrastructure to deliver that coverage does not exist. This is more +dangerous than a known gap because it creates false confidence. + +Report: "Infrastructure Verification: X/Y claims verified (Z% rate)" +List all INFRA-GAPs with the claim, expected file, and actual status. + +PLAN LINT RULES (automated, run before presenting results): +These are binary pass/fail checks. Any FAIL is a gap. + +Rule text and the applicable rule set live in `docs/planning-techniques/lint-registry.md`. +Read it and apply every rule the registry assigns to Phase 5 in the current audit mode. +This file names ids only — it does not restate what a rule means, so the two cannot +drift apart. Report one PASS/FAIL per id, using the ids exactly as the registry +numbers them. + +Apply at Phase 5: the registry's Phase 5 set. +LINT-14 is skipped on the first audit (no baseline exists to regress from). +LINT-11 and LINT-12 belong to Phase 7 and do not run here. + +(The registry still keys its rule sets by the old phase numbers: "Phase 5" is the +design-gate set applied here; "Phase 7" is the impact-review set applied at the +end of Stage 3 (Build). The registry keys are unchanged so the two files cannot +drift apart.) + +GAP SUMMARY: +After all 4 outputs + lint rules, produce: + +```markdown +## Gap Summary + +Lint: {N}/{applicable} passed, {M} failed <- denominator = the registry's Phase 5 set for this mode +Coverage Matrix: {N} items, {M} gaps +Assumption Register: {N} assumptions, {M} unverified high-impact +Scenario Matrix: 8 scenarios, {M} gaps +Cross-Cutting Sweep: {N} concerns, {M} gaps + +Total gaps: {sum} +Total warnings: {sum} + +Gap-checked: YES / NO +``` + +A plan is gap-checked ONLY when: +- Every rule in the registry's Phase 5 set passes (enumerating a subset here is how + the count drifted to four different values before PH5-001) +- Coverage matrix has zero GAPs +- No unverified HIGH-impact assumptions +- Scenario matrix has zero GAPs +- Cross-cutting sweep has zero GAPs +- Infrastructure verification has zero INFRA-GAPs + +Write docs/plans/{date}-{plan-name}/audit.md with: criterion records (verdict and +evidence per criterion), challenges, verification results, ALL 4 gap verification +outputs, lint results, gap summary. + +Update manifest.md: add audit.md to Plan Files table with date and gate result. + +EVIDENCE REINFORCEMENT (after audit, before baseline): + +Re-read the spec.md Evidence section (written in Part A) and reinforce it with +audit findings: + +1. AUDIT-DRIVEN ADDITIONS: + - If the audit identified new dependencies, patterns, or tools not in the + original Evidence section (e.g., from gap-filling revisions), add entries. + - If the audit challenged an assumption about a tool/method and the + challenge was resolved, add a "Validated by audit" note to that entry. + +2. STRESS-TEST ANNOTATIONS: + For entries where the audit found weakness or gaps, add a subsection: + ```markdown + **Audit note ({date}):** {What the audit found — e.g., "Devil's advocate + challenged whether YamlDotNet handles multi-document streams. Verified: + YamlDotNet 16.x supports multi-doc via `LoadStream()`. No gap."} + ``` + For entries where audit found a real gap, note the gap AND how it was resolved: + ```markdown + **Audit note ({date}):** {Gap found and resolution — e.g., "Audit flagged + missing error handling for malformed YAML. Added try/catch in design gate + revision v2. Gap closed."} + ``` + +3. UPDATE HEADER: + Set "Last reinforced: {date} (design gate)" in the Evidence section header. + +4. NEW CROSS-PLAN REFERENCES: + If the audit revision introduced tools/patterns that exist in other plans, + add "Also referenced in" links. + +Update manifest.md: update the spec.md row with the reinforcement date. + +BASELINE SNAPSHOT: +After writing the audit, capture a per-element baseline in status.json: +```json +{ + "baseline": { + "run_number": 1, + "date": "{ISO date}", + "plan_version": "v1", + "lint_results": { "LINT-01": "pass", "LINT-02": "pass", ... }, + "coverage_items": [{ "name": "...", "status": "covered|gap" }], + "assumption_counts": { "total": N, "verified": N, "unverified": N, "waived": N }, + "scenario_statuses": [{ "id": 1, "name": "Happy path", "status": "covered|partial|gap" }], + "concern_statuses": [{ "name": "API contract", "status": "ok|warn|gap" }], + "infra_gaps": N + } +} +``` + +On re-audit (after revision loop or manual re-run), compare current vs baseline: +- REGRESSION: item was covered/passing, now gap/failing -> flag in audit output +- IMPROVEMENT: item was gap/failing, now covered/passing -> report as progress +- NEW: item not in previous baseline -> report for awareness + +Report: "Baseline comparison: X regressions, Y improvements, Z new items" +Regressions are flagged as HIGH priority in the audit output. + +This comparison is what LINT-14 is evaluated against (see the registry for its text). +Only an element that was covered/passing in the previous baseline and is now +gap/failing counts; pre-existing gaps do not trigger it. Skipped on the first audit, +when no baseline exists. + +Update the baseline in status.json after each comparison (append to history array +for trend tracking). + +GATE: Evaluator-Optimizer Loop. + +RUBRIC-FREE HOLISTIC PASS (advisory, runs alongside the gate): + +RUN one additional judge with no rubric, no criterion list, and no dimension names. + +Its entire prompt is: "Ignore any checklist. What would make this plan fail in +production?" Fresh instance, same input manifest as the auditor, none of the +criterion files. + +Map its findings against the criterion set afterwards. A finding that maps to an +existing criterion is discarded — the gate already covers it. A finding that maps +to NOTHING is appended to docs/planning-techniques/lint-candidates.md with the plan +name and date, as a candidate rule for owner review. + +This pass never gates, and that is deliberate. Every other mechanism in the design +gate makes the judge honest ABOUT the criteria; none of them can notice that the +criteria are incomplete. A plan can satisfy every rule and still be bad in a way no +rule names — rubric-design failure as distinct from verifier failure. This is the +only check on that class, and its output is a proposed rule, not a verdict on the +current plan: gating on unmapped findings would just re-create the unfalsifiable +prose judgment the gate rewrite removed. + +The gate reads whether the claims survived checking. + + +CANARY_OK = the criterion the planted defect violates came back UNMET +EVIDENCE_OK = dg-evidence-validate.js exited 0 (nothing was demoted) +VERIFIED = every applicable criterion is MET or N_A after validation +INFRA_OK = infra_gaps == 0 + +PASS = CANARY_OK AND EVIDENCE_OK AND VERIFIED AND INFRA_OK + + +Every term is re-derivable by someone who has the plan folder and did not run the +audit. That is the property being bought here: a gate that authorised passage on a +number the audited model chose for itself let no reader tell a plan that earned it +from one that was written to earn it. + +There is no weighted sum, so a strong showing on seven criteria cannot offset a +failure on the eighth. Non-compensability is the thing a point total structurally +cannot give you. + +IF PASS: + -> "Design is solid. Ready for human review." + -> Proceed to HUMAN REVIEW GATE below. + +IF NOT PASS: + -> If CANARY_OK is false after a re-run: STOP. Do not revise. The audit could not + see a defect placed for it to find, so its other findings are not a basis for + rewriting anything. + -> Otherwise auto-trigger revision of spec.md, using the feedback form below. + -> Revise ONLY the failing sections (not the entire spec). + -> Re-run the audit on the revised spec. + -> Compare re-audit against baseline: flag any regressions (items that + were passing in v1 but now fail in v2). Regressions indicate the + revision broke something that was previously working. + -> Maximum 2 revision iterations. + + +Send the generator defects and locations. One line per unmet criterion: + + {criterion_id} UNMET: {what is missing}. Location: {file}:{line}. + +Worked example: + + LINT-03 UNMET: Phase 2 database migration has no rollback step. + Location: docs/plans/2026-07-20-plugin-hardening-v5/spec.md:142. + +Never send the rubric, the totals, the bands, or how near the plan came to passing. +The generator cannot see any of that when it writes, and returning it through the +revision channel would hand back exactly what was withheld — after which the cheapest +response is prose shaped like the missing thing rather than the missing thing itself. + +A defect the generator can locate is a defect it can fix. A number it can chase is a +number it will chase. + + +SPAWN A NEW plan-auditor INSTANCE for every audit iteration. Do not re-audit inside +the instance that produced the previous verdict, and do not pass it the previous +audit.md, the previous score, or a summary of either. + +An evaluator that already published a number for v1 is, on v2, checking its own +prior judgement. The consistent story available to it is that the revision fixed +what it said was broken, so the second audit tends to ratify the first rather than +re-derive it — and the loop's regression check is exactly the thing that cannot +work if the same evaluator grades both sides of it. The agent refuses prior-iteration +scores on its side too (see in agents/plan-auditor.md); both +halves are required, because either alone is a single point of failure. + +The baseline comparison above is done by the CALLER, which holds both audits. The +judge sees one spec and reports on it, and never learns that a previous attempt +existed. + +After revision loop completes, report against the gate, not against a band: +- PASS: "Design revised and now solid. Ready for human review." +- NOT PASS, criteria still unmet after 2 iterations: "Design has remaining unmet + criteria. Fix manually: [list each id with its defect and location]" +- NOT PASS because evidence was demoted: "Claims in this spec are not supported by + what they cite: [list each flag]. These are not near-misses; the cited text does + not say what the spec says it says." +- NOT PASS because the canary was missed twice: "The audit could not be trusted and + no revision was attempted. Re-run the design gate before reading any of its findings." + +A plan does not "usably pass with known gaps". Either every applicable criterion is +satisfied and evidenced, or the specific ones that are not get named. A "proceed +with known gaps" rung was the rung most often used to proceed without reading them, +and there is nothing here for it to mean. + +Track revision history in audit.md: +```markdown +## Revision History +| Version | Unmet criteria | Gaps | Action | +|---------|----------------|------|--------| +| v1 | LINT-03, LINT-07, SCN-4 | 7 | Auto-revised Delivery phases 2 and 4, Verification plan | +| v2 | (none) | 0 | Accepted | +``` + +Update status.json (include gate_passed boolean, unmet_criteria list, gap_checked +boolean, gap_count, canary_found), manifest.md. + +HUMAN REVIEW GATE (conditionally waivable): +After the automated design gate completes, prompt for human review before Build: + +"Design gate complete ({N} criteria MET, {M} UNMET, canary {found/missed}). + Before starting Build, this spec should be reviewed by at least one person. + [1] Enter reviewer name(s) to proceed + [2] Waive review (solo mode) — requires documented reason, and only offered + when the waiver condition below holds + [3] View audit summary first" + + +waiver_allowed = (infra_gaps == 0) + AND (canary_found == true) + AND (evidence_demotions == 0) + + +The waiver is offered only when the automated gate itself was trustworthy: the +canary proves the auditor was reading, zero demotions prove its claims survived +mechanical re-checking, and zero infra-gaps prove the coverage it accepted exists. +A gate that missed its canary or had verdicts demoted may still have produced a +correct PASS, but nothing in its output can show that, so a human has to look. The +asymmetry is the design: a doubtful automated result can never open the gate, but +it can remove the owner's ability to SKIP review. + +If the waiver condition fails, option [2] is not offered at all. Do not present it +greyed out with the reason; a visible near-miss invites one more revision aimed at +the waiver rather than at the plan. + +If [1]: Record reviewer name(s) and date in status.json: + { "review": { "reviewers": [{"name": "...", "date": "..."}], "outcome": "accepted" } } + Proceed to EXIT below. + +If [2]: Record waiver in status.json AND stamp it visibly: + { "review": { "waived": true, "reason": "...", "waived_by": "...", + "waiver_condition": { "infra_gaps": 0, "canary_found": true, + "evidence_demotions": 0 } } } + Also append one line to audit.md and to the handoff document produced in a + later stage: + "Review waived (solo mode) by {name} on {date}: {reason}" + A waiver recorded only in machine state is invisible to the person reading the + plan later, which is the person it exists to warn. Proceed to EXIT below. + +If [3]: Show audit-derived review checklist: + - Criterion records (each id with MET / UNMET / N_A and its evidence) + - Top 3 gaps identified + - Top 5 risks identified + - Key assumptions and their verification status + - Cross-cutting concerns flagged as partially addressed + Then re-prompt [1] or [2]. + +If [1] with reviewer names: Record review in status.json: + { "review": { + "reviewers": [{"name": "...", "date": "...", "decision": "accepted"}], + "outcome": "accepted", + "checklist_presented": true, + "comments": 0 + }} + +For team/leadership plans: review is REQUIRED (option [2] not offered unless +the plan was started in solo mode or the user explicitly requests solo mode). + +For solo mode: review is recommended but waivable with documented reason. + +--- + +## EXIT: spec.md Status: Approved + +Three conditions, all required: +1. Design gate PASS (gate_expression above) +2. Human review recorded, or waiver recorded under the waiver condition +3. spec.md header set to Status: Approved, with the reviewer (or waiver holder) + named in the Author line + +Set the header, commit spec.md together with audit.md and the evidence directory. +Update status.json: design -> complete (set completed timestamp) +Update manifest.md progress table. + +-> "Spec approved. Ready to plan the build." +-> Proceed to Stage 3 (Build). diff --git a/plugins/deepgrade/skills/plan/stages/stage-3-build.md b/plugins/deepgrade/skills/plan/stages/stage-3-build.md new file mode 100644 index 0000000..b4819c0 --- /dev/null +++ b/plugins/deepgrade/skills/plan/stages/stage-3-build.md @@ -0,0 +1,434 @@ +# Stage 3: BUILD + +Stage file for /deepgrade:plan. Loaded by SKILL.md on entry; re-read after compaction. Do not read ahead. + +Question: What exactly will change, in what order, and what else does the change affect? +Reads: spec.md (Status: Approved), audit.md, status.json assumptions +Produces: docs/plans/{date}-{plan-name}/plan.md (build plan), changes/CR-{N}.md, impact-review.md, codebase changes on approval +Gate: plan.md approved before any implementation; impact review confirmed by user to close the stage + +## Contents + +- Step 1: Write the build plan (plan.md) and get it approved +- Step 2: Hard gate: assumption verification (LINT-08) +- Step 2: Parallel execution rule, document and codebase actions +- Step 2: Change control and change record template +- Step 3: Impact review (exit check) - dimensions 1-7, parallel subagents, impact-review.md +- Gate + +Do not start this stage unless spec.md Status is Approved. If it is Draft, return +to Stage 2 (Design). + +Update status.json: build -> in_progress (set started timestamp) + +--- + +## Step 1: Write the build plan + +Nothing is implemented without an approved plan.md. The spec says WHAT and WHY; +plan.md says exactly WHICH FILES, in WHAT ORDER, and HOW WE WILL KNOW. It is +written for an engineer (or agent) who never saw this conversation. + +Read spec.md Delivery and Verification plan, then write +docs/plans/{date}-{plan-name}/plan.md: + +```markdown +# {Title} — Build Plan + +- Derived from: spec.md ({commit or path}) +- Status: Draft +- Date: {YYYY-MM-DD} + +## Files that change + +{Files to create and modify. One line each: path, create|modify|delete, which +spec.md ticket authorizes it.} + +## Order of work + +1. {Step with concrete commands where relevant. Each step names its ticket and + the delivery phase it belongs to.} + +## Risks + +{What could go wrong and how we de-risk it; e.g., "the claims-core API +rate-limits at 50 rps; the panel must cache."} + +## Proof + +{The tests that prove the change, and the visual evidence where relevant; e.g., +"test_status.py covers the four claim states; screenshot matches the approved +mock." Test authorship is separate from implementation authorship for +AI-generated code (spec.md Verification plan).} + +## Verification + +{Commands to run and what healthy output looks like; e.g., `make build` ends +with "Build succeeded", `make test` with all green.} + +## Parallelization + +{Which sessions/subagents can work in isolation, and how changes stay +separated. Derive from the ticket dependency graph (Step 2).} + +- Each session/subagent has a functional name, a defined scope, and a visible + report; no silent or unbounded background work. +``` + +DONE WHEN: an engineer who never saw the conversation could implement from +plan.md alone. If a step needs a decision the reader cannot make from plan.md +and spec.md, the step is not written yet. + +REVIEW (user gate). Present plan.md and ask the reviewer three questions: + 1. "What could this break?" + 2. "Which step is riskiest?" + 3. "What was ruled out, and why?" + +Record the answers under ## Risks (questions 1 and 2) and as a "Ruled out" +list under ## Order of work (question 3). Then: + +"Build plan ready. Approve plan.md? [approve / adjust]" + +On "adjust" -> revise and re-ask. +On "approve" -> set plan.md Status: Approved, commit plan.md, +record status.json phases.build.plan_approved = {ISO timestamp}. + +LIVING DOCUMENT RULE: when implementation departs from plan.md, update plan.md +in the SAME commit as the code change. A plan that describes what was intended +rather than what was done is worse than no plan: the impact review (Step 3) and +Stage 4 (Test) read plan.md as the record of what changed. Material departures +also need a Change Record (see change control below); the CR explains why, the +plan.md edit records what. + +--- + +## Step 2: Build + +HARD GATE: ASSUMPTION VERIFICATION (LINT-08) +Before ANY build work begins, check assumptions in status.json: + +``` +For each assumption where impact = HIGH: + If status = unverified: + -> BLOCK entry to build work + -> Present: "Cannot start Build. These HIGH-impact assumptions are unverified:" + -> List each with its verification method + -> Offer: [1] Verify now [2] Accept risk (waiver) [3] Back to research + + If status = verified: -> PASS + If status = waived: -> PASS (with documented risk acceptance) + If status = falsified: -> BLOCK and return to Stage 2 (Design) (approach is invalid) + +For each assumption where impact = MEDIUM and status = unverified: + -> WARN but allow proceeding + +For each assumption where impact = LOW and status = unverified: + -> INFO only +``` + +If user chooses [2] Accept risk (waiver), require: +- Documented risk statement +- Approver name +- Contingency plan if assumption fails +- Update assumption status to "waived" in status.json + +This gate is NOT advisory. It is a hard block. The plan CANNOT proceed to +build work with unverified HIGH-impact assumptions unless explicitly waived. + +This step actively assists with implementation. + +PARALLEL EXECUTION RULE: +Before starting tickets, analyze the dependency graph from the plan: +- Tickets with NO dependencies on other tickets can run IN PARALLEL as subagents +- Tickets that depend on other tickets must wait until dependencies complete +- Group independent tickets into parallel batches + +``` +Example dependency graph: + POS-5160 (no deps) -> Batch 1 (parallel) + POS-5161 (no deps) -> Batch 1 (parallel) + POS-5162 (no deps) -> Batch 1 (parallel) + POS-5163 (needs 5160) -> Batch 2 (after 5160 completes) + POS-5164 (needs 5162) -> Batch 2 (after 5162 completes) + POS-5165 (needs 5163, 5164) -> Batch 3 (after Batch 2) +``` + +Present the batch plan to the user: +"I can run {N} tickets in parallel (Batch 1: {tickets}). +Batch 2 ({tickets}) depends on Batch 1. Execute Batch 1 in parallel? [Y/n]" + +For each parallel batch, deploy subagents: +- Each subagent gets: ticket description, relevant plan sections, codebase context +- Each subagent writes to a separate branch or file set +- Orchestrator tracks progress and resolves conflicts between parallel work + +DOCUMENT ACTIONS (no approval needed): +- Track ticket progress (update status.json with per-ticket notes) +- Answer questions about the plan ("what file for POS-5162?") +- Provide code context from research +- Suggest next ticket to work on based on dependencies + +CODEBASE ACTIONS (approval required per action): +- "Generate code scaffold for CcReceiptStrings.cs? [Y/n]" +- "Run characterization tests on Printing.FormatReceipt? [Y/n]" +- "Create branch description for Phase 1 tickets? [Y/n]" + +CHANGE CONTROL (backward flow rules with immutable records): +After the Stage 2 (Design) scope lock, accepted plan documents are immutable. +Changes require a formal Change Record, not silent edits. + +- Minor discovery during build: + 1. Create docs/plans/{date}-{name}/changes/CR-{N}.md with: + - What changed and why + - Which document/section it supersedes + - The NEW content (the CR is the authoritative version going forward) + - Impact on other phases + 2. Add a status line to the TOP of the original document: "SUPERSEDED by CR-{N} on {date}" + Do NOT modify the original document's content. The CR contains the new version. + 3. Update manifest.md with link to the Change Record + 4. Update status.json: { "change_records": [{ "id": "CR-001", "date": "...", "summary": "..." }] } + +- Scope change discovered -> "This changes the scope. Go back to Design? [Y/n]" + If yes: create CR-{N} documenting the scope change reason, mark design + and build as STALE, return to Stage 2 (Design). Original spec.md preserved. + +- New blocker found -> mark current build ticket as BLOCKED with reason, + create CR-{N} documenting the blocker and its impact. + +- Implementation diverges from plan -> create CR-{N} documenting the divergence + and rationale, and update plan.md in the same commit (living document rule). + This replaces informal ADR/change notes. + +Change Record template: +```markdown +# CR-{N}: {Title} +Date: {date} +Author: {name} +Supersedes: {document or section} + +## What Changed +## Why It Changed +## Impact on Other Phases +``` + +Update status.json with build progress, manifest.md. + +No gate on build work itself. User stays in build until ready for the impact +review, which is the exit check for this stage. + +--- + +## Step 3: Impact review (exit check) + +Question: What else does this change affect across layers? + +This is a cross-cutting verification gate. Code that works locally and passes +targeted tests can still break integration edges, scale behavior, transition-state +UX, and downstream consumers. This step explicitly asks "what did we miss?" + +WHAT IT CHECKS: + +1. INTEGRATION EDGES + - What other modules call the code we changed? + - Did we update all callers, or just the ones we knew about? + - Are there event handlers, webhooks, or async consumers that depend on + the old behavior? + ```bash + # Find all callers of changed functions + grep -rn "{function-name}" --include="*.cs" --include="*.vb" --include="*.ts" \ + . 2>/dev/null | grep -v node_modules | grep -v test + ``` + +2. CROSS-LAYER EFFECTS + - Database: did schema changes affect other queries or stored procedures? + - API: did response format changes break downstream consumers? + - UI: did state changes affect other screens or components? + - Config: did new settings need to be added to all environments? + +3. SCALE AND PERFORMANCE + - Will this change behave differently at production load? + - Did we add queries inside loops? New N+1 patterns? + - Did we add memory-intensive operations without limits? + +4. TRANSITION-STATE BEHAVIOR + - During rollout, old and new code may run simultaneously. + - Feature flags: is the off-state still safe? + - Database migrations: is the schema compatible with both old and new code? + - What happens to in-flight requests during deployment? + +5. TEST DELTA + - What tests existed before vs after? + - Did we add tests for the new behavior? + - Did existing tests need updating and did we miss any? + - Are there integration tests that cover the cross-cutting paths? + +6. STRING PATH REFERENCES (critical for file moves/renames) + If ANY files were moved or renamed during build, scan for stale + string-based path references that don't auto-update. This is a KNOWN gap: + TypeScript/VSCode updates import statements on file move, but does NOT + update string literals. + + Patterns to scan for old file paths: + - vi.mock("old/path") and jest.mock("old/path") + - require("old/path") string arguments + - eslint.config.js ignore arrays + - tsconfig.json paths and includes + - vite.config.ts resolve.alias + - webpack.config.js alias/resolve + - storybook stories globs + - jest.config moduleNameMapper + - package.json scripts that reference file paths + - .env files with path values + - CLAUDE.md or README references to file locations + + ```bash + # For each moved/renamed file, find stale string references + OLD_PATH="{old-file-path-without-extension}" + grep -rn "$OLD_PATH" --include="*.ts" --include="*.tsx" --include="*.js" \ + --include="*.json" --include="*.config.*" --include="*.md" \ + . 2>/dev/null | grep -v node_modules | grep -v ".git/" + ``` + + Any match is a potential stale reference that needs updating. + TypeScript Issue #62835 (open): This is a known gap in all major IDEs. + +7. BACKWARD TRACEABILITY (does every change serve a goal?) + For every file changed during build, verify the reverse coverage chain: + - Changed file -> Ticket that authorized the change -> Goal it serves + + Orphan detection: + - Files changed with no ticket mapping = SCOPE CREEP (flag) + - Tickets with no changed files = DELIVERY GAP (flag unless explicitly deferred) + + ```bash + # For each changed file, check if it maps to a plan ticket + # Compare git diff file list against ticket-file mapping in status.json + git diff --name-only HEAD~{N}..HEAD | while read FILE; do + grep -q "$FILE" docs/plans/{date}-{name}/status.json || echo "ORPHAN: $FILE" + done + ``` + + Also compare the diff against plan.md ## Files that change. A file in the + diff but not in plan.md means plan.md was not kept current (living document + rule); fix plan.md before proceeding. + + Any orphan file must be either: + - Linked to an existing ticket (developer forgot to log it) + - Justified as necessary infrastructure (added to a new ticket) + - Flagged as scope creep for review + + This traceability check is what LINT-11 and LINT-12 are evaluated against; + the registry holds their text and marks both as Phase 7 (its key for the + impact-review set), Full mode only. + +PROCESS: +PARALLELIZATION RULE: The check dimensions are independent. Deploy parallel +subagents for each dimension to speed up the review. + +Deploy up to 3 subagents in parallel (scale to the size of the change): + +SUBAGENT A - Integration & Cross-Layer (Sonnet): +Objective: Find all callers of changed code, check integration edges and cross-layer effects +Tools: Read, Grep, Glob, Bash +Checks: dimensions 1 (Integration Edges) and 2 (Cross-Layer Effects) + +SUBAGENT B - Scale & Transition State (Sonnet): +Objective: Analyze performance impact and transition-state safety +Tools: Read, Grep, Glob +Checks: dimensions 3 (Scale) and 4 (Transition-State) + +SUBAGENT C - Test Delta, String Paths & Backward Trace (Sonnet): +Objective: Compare test coverage before vs after, scan for stale string path references, AND verify backward traceability of all changed files +Tools: Read, Grep, Glob, Bash +Checks: dimensions 5 (Test Delta), 6 (String Path References), and 7 (Backward Traceability) + +Each subagent writes its section to a temp file. Orchestrator synthesizes. + +Steps: +1. Read the changed files from status.json and plan.md ## Files that change +2. Deploy subagents with the list of changed files + relevant audit data +3. Each subagent scans for its dimensions +4. Cross-reference with docs/audit/dependency-map.md (if exists) +5. Cross-reference with docs/audit/integration-scan.md (if exists) +6. Synthesize all subagent findings +7. Flag any untested integration path +8. Present findings as a checklist + +OUTPUT: Written to docs/plans/{date}-{plan-name}/impact-review.md with: + +```markdown +# Impact Review: {Plan Name} +Date: {date} +Changed files: {count} +Integration edges checked: {count} + +## Cross-Cutting Findings + +| # | Finding | Severity | File | Checked? | +|---|---------|----------|------|----------| +| 1 | OrderReceipt.tsx also formats receipt strings | HIGH | src/features/orders/ | [VERIFY] | +| 2 | CCApproval.vb has hardcoded receipt text | MEDIUM | POSetcPOS/CreditCard/ | [VERIFY] | +| 3 | Print preview doesn't use new string table | LOW | POSetcPOS/Printer/ | [VERIFY] | + +## Integration Paths Not Covered by Tests +- [list of caller->callee paths that have no test coverage] + +## Scale Concerns +- [any performance-related observations] + +## Transition-State Risks +- [anything that could break during partial rollout] + +## Checklist Before Test Stage +- [ ] All callers of changed functions verified +- [ ] No untested integration paths remaining (or explicitly accepted) +- [ ] Scale behavior reviewed for production load +- [ ] Feature flag off-state tested +- [ ] Database migration compatible with old and new code +- [ ] No orphan code changes (all changes traced to tickets) [LINT-11] +- [ ] No orphan tickets (all tickets have implementation or are deferred) [LINT-12] +- [ ] plan.md ## Files that change matches the diff (living document rule) + +TESTING METHODOLOGY VERIFICATION: +For each deliverable with an assigned testing methodology (from spec.md Verification plan): +- [ ] Methodology is appropriate for the type of change (not defaulting to "unit tests") +- [ ] Test authorship is separate from implementation authorship for AI-generated code +- [ ] Database changes use Expand/Contract with forward AND backward migration scripts +- [ ] API changes have contract tests covering old code + new schema AND new code + old schema +- [ ] Characterization tests captured BEFORE refactoring (not after) +- [ ] AI Failure Mode Checklist applied to all AI-generated deliverables + +Database Migration Testing (if applicable): + +| Phase | What to Test | Method | +|-------|-------------|--------| +| Expand | New columns/tables exist, old untouched | Structural assertions | +| Migrate | Row counts, checksums, referential integrity preserved | Characterization + Shadow | +| Contract | Old structures removed, no orphan refs, all code uses new schema | Structural assertions | +| Rollback | Backward migration restores original state | Apply -> verify -> rollback -> verify | +| Backward compat | Old code + new schema works, new code + old schema works | Contract Testing | +| Performance | Queries under threshold, indexes present, no N+1 | Property-Based + Profiling | +``` + +--- + +## Gate + +GATE: User confirmation required. +"Impact review complete. {N} cross-cutting findings, {M} untested integration +paths. Review the findings and confirm before proceeding to Test." + +If HIGH severity findings exist: +"HIGH severity: {finding}. This should be addressed before Stage 4 (Test). +Fix it now, or accept the risk and proceed? [fix / accept with reason]" + +On "fix": return to Step 2, make the change (update plan.md in the same commit), +re-run the affected impact-review dimension. +On "accept with reason": record the accepted finding and reason in +impact-review.md and status.json. + +On confirm: +Commit impact-review.md and plan.md together. +Update status.json: build -> complete (set completed timestamp) +Update manifest.md progress table. +-> Proceed to Stage 4 (Test). diff --git a/plugins/deepgrade/skills/plan/phases/phase-8-test.md b/plugins/deepgrade/skills/plan/stages/stage-4-test.md similarity index 81% rename from plugins/deepgrade/skills/plan/phases/phase-8-test.md rename to plugins/deepgrade/skills/plan/stages/stage-4-test.md index fe67d6c..d4ae24a 100644 --- a/plugins/deepgrade/skills/plan/phases/phase-8-test.md +++ b/plugins/deepgrade/skills/plan/stages/stage-4-test.md @@ -1,6 +1,11 @@ -# Phase 8: TEST +# Stage 4: TEST -Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when the workflow enters this phase. Do not read ahead to other phase files. +Stage file for /deepgrade:plan. Loaded by SKILL.md on entry; re-read after compaction. Do not read ahead. + +Question: Does it work safely? +Reads: spec.md (## Verification plan), plan.md (## Proof, ## Verification), audit.md, impact-review.md, status.json +Produces: docs/plans/{date}-{plan-name}/test-plan.md, status.json test_gate, manifest.md update +Gate: Hard readiness gate (all Tier 1 automated checks pass AND all Tier 2 manual checks confirmed by a human) ## Contents @@ -10,8 +15,6 @@ Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when - Two-tier verification - Hard readiness gate -Question: Does it work safely? - DOCUMENT ACTIONS (automatic): Write docs/plans/{date}-{plan-name}/test-plan.md with: - Per-phase test matrix (test name, type, what it verifies) @@ -20,9 +23,9 @@ Write docs/plans/{date}-{plan-name}/test-plan.md with: - Each criterion categorized as AUTOMATED or MANUAL (see below) METHODOLOGY-SPECIFIC TEST PROCEDURES: -Based on the testing methodology assigned in Phase 4, execute the appropriate -test procedure for each deliverable. Reference the full framework at -docs/planning-techniques/10-testing-methodology-selection.md. +Based on the testing methodology assigned in Stage 2 (spec.md ## Verification plan), +execute the appropriate test procedure for each deliverable. Reference the full +framework at docs/planning-techniques/10-testing-methodology-selection.md. IF methodology = expand_contract: Execute all 18 steps of the database migration test checklist: @@ -105,12 +108,13 @@ TIER 1 — AUTOMATED VERIFICATION (run without human intervention): - [ ] TypeScript/code compiles with no errors (run build command) - [ ] No lint errors in changed files - [ ] Characterization baseline captured for any refactored code -- [ ] Audit score is GREEN with gap-checked = YES, or YELLOW with gap-checked = YES +- [ ] Design gate passed (audit.md records PASS) and plan.md Status is Approved +- [ ] Verification commands from plan.md ## Verification run and produce their healthy output Run all Tier 1 checks. Report results. Then PAUSE: ``` -Phase 8 — Automated Verification Complete +Stage 4 — Automated Verification Complete Automated checks passed: - [list each Tier 1 check and its result] @@ -119,7 +123,7 @@ Ready for manual verification. Please perform these checks: - [ ] [Manual item 1] - [ ] [Manual item 2] -Let me know when manual testing is complete so I can proceed to Handoff. +Let me know when manual testing is complete so I can proceed to Deploy. ``` TIER 2 — MANUAL VERIFICATION (requires human testing): @@ -134,11 +138,11 @@ Track which items the human confirmed and when: { "test_gate": { "automated": { "passed": 5, "failed": 0 }, "manual": { "verified": 4, "pending": 1, "verified_by": "J. Smith", "date": "..." } } } HARD READINESS GATE: -Before proceeding to Handoff, ALL of these must be true: +Before proceeding to Deploy, ALL of these must be true: - All Tier 1 (automated) checks pass - All Tier 2 (manual) checks confirmed by a human - No Tier 2 items left in "pending" state -If gate fails, report what's missing and stay in Test phase. +If gate fails, report what's missing and stay in Stage 4. -Update status.json, manifest.md. +Update status.json (phases.test.status -> complete, completed -> ISO timestamp), manifest.md. diff --git a/plugins/deepgrade/skills/plan/stages/stage-5-deploy.md b/plugins/deepgrade/skills/plan/stages/stage-5-deploy.md new file mode 100644 index 0000000..1000f34 --- /dev/null +++ b/plugins/deepgrade/skills/plan/stages/stage-5-deploy.md @@ -0,0 +1,152 @@ +# Stage 5: DEPLOY + +Stage file for /deepgrade:plan. Loaded by SKILL.md on entry; re-read after compaction. Do not read ahead. + +Question: Is this the change the plan intended, and who authorizes its release? +Reads: intent.md (## Constraints), plan.md (## Files that change, ## Verification), test-plan.md, status.json, `git diff --name-only {base}..HEAD` +Produces: docs/plans/{date}-{plan-name}/review.md, plan.md ## Departures from plan, status.json phases.deploy, manifest.md final status +Gate: Named human release authorization. The skill never runs a deploy command. + +## Contents + +- Readiness check +- Step A: Diff-versus-plan check (fresh subagent) +- Step B: review.md +- Step C: Release authorization (hard rule) +- Step D: Final summary + +READINESS CHECK before entering this stage: +- Test stage complete (status.json phases.test.status = complete, test_gate has no pending manual items) +- No BLOCKED tickets remaining (or explicitly deferred, with the deferral recorded in plan.md) +- Rollback plan documented (spec.md ## Delivery or plan.md ## Risks) + +If any item fails, report what is missing and stay in Stage 4. + +## Step A: Diff-versus-plan check + +This is the drift control. It is run by a FRESH subagent (not the agent that +did the Build) so the comparison is not biased by memory of why files changed. + +Subagent brief: +``` +Objective: Compare what changed against what was planned. Report, do not judge. +Tools: Read, Grep, Bash +Inputs: + - docs/plans/{date}-{plan-name}/plan.md (## Files that change) + - docs/plans/{date}-{plan-name}/intent.md (## Constraints) + - git diff --name-only {base}..HEAD ({base} = branch point recorded in status.json phases.build.base, else merge-base with main) +Output: write to docs/plans/{date}-{plan-name}/.deploy-diff-check.md + +1. FILE DELTA + - UNPLANNED: every file in the diff that is not listed in plan.md ## Files that change + - UNTOUCHED: every file listed in plan.md ## Files that change that is not in the diff + - MATCHED: count of files in both + Match on path; treat a planned glob or directory as matching any file under it. + +2. CONSTRAINT CHECK + For each bullet in intent.md ## Constraints, inspect the diff for auth, data scope, + and external dependencies: + - auth: new or changed auth checks, roles, tokens, public endpoints + - data scope: new tables/columns/queries, widened selects, PII handling, retention + - external dependencies: new packages, new network calls, new services, version bumps + List every constraint the diff APPEARS to violate, with file:line evidence. + "Appears" is deliberate: the human decides; you supply evidence. +``` + +When the subagent returns: +- A non-empty delta is NOT automatically a rejection. It MUST be acknowledged: + append a `## Departures from plan` section to plan.md listing every UNPLANNED + and UNTOUCHED file with a one-line reason each (or "unexplained" if the + reason is not known; an unexplained departure is a Finding in Step B). +- The `## Departures from plan` append lands in the SAME commit as the release + candidate, before any release. Drift that is not written down is drift that + did not get reviewed. +- Delete .deploy-diff-check.md after its content is folded into review.md. + +## Step B: review.md + +Write docs/plans/{date}-{plan-name}/review.md using `${CLAUDE_SKILL_DIR}/templates/review.md`. +Evidence before opinions. Sections, in order: + +1. Summary — what is being released, in three sentences or fewer. +2. Diff-versus-plan — MATCHED / UNPLANNED / UNTOUCHED lists from Step A, and a + pointer to plan.md ## Departures from plan. +3. Constraint check — each intent.md constraint with VERIFIED / APPEARS VIOLATED / + NOT APPLICABLE and the evidence from Step A. +4. Findings — each cites file:line and the evidence. Order by severity: + Important (would break behavior, leak data, or breach a policy) first, then + nits. At most 5 nit-level comments; summarize the rest as a count. + Do not report generated files or anything CI already enforces. +5. Release checklist — + - Deployment sequence with a verification step after each step (what to run, + what healthy output looks like; reuse plan.md ## Verification) + - Rollback trigger (the observable condition that means "roll back now") + and rollback steps + - Monitoring to watch, for how long, and the threshold that trips rollback + - Owner of the release window +6. Release authorization — name, date, decision (Authorized | Rejected | Deferred). + Leave blank until Step C. + +Update manifest.md (review.md row) and status.json documents. + +## Step C: Release authorization (HARD RULE) + +The agent never crosses the production gate. It prepares everything, then STOPS. + +- No deploy, publish, release, tag-push, merge-to-production, or migration + command is run by this skill, in any approval tier, even if the user says + "just do it" in passing. A deliberate release is a human action. +- Present review.md and ask a NAMED human for authorization: + +``` +Stage 5 — Ready for release authorization + +review.md: docs/plans/{date}-{plan-name}/review.md +Plan match: {N} of {M} planned files changed, {K} unplanned +Constraint check: {count} verified, {count} appear violated +Findings: {important} important, {nits} nits + +Two questions for the reviewer: + 1. Is this the change the plan intended? + 2. Is the risk acceptable? + +Who is authorizing this release, and what is the decision? (name, Authorized | Rejected | Deferred) +``` + +- Record the answer in review.md ## Release authorization and in + status.json phases.deploy.authorized_by (name), authorized_at (ISO), decision. +- Rejected or Deferred: stay in Stage 5; list what must change; do not re-ask + until it has. +- Authorized: the human performs the release using the review.md checklist. + The skill may run the VERIFICATION steps from the checklist after the human + confirms each deployment step is done; it never runs the deployment steps. + +## Step D: Final summary + +After authorization is recorded, update manifest.md with final status, decisions +made, and lessons learned. Update status.json: phases.deploy.status -> complete, +completed -> ISO timestamp. Then present: + +``` +Plan: {name} - Released + +Stages: 5/6 (Maintain is the steady state) +Duration: {phases.plan.started} to {phases.deploy.completed} +Plan match: {N} of {M} planned files changed, {K} unplanned +Intent -> spec: {phases.design.started - phases.plan.started} +Spec -> plan: {phases.build.started - phases.design.started} +Plan -> release: {phases.deploy.completed - phases.build.started} +Tickets: {done}/{total} +Authorized by: {name}, {date} + +Key decisions: [from spec.md ## Gotchas and change records] +Change records: {count} (see changes/ folder) +Departures from plan: {count} (see plan.md) +What shipped: [summary] +What's deferred: [if anything] +``` + +Elapsed values are computed from status.json ISO timestamps; print "n/a" for +any stage missing a timestamp rather than guessing. + +Proceed to Stage 6. diff --git a/plugins/deepgrade/skills/plan/stages/stage-6-maintain.md b/plugins/deepgrade/skills/plan/stages/stage-6-maintain.md new file mode 100644 index 0000000..c607978 --- /dev/null +++ b/plugins/deepgrade/skills/plan/stages/stage-6-maintain.md @@ -0,0 +1,79 @@ +# Stage 6: MAINTAIN + +Stage file for /deepgrade:plan. Loaded by SKILL.md on entry; re-read after compaction. Do not read ahead. + +Question: What did production teach us, and does any of it need a new plan? +Reads: docs/plans/{date}-{plan-name}/ (the record), troubleshooting/ logs, docs/troubleshooting/knowledge-base.md +Produces: status.json phases.maintain metrics; new intent.md files under docs/plans/ when the trigger rule fires +Gate: None. This stage never completes; it is the steady state. + +Purpose: close the loop. Everything learned after release flows back to Stage 1 +as a new intent, through the same acceptance gate as the original. + +## 1. The record + +After release the plan folder is the record of what was intended, specified, +planned, built, tested, and authorized. Nothing in it is rewritten after +Stage 5; new facts go in new files. + +Incidents against this release are handled by `/deepgrade:troubleshoot` with +`--plan {plan-name}`, which writes its log under the plan's troubleshooting/ +folder and links it from manifest.md. This stage reads those logs; it does +not investigate. + +## 2. Trigger rule + +When troubleshoot logs an incident against this plan that is EITHER +- severity SEV1 or SEV2, OR +- a recurrence of a known pattern (knowledge-base Recurrence count >= 2, or a + RECURRENCE ALERT / Guardrail pattern message for this plan's code paths), + +propose a new intent. Write docs/plans/{date}-{new-name}/intent.md from +`${CLAUDE_SKILL_DIR}/templates/intent.md`, pre-filled from the incident: + +| intent.md field | Filled from | +|---|---| +| Problem | Root Cause plus impact (what users saw, blast radius) | +| Proposed outcome | The fix or guard recommended by the log (Recommended Actions, Prevention) | +| Affected users and systems | Incident scope: Service/Module, Code Path, Affected users | +| Constraints | What must not change (the released behavior that is working, data compatibility, existing guardrails) | +| Out of scope | Containment already applied; anything the log rules out | +| Open questions | Every unverified hypothesis and every "unverified" claim in the log | +| Status | Draft | +| Source | incident {path to troubleshooting log} | +| Date | today | + +Then stop. The new intent re-enters Stage 1 for a human to accept or reject. +It is NEVER auto-accepted, and this stage never edits code. Say: + +``` +Stage 6 — Incident {log path} met the trigger rule ({SEV1|SEV2|recurrence}). +Proposed intent: docs/plans/{date}-{new-name}/intent.md (Status: Draft) +Review it with: /deepgrade:plan {new-name} +``` + +Incidents below the trigger (SEV3/SEV4, first occurrence) are linked and +counted only. + +## 3. Metrics + +Record in status.json phases.maintain, updated on every linked incident: + +```json +"maintain": { + "status": "steady_state", + "started": "{ISO, set when deploy completed}", + "incidents_linked": 0, + "intents_proposed": [], + "repeat_incidents_same_class": 0 +} +``` + +intents_proposed entries are {intent path, source log, date}. A repeat is an +incident sharing a knowledge-base category or guardrail token with an earlier +incident on this plan. + +## 4. Steady state + +There is no "completed" timestamp for this stage. `/deepgrade:plan-status` +reports it as Maintain with the metrics above; "done" is observed, not declared. diff --git a/plugins/deepgrade/skills/plan/templates/intent.md b/plugins/deepgrade/skills/plan/templates/intent.md new file mode 100644 index 0000000..640a1b6 --- /dev/null +++ b/plugins/deepgrade/skills/plan/templates/intent.md @@ -0,0 +1,43 @@ +# + +- Author: <name> +- Source: <team, channel, ticket, or "incident <troubleshooting log path>"> +- Status: Draft | Accepted | Rejected +- Date: <YYYY-MM-DD> +- Accepted by: <name and date, blank until Accepted> + +## Problem + +<In your own words: what cannot be done today, and why it matters. For an +incident-sourced intent: the root cause and its impact.> + +## Proposed outcome + +<What should be true when this is done? Make it observable and measurable +where possible.> + +## Affected users and systems + +<Who is affected, which systems are touched, who owns the decision.> + +## Constraints + +<Time, budget, compliance, brand, security, compatibility, non-negotiables. +List auth, data scope, and external dependency limits explicitly; Stage 5 +checks the diff against each one.> + +## Out of scope + +<What this intent explicitly does not cover.> + +## Open questions + +<Questions that must be answered before or during design. Unverified +hypotheses belong here, not in Problem.> + +--- + +> Format note: keep this file human-readable (the product owner reviews and +> accepts it) and machine-actionable (the agent reads it and produces spec.md +> from it). Fields are structured on purpose; keep each section short and +> concrete. diff --git a/plugins/deepgrade/skills/plan/templates/plan.md b/plugins/deepgrade/skills/plan/templates/plan.md new file mode 100644 index 0000000..48a9096 --- /dev/null +++ b/plugins/deepgrade/skills/plan/templates/plan.md @@ -0,0 +1,45 @@ +# <Title> — Build Plan + +- Derived from: spec.md <commit or path> +- Status: Draft | Approved +- Date: <YYYY-MM-DD> + +## Files that change + +<Files to create and modify, one per line with a one-phrase reason. Stage 5 +compares the git diff against this list; a directory or glob matches any file +under it.> + +## Order of work + +1. <Step with concrete commands where relevant, and the ticket it delivers> + +## Risks + +<What could go wrong and how we de-risk it; e.g., "the claims-core API +rate-limits at 50 rps; the panel must cache."> + +## Proof + +<The tests that prove the change, and the visual evidence where relevant; +e.g., "test_status.py covers the four claim states; screenshot matches the +approved mock."> + +## Verification + +<Commands to run and what healthy output looks like; e.g., `make build` ends +with "Build succeeded", `make test` with all green. Stage 4 runs these as a +Tier 1 check.> + +## Parallelization + +<Which sessions/subagents can work in isolation, and how changes stay +separated.> + +- Each session/subagent has a functional name, a defined scope, and a visible + report; no silent or unbounded background work. + +## Departures from plan + +<Empty until Stage 5. Filled by the diff-versus-plan check: every unplanned +file and every planned-but-untouched file, with a one-line reason each.> diff --git a/plugins/deepgrade/skills/plan/templates/review.md b/plugins/deepgrade/skills/plan/templates/review.md new file mode 100644 index 0000000..10c2f71 --- /dev/null +++ b/plugins/deepgrade/skills/plan/templates/review.md @@ -0,0 +1,48 @@ +# <Title> — Release Review + +- Plan: docs/plans/<date>-<name>/ +- Base: <commit or branch the diff was taken against> +- Date: <YYYY-MM-DD> + +## Summary + +<What is being released, in three sentences or fewer.> + +## Diff-versus-plan + +- Matched: <N> of <M> planned files changed +- Unplanned: <list of files in the diff not in plan.md ## Files that change> +- Untouched: <list of planned files not in the diff> +- Departures acknowledged in plan.md ## Departures from plan: Yes | No + +## Constraint check + +| Constraint (intent.md) | Result | Evidence | +|---|---|---| +| <constraint> | VERIFIED / APPEARS VIOLATED / NOT APPLICABLE | <file:line> | + +## Findings + +<Ordered by severity. Important = would break behavior, leak data, or breach +a policy. At most 5 nits; summarize the rest as a count.> + +1. [Important | Nit] <file:line> — <finding>. Evidence: <what was observed>. + +Nits not listed: <count> + +## Release checklist + +- Deployment sequence: + 1. <step> — verify: <command, healthy output> +- Rollback trigger: <observable condition> +- Rollback steps: + 1. <step> +- Monitoring: <what to watch, for how long, threshold that trips rollback> +- Owner: <name> + +## Release authorization + +- Name: <human who authorized> +- Date: <YYYY-MM-DD> +- Decision: Authorized | Rejected | Deferred +- Notes: <conditions, or reason for rejection/deferral> diff --git a/plugins/deepgrade/skills/plan/templates/spec.md b/plugins/deepgrade/skills/plan/templates/spec.md new file mode 100644 index 0000000..56c951e --- /dev/null +++ b/plugins/deepgrade/skills/plan/templates/spec.md @@ -0,0 +1,54 @@ +# <Title> — Specification + +- Derived from: intent.md <commit or path> +- Author: <agent + human reviewer> +- Status: Draft | Approved +- Date: <YYYY-MM-DD> + +## Requirements + +### Functional + +<What the system must do.> + +### Non-functional + +<Performance, security, accessibility, compliance, operability.> + +## Design + +<Approach and rationale; architecture or data flow; interfaces (APIs, data, UI).> + +## Standards applied + +<Which org standards (brand, security, UX, compliance) were applied, and how.> + +## Gotchas + +<Conflict points, risky decisions, trade-offs, and what to watch.> + +## Evidence + +<The confidence brief lives here. Max 10 entries. Each entry: what it is / +who uses it at scale / why it works / reference / connection to this plan / +impact tier (High | Medium | Low) with rationale.> + +1. <Name> — what: <> / who uses it: <> / why it works: <> / reference: <> / + connection: <> / impact: <tier, rationale> + +## Open questions + +<Answered or deferred, with owners and due dates.> + +## Verification plan + +<Testing methodology (tdd | characterization | expand_contract | contract_testing | +shadow_parallel | property_based | bdd | snapshot_approval | mutation_testing) per +deliverable, and how this will be tested at build time and in Stage 4.> + +## Delivery + +- Tickets: <ID, title, deliverable, depends on> +- Timeline: <phases with dates or effort> +- Rollback per phase: <trigger and steps for each phase> +- Go/no-go: <criteria a human checks before each phase proceeds> diff --git a/plugins/deepgrade/skills/troubleshoot/phases/step-5-knowledge-base.md b/plugins/deepgrade/skills/troubleshoot/phases/step-5-knowledge-base.md index 083170f..1d655c8 100644 --- a/plugins/deepgrade/skills/troubleshoot/phases/step-5-knowledge-base.md +++ b/plugins/deepgrade/skills/troubleshoot/phases/step-5-knowledge-base.md @@ -192,3 +192,22 @@ same service/module AND same error signature ARE recurrence. If the issue reveals something the Impact Review missed: "This wasn't caught by the Impact Review. Consider adding '{check}' to future reviews for changes in this area." + +### Close the Loop: Propose a New Intent (Stage 6 of /deepgrade:plan) + +The playbook's Maintain stage feeds incidents back into planning as intent, never +as a silent patch. When BOTH hold: (a) the incident is linked to a plan +(`--plan {name}` or detected via plan_detection) and (b) severity is SEV1 or SEV2, +OR the recurrence count for this pattern reached 3+: + +1. Read `${CLAUDE_PLUGIN_ROOT}/skills/plan/templates/intent.md`. +2. Write `docs/plans/{today}-{issue-slug}/intent.md` pre-filled from this log: + Problem = root cause and impact; Proposed outcome = the fix or the guardrail + that prevents the class; Affected users and systems = the incident scope; + Constraints = what must not change; Open questions = every hypothesis that + was not verified; header `Status: Draft`, `Source: incident {log path}`. +3. Append to the originating plan's status.json `phases.maintain`: + `incidents_linked`, `intents_proposed` (path), `repeat_incidents`. +4. Tell the user: "Proposed a new intent at {path}. It re-enters Stage 1 of + /deepgrade:plan for acceptance; nothing is accepted automatically." + diff --git a/tests/layer1-core.sh b/tests/layer1-core.sh index cba5ec5..0248c18 100644 --- a/tests/layer1-core.sh +++ b/tests/layer1-core.sh @@ -1258,7 +1258,7 @@ else # followed by the path — keeps this structural. A script named only in a sentence # is still an orphan, which is the correct answer. inv_re='node[^`]*scripts/[A-Za-z0-9._-]+\.js' - inv=$(grep -ohE "$inv_re" commands/*.md agents/*.md skills/*/*.md skills/*/phases/*.md 2>/dev/null | sed 's|.*/||' | sort -u) + inv=$(grep -ohE "$inv_re" commands/*.md agents/*.md skills/*/*.md skills/*/phases/*.md skills/*/stages/*.md 2>/dev/null | sed 's|.*/||' | sort -u) inv_count=$(echo "$inv" | grep -c . || true) # Self-tests. The known-positive is the QUOTED form, copied from how the plugin @@ -1598,7 +1598,7 @@ for d in "$SKILLS_DIR"/*/; do # An explicit ${CLAUDE_PLUGIN_ROOT}/skills/<name>/ path is accepted too: it is a real, # unambiguous reference, and rejecting it was over-strict (Codex Q3). if ! grep -rhE "$OWN_NS:$sk([^A-Za-z0-9_-]|\$)|skills/$sk/SKILL\.md" \ - "$AGENTS_DIR" "$COMMANDS_DIR" "$SKILLS_DIR"/*/SKILL.md "$SKILLS_DIR"/*/phases/*.md 2>/dev/null \ + "$AGENTS_DIR" "$COMMANDS_DIR" "$SKILLS_DIR"/*/SKILL.md "$SKILLS_DIR"/*/phases/*.md "$SKILLS_DIR"/*/stages/*.md 2>/dev/null \ --exclude-dir="$sk" \ | grep -viE '(never|do not|don'"'"'t|no longer|deprecated|avoid)[^.]{0,60}('"$sk"')' \ | grep -q .; then diff --git a/tests/layer1-repo.sh b/tests/layer1-repo.sh index e15a101..86dc87f 100644 --- a/tests/layer1-repo.sh +++ b/tests/layer1-repo.sh @@ -305,10 +305,10 @@ fi # --- A1a: machine-read files carry ids, never rule text ------------------- # commands/ and agents/ are loaded into agent context. Text that drifts here is # text a judge actually applies, so nothing may follow a LINT id but the id. -git ls-files -z 'plugins/*/commands/*.md' 'plugins/*/agents/*.md' 'plugins/*/skills/plan/*.md' 'plugins/*/skills/plan/phases/*.md' 2>/dev/null | lint_extract | sort -u > "$lint_hits" +git ls-files -z 'plugins/*/commands/*.md' 'plugins/*/agents/*.md' 'plugins/*/skills/plan/*.md' 'plugins/*/skills/plan/stages/*.md' 2>/dev/null | lint_extract | sort -u > "$lint_hits" -for must in plugins/deepgrade/skills/plan/phases/phase-5-audit.md plugins/deepgrade/agents/plan-auditor.md; do - git ls-files -z 'plugins/*/commands/*.md' 'plugins/*/agents/*.md' 'plugins/*/skills/plan/*.md' 'plugins/*/skills/plan/phases/*.md' 2>/dev/null | tr '\0' '\n' | grep -qxF "$must" \ +for must in plugins/deepgrade/skills/plan/stages/stage-2-design.md plugins/deepgrade/agents/plan-auditor.md; do + git ls-files -z 'plugins/*/commands/*.md' 'plugins/*/agents/*.md' 'plugins/*/skills/plan/*.md' 'plugins/*/skills/plan/stages/*.md' 2>/dev/null | tr '\0' '\n' | grep -qxF "$must" \ || { fail "PH5-001a: $must is not in the machine-read set — the derivation is wrong, not the repo clean"; lint_bad=1; } done @@ -358,7 +358,7 @@ rm -f "$lint_hits" "$lint_reg" "$lint_hf" "$lint_drift" # PH5-002 / acceptance row A1: rule COUNTS live only in the registry. # # Rule text was not the only thing that drifted. Four different Phase 5 counts were -# in print at once — 14 in plugins/deepgrade/skills/plan/phases/phase-5-audit.md, 14 and 15 in plugins/deepgrade/agents/plan-auditor.md, +# in print at once — 14 in plugins/deepgrade/skills/plan/stages/stage-2-design.md, 14 and 15 in plugins/deepgrade/agents/plan-auditor.md, # 16 in the registry, 15 in METHODOLOGY.md — plus a fifth ("13 in Lite mode") in the # same METHODOLOGY sentence. A count is a claim about the rule SET, so it belongs # where the set is defined. @@ -472,7 +472,7 @@ done # =========================================================================== # PH5-010 / acceptance row A3: audit criteria are not in the generator's reach. # -# plugins/deepgrade/skills/plan/phases/phase-5-audit.md is what the Phase 4 generator reads. It carried a full copy of +# plugins/deepgrade/skills/plan/stages/stage-2-design.md is what the Phase 4 generator reads. It carried a full copy of # the scoring rubric and the gap matrices — the 1-5 anchors, the Scenario Matrix with # its eight scenarios named, the Cross-Cutting Sweep with its concerns named. A # generator holding that list writes sections matching the list, which is compliance @@ -503,7 +503,7 @@ if printf '%s\n' 'Set iterations = 2 when the loop re-runs.' | grep -qE "$anchor fi # --- generator side: the criteria must be absent ------------------------- -GENERATOR_FILES="plugins/deepgrade/skills/plan/SKILL.md plugins/deepgrade/skills/plan/phases/*.md plugins/deepgrade/commands/quick-plan.md plugins/deepgrade/agents/plan-scaffolder.md" +GENERATOR_FILES="plugins/deepgrade/skills/plan/SKILL.md plugins/deepgrade/skills/plan/stages/*.md plugins/deepgrade/commands/quick-plan.md plugins/deepgrade/agents/plan-scaffolder.md" for gf in $GENERATOR_FILES; do [ -f "$gf" ] || { fail "PH5-010: generator file $gf not found — the subject set is wrong, not the repo clean"; crit_bad=1; continue; } for probe in "$anchor_re:scoring anchor" "$scen_re:Scenario Matrix criteria" "$conc_re:Cross-Cutting criteria"; do @@ -518,10 +518,13 @@ done # --- judge side: the criteria must still exist --------------------------- # Without this the guard would go green on a repo that had simply lost its rubric. -ja=$(grep -cE '^[[:space:]]*[1-5]/5:' plugins/deepgrade/agents/plan-auditor.md || true) -if [ "${ja:-0}" -lt 5 ]; then +# 8.0.0: the 1-5 anchors are gone with the score. The judge-side floor is now the +# eight review dimensions themselves (numbered H2 headings with their question +# lists), which is where the criteria moved to. +ja=$(grep -cE '^## [1-8]\. ' plugins/deepgrade/agents/plan-auditor.md || true) +if [ "${ja:-0}" -lt 8 ]; then crit_bad=1 - fail "PH5-010: plugins/deepgrade/agents/plan-auditor.md holds only ${ja:-0} per-level scoring anchors — the criteria were deleted, not moved" + fail "PH5-010: plugins/deepgrade/agents/plan-auditor.md holds only ${ja:-0} of 8 review dimensions — the criteria were deleted, not moved" fi for probe in "$scen_re:Scenario Matrix" "$conc_re:Cross-Cutting Sweep"; do re="${probe%:*}"; what="${probe##*:}" @@ -531,7 +534,7 @@ for probe in "$scen_re:Scenario Matrix" "$conc_re:Cross-Cutting Sweep"; do fi done -[ "$crit_bad" -eq 0 ] && pass "PH5-010: audit criteria absent from the generator set, present in the judge set ($ja anchors + both matrices)" +[ "$crit_bad" -eq 0 ] && pass "PH5-010: audit criteria absent from the generator set, present in the judge set ($ja dimensions + both matrices)" # =========================================================================== # PH5-011 / acceptance row A4: the judge's forbidden inputs are enumerated. @@ -594,7 +597,7 @@ fi # a sentence-initial imperative for the same negation-proofing reason as PH5-011. # =========================================================================== iso_bad=0 -ISO_FILE="plugins/deepgrade/skills/plan/phases/phase-5-audit.md" +ISO_FILE="plugins/deepgrade/skills/plan/stages/stage-2-design.md" iso_re='^SPAWN A NEW plan-auditor INSTANCE' if ! printf '%s\n' 'SPAWN A NEW plan-auditor INSTANCE for every audit iteration.' | grep -qE "$iso_re"; then @@ -709,8 +712,8 @@ if ! grep -qxF "$PH5_021_LINE" plugins/deepgrade/agents/plan-auditor.md; then fail "PH5-021: plugins/deepgrade/agents/plan-auditor.md does not require emitting evidence records — the validator has no input, so the gate cannot open" emit_bad=1 fi -if ! grep -qxF "$PH5_022_LINE" plugins/deepgrade/skills/plan/phases/phase-5-audit.md; then - fail "PH5-022: plugins/deepgrade/skills/plan/phases/phase-5-audit.md does not require committing the evidence directory — evidence that is not committed cannot be re-checked later" +if ! grep -qxF "$PH5_022_LINE" plugins/deepgrade/skills/plan/stages/stage-2-design.md; then + fail "PH5-022: plugins/deepgrade/skills/plan/stages/stage-2-design.md does not require committing the evidence directory — evidence that is not committed cannot be re-checked later" emit_bad=1 fi @@ -733,10 +736,10 @@ fi # =========================================================================== gate_bad=0 GATE_LINE='PASS = CANARY_OK AND EVIDENCE_OK AND VERIFIED AND INFRA_OK' -gate_block=$(sed -n '/^<gate_expression>$/,/^<\/gate_expression>$/p' plugins/deepgrade/skills/plan/phases/phase-5-audit.md 2>/dev/null) +gate_block=$(sed -n '/^<gate_expression>$/,/^<\/gate_expression>$/p' plugins/deepgrade/skills/plan/stages/stage-2-design.md 2>/dev/null) if [ -z "$gate_block" ]; then - fail "PH5-041: plugins/deepgrade/skills/plan/phases/phase-5-audit.md has no delimited <gate_expression> block" + fail "PH5-041: plugins/deepgrade/skills/plan/stages/stage-2-design.md has no delimited <gate_expression> block" gate_bad=1 else printf '%s\n' "$gate_block" | grep -qxF "$GATE_LINE" \ @@ -753,10 +756,10 @@ else fi # The superseded form must be gone, not merely superseded by a newer block below it. -if grep -qE '^IF score (>=|<) [0-9]+' plugins/deepgrade/skills/plan/phases/phase-5-audit.md; then +if grep -qE '^IF score (>=|<) [0-9]+' plugins/deepgrade/skills/plan/stages/stage-2-design.md; then gate_bad=1 - fail "PH5-041: the score-based gate branch is still present in plugins/deepgrade/skills/plan/phases/phase-5-audit.md" - grep -nE '^IF score (>=|<) [0-9]+' plugins/deepgrade/skills/plan/phases/phase-5-audit.md | sed 's/^/ /' | head -4 + fail "PH5-041: the score-based gate branch is still present in plugins/deepgrade/skills/plan/stages/stage-2-design.md" + grep -nE '^IF score (>=|<) [0-9]+' plugins/deepgrade/skills/plan/stages/stage-2-design.md | sed 's/^/ /' | head -4 fi [ "$gate_bad" -eq 0 ] && pass "PH5-041: the gate keys on canary, evidence, verdicts and infra — not on a score" @@ -770,7 +773,7 @@ fi # UNMET: Phase 2 migration has no rollback step" names a defect it can actually fix. # =========================================================================== fb_bad=0 -fb_block=$(sed -n '/^<revision_feedback>$/,/^<\/revision_feedback>$/p' plugins/deepgrade/skills/plan/phases/phase-5-audit.md 2>/dev/null) +fb_block=$(sed -n '/^<revision_feedback>$/,/^<\/revision_feedback>$/p' plugins/deepgrade/skills/plan/stages/stage-2-design.md 2>/dev/null) fb_forbidden='dimension|score|/40|points|threshold|GREEN|YELLOW|ORANGE' if ! printf '%s\n' 'Dimension 4 scored 2 — improve rollback coverage.' | grep -qEi "$fb_forbidden"; then @@ -783,7 +786,7 @@ if printf '%s\n' 'LINT-03 UNMET: Phase 2 migration has no rollback step. Locatio fi if [ -z "$fb_block" ]; then - fail "PH5-040: plugins/deepgrade/skills/plan/phases/phase-5-audit.md has no delimited <revision_feedback> block defining what goes back to the generator" + fail "PH5-040: plugins/deepgrade/skills/plan/stages/stage-2-design.md has no delimited <revision_feedback> block defining what goes back to the generator" fb_bad=1 else offend=$(printf '%s\n' "$fb_block" | grep -nEi "$fb_forbidden" || true) @@ -797,7 +800,12 @@ fi [ "$fb_bad" -eq 0 ] && pass "PH5-040: revision feedback carries defects and locations, no scoring vocabulary" # =========================================================================== -# PH5-060 / row A14: the waiver is conditional, and DOES use the score. +# PH5-060 / row A14: the waiver is conditional on the gate itself being trustworthy. +# +# 8.0.0 removed the numeric score entirely, so the old "borderline score removes +# the waiver" clause is gone with it. What remains: the waiver is only offered +# when the automated gate had nothing wrong with it (no infra gaps, canary +# found, nothing demoted by the evidence validator). # # The mirror image of PH5-041, and the reason that guard is scoped to a block # rather than banning the word outright. The score cannot let a plan pass, but a @@ -810,17 +818,17 @@ fi # mentions the word "waiver" — a mention survives the rule being deleted. # =========================================================================== wv_bad=0 -wv_block=$(sed -n '/^<waiver_condition>$/,/^<\/waiver_condition>$/p' plugins/deepgrade/skills/plan/phases/phase-5-audit.md 2>/dev/null) +wv_block=$(sed -n '/^<waiver_condition>$/,/^<\/waiver_condition>$/p' plugins/deepgrade/skills/plan/stages/stage-2-design.md 2>/dev/null) if [ -z "$wv_block" ]; then - fail "PH5-060: plugins/deepgrade/skills/plan/phases/phase-5-audit.md has no delimited <waiver_condition> block" + fail "PH5-060: plugins/deepgrade/skills/plan/stages/stage-2-design.md has no delimited <waiver_condition> block" wv_bad=1 else - for term in 'infra_gaps == 0' 'score >= 35' 'canary_found == true'; do + for term in 'infra_gaps == 0' 'evidence_demotions == 0' 'canary_found == true'; do printf '%s\n' "$wv_block" | grep -qF "$term" \ || { fail "PH5-060: <waiver_condition> does not require: $term"; wv_bad=1; } done fi -[ "$wv_bad" -eq 0 ] && pass "PH5-060: review waiver is blocked by infra gaps, a borderline score, or a missed canary" +[ "$wv_bad" -eq 0 ] && pass "PH5-060: review waiver is blocked by infra gaps, an evidence demotion, or a missed canary" # =========================================================================== # PH5-050 / row A15: something looks for what the criteria do not cover. @@ -832,23 +840,24 @@ fi # =========================================================================== hol_bad=0 HOL_LINE='RUN one additional judge with no rubric, no criterion list, and no dimension names.' -grep -qxF "$HOL_LINE" plugins/deepgrade/skills/plan/phases/phase-5-audit.md \ - || { fail "PH5-050: plugins/deepgrade/skills/plan/phases/phase-5-audit.md does not run a rubric-free pass — nothing checks the criteria for completeness"; hol_bad=1; } +grep -qxF "$HOL_LINE" plugins/deepgrade/skills/plan/stages/stage-2-design.md \ + || { fail "PH5-050: plugins/deepgrade/skills/plan/stages/stage-2-design.md does not run a rubric-free pass — nothing checks the criteria for completeness"; hol_bad=1; } [ -f plugins/deepgrade/docs/planning-techniques/lint-candidates.md ] \ || { fail "PH5-050: plugins/deepgrade/docs/planning-techniques/lint-candidates.md missing — unmapped findings have nowhere to land"; hol_bad=1; } [ "$hol_bad" -eq 0 ] && pass "PH5-050: a rubric-free pass runs and its unmapped findings land in lint-candidates.md" # =========================================================================== -# PH5-051 / row A15: score distribution is retained. -# -# The score no longer gates, but it is still the cheapest detector of a gate being -# gamed: a cluster of totals sitting just above any historical threshold is the -# signature of threshold-aiming. Keeping the series costs nothing and is the only -# way to see that pattern at all. +# PH5-051 / row A15 (inverted in 8.0.0): no score survives anywhere the plan +# skill or the auditor can see. The score used to be retained as a series for +# threshold-aiming detection; 8.0.0 dropped scoring altogether, so the guard now +# asserts the removal held. # =========================================================================== -grep -qF 'score_history' plugins/deepgrade/skills/plan/phases/phase-5-audit.md \ - && pass "PH5-051: audit scores are retained as a series for distribution monitoring" \ - || fail "PH5-051: plugins/deepgrade/skills/plan/phases/phase-5-audit.md does not record score_history — threshold-aiming would be invisible" +score_bad=0 +for sf in plugins/deepgrade/skills/plan/SKILL.md plugins/deepgrade/skills/plan/stages/*.md plugins/deepgrade/agents/plan-auditor.md; do + hits=$(grep -nE 'score_history|/40\b|[0-9]+-[0-9]+ = (GREEN|YELLOW|ORANGE|RED)' "$sf" || true) + [ -n "$hits" ] && { fail "PH5-051: $sf still carries scoring vocabulary: $(printf '%s' "$hits" | head -1)"; score_bad=1; } +done +[ "$score_bad" -eq 0 ] && pass "PH5-051: no score history or band vocabulary in the plan skill or the auditor" # =========================================================================== # 16R. Root-doc conformance (§9.2, class G) — the root-level docs. diff --git a/tests/mutation/wave5-guards.py b/tests/mutation/wave5-guards.py index c0402b2..c7ad14a 100644 --- a/tests/mutation/wave5-guards.py +++ b/tests/mutation/wave5-guards.py @@ -22,7 +22,7 @@ FILES = ['plugins/deepgrade/commands/quick-cleanup.md', 'plugins/deepgrade/commands/plan-status.md', 'plugins/deepgrade/commands/plan-export.md', - 'plugins/deepgrade-readiness/commands/readiness-generate.md', 'plugins/deepgrade/skills/plan/phases/phase-2-research.md', 'plugins/deepgrade/commands/help.md', + 'plugins/deepgrade-readiness/commands/readiness-generate.md', 'plugins/deepgrade/skills/plan/stages/stage-1-plan.md', 'plugins/deepgrade/commands/help.md', 'plugins/deepgrade-audit/commands/codebase-gates.md', 'plugins/deepgrade-audit/agents/gate-generator.md', 'plugins/deepgrade/skills/documentation/SKILL.md', 'plugins/deepgrade/skills/mcp-research/SKILL.md', 'README.md', 'CHANGELOG.md', @@ -33,7 +33,7 @@ 'plugins/deepgrade/commands/plan-status.md': 'PLANS_DIR="docs/plans"', 'plugins/deepgrade/commands/quick-cleanup.md': 'No source folder given', 'plugins/deepgrade-audit/agents/gate-generator.md': 'PowerShell variant', - 'plugins/deepgrade/skills/plan/phases/phase-2-research.md': 'deepgrade:mcp-research', + 'plugins/deepgrade/skills/plan/stages/stage-1-plan.md': 'deepgrade:mcp-research', } FORBIDDEN = { 'README.md': 'deepgrade:doc adr topic', @@ -188,7 +188,7 @@ def append_block(f, body): ('Y8 PowerShell instruction inverted to a prohibition', l1, 'F08', lambda: patch('plugins/deepgrade-audit/agents/gate-generator.md', 'PowerShell variant', 'do not emit a PowerShell variant'), 'catch'), ('Y9 skill wired by PROSE only, not a namespaced name', l1, 'F28', - lambda: patch('plugins/deepgrade/skills/plan/phases/phase-2-research.md', '`deepgrade:mcp-research` skill', 'mcp-research skill'), 'catch'), + lambda: patch('plugins/deepgrade/skills/plan/stages/stage-1-plan.md', '`deepgrade:mcp-research` skill', 'mcp-research skill'), 'catch'), # --- Codex F4: clauses that previously had no falsifying assertion --- ('Y10 drop the ${CLAUDE_PROJECT_DIR} resolution', l1, 'F10', lambda: patch('plugins/deepgrade/commands/plan-export.md', '${CLAUDE_PROJECT_DIR:-$OLDPWD}', '$PWD', 2), 'catch'), @@ -248,7 +248,7 @@ def append_block(f, body): ('W4 `tree` after an `if` keyword', l1, 'F15', lambda: append_block('plugins/deepgrade-readiness/commands/readiness-generate.md', 'if tree .; then :; fi'), 'catch'), ('W5 skill referenced only to FORBID it', l1, 'F28', - lambda: patch('plugins/deepgrade/skills/plan/phases/phase-2-research.md', 'see the `deepgrade:mcp-research` skill', + lambda: patch('plugins/deepgrade/skills/plan/stages/stage-1-plan.md', 'see the `deepgrade:mcp-research` skill', 'never invoke `deepgrade:mcp-research`; it is deprecated'), 'catch'), ('W6 description states it should NOT load', l1, 'F28', lambda: patch('plugins/deepgrade/skills/mcp-research/SKILL.md', 'description: ',