gsdd-cli 0.3.1 → 0.16.1

package/README.md

@@ -1,20 +1,20 @@
 <div align="center">
 
-# GSD Distilled
+# Northline
 
-**A portable, spec-driven development kernel for AI coding agents.**
+**A repo-native workflow kernel for long-horizon AI software delivery.**
 
-Extracted from [Get Shit Done](https://github.com/gsd-build/get-shit-done). Same long-horizon delivery spine — fewer moving parts.
+Northline gives long-horizon AI-assisted software work one repo-native planning, execution, verification, and handoff spine so progress survives runtime switching and session loss. The package and CLI remain `gsdd-cli` / `gsdd`.
 
 [![npm version](https://img.shields.io/npm/v/gsdd-cli?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/gsdd-cli)
 [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
-[![Tests](https://img.shields.io/badge/assertions-862_passing-brightgreen?style=for-the-badge)](tests/)
 
 ```bash
 npx gsdd-cli init
 ```
 
-**Works with Claude Code, OpenCode, Codex CLI, Cursor, Copilot, and Gemini CLI.**
+**Directly validated today:** Claude Code, Codex CLI, and OpenCode.  
+**Qualified support:** Cursor, Copilot, and Gemini CLI use the same portable skill surfaces, but this launch does not present them as parity-validated runtimes.
 
 </div>
 
@@ -22,7 +22,11 @@ npx gsdd-cli init
 
 ## What This Is
 
-GSDD is a distilled fork of GSD. It preserves the high-leverage parts of long-horizon AI-assisted development:
+Northline gives serious AI-assisted software work one repo-native planning, execution, verification, and handoff spine so progress survives long horizons, runtime switching, and session loss without turning into a dashboard or orchestration control plane.
+
+The current package and CLI stay `gsdd-cli` and `gsdd`. Northline is the public product brand layered on top of that stable install surface.
+
+It preserves the high-leverage parts of long-horizon AI-assisted development:
 
 - **Persistent artifacts** — SPEC.md, ROADMAP.md, and config.json as the durable workspace
 - **Codebase mapping** — 4 parallel mappers produce STACK, ARCHITECTURE, CONVENTIONS, CONCERNS
@@ -32,9 +36,9 @@ GSDD is a distilled fork of GSD. It preserves the high-leverage parts of long-ho
 - **Milestone audit** — cross-phase integration, requirements coverage, E2E flows
 - **Session management** — pause work with checkpoint, resume with context restoration and routing
 
-What it strips: GSD's broader operator surface (32 workflows, 11 agents, discovery modes, sprint ceremony, a settings flow, and additional operator ergonomics). GSDD has 10 workflows and 10 roles.
+What it strips: GSD's broader operator surface (32 workflows, 11 agents, discovery modes, sprint ceremony, a settings flow, and additional operator ergonomics). Northline keeps 14 workflows and 10 roles.
 
-**Target user:** Developer or small team that wants a spec-driven long-horizon kernel, not full operator comfort.
+**Target user:** Developer or small team that wants a repo-native, spec-driven workflow kernel with durable proof and handoff, not a dashboard or orchestration control plane.
 
 ---
 
@@ -60,6 +64,11 @@ In a terminal, `gsdd init` now opens a guided install wizard:
 
 Portable `.agents/skills/gsdd-*` skills are always generated. The wizard controls extra native adapters and optional governance, not the portable baseline.
 
+### Launch Proof Status
+
+- **Directly validated in this repo:** Claude Code, Codex CLI, and OpenCode have recorded `plan -> execute -> verify` evidence for the core lifecycle.
+- **Qualified support:** Cursor, Copilot, and Gemini CLI use the shared `.agents/skills/` surface plus optional governance, but this launch does not describe them as equally proven native runtimes.
+
 ### Quickstart (after init)
 
 Your tool determines how you invoke workflows:
@@ -86,14 +95,14 @@ npx gsdd-cli init --tools cursor     # Backward-compatible AGENTS.md governance
 npx gsdd-cli init --tools all        # All of the above
 ```
 
-| Platform | Tier | What's generated |
-|----------|------|-----------------|
-| **All** (default) | Open standard | `.agents/skills/gsdd-*/SKILL.md` — portable workflow entrypoints (always generated) |
-| **Claude Code** | Native | `.claude/skills/`, `.claude/commands/`, `.claude/agents/` — slash commands work immediately |
-| **OpenCode** | Native | `.opencode/commands/`, `.opencode/agents/` — slash commands work immediately |
-| **Codex CLI** | Native | `.codex/agents/gsdd-plan-checker.toml` — skill reference `$gsdd-plan` works immediately |
-| **Cursor / Copilot / Gemini** | Skills-native runtime + optional governance | Native slash-command discovery from `.agents/skills/`; optional root `AGENTS.md` block adds behavioral governance |
-| **Other AI tools** | Open standard fallback | Open `.agents/skills/gsdd-*/SKILL.md` directly |
+| Platform | Public claim | What's generated |
+|----------|--------------|-----------------|
+| **All** (default) | Shared portable surface | `.agents/skills/gsdd-*/SKILL.md` — portable workflow entrypoints (always generated) |
+| **Claude Code** | Directly validated | `.claude/skills/`, `.claude/commands/`, `.claude/agents/` — native workflow surfaces |
+| **OpenCode** | Directly validated | `.opencode/commands/`, `.opencode/agents/` — native workflow surfaces |
+| **Codex CLI** | Directly validated | Portable skill entry plus `.codex/agents/gsdd-plan-checker.toml` |
+| **Cursor / Copilot / Gemini** | Qualified support | Skills-native discovery from `.agents/skills/`; optional root `AGENTS.md` block adds behavioral governance |
+| **Other AI tools** | Fallback only | Open `.agents/skills/gsdd-*/SKILL.md` directly |
 
 ### Updating
 
@@ -225,7 +234,7 @@ Use for: bug fixes, small features, config changes, one-off tasks.
 
 ## Workflows
 
-GSDD has 10 workflows, run via generated skills or adapters:
+GSDD has 14 workflows, run via generated skills or adapters:
 
 | Workflow | What it does |
 |----------|--------------|
@@ -234,7 +243,11 @@ GSDD has 10 workflows, run via generated skills or adapters:
 | `gsdd-plan` | Research + plan + check for a phase |
 | `gsdd-execute` | Execute phase plan: implement tasks, verify changes |
 | `gsdd-verify` | Verify completed phase: 3-level checks, anti-pattern scan |
+| `gsdd-verify-work` | Conversational UAT testing: validate user-facing behavior with structured gap tracking |
 | `gsdd-audit-milestone` | Audit milestone: cross-phase integration, requirements coverage, E2E flows |
+| `gsdd-complete-milestone` | Archive shipped milestone, evolve spec, collapse roadmap |
+| `gsdd-new-milestone` | Start next milestone: gather goals, define requirements, create roadmap phases |
+| `gsdd-plan-milestone-gaps` | Create gap-closure phases from audit results |
 | `gsdd-quick` | Quick task: plan and execute sub-hour work outside the phase cycle |
 | `gsdd-pause` | Pause work: save session context to checkpoint for seamless resumption |
 | `gsdd-resume` | Resume work: restore context from artifacts and route to next action |
@@ -257,7 +270,9 @@ Workflows are agent skills or commands, not plain shell utilities. How you invok
 | `gsdd init [--tools <platform>]` | Set up `.planning/`, generate adapters |
 | `gsdd update [--tools <platform>] [--templates]` | Regenerate adapters; `--templates` refreshes `.planning/templates/` and role contracts |
 | `gsdd health [--json]` | Check workspace integrity (healthy/degraded/broken) |
+| `gsdd file-op <copy\|delete\|regex-sub>` | Run deterministic workspace-confined file copy, delete, and regex substitution |
 | `gsdd find-phase [N]` | Show phase info as JSON (for agent consumption) |
+| `gsdd phase-status <N> <status>` | Update a single ROADMAP phase status through the status-aware helper |
 | `gsdd verify <N>` | Run artifact checks for phase N |
 | `gsdd scaffold phase <N> [name]` | Create a new phase plan file |
 | `gsdd models [show\|profile\|set\|...]` | Inspect and manage model profile propagation |
@@ -294,13 +309,13 @@ GSDD consolidates GSD's agent surface into 10 roles with durable contracts:
 
 GSDD generates vendor-specific files from vendor-agnostic markdown — it does not convert from one vendor format to another. This means every adapter gets first-class output shaped to its platform's native capabilities.
 
-| Adapter | Kind | Strategy |
-|---------|------|----------|
-| **Claude Code** | `native_capable` adapter + skills-native runtime | Skill-primary plan surface (stays in main context to spawn checker subagent), thin command alias, native `gsdd-plan-checker` agent |
-| **OpenCode** | `native_capable` adapter + skills-native runtime | Specialized `/gsdd-plan` command (`subtask: false`), hidden `gsdd-plan-checker` subagent (`mode: subagent`) |
-| **Codex CLI** | `native_capable` adapter + skills-native runtime | Portable skill as entry surface, `.codex/agents/gsdd-plan-checker.toml` (read-only, high reasoning effort) |
-| **Cursor / Copilot / Gemini** | skills-native runtime + `governance_only` adapter | Runtime discovers `.agents/skills/` natively; optional root `AGENTS.md` block adds behavioral governance only |
-| **agents** (`--tools agents`) | `governance_only` adapter | Root `AGENTS.md` block for tools that benefit from governance or need open-standard fallback guidance |
+| Adapter | Evidence posture | Strategy |
+|---------|------------------|----------|
+| **Claude Code** | Directly validated | Skill-primary plan surface, thin command alias, native `gsdd-plan-checker` agent |
+| **OpenCode** | Directly validated | Specialized `/gsdd-plan` command (`subtask: false`), hidden `gsdd-plan-checker` subagent (`mode: subagent`) |
+| **Codex CLI** | Directly validated | Portable skill as entry surface, `.codex/agents/gsdd-plan-checker.toml` (read-only, high reasoning effort) |
+| **Cursor / Copilot / Gemini** | Qualified support | Runtime discovers `.agents/skills/` natively; optional root `AGENTS.md` block adds behavioral governance only |
+| **agents** (`--tools agents`) | Governance-only helper | Root `AGENTS.md` block for tools that benefit from governance or need open-standard fallback guidance |
 
 All adapters render the plan-checker from a single source (`distilled/templates/delegates/plan-checker.md`). Each adapter shapes the output to its platform's native mechanics, and the portable skill remains the shared workflow source.
 
@@ -428,7 +443,7 @@ For detailed troubleshooting and recovery procedures, see the [User Guide](docs/
 
 ## Design Decisions
 
-GSDD makes 36 documented design decisions relative to GSD, each with evidence from source files and external research. See [`distilled/DESIGN.md`](distilled/DESIGN.md) for the full rationale.
+GSDD makes 39 documented design decisions relative to GSD, each with evidence from source files and external research. See [`distilled/DESIGN.md`](distilled/DESIGN.md) for the full rationale.
 
 Key choices:
 - **4-file codebase standard** — drop state that rots (STRUCTURE, INTEGRATIONS, TESTING), keep rules that don't
@@ -446,7 +461,7 @@ Key choices:
 
 ## Testing
 
-GSDD has 862 structural assertions across 9 test files — 41 named suites that guard properties PRs repeatedly fixed manually. These are not unit tests for application code; they are invariant checks on the specification itself.
+GSDD has 1228 structural assertions across 10 test files — named suites that guard properties PRs repeatedly fixed manually. These are not unit tests for application code; they are invariant checks on the specification itself.
 
 ### Invariant Suites (I-series)
 
@@ -458,7 +473,7 @@ Structural contracts that prevent drift between roles, delegates, workflows, and
 | **I2** | Role section structure — 10 roles have role def, scope, output format, success criteria |
 | **I3** | Delegate thinness — no leaked role-contract sections in delegates |
 | **I3-gate** | New-project approval gates — required human checkpoints present |
-| **I4** | Workflow references — 10 workflows, all delegate/role refs resolve |
+| **I4** | Workflow references — 14 workflows, all delegate/role refs resolve |
 | **I5** | Session management — no vendor APIs, no STATE.md, checkpoint contract |
 | **I5b** | Session workflow scope boundaries |
 | **I6** | Artifact schema definitions |
@@ -518,7 +533,7 @@ Golden-path eval tests that verify artifact-chain contracts across end-to-end wo
 | Health | Pre-init guard, all check categories, verdict logic, JSON/human output |
 
 ```bash
-npm run test:gsdd
+npm test
 ```
 
 ---
@@ -529,7 +544,7 @@ GSDD is a distilled fork of [Get Shit Done](https://github.com/gsd-build/get-shi
 
 **What GSDD preserves** (~76% of core method): the long-horizon delivery spine — persistent artifacts, codebase mapping, scoped planning, execution, verification, and milestone auditing.
 
-**What GSDD does not cover** (~44% of full upstream surface): GSD currently exposes 32 workflow files and 11 agent files including discovery modes, a settings flow, extra operator ergonomics, and broader session-management/control-plane surface area. GSDD intentionally does not recreate this full surface.
+**What GSDD does not cover** (~44% of full upstream surface): GSD currently exposes 32 workflow files and 11 agent files including discovery modes, a settings flow, extra operator ergonomics, and broader session-management surface area. GSDD intentionally does not recreate this full surface.
 
 **The trade-off:** Fewer moving parts for the human operator. Cleaner role contracts and a simpler artifact model. But reduced operator comfort and limited control-plane features (no telemetry, no artifact linting). Health diagnostics are available via `gsdd health`.
 

package/agents/DISTILLATION.md

@@ -356,21 +356,23 @@ Do not add speculative content. Every entry must reference actual source files a
 
 Cross-source best practices applied to GSDD role contracts, audited against 6 external resources. These principles govern how role contracts should be written and revised. Ranked by impact.
 
+> **Source note:** "Anthropic CE" in this section refers to Anthropic's "Building effective agents" (Dec 2024) for orchestration and sub-agent patterns, and LangChain's "Context Engineering for Agents" (2025) for Write/Select/Compress/Isolate context management patterns. They are cited separately where attribution is precise.
+
 ### Architecture-Level (highest leverage)
 
 | Principle | What It Means | Source | GSDD Implementation |
 |-----------|--------------|--------|---------------------|
-| **Context isolation** | Research and heavy reads go in subagents; only compressed summaries enter the main context | Anthropic CE: "sub-agents perform deep technical work, returning condensed summaries" | Approach explorer research subagents return ~1000-token summaries; plan-checker runs in fresh context |
-| **JIT context loading** | Never say "read everything." Specify what to extract from each file | Anthropic CE: "maintain lightweight identifiers and use these references to dynamically load data into context at runtime" | `<input_contract>` with extraction guidance: "From SPEC.md read ONLY locked decisions" |
-| **Intermediate persistence** | For long interactions, write confirmed state to disk incrementally | Anthropic CE: "Agent regularly writes notes persisted to memory outside of the context window" | Approach explorer writes decisions to disk as they're confirmed during conversation |
-| **Progressive disclosure** | Don't front-load all context; let agents discover incrementally | Anthropic CE: "agents can assemble understanding layer by layer" | Gray areas presented individually; research loaded per area on demand |
+| **Context isolation** | Research and heavy reads go in subagents; only compressed summaries enter the main context | Anthropic "Building effective agents" (Dec 2024): orchestrator-worker pattern — sub-agents do deep technical work and return condensed summaries | Approach explorer research subagents return ~1000-token summaries; plan-checker runs in fresh context |
+| **JIT context loading** | Never say "read everything." Specify what to extract from each file | LangChain "Context Engineering for Agents" (2025): Select step of Write/Select/Compress/Isolate — load only the specific content needed, not full files | `<input_contract>` with extraction guidance: "From SPEC.md read ONLY locked decisions" |
+| **Intermediate persistence** | For long interactions, write confirmed state to disk incrementally | Anthropic BEA: agent memory outside context window. LangChain CE: Write pattern — confirmed state persisted to disk | Approach explorer writes decisions to disk as they're confirmed during conversation |
+| **Progressive disclosure** | Don't front-load all context; let agents discover incrementally | LangChain CE: Compress/Isolate patterns — agents assemble understanding incrementally rather than loading everything upfront | Gray areas presented individually; research loaded per area on demand |
 
 ### Prompt Structure (medium leverage)
 
 | Principle | What It Means | Source | GSDD Implementation |
 |-----------|--------------|--------|---------------------|
 | **XML semantic structure** | Use XML tags to separate role, instructions, examples, inputs, outputs, anti-patterns | Anthropic Claude: "XML tags help Claude parse complex prompts unambiguously" | All roles use `<role>`, most use `<quality_guarantees>`, `<anti_patterns>`. Approach-explorer adds `<algorithm>`, `<examples>`, `<scope_guardrail>` |
-| **Anti-patterns early** | Place "don't do this" instructions near the top, after role definition | Anthropic CE: critical information at the beginning gets more attention. NeoLab: early placement for high attention weight | `<anti_patterns>` placed immediately after `<role>` in all roles that have them |
+| **Anti-patterns early** | Place "don't do this" instructions near the top, after role definition | Anthropic Claude prompting docs: critical information at the beginning receives more attention (primacy effect in long-context prompts) | `<anti_patterns>` placed immediately after `<role>` in all roles that have them |
 | **Few-shot examples** | Show the pattern of interaction, not just output format | Anthropic Claude: "3-5 examples for best results." Examples in `<example>` tags | Approach-explorer: 3 examples. Other roles use inline format examples within algorithm sections |
 | **Self-check before output** | Run an explicit checklist before producing the final artifact | OpenAI: "verification loops." Anthropic Claude: "Ask Claude to self-check" | Approach-explorer step 7; planner `<plan_self_check>`; executor completion verification |
 | **Scope boundaries with heuristics** | Don't just list in/out of scope — give the agent a judgment rule | Novel, validated in approach-explorer | "Does this clarify implementation within the phase, or does it add a capability that could be its own phase?" |
@@ -379,7 +381,7 @@ Cross-source best practices applied to GSDD role contracts, audited against 6 ex
 
 | Principle | What It Means | Source | GSDD Implementation |
 |-----------|--------------|--------|---------------------|
-| **Authority language: intentional leverage** | Anthropic Claude 4.6 warns "CRITICAL:" can overtrigger on newer models. NeoLab persuasion research found imperative language doubled compliance (33%→72%). GSDD decision: **keep CRITICAL: for mandatory initial-read** — this is a genuine compliance-critical instruction where skipping it causes cascading failures. Use normal language for non-critical instructions. | Anthropic Claude 4.6 vs. NeoLab persuasion research (direct conflict). GSDD sides with NeoLab for this specific use case | `CRITICAL: Mandatory initial read` kept in all 7 roles. `NEVER` kept for security (mapper secret protection). Normal language used for algorithm steps, scope guidance, and quality rules |
+| **Authority language: intentional leverage** | Anthropic Claude warns "CRITICAL:" can overtrigger on newer models. GSDD decision: **keep CRITICAL: for mandatory initial-read** — a genuine compliance-critical instruction where skipping causes cascading failures. Emphasis markers work when rare and specific (signal-to-noise principle: one CRITICAL: in a role contract is a load-bearing gate; ten would be noise). Use normal language for algorithm steps, scope guidance, and quality rules. | Anthropic Claude prompting docs (overtriggering caution) + technical writing signal-to-noise principle. GSDD applies the caution selectively: only compliance-critical context gates use CRITICAL: | `CRITICAL: Mandatory initial read` kept in all 7 roles. `NEVER` kept for security (mapper secret protection). Normal language used for algorithm steps, scope guidance, and quality rules |
 | **Tell what to do, not just what not to do** | Anti-patterns alone are insufficient; pair with positive instructions | Anthropic Claude: "Tell Claude what to do instead of what not to do" | Every role has both `<anti_patterns>` AND positive algorithm/process sections |
 | **Context for instructions** | Explain WHY a rule exists so the agent can generalize | Anthropic Claude: "Providing context or motivation behind your instructions helps Claude better understand your goals" | Research quality rules explain WHY: "Training data is a hypothesis. Verify before asserting." |
 
@@ -394,17 +396,17 @@ These patterns emerged from GSDD's specific needs and were validated through imp
 | **5-dimension assumption surfacing** | Forces transparency about inferences vs. confirmed facts, with confidence levels | Approach-explorer step 6 |
 | **Agent's Discretion delegation** | User can explicitly say "you decide" — reduces fatigue on low-stakes choices | Approach-explorer step 4, planner `<approach_decisions>` |
 | **Domain classification table** | SEE/CALL/RUN/READ/ORGANIZED determines gray area focus per phase type | Approach-explorer step 2 |
-| **Degrees of freedom mapping** | Taste=high freedom, technical=low freedom (research-constrained). Maps to NeoLab's concept | Approach-explorer classification system |
+| **Degrees of freedom mapping** | Taste=high freedom, technical=low freedom (research-constrained). GSDD-originated: applies statistical degrees-of-freedom concept to prompt design scope | Approach-explorer classification system |
 
 ### Source Ranking
 
 Sources are ranked by soundness for agent prompt design. Higher-ranked sources take precedence when sources disagree.
 
-1. **Anthropic — Effective Context Engineering for AI Agents** — Architecture-level patterns with real production evidence (Claude Code, Pokémon). Most authoritative for context window management, sub-agent design, and information flow.
-2. **Anthropic — Claude Prompting Best Practices (Claude 4.6)** — Model-specific, up-to-date. Critical for behavioral warnings (overtriggering, subagent overuse). Supersedes general guidance for Claude-targeted agents.
-3. **OpenAI — Prompt Guidance (GPT-5.4)** — Deepest general-purpose reference. Novel concepts: completeness contracts, verification loops, tool persistence rules, empty result recovery. Model-specific but patterns transfer.
-4. **NeoLab Context Engineering Kit** — Good synthesis. "Degrees of Freedom" concept is useful. Persuasion research contradicts Anthropic on authority language (trust Anthropic for Claude).
-5. **OpenAI Cookbook — Meta-Prompting** — Narrow scope: LLM-as-judge evaluation, iterative prompt refinement. Useful technique, not a framework.
+1. **Anthropic — "Building effective agents" (Dec 2024)** — Agent architecture patterns with production evidence (Claude Code). Most authoritative for orchestrator-worker design, sub-agent fresh context, and task decomposition.
+2. **LangChain — "Context Engineering for Agents" (2025)** — Write/Select/Compress/Isolate framework. Most authoritative for context window management, JIT loading, and information flow patterns.
+3. **Anthropic — Claude Prompting Best Practices (Claude 4.6)** — Model-specific, up-to-date. Critical for behavioral warnings (overtriggering, subagent overuse). Supersedes general guidance for Claude-targeted agents.
+4. **OpenAI — Prompt Guidance (GPT-5.4)** — Deepest general-purpose reference. Novel concepts: completeness contracts, verification loops, tool persistence rules, empty result recovery. Model-specific but patterns transfer.
+5. **OpenAI Cookbook — Meta-Prompting** — Narrow scope: LLM-as-judge evaluation, iterative prompt refinement. Useful technique, not a framework. See also: Suzgun & Kalai "Meta-Prompting" (2024, arXiv 2401.12954).
 6. **JBurlison/MetaPrompts** — Structural skeleton (agent/skill/prompt/instruction hierarchy). Minimal actual guidance on prompt quality.
 
 ### Key Discrepancy Resolution
@@ -413,7 +415,7 @@ When sources conflict, these resolutions apply:
 
 | Conflict | Resolution | Why |
 |----------|------------|-----|
-| Authority language ("YOU MUST" vs. normal) | Keep CRITICAL: for mandatory initial-read (compliance-critical). Use normal language elsewhere | NeoLab's doubled-compliance research applies to instructions where skipping causes cascading failures. Anthropic's overtriggering concern applies to general guidance, not load-bearing context gates |
+| Authority language ("YOU MUST" vs. normal) | Keep CRITICAL: for mandatory initial-read (compliance-critical). Use normal language elsewhere | Emphasis markers work when rare and specific (signal-to-noise). Anthropic's overtriggering concern applies to general guidance; a single CRITICAL: for a mandatory context gate is a load-bearing instruction, not noise |
 | Example count (2 vs. 3-5) | Target 3+ for conversational agents; inline format examples are sufficient for structured output agents | Anthropic's 3-5 recommendation is general; interactive roles benefit more than output-only roles |
 | Subagent return size (200 vs. 1000-2000 tokens) | Use 300-500 tokens | Anthropic's 1000-2000 is upper bound; 200 was too tight for structured approach summaries with trade-offs |
 | "Don't invent alternatives" vs. "try fallback strategies" | Keep "don't invent" for approach research; use fallbacks for information retrieval | These solve different problems: manufacturing fake options is worse than acknowledging one viable path |

package/agents/planner.md

@@ -238,6 +238,8 @@ Before returning, self-check against the checker dimensions:
 5. scope sanity
 6. must-have quality
 7. context compliance
+8. goal achievement
+9. approach alignment (when APPROACH.md exists)
 
 Task completeness rules:
 - every task has files, action, verify, and done

package/bin/adapters/agents.mjs

@@ -6,6 +6,7 @@ function createRootAgentsAdapter({ cwd, renderAgentsBoundedBlock, renderAgentsFi
     id: 'agents',
     name,
     kind: 'governance_only',
+    subagentFiles: [],
     detect() {
       return false;
     },

package/bin/adapters/claude.mjs

@@ -1,5 +1,10 @@
 import { existsSync, mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
+import {
+  PLAN_CHECK_DIMENSIONS,
+  MAX_CHECKER_CYCLES,
+  CHECKER_STATUSES,
+} from '../lib/plan-constants.mjs';
 
 const CLAUDE_MODEL_PROFILES = {
   quality: 'opus',
@@ -75,7 +80,7 @@ Execution flow:
      "summary": "One sentence overall assessment",
      "issues": [
        {
-         "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance | goal_achievement | approach_alignment",
+         "dimension": "${PLAN_CHECK_DIMENSIONS.join(' | ')}",
          "severity": "blocker | warning",
          "description": "What is wrong",
          "plan": "01-PLAN",
@@ -84,10 +89,10 @@ Execution flow:
        }
      ]
    }
-   Status must be either "passed" or "issues_found".
+   Status must be either "${CHECKER_STATUSES[0]}" or "${CHECKER_STATUSES[1]}".
 9. If the checker returns \`passed\`, finish and summarize.
 10. If the checker returns \`issues_found\`, revise the existing plan files only where needed, then run the checker again.
-11. Maximum 3 checker cycles total. If blockers remain after cycle 3, stop and escalate to the user instead of pretending the plan is ready.
+11. Maximum ${MAX_CHECKER_CYCLES} checker cycles total. If blockers remain after cycle ${MAX_CHECKER_CYCLES}, stop and escalate to the user instead of pretending the plan is ready.
 
 Return a concise orchestration summary:
 - target phase
@@ -125,6 +130,10 @@ function createClaudeAdapter({ cwd, workflows, renderSkillContent, getDelegateCo
     id: 'claude',
     name: 'claude',
     kind: 'native_capable',
+    subagentFiles: [
+      '.claude/agents/gsdd-plan-checker.md',
+      '.claude/agents/gsdd-approach-explorer.md',
+    ],
     detect() {
       return existsSync(join(cwd, 'CLAUDE.md')) || existsSync(join(cwd, '.claude'));
     },

package/bin/adapters/codex.mjs

@@ -44,6 +44,10 @@ function createCodexAdapter({
     id: 'codex',
     name: 'codex',
     kind: 'native_capable',
+    subagentFiles: [
+      '.codex/agents/gsdd-plan-checker.toml',
+      '.codex/agents/gsdd-approach-explorer.toml',
+    ],
     detect() {
       return existsSync(join(cwd, '.codex'));
     },

package/bin/adapters/opencode.mjs

@@ -1,6 +1,11 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import os from 'os';
 import { join } from 'path';
+import {
+  PLAN_CHECK_DIMENSIONS,
+  MAX_CHECKER_CYCLES,
+  CHECKER_STATUSES,
+} from '../lib/plan-constants.mjs';
 
 function expandHome(filePath) {
   if (!filePath) return filePath;
@@ -115,7 +120,7 @@ function renderOpenCodeApproachExplorer(delegateContent, modelId = null) {
   const modelLine = modelId ? `model: ${modelId}\n` : '';
   return `---
 description: Explores implementation approaches for a phase and aligns with the user through structured questioning before planning begins.
-mode: agent
+mode: subagent
 ${modelLine}tools:
   bash: false
 ---
@@ -183,7 +188,7 @@ Execution flow:
      "summary": "One sentence overall assessment",
      "issues": [
        {
-         "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance | goal_achievement | approach_alignment",
+         "dimension": "${PLAN_CHECK_DIMENSIONS.join(' | ')}",
          "severity": "blocker | warning",
          "description": "What is wrong",
          "plan": "01-PLAN",
@@ -192,10 +197,10 @@ Execution flow:
        }
      ]
    }
-   Status must be either "passed" or "issues_found".
+   Status must be either "${CHECKER_STATUSES[0]}" or "${CHECKER_STATUSES[1]}".
 9. If the checker returns \`passed\`, finish and summarize.
 10. If the checker returns \`issues_found\`, revise the existing plan files only where needed, then run the checker again.
-11. Maximum 3 checker cycles total. If blockers remain after cycle 3, stop and escalate to the user instead of pretending the plan is ready.
+11. Maximum ${MAX_CHECKER_CYCLES} checker cycles total. If blockers remain after cycle ${MAX_CHECKER_CYCLES}, stop and escalate to the user instead of pretending the plan is ready.
 
 Return a concise orchestration summary:
 - target phase
@@ -223,6 +228,10 @@ function createOpenCodeAdapter({
     id: 'opencode',
     name: 'opencode',
     kind: 'native_capable',
+    subagentFiles: [
+      '.opencode/agents/gsdd-plan-checker.md',
+      '.opencode/agents/gsdd-approach-explorer.md',
+    ],
     detect() {
       return existsSync(join(cwd, '.opencode'));
     },

package/bin/gsdd.mjs

@@ -16,7 +16,8 @@ import {
 } from './lib/rendering.mjs';
 import { loadProjectModelConfig, getRuntimeModelOverride, resolveRuntimeAgentModel, cmdModels } from './lib/models.mjs';
 import { createCmdInit, createCmdUpdate, cmdHelp } from './lib/init.mjs';
-import { cmdFindPhase, cmdVerify, cmdScaffold } from './lib/phase.mjs';
+import { cmdFindPhase, cmdVerify, cmdScaffold, cmdPhaseStatus } from './lib/phase.mjs';
+import { cmdFileOp } from './lib/file-ops.mjs';
 import { createCmdHealth } from './lib/health.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -45,14 +46,18 @@ const WORKFLOWS = [
   defineWorkflow({ name: 'gsdd-plan', workflow: 'plan.md', description: 'Plan a phase - research check, backward planning, task creation' }),
   defineWorkflow({ name: 'gsdd-execute', workflow: 'execute.md', description: 'Execute a phase plan - implement tasks, verify changes, follow repo git conventions' }),
   defineWorkflow({ name: 'gsdd-verify', workflow: 'verify.md', description: 'Verify a completed phase - 3-level checks, anti-pattern scan' }),
+  defineWorkflow({ name: 'gsdd-verify-work', workflow: 'verify-work.md', description: 'Conversational UAT testing - validate user-facing behavior with structured gap tracking' }),
   defineWorkflow({ name: 'gsdd-audit-milestone', workflow: 'audit-milestone.md', description: 'Audit a completed milestone - cross-phase integration, requirements coverage, E2E flows' }),
+  defineWorkflow({ name: 'gsdd-complete-milestone', workflow: 'complete-milestone.md', description: 'Complete milestone - archive, evolve spec, collapse roadmap' }),
+  defineWorkflow({ name: 'gsdd-new-milestone', workflow: 'new-milestone.md', description: 'New milestone - gather goals, define requirements, create roadmap phases' }),
+  defineWorkflow({ name: 'gsdd-plan-milestone-gaps', workflow: 'plan-milestone-gaps.md', description: 'Plan gap closure phases from audit results' }),
   defineWorkflow({ name: 'gsdd-quick', workflow: 'quick.md', description: 'Quick task - plan and execute a sub-hour task outside the phase cycle' }),
   defineWorkflow({ name: 'gsdd-pause', workflow: 'pause.md', description: 'Pause work - save session context for seamless resumption' }),
   defineWorkflow({ name: 'gsdd-resume', workflow: 'resume.md', description: 'Resume work - restore context and route to next action' }),
   defineWorkflow({ name: 'gsdd-progress', workflow: 'progress.md', description: 'Check progress - show project status and route to next action', mutatesArtifacts: false }),
 ];
 
-const FRAMEWORK_VERSION = 'v1.2';
+const FRAMEWORK_VERSION = 'v1.3';
 
 function createCliContext(cwd = process.cwd()) {
   return {
@@ -89,24 +94,34 @@ const COMMANDS = {
   update: cmdUpdate,
   models: cmdModels,
   health: cmdHealth,
+  'file-op': cmdFileOp,
   'find-phase': cmdFindPhase,
+  'phase-status': cmdPhaseStatus,
   verify: cmdVerify,
   scaffold: cmdScaffold,
   help: cmdHelp,
 };
 
-async function runCli(cliCommand = command, cliArgs = args) {
+async function runCli(cliCommand = command, ...cliArgs) {
+  const normalizedArgs = cliArgs.length === 0
+    ? args
+    : cliArgs.length === 1 && Array.isArray(cliArgs[0])
+      ? cliArgs[0]
+      : cliArgs;
+
+  process.exitCode = 0;
+
   if (!cliCommand || !COMMANDS[cliCommand]) {
     cmdHelp();
     if (cliCommand) process.exitCode = 1;
     return;
   }
 
-  await COMMANDS[cliCommand](...cliArgs);
+  await COMMANDS[cliCommand](...normalizedArgs);
 }
 
 if (IS_MAIN) {
   await runCli();
 }
 
-export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFindPhase, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };
+export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFileOp, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };

package/bin/lib/cli-utils.mjs

@@ -15,7 +15,7 @@ export function parseFlagValue(flagArgs, flagName) {
 export function parseToolsFlag(flagArgs) {
   const { value } = parseFlagValue(flagArgs, '--tools');
   if (!value) return [];
-  if (value === 'all') return ['claude', 'opencode', 'codex', 'agents'];
+  if (value === 'all') return ['claude', 'opencode', 'codex', 'agents', 'cursor', 'copilot', 'gemini'];
   return value.split(',').map((v) => v.trim()).filter(Boolean);
 }
 

package/bin/lib/file-ops.mjs

@@ -0,0 +1,161 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'fs';
+import { dirname, isAbsolute, relative, resolve } from 'path';
+import { output, parseFlagValue } from './cli-utils.mjs';
+
+class FileOpError extends Error {}
+
+function fail(message) {
+  console.error(message);
+  throw new FileOpError(message);
+}
+
+function resolveWorkspacePath(cwd, target) {
+  const workspaceRoot = resolve(cwd);
+  const resolved = resolve(workspaceRoot, target);
+  const rel = relative(workspaceRoot, resolved);
+
+  if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))) {
+    return resolved;
+  }
+
+  fail(`Path must stay inside the workspace: ${target}`);
+}
+
+function getMissingBehavior(args) {
+  const parsed = parseFlagValue(args, '--missing');
+  if (!parsed.present) return 'error';
+  if (parsed.invalid) fail('Usage: --missing <error|ok>');
+  if (!['error', 'ok'].includes(parsed.value)) fail('Usage: --missing <error|ok>');
+  return parsed.value;
+}
+
+function cmdCopy(cwd, args) {
+  const [sourceArg, destinationArg, ...flags] = args;
+  if (!sourceArg || !destinationArg) {
+    fail('Usage: gsdd file-op copy <source> <destination> [--missing <error|ok>]');
+  }
+
+  const missingBehavior = getMissingBehavior(flags);
+  const source = resolveWorkspacePath(cwd, sourceArg);
+  const destination = resolveWorkspacePath(cwd, destinationArg);
+
+  if (!existsSync(source)) {
+    if (missingBehavior === 'ok') {
+      output({ operation: 'copy', source: sourceArg, destination: destinationArg, changed: false, reason: 'missing_source' });
+      return;
+    }
+    fail(`Source file does not exist: ${sourceArg}`);
+  }
+
+  if (statSync(source).isDirectory()) {
+    fail(`Copy only supports files in this phase: ${sourceArg}`);
+  }
+
+  mkdirSync(dirname(destination), { recursive: true });
+  cpSync(source, destination, { force: true });
+  output({ operation: 'copy', source: sourceArg, destination: destinationArg, changed: true });
+}
+
+function cmdDelete(cwd, args) {
+  const [targetArg, ...flags] = args;
+  if (!targetArg) {
+    fail('Usage: gsdd file-op delete <target> [--missing <error|ok>]');
+  }
+
+  const missingBehavior = getMissingBehavior(flags);
+  const target = resolveWorkspacePath(cwd, targetArg);
+
+  if (!existsSync(target)) {
+    if (missingBehavior === 'ok') {
+      output({ operation: 'delete', target: targetArg, changed: false, reason: 'missing_target' });
+      return;
+    }
+    fail(`Target file does not exist: ${targetArg}`);
+  }
+
+  if (statSync(target).isDirectory()) {
+    fail(`Delete only supports files in this phase: ${targetArg}`);
+  }
+
+  unlinkSync(target);
+  output({ operation: 'delete', target: targetArg, changed: true });
+}
+
+function cmdRegexSub(cwd, args) {
+  const [targetArg, pattern, replacement, ...flags] = args;
+  if (!targetArg || pattern === undefined || replacement === undefined) {
+    fail('Usage: gsdd file-op regex-sub <target> <pattern> <replacement> [--flags <flags>] [--missing <error|ok>]');
+  }
+
+  const regexFlags = parseFlagValue(flags, '--flags');
+  if (regexFlags.present && regexFlags.invalid) {
+    fail('Usage: --flags <regex-flags>');
+  }
+
+  const missingBehavior = getMissingBehavior(flags);
+  const target = resolveWorkspacePath(cwd, targetArg);
+
+  if (!existsSync(target)) {
+    if (missingBehavior === 'ok') {
+      output({ operation: 'regex-sub', target: targetArg, changed: false, reason: 'missing_target' });
+      return;
+    }
+    fail(`Target file does not exist: ${targetArg}`);
+  }
+
+  if (statSync(target).isDirectory()) {
+    fail(`regex-sub only supports files in this phase: ${targetArg}`);
+  }
+
+  let regex;
+  try {
+    regex = new RegExp(pattern, regexFlags.value || 'g');
+  } catch (error) {
+    fail(`Invalid regex pattern: ${error.message}`);
+  }
+
+  const source = readFileSync(target, 'utf-8');
+  let replacementCount = 0;
+  if (regex.global) {
+    const matches = source.match(regex);
+    replacementCount = matches ? matches.length : 0;
+  } else {
+    replacementCount = regex.test(source) ? 1 : 0;
+  }
+
+  if (replacementCount === 0) {
+    fail(`Pattern did not match any text in ${targetArg}`);
+  }
+
+  const updated = source.replace(regex, replacement);
+  const changed = updated !== source;
+  writeFileSync(target, updated);
+  output({ operation: 'regex-sub', target: targetArg, changed, replacements: replacementCount });
+}
+
+export function cmdFileOp(...args) {
+  const cwd = process.cwd();
+  const [operation, ...rest] = args;
+
+  try {
+    switch (operation) {
+      case 'copy':
+        cmdCopy(cwd, rest);
+        return;
+      case 'delete':
+        cmdDelete(cwd, rest);
+        return;
+      case 'regex-sub':
+        cmdRegexSub(cwd, rest);
+        return;
+      default:
+        fail('Usage: gsdd file-op <copy|delete|regex-sub> ...');
+    }
+  } catch (error) {
+    if (error instanceof FileOpError) {
+      process.exitCode = 1;
+      return;
+    }
+    throw error;
+  }
+}