gsdd-cli 0.2.0 → 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.
 
 ---
 
@@ -48,17 +52,32 @@ This creates:
 
 1. `.planning/` — durable workspace with templates, role contracts, and config
 2. `.agents/skills/gsdd-*` — portable workflow entrypoints
-3. Tool-specific adapters if detected (Claude skills/commands/agents, OpenCode commands/agents, Codex agents)
+3. Tool-specific adapters you choose in the install wizard (Claude skills/commands/agents, OpenCode commands/agents, Codex agents, optional governance)
 
 Then run the new-project workflow to produce `.planning/SPEC.md` and `.planning/ROADMAP.md`.
 
+In a terminal, `gsdd init` now opens a guided install wizard:
+
+- Step 1: select the runtimes/vendors you want to support
+- Step 2: decide separately whether repo-wide `AGENTS.md` governance is worth installing
+- Step 3: configure planning defaults in the same guided flow
+
+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:
 
-- **Claude Code / OpenCode:** Use slash commands directly — `/gsdd-new-project`, `/gsdd-plan`, etc.
+- **Claude Code / OpenCode / Cursor / Copilot / Gemini:** Use slash commands directly — `/gsdd-new-project`, `/gsdd-plan`, etc.
 - **Codex CLI:** Use skill references — `$gsdd-new-project`, `$gsdd-plan`, etc.
-- **Cursor / Copilot / Gemini / Others:** Open `.agents/skills/gsdd-<workflow>/SKILL.md` and follow the instructions. The root `AGENTS.md` governance block keeps the agent on track.
+- **Other AI tools:** Open `.agents/skills/gsdd-<workflow>/SKILL.md` and follow the instructions.
+
+If you generate the root `AGENTS.md` block, it adds GSDD behavioral governance. For Cursor, Copilot, and Gemini, that governance is optional discipline on top of native skill discovery — not the mechanism that makes workflows discoverable.
 
 First workflow to run: **new-project** — it asks about your goals, audits the codebase (if brownfield), and produces `.planning/SPEC.md` + `.planning/ROADMAP.md`.
 
@@ -67,21 +86,23 @@ First workflow to run: **new-project** — it asks about your goals, audits the
 GSDD generates adapters for whichever tools you use:
 
 ```bash
-npx gsdd-cli init                    # Auto-detect installed tools
+npx gsdd-cli init                    # Guided install wizard (detected runtimes preselected)
 npx gsdd-cli init --tools claude     # Claude Code: .claude/skills + commands + agents
 npx gsdd-cli init --tools opencode   # OpenCode: .opencode/commands + agents
 npx gsdd-cli init --tools codex      # Codex CLI: portable gsdd-plan skill + .codex/agents checker
 npx gsdd-cli init --tools agents     # Root AGENTS.md fallback
+npx gsdd-cli init --tools cursor     # Backward-compatible AGENTS.md governance alias
 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** | Governance | Root `AGENTS.md` block — governs agent behavior; invoke workflows by opening `.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
 
@@ -102,10 +123,13 @@ npx gsdd-cli init --auto --tools claude --brief path/to/PRD.md
 
 `--auto` skips interactive prompts, uses smart defaults (`autoAdvance: true` in config). `--brief` copies a project document to `.planning/PROJECT_BRIEF.md` for `new-project` to consume.
 
+If you already know exactly what to generate, `--tools ...` remains the manual path. The wizard is the primary onboarding UX; flags remain the advanced/headless contract.
+
 ### Team Use
 
 - **Shared state:** Set `commitDocs: true` (default) — `.planning/` is tracked in git. Everyone sees the same spec, roadmap, and phase plans.
 - **Onboarding:** After cloning, run `npx gsdd-cli init` to generate tool-specific adapters. `.planning/` is already tracked — no re-initialization needed.
+- **Governance is explicit:** The wizard asks separately whether to install repo-wide `AGENTS.md` rules, and explains why you may care before writing to the repo root.
 - **Session handoff:** Use `gsdd-pause` / `gsdd-resume` to hand off work. The checkpoint (`.planning/.continue-here.md`) captures context for the next person.
 - **Adapter isolation:** Each developer runs `gsdd init --tools <their-tool>`. Adapter files don't conflict across tools.
 
@@ -192,7 +216,8 @@ When all phases are done, run `gsdd-audit-milestone` to verify:
 
 - `Claude Code / OpenCode`: `/gsdd-quick`
 - `Codex CLI`: `$gsdd-quick`
-- `Cursor / Copilot / Gemini / Others`: open `.agents/skills/gsdd-quick/SKILL.md`
+- `Cursor / Copilot / Gemini`: `/gsdd-quick`
+- `Other AI tools`: open `.agents/skills/gsdd-quick/SKILL.md`
 
 For sub-hour tasks that don't need the full phase cycle:
 
@@ -209,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 |
 |----------|--------------|
@@ -218,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 |
@@ -231,7 +260,8 @@ Workflows are agent skills or commands, not plain shell utilities. How you invok
 | Claude Code | `/gsdd-plan` (slash command, works immediately after init) |
 | OpenCode | `/gsdd-plan` (slash command, works immediately after init) |
 | Codex CLI | `$gsdd-plan` (skill reference, works immediately after init) |
-| Cursor / Copilot / Gemini | Open `.agents/skills/gsdd-plan/SKILL.md` and paste or reference its content. The `AGENTS.md` governance block steers agent behavior. |
+| Cursor / Copilot / Gemini | `/gsdd-plan` (skills-native slash command). If the root `AGENTS.md` block is present, it adds governance, not workflow discovery. |
+| Other AI tools | Open `.agents/skills/gsdd-plan/SKILL.md` and paste or reference its content. |
 
 ## CLI Commands
 
@@ -240,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 |
@@ -277,16 +309,17 @@ 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` | Skill-primary plan surface (stays in main context to spawn checker subagent), thin command alias, native `gsdd-plan-checker` agent |
-| **OpenCode** | `native_capable` | Specialized `/gsdd-plan` command (`subtask: false`), hidden `gsdd-plan-checker` subagent (`mode: subagent`) |
-| **Codex CLI** | `native_capable` | Portable skill as entry surface, `.codex/agents/gsdd-plan-checker.toml` (read-only, high reasoning effort) |
-| **Cursor / Copilot / Gemini** | `governance_only` | Root `AGENTS.md` block governs agent behavior; invoke workflows by opening `.agents/skills/gsdd-*/SKILL.md` directly |
+| 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.
 
-Cursor, Copilot, and Gemini CLI generate the same root `AGENTS.md` governance block as `--tools agents`. They do not have native adapter surfaces — invoke workflows by opening `.agents/skills/gsdd-*/SKILL.md` directly.
+Cursor, Copilot, and Gemini CLI generate the same root `AGENTS.md` governance block as `--tools agents`, but that file is governance only. Those runtimes already discover `.agents/skills/` natively and surface the workflows as slash commands.
 
 Model IDs pass through a two-layer injection guard: a regex whitelist (`/^[a-zA-Z0-9._\/:@-]+$/`) at the CLI boundary, plus format-specific escaping (TOML string escaping, triple-quote break prevention) at the adapter layer.
 
@@ -410,7 +443,7 @@ For detailed troubleshooting and recovery procedures, see the [User Guide](docs/
 
 ## Design Decisions
 
-GSDD makes 29 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
@@ -428,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)
 
@@ -440,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 |
@@ -500,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
 ```
 
 ---
@@ -511,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 | 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 | 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);
@@ -24,51 +25,65 @@ const __dirname = dirname(__filename);
 const DISTILLED_DIR = join(__dirname, '..', 'distilled');
 const AGENTS_DIR = join(__dirname, '..', 'agents');
 const CWD = process.cwd();
-const PLANNING_DIR = join(CWD, '.planning');
 const IS_MAIN = process.argv[1]
   ? realpathSync(process.argv[1]) === realpathSync(__filename)
   : false;
 
 const [,, command, ...args] = process.argv;
 
+function defineWorkflow({ mutatesArtifacts = true, ...workflow }) {
+  return {
+    ...workflow,
+    mutatesArtifacts,
+    agent: mutatesArtifacts ? 'Code' : 'Plan',
+    opencodeType: mutatesArtifacts ? 'edit' : 'plan',
+  };
+}
+
 const WORKFLOWS = [
-  { name: 'gsdd-new-project', workflow: 'new-project.md', description: 'New project - questioning, codebase audit, research, spec, roadmap', agent: 'Plan', opencodeType: 'plan' },
-  { name: 'gsdd-map-codebase', workflow: 'map-codebase.md', description: 'Map or refresh codebase - 4 parallel mappers, staleness check, secrets scan', agent: 'Plan', opencodeType: 'plan' },
-  { name: 'gsdd-plan', workflow: 'plan.md', description: 'Plan a phase - research check, backward planning, task creation', agent: 'Plan', opencodeType: 'plan' },
-  { name: 'gsdd-execute', workflow: 'execute.md', description: 'Execute a phase plan - implement tasks, verify changes, follow repo git conventions', agent: 'Code', opencodeType: 'edit' },
-  { name: 'gsdd-verify', workflow: 'verify.md', description: 'Verify a completed phase - 3-level checks, anti-pattern scan', agent: 'Plan', opencodeType: 'plan' },
-  { name: 'gsdd-audit-milestone', workflow: 'audit-milestone.md', description: 'Audit a completed milestone - cross-phase integration, requirements coverage, E2E flows', agent: 'Plan', opencodeType: 'plan' },
-  { name: 'gsdd-quick', workflow: 'quick.md', description: 'Quick task - plan and execute a sub-hour task outside the phase cycle', agent: 'Code', opencodeType: 'edit' },
-  { name: 'gsdd-pause', workflow: 'pause.md', description: 'Pause work - save session context for seamless resumption', agent: 'Plan', opencodeType: 'plan' },
-  { name: 'gsdd-resume', workflow: 'resume.md', description: 'Resume work - restore context and route to next action', agent: 'Plan', opencodeType: 'plan' },
-  { name: 'gsdd-progress', workflow: 'progress.md', description: 'Check progress - show project status and route to next action', agent: 'Plan', opencodeType: 'plan' },
+  defineWorkflow({ name: 'gsdd-new-project', workflow: 'new-project.md', description: 'New project - questioning, codebase audit, research, spec, roadmap' }),
+  defineWorkflow({ name: 'gsdd-map-codebase', workflow: 'map-codebase.md', description: 'Map or refresh codebase - 4 parallel mappers, staleness check, secrets scan' }),
+  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';
 
-const ADAPTERS = createAdapterRegistry({
-  cwd: CWD,
-  workflows: WORKFLOWS,
-  renderAgentsBoundedBlock,
-  renderAgentsFileContent,
-  renderOpenCodeCommandContent,
-  renderSkillContent,
-  upsertBoundedBlock,
-  getDelegateContent,
-  loadProjectModelConfig,
-  getRuntimeModelOverride,
-  resolveRuntimeAgentModel,
-});
-
-const INIT_CONTEXT = {
-  cwd: CWD,
-  planningDir: PLANNING_DIR,
-  distilledDir: DISTILLED_DIR,
-  agentsDir: AGENTS_DIR,
-  workflows: WORKFLOWS,
-  frameworkVersion: FRAMEWORK_VERSION,
-  adapters: ADAPTERS,
-};
+function createCliContext(cwd = process.cwd()) {
+  return {
+    cwd,
+    planningDir: join(cwd, '.planning'),
+    distilledDir: DISTILLED_DIR,
+    agentsDir: AGENTS_DIR,
+    workflows: WORKFLOWS,
+    frameworkVersion: FRAMEWORK_VERSION,
+    adapters: createAdapterRegistry({
+      cwd,
+      workflows: WORKFLOWS,
+      renderAgentsBoundedBlock,
+      renderAgentsFileContent,
+      renderOpenCodeCommandContent,
+      renderSkillContent,
+      upsertBoundedBlock,
+      getDelegateContent,
+      loadProjectModelConfig,
+      getRuntimeModelOverride,
+      resolveRuntimeAgentModel,
+    }),
+  };
+}
+
+const INIT_CONTEXT = createCliContext(CWD);
 
 const cmdInit = createCmdInit(INIT_CONTEXT);
 const cmdUpdate = createCmdUpdate(INIT_CONTEXT);
@@ -79,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 };
+export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFileOp, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };