specky-sdd 3.8.0 → 3.10.0

package/.apm/skills/specky-sdd-pipeline/SKILL.md

@@ -29,27 +29,20 @@ The SDD pipeline consists of 10 sequential phases designed to transform feature
 
 **Phase 9: Release** — Release gate execution, documentation generation, PR creation, work item export, and changelog preparation.
 
-## EARS Notation (Extended Requirements)
+## EARS Notation (Canonical 6 Patterns)
 
-EARS (Easy Approach to Requirements Syntax) provides five core patterns plus a complex pattern for unambiguous requirement capture:
+EARS (Easy Approach to Requirements Syntax) uses six requirement patterns. Should/May express priority or obligation level inside a requirement; they are not separate Specky EARS patterns.
 
-1. **Shall** — Mandatory requirements. Format: "The system shall [action]."
-   - Example: "The system shall validate email format before submission."
+| Pattern | Format |
+|---------|--------|
+| Ubiquitous | The system shall... |
+| Event-driven | When [event], the system shall... |
+| State-driven | While [state], the system shall... |
+| Optional | Where [condition], the system shall... |
+| Unwanted | If [condition], then the system shall... |
+| Complex | While [state], when [event], the system shall... |
 
-2. **Should** — Desired but not mandatory. Format: "The system should [action]."
-   - Example: "The system should display results within 2 seconds."
-
-3. **May** — Optional enhancements. Format: "The system may [action]."
-   - Example: "The system may support bulk import operations."
-
-4. **If...Then...** — Conditional requirements. Format: "If [condition] then [action]."
-   - Example: "If user is admin then system shall grant access to configuration panel."
-
-5. **When...Then...** — Trigger-based requirements. Format: "When [event] then [action]."
-   - Example: "When form is submitted then system shall validate all required fields."
-
-6. **Complex** — Combination patterns for intricate business logic.
-   - Example: "If user role is editor, when publish button is clicked, then system shall validate content and if valid shall queue for approval."
+See `references/ears-notation.md` for examples and validation guidance.
 
 ## Model Recommendation Table
 
@@ -98,6 +91,14 @@ The pipeline includes 16 automation hooks for customization:
 
 Hooks are configured in `sdd-hooks.json` with PreToolUse and PostToolUse matchers.
 
+## Server-Enforced Analysis Gate (v3.10+)
+
+Once the pipeline reaches **Analyze**, implement/verify/release MCP tools require `gate_decision: APPROVE` from `sdd_run_analysis`. The server blocks tools such as `sdd_implement`, `sdd_generate_iac`, and `sdd_create_pr` centrally via `validateGateForTool` — not only when calling `sdd_advance_phase`.
+
+Rewriting SPECIFICATION.md, DESIGN.md, or TASKS.md invalidates the gate; re-run analysis before implementation.
+
+Phase bookkeeping: write-tools call `ensurePhasesThrough` so skipping `sdd_advance_phase` does not leave orphan phases (e.g. Discover stuck in `in_progress`).
+
 ## Key Artifacts per Phase
 
 - **CONSTITUTION.md** (Phase 0 — Init) — Project charter, scope boundaries, success criteria, stakeholder register
@@ -132,7 +133,7 @@ Hooks are configured in `sdd-hooks.json` with PreToolUse and PostToolUse matcher
 @specky-implementer                   (Phase 7 — scaffold code + tests)
 ```
 
-See [copilot-instructions.instructions.md](../../instructions/copilot-instructions.instructions.md) for the full agent catalog.
+See the target-specific instruction rule for the full runtime entry point guidance.
 
 ## Workflow Entry Points
 

package/.apm/skills/specky-spec-engineer/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: specky-spec-engineer
+description: "Use for Phase 2 (Specify): write SPECIFICATION.md with EARS, REQ-IDs, and acceptance criteria. Trigger on sdd_write_spec, sdd_turnkey_spec, sdd_validate_ears, or /specky-specify."
+---
+
+# Phase 2 — Specify
+
+## Prerequisites
+- CONSTITUTION.md and RESEARCH.md exist on `spec/NNN-*`
+
+## Workflow
+1. Read CONSTITUTION.md and RESEARCH.md
+2. Call `sdd_write_spec` or `sdd_turnkey_spec`
+3. Optional: call `sdd_figma_to_spec`
+4. Call `sdd_validate_ears` and fix every failure
+5. Present SPECIFICATION.md for LGTM at the Phase 2 gate
+
+## EARS
+Use the canonical 6 patterns in `../specky-sdd-pipeline/references/ears-notation.md`.
+
+## REQ-ID Format
+`REQ-{DOMAIN}-{NNN}` — unique, uppercase domain, zero-padded sequence.
+
+## Hard Rules
+- Every requirement needs an EARS pattern, REQ-ID, and measurable acceptance criteria
+- Always run `sdd_validate_ears` before presenting
+- Branch must be `spec/NNN-*`

package/.apm/skills/specky-task-planner/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: specky-task-planner
+description: "Use for Phase 5 (Tasks): produce TASKS.md and CHECKLIST.md with dependencies, REQ traceability, and complexity. Trigger on sdd_write_tasks, sdd_checklist, or /specky-tasks."
+---
+
+# Phase 5 — Tasks
+
+## Prerequisites
+- Approved DESIGN.md at the Phase 4 LGTM gate
+
+## Workflow
+1. Read DESIGN.md and SPECIFICATION.md
+2. Call `sdd_write_tasks` to create TASK-NNN items with [P], S/M/L/XL, dependencies, and REQ links
+3. Call `sdd_checklist` for security, testing, and NFR checks
+4. Present TASKS.md and CHECKLIST.md for LGTM at the Phase 5 gate
+
+## Hard Rules
+- Every task traces to at least one REQ-ID
+- Parallel tasks are marked `[P]`
+- Dependencies are explicit

package/CHANGELOG.md

@@ -7,6 +7,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.10.0] - 2026-07-13
+
+Pipeline MCP hardening and harness completeness: server-enforced analysis gates, strict phase bookkeeping, and expanded per-target doctor/install coverage.
+
+### Added
+
+- **Central analysis gate enforcement** via `validateGateForTool` in tool-enforcement — implement/verify/release tools require `gate_decision: APPROVE` once the pipeline reaches Analyze.
+- **`ensurePhasesThrough`** closes orphan phase states when write-tools run without intermediate `sdd_advance_phase` calls.
+- **`invalidateGateDecision`** clears stale approvals when SPEC/DESIGN/TASKS are rewritten.
+- **Strict feature resolution** — wrong `feature_number` throws instead of silently falling back to `features[0]`.
+- **OpenCode instruction primitive** (`.apm/instructions/opencode-instructions.instructions.md`) and target-aware `specky compile --target=opencode`.
+- **Expanded Cursor instructions** with full agent/command/gate documentation.
+- **Doctor checks:** Copilot hooks manifest, Claude hooks-in-settings, agent-skills skill count, OpenCode AGENTS.md advisory, improved workspace target inference (Cursor/OpenCode/agent-skills).
+- **Regression tests:** pipeline gate MCP integration, Cursor full install, mcp-writer dual VS Code schema, expanded pipeline-honesty and state-integrity coverage.
+
+### Changed
+
+- **`sdd_write_spec`** persists `discovery_answers` in SPECIFICATION.md, computes real EARS scores, blocks invalid EARS without `force: true`, and reorders phase recording (start-before-write).
+- **`sdd_run_analysis`** marks Analyze completed only on APPROVE; BLOCK/CHANGES_NEEDED leave Analyze in progress.
+- **`sdd_clarify`** no longer auto-completes Clarify — only starts the phase.
+- **`sdd_discover`** completes Discover phase and uses correct MCP `readOnlyHint`.
+- **`sdd_advance_phase`** loads `pipeline.require_lgtm` dynamically; LGTM check runs inside the state-machine lock.
+- **VS Code MCP registration** writes both `servers` and `mcpServers` for legacy compatibility.
+- **Claude/Cursor tool map** includes `MultiEdit` for `workspace.edit` parity with hook permissions.
+- **Doctor default targets** returns empty scope with guidance when no install metadata or signals are found (no more silent claude+copilot default).
+
+### Fixed
+
+- Analysis gate was only enforced on `sdd_advance_phase`, not on downstream implement tools.
+- Phase state could become inconsistent when skipping `advance_phase` between discover and specify.
+- Stale `gate_decision` survived artifact rewrites.
+- Multi-feature silent fallback to the wrong feature directory.
+- Cognitive-debt timing improved via start-before-write phase recording on write tools.
+- Audited public documentation and website assets (carried from unreleased work).
+- Aligned container security claims with the workflow (SBOM always; Cosign optional).
+
+## [3.9.0] - 2026-07-09
+
+Cursor-native hook automation, six dedicated phase skills, full `specky doctor` install parity across harnesses, and cross-target instruction isolation fixes.
+
+### Added
+
+- **Cursor-native hook automation.** `specky install --target=cursor` now installs `.cursor/hooks.json` (Cursor schema v1), the `.cursor/hooks/specky-run.sh` stdin adapter, and `.cursor/hooks/scripts/` (16 scripts). Blocking gates (artifact validation, phase gate, security scan, release gate) deny unsafe actions with `failClosed`; advisory gates warn without blocking.
+- **Six dedicated phase companion skills** (14 total): `specky-sdd-init`, `specky-spec-engineer`, `specky-sdd-clarify`, `specky-design-architect`, `specky-task-planner`, and `specky-quality-reviewer`. Each phase agent loads its dedicated skill first; `specky-sdd-pipeline` remains the shared cross-phase overview.
+- **Dedicated Cursor instruction primitive** compiled to `.cursor/rules/specky-sdd.mdc` with `alwaysApply` and a neutral title.
+- **Dedicated Claude instruction primitive** compiled to `.claude/rules/specky-sdd.md` with neutral naming (no Copilot title or `@workspace` references).
+- **Full `specky doctor` install parity** for Cursor (11 checks), Claude (10), Copilot (9), and OpenCode (7): agent/prompt/skill/hook-script counts, rule format, MCP registration, and a cross-target leakage scan.
+- Regression suites: `cursor-target`, `copilot-target`, `claude-target`, and `opencode-target`.
+- APM policy now allows the Cursor-native hook events (`sessionStart`, `beforeSubmitPrompt`, `beforeMCPExecution`, `afterMCPExecution`, `preToolUse`, `postToolUse`, `stop`).
+
+### Changed
+
+- Renamed the hook-manifest generator `scripts/build-claude-hooks.mjs` → `scripts/build-hook-manifests.mjs`; it now emits Claude, Copilot, **and** Cursor manifests from the single `.apm/hooks/sdd-hooks.json` source of truth.
+- `specky compile` is now target-aware: each target renders only its own instruction primitive (with the Copilot primitive as the neutral fallback) instead of concatenating every primitive into each root context file.
+- EARS notation is unified to the canonical six patterns (Ubiquitous, Event-driven, State-driven, Optional, Unwanted, Complex) across the rule, phase agents, and the `specky-sdd-pipeline` skill.
+- All slash-command prompts now carry an `argument-hint`.
+
+### Fixed
+
+- Copilot installs no longer copy the Cursor/Claude instruction primitives into `.github/instructions/` (cross-target leak); only the Copilot instruction is installed and stale primitives are removed.
+- Claude installs no longer receive the Copilot-named rule (`copilot-instructions.md`) or `@workspace`/`applyTo` leakage; the stale file is removed on install.
+- Copilot instruction content: merged the orphaned `## Rule #7`/`## Rule #8` headings back into the Key Rules list and replaced the outdated `@workspace /prompt-name` invocation with `/prompt-name`.
+- Corrected duplicated workflow step numbering in phase agents.
+
 ## [3.8.0] - 2026-07-07
 
 Wave 1 multi-harness APM targets (Cursor, OpenCode, Agent Skills) plus a multi-feature phase-advancement fix.