@skilly-hand/skilly-hand 0.29.2 → 0.30.0

package/CHANGELOG.md

@@ -16,6 +16,37 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.30.0] - 2026-06-20
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.30.0)
+
+### Added
+- _None._
+
+### Changed
+- Expanded `review-rangers` with an approval-gated Mender remediation loop, independent re-review, critical-stop rules, bounded termination, repository-native verification, and automatic `test-driven-development` installation.
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
+## [0.29.3] - 2026-06-20
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.29.3)
+
+### Added
+- _None._
+
+### Changed
+- Reworked `spec-driven-development` around a portable lifecycle with repository-native capability discovery, evidence-backed task state, explicit change control, and archive invariants.
+- Rebuilt `test-driven-development` guidance around evidence-based RED, GREEN, and REFACTOR cycles without fixed framework or test-runner assumptions.
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
 ## [0.29.2] - 2026-06-20
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.29.2)
 

package/README.md

@@ -47,9 +47,9 @@ The full skill catalog is also discoverable through the [skills.sh](https://www.
 npx skills add Davecelot/skilly-hand --skill '*'
 ```
 
-Use `npx skills add Davecelot/skilly-hand --list` to inspect the available skills before installing. The `skills/` directory is a GitHub-facing overlay made of symlinks to `catalog/skills/`; it helps skills.sh discover the catalog without changing the regular `npx skilly-hand` npm package contents or CLI flow.
+Use `npx skills add Davecelot/skilly-hand --list` to inspect the available skills before installing. The `skills/` directory is a generated GitHub-facing mirror of `catalog/skills/`, using real files because skills.sh discovers `SKILL.md` entries from GitHub's repository tree. Run `npm run skills:sync` after catalog changes; `npm run catalog:check` rejects mirror drift.
 
-Windows contributors who clone the repo locally should enable symlink support before checkout, for example with `git config --global core.symlinks true`, and may also need Developer Mode or elevated symlink privileges. If the repo was already checked out without symlinks, re-check out or reclone after enabling support.
+skills.sh adds a repository to its public catalog after a skill is installed through the official CLI with telemetry enabled. The public page and automated security audits may take a few minutes to appear after the first installation.
 
 ---
 

package/catalog/README.md

@@ -18,10 +18,10 @@ Published portable skills consumed by the `skilly-hand` CLI.
 | `project-teacher` | Scan the active project and teach any concept, code path, or decision using verified information, interactive questions, and simple explanations. Trigger: user asks to explain, understand, clarify, or learn about anything in the project or codebase. | core, workflow, education | all |
 | `prompt-engineering` | Guide users in writing, improving, evaluating, and tuning prompts for LLMs across factual, creative, structured, grounded, coding, safety-sensitive, and production scenarios. Trigger: writing, improving, evaluating, or tuning prompts for LLMs. | prompting, llm, workflow, quality | all |
 | `react-guidelines` | Guide React and Next.js code generation, review, and performance tuning using latest stable React verification and modern framework best practices. Trigger: generating, reviewing, refactoring, or optimizing React code artifacts in React projects. | react, frontend, workflow, best-practices | all |
-| `review-rangers` | Review code, decisions, and artifacts through a multi-perspective committee and a domain expert safety guard, then synthesize a structured verdict. | core, workflow, review, quality | all |
+| `review-rangers` | Review code, decisions, and artifacts through an independent committee and safety guard, then optionally run bounded, approval-gated remediation. Trigger: reviewing risky artifacts or remediating structured review findings. | core, workflow, review, quality | all |
 | `roaster` | Challenge plans with constructive roast-style critique that exposes weak assumptions, missing angles, shallow sequencing, and unclear success criteria. Trigger: when the user proposes, requests, or evaluates a plan of any kind. | core, workflow, planning, quality | all |
-| `spec-driven-development` | Plan, execute, and verify multi-step work through versioned specs with small, testable tasks. | core, workflow, planning | all |
-| `test-driven-development` | Guide implementation using the RED → GREEN → REFACTOR TDD cycle: write a failing test first, write the minimum code to pass, then refactor while tests stay green. | testing, workflow, quality, core | all |
+| `spec-driven-development` | Plan, execute, and verify multi-step work through versioned specs with small, testable tasks. Trigger: planning or executing feature work, bug fixes, and multi-phase implementation. | core, workflow, planning | all |
+| `test-driven-development` | Guide implementation through evidence-based RED, GREEN, and REFACTOR cycles without assuming a language, framework, or test runner. Trigger: implementing testable behavior or reproducing a regression with tests first. | testing, workflow, quality, core | all |
 | `token-optimizer` | Classify task complexity and right-size reasoning depth, context gathering, and response detail to reduce wasted tokens. | core, workflow, efficiency | all |
 | `user-story-crafting` | Create and refine user stories with structured quality gates, splitting heuristics, and lightweight story mapping for release slicing. Trigger: writing, restructuring, splitting, or sequencing user stories for delivery-ready backlog work. | product, workflow, planning, quality | all |
 

package/catalog/skills/review-rangers/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: "review-rangers"
-description: "Review code, decisions, and artifacts through a multi-perspective committee and a domain expert safety guard, then synthesize a structured verdict."
+description: "Review code, decisions, and artifacts through an independent committee and safety guard, then optionally run bounded, approval-gated remediation. Trigger: reviewing risky artifacts or remediating structured review findings."
 skillMetadata:
   author: "skilly-hand"
-  last-edit: "2026-04-26"
+  last-edit: "2026-06-20"
   license: "Apache-2.0"
-  version: "1.1.0"
-  changelog: "Added DECISIONS.md registry ownership guidance; preserves durable review insights and anti-slop decisions across sessions; affects review-rangers workflow, install scaffolding, and project memory usage"
-  auto-invoke: "Reviewing code, decisions, or artifacts where adversarial multi-perspective evaluation adds value"
+  version: "1.2.0"
+  changelog: "Added approval-gated Mender remediation with bounded independent re-review; prevents unauthorized writes and unbounded fix loops; affects review orchestration, installation dependencies, and prompt assets"
+  auto-invoke: "Reviewing risky code, decisions, or artifacts, or remediating structured review findings"
   allowed-tools:
     - "Read"
     - "Edit"
@@ -48,8 +48,13 @@ Do not use this skill for:
 7. Run the committee and safety guard in parallel.
 8. Collect all outputs.
 9. Synthesize a structured verdict following the Synthesis Rules.
-10. Emit the final verdict with confidence tier, top findings, and recommended action.
-11. Decide whether any insight qualifies for `.ai/DECISIONS.md`; if yes, update the registry and its changelog in the same edit.
+10. If the verdict is `HIGH`, emit the final report and stop. If it is `VETO` or any critical-stop condition applies, return control to a human without modifying the target.
+11. For `MEDIUM` or `LOW`, present the open findings and request explicit approval before the first mutation. Skip this checkpoint only when the caller explicitly requested unattended or autonomous remediation in the current task.
+12. After approval, invoke The Mender using `assets/mender-template.md`. Pass only the target context and open findings; do not pass intermediate reviewer discussion.
+13. Run repository-native verification, then send the changed target to a fresh independent committee and safety guard. Reviewers from every round remain read-only.
+14. Repeat only while progress is material and no termination rule applies. Allow at most three remediation rounds and stop when the same finding survives two consecutive rounds without material progress.
+15. Emit the final report with confidence tier, finding-to-fix evidence, unresolved items, stop reason when applicable, and recommended action.
+16. Evaluate durable `.ai/DECISIONS.md` updates after the final `HIGH` report or terminal escalation; if an insight qualifies, update the registry and its changelog in the same edit.
 
 ---
 
@@ -80,6 +85,7 @@ Never assign the same lens to two committee members. Each member evaluates indep
 - Spawn committee members in parallel.
 - Pass only the target artifact and the member's assigned lens as context.
 - Do not share intermediate findings between members before synthesis.
+- Committee members and the safety guard are read-only in every round. They MUST NOT modify the target, assign work, or reuse another reviewer's conclusions.
 
 ---
 
@@ -108,6 +114,66 @@ The safety guard:
 
 ---
 
+## Remediation Protocol
+
+### Role Separation
+
+The Mender is the only role allowed to modify the target during a Review Rangers remediation cycle.
+
+- Committee members and the safety guard remain independent, read-only judges.
+- The Mender receives the synthesized open findings and target context, not reviewer identities or hidden reasoning.
+- The Mender MUST NOT assign, raise, lower, or otherwise edit confidence tiers.
+- The orchestrator owns approval, round counting, critical-stop evaluation, re-review, and the final verdict.
+- A Mender MUST NOT invoke Review Rangers recursively. Re-review returns to the orchestrator.
+
+### Approval Boundary
+
+Interactive review MUST pause before the first file mutation and obtain explicit approval.
+
+- A request to review, assess, audit, or invoke this skill is not write approval.
+- Skill invocation alone is not write approval.
+- The checkpoint may be skipped only when the caller explicitly asks for unattended or autonomous remediation in the current task.
+- Approval covers only the presented open findings and target. New scope or a critical-stop condition returns control to the caller.
+
+### Critical Stops
+
+Stop before another mutation or remediation round when any of these applies:
+
+- The verdict is `VETO`.
+- A security, privacy, accessibility, or data-integrity blocker requires human judgment.
+- A fix would cause a breaking public API change.
+- A fix would alter a broadly shared foundation, architecture, release policy, CI/CD policy, or security policy without explicit authority.
+- Required repository-native verification is unavailable or failing for reasons the remediation cannot safely resolve.
+- Product intent, ownership, migration policy, or another authoritative decision is required.
+- Three remediation rounds have completed.
+- The same finding survives two consecutive rounds without material progress.
+
+For every stop, report the unresolved finding, available evidence, stop reason, and required human decision. Do not broaden scope to conceal a failed check or force a higher confidence tier.
+
+### Repository-Native Verification
+
+The Mender MUST discover and run the narrowest relevant verification supported by the target repository.
+
+1. Read repository instructions and declared scripts or commands.
+2. Choose relevant lint, test, type-check, build, artifact, or deterministic document checks.
+3. When testable behavior changes, follow the installed `test-driven-development` guidance and record RED, GREEN, REFACTOR, and regression evidence.
+4. For non-code artifacts, use the narrowest deterministic structural or content check.
+5. Report exact commands, outcomes, failures, and checks that could not run.
+
+Never assume npm, a particular test runner, or a fixed toolchain. A failed required check blocks `HIGH` unless a human explicitly accepts the residual risk.
+
+### Re-review and Termination
+
+- Every remediation round receives a monotonically increasing round number from 1 through 3.
+- After verification, use a fresh committee and safety guard with the same independence rules as the initial review.
+- Compare findings by underlying issue, not wording alone.
+- Material progress means a finding is resolved, reduced in severity with evidence, or narrowed by a verified constraint.
+- `HIGH` ends the loop successfully.
+- `MEDIUM` or `LOW` may enter another approved round only when progress is material and no stop applies.
+- Any stop ends the loop with a terminal escalation report.
+
+---
+
 ## Synthesis Rules
 
 ### Confidence Tiers
@@ -194,6 +260,8 @@ Every change to `.ai/DECISIONS.md` must update `## Changelog` in the same edit.
 
 If the changelog section is missing, add it as the final section before making any other registry change.
 
+Evaluate registry writes only after the final `HIGH` report or terminal escalation. Intermediate remediation rounds MUST NOT create duplicate or provisional decision entries.
+
 ---
 
 ## Decision Tree
@@ -215,6 +283,17 @@ Does any committee member flag a security or data-integrity risk?
 Does committee majority agree the target is sound?
   YES and safety guard passes -> HIGH or MEDIUM depending on split
   NO                          -> LOW
+
+Is the verdict MEDIUM or LOW without a critical stop?
+  YES -> obtain explicit mutation approval unless unattended remediation was explicitly requested
+
+Is remediation approved and within the termination bounds?
+  YES -> invoke The Mender, verify with repository-native checks, then run a fresh independent review
+  NO  -> emit a terminal escalation report
+
+Did the review reach HIGH, three rounds, or two stagnant rounds?
+  YES -> stop and emit the final report
+  NO  -> continue only when material progress is evidenced
 ```
 
 ---
@@ -227,6 +306,9 @@ cat .skilly-hand/catalog/review-rangers/assets/committee-member-template.md
 
 # Reference safety guard template when constructing agent prompts
 cat .skilly-hand/catalog/review-rangers/assets/safety-guard-template.md
+
+# Reference the only write-capable remediation template after approval
+cat .skilly-hand/catalog/review-rangers/assets/mender-template.md
 ```
 
 ---
@@ -235,3 +317,5 @@ cat .skilly-hand/catalog/review-rangers/assets/safety-guard-template.md
 
 - Committee member prompt template: [assets/committee-member-template.md](assets/committee-member-template.md)
 - Safety guard prompt template: [assets/safety-guard-template.md](assets/safety-guard-template.md)
+- Mender prompt template: [assets/mender-template.md](assets/mender-template.md)
+- Test-driven remediation guidance: [../test-driven-development/SKILL.md](../test-driven-development/SKILL.md)

package/catalog/skills/review-rangers/assets/mender-template.md

@@ -0,0 +1,70 @@
+# The Mender: Remediation Round {{ROUND_NUMBER}}
+
+## Role
+
+You are The Mender, the only write-capable role in this Review Rangers remediation cycle. You repair approved findings; you do not judge the target or choose the final verdict.
+
+## Target
+
+{{TARGET_CONTEXT}}
+
+## Approved Open Findings
+
+{{OPEN_FINDINGS}}
+
+## Repository Context
+
+{{REPOSITORY_INSTRUCTIONS_AND_COMMANDS}}
+
+## Remediation Instructions
+
+1. Confirm every requested change maps to an approved open finding.
+2. Read repository instructions, conventions, scripts, and the affected files before editing.
+3. Stop and return control when a critical-stop condition, new scope, or required authority is discovered.
+4. Apply the smallest coherent fix for each finding. Preserve unrelated behavior and user changes.
+5. For testable behavior, follow the installed `test-driven-development` guidance and record RED, GREEN, REFACTOR, and regression evidence.
+6. For non-code changes, use the narrowest deterministic structural or content check.
+7. Run repository-native verification. Do not assume a package manager, test runner, language, or fixed command.
+8. Return a finding-to-fix map, files changed, exact verification outcomes, unresolved items, and any required human decision.
+
+## Critical Stops
+
+Do not mutate further when remediation requires any of the following without explicit authority:
+
+- Resolving a `VETO` or a security, privacy, accessibility, or data-integrity blocker that requires human judgment.
+- Introducing a breaking public API change.
+- Changing a broadly shared foundation, architecture, release policy, CI/CD policy, or security policy.
+- Proceeding without required verification or concealing a failing check.
+- Choosing product intent, migration policy, ownership, or another authoritative decision.
+
+## Output Format
+
+```text
+ROUND: {{ROUND_NUMBER}}
+
+FINDING-TO-FIX MAP:
+1. Finding: {stable finding summary}
+   Fix: {what changed and why it addresses the finding}
+   Files: {paths}
+   Status: {Resolved | Partially resolved | Unresolved | Stopped}
+
+VERIFICATION:
+1. {exact command or deterministic check} -> {PASS | FAIL | NOT_RUN}
+   Evidence: {short factual result}
+
+UNRESOLVED ITEMS:
+1. {finding or none}
+
+STOP REASON:
+{none | critical-stop condition and required human decision}
+```
+
+## Constraints
+
+- MUST modify only the approved target and findings.
+- MUST preserve unrelated user changes.
+- MUST use repository-native verification and report failures honestly.
+- MUST NOT change confidence, assign a confidence tier, or claim the review passed.
+- MUST NOT invoke Review Rangers, committee members, or the safety guard recursively.
+- MUST NOT edit `.ai/DECISIONS.md`; final registry timing belongs to the orchestrator.
+- MUST NOT begin another remediation round.

package/catalog/skills/review-rangers/manifest.json

@@ -1,7 +1,7 @@
 {
   "id": "review-rangers",
   "title": "Review Rangers",
-  "description": "Review code, decisions, and artifacts through a multi-perspective committee and a domain expert safety guard, then synthesize a structured verdict.",
+  "description": "Review code, decisions, and artifacts through an independent committee and safety guard, then optionally run bounded, approval-gated remediation. Trigger: reviewing risky artifacts or remediating structured review findings.",
   "portable": true,
   "tags": ["core", "workflow", "review", "quality"],
   "detectors": ["always"],
@@ -10,11 +10,11 @@
   "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
   "skillMetadata": {
     "author": "skilly-hand",
-    "last-edit": "2026-04-26",
+    "last-edit": "2026-06-20",
     "license": "Apache-2.0",
-    "version": "1.1.0",
-    "changelog": "Added DECISIONS.md registry ownership guidance; preserves durable review insights and anti-slop decisions across sessions; affects review-rangers workflow, install scaffolding, and project memory usage",
-    "auto-invoke": "Reviewing code, decisions, or artifacts where adversarial multi-perspective evaluation adds value",
+    "version": "1.2.0",
+    "changelog": "Added approval-gated Mender remediation with bounded independent re-review; prevents unauthorized writes and unbounded fix loops; affects review orchestration, installation dependencies, and prompt assets",
+    "auto-invoke": "Reviewing risky code, decisions, or artifacts, or remediating structured review findings",
     "allowed-tools": [
       "Read",
       "Edit",
@@ -29,7 +29,8 @@
   "files": [
     { "path": "SKILL.md", "kind": "instruction" },
     { "path": "assets/committee-member-template.md", "kind": "asset" },
-    { "path": "assets/safety-guard-template.md", "kind": "asset" }
+    { "path": "assets/safety-guard-template.md", "kind": "asset" },
+    { "path": "assets/mender-template.md", "kind": "asset" }
   ],
-  "dependencies": []
+  "dependencies": ["test-driven-development"]
 }

package/catalog/skills/spec-driven-development/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: "spec-driven-development"
-description: "Plan, execute, and verify multi-step work through versioned specs with small, testable tasks."
+description: "Plan, execute, and verify multi-step work through versioned specs with small, testable tasks. Trigger: planning or executing feature work, bug fixes, and multi-phase implementation."
 skillMetadata:
   author: "skilly-hand"
-  last-edit: "2026-04-03"
+  last-edit: "2026-06-20"
   license: "Apache-2.0"
-  version: "1.0.3"
-  changelog: "Added OpenSpec complementary support routing guidance to spec-driven-development instructions; improves planning continuity and review clarity when local SDD needs reinforcement; affects spec-driven-development SKILL guidance and manifest metadata"
+  version: "1.1.0"
+  changelog: "Added a portable SDD lifecycle with capability-based routing, task evidence, change control, and archive invariants; prevents fixed tool dependencies and duplicated task state; affects planning, apply, verify, orchestrate, and spec templates"
   auto-invoke: "Planning or executing feature work, bug fixes, and multi-phase implementation"
   allowed-tools:
     - "Read"
@@ -22,192 +22,143 @@ skillMetadata:
 
 ## When to Use
 
-Use this skill when:
+Use this skill when work spans multiple steps, requirements need written boundaries, or progress must survive across contributors or sessions.
 
-- Work spans multiple commits or phases.
-- Requirements are easy to misinterpret without written constraints.
-- You need a repeatable plan that can be reviewed before coding.
-- Several contributors or sessions may touch the same feature.
+Skip it for trivial edits, urgent recovery work, and tasks with no meaningful verification path.
 
-Do not use this skill for:
+## Portable Contract
 
-- Trivial one-file edits.
-- Emergency fixes where immediate response matters more than process.
-- Tasks with no meaningful verification path.
+The workflow MUST remain executable with this skill alone.
 
----
-
-## Core Workflow
-
-1. Define the spec in `.sdd/active/<feature-name>/spec.md`.
-2. Review and refine scope, constraints, and tasks.
-3. Execute one small task at a time.
-4. Verify each task and the end-to-end outcome, ending with a required `review-rangers` final gate.
-5. Archive to `.sdd/archive/` when complete.
-
-Recommended task size:
-
-- Up to 3 files per task.
-- Around 30 minutes of implementation effort.
-- Clear, concrete verify step.
+- Treat integrations as optional capabilities, never required product names.
+- Discover available tools, commands, and repository conventions before selecting them.
+- When a capability is unavailable, use a local structured fallback or record a blocker.
+- Keep requirements, tasks, progress, evidence, and changes in `spec.md` as the single source of truth.
+- Do not create a second task list that can drift from the spec.
 
----
-
-## OpenSpec Complementary Support
+## Lifecycle
 
-Default execution SHOULD remain the local `.sdd` workflow.
+```text
+DRAFT -> APPROVED -> IN_PROGRESS -> VERIFYING -> COMPLETE -> ARCHIVED
+             |             |            |
+             +----------> BLOCKED <------+
+```
 
-Recur to OpenSpec support when the task needs complementary structure for:
+Rules:
 
-- Multi-session continuity where planning context must persist across chats.
-- Shareable planning artifacts for review before implementation.
-- Requirement-delta clarity that benefits from explicit change proposals.
+1. Planning creates or updates `.sdd/active/<work-name>/spec.md`.
+2. Implementation begins after the approval policy is satisfied.
+3. Only one task should normally be `IN_PROGRESS` at a time.
+4. A task becomes `DONE` only after its verify step passes and evidence is recorded.
+5. Changed requirements return affected tasks to planning before implementation continues.
+6. Archive only after feature validation passes and no task remains open or blocked.
 
-Routing rules:
+Valid task states: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`.
 
-- Keep the local `.sdd/active/<feature-name>/spec.md` as the execution source of truth unless the team explicitly standardizes on OpenSpec paths.
-- If OpenSpec is unavailable, continue in `.sdd` and document assumptions directly in the active spec.
+## Approval Policy
 
-| Use local SDD only | Use OpenSpec support |
-| --- | --- |
-| Single-session or straightforward work with clear requirements | Work spans multiple sessions and needs persistent planning context |
-| Existing `.sdd` artifacts already provide enough review clarity | Team needs proposal/design/tasks artifacts for async review |
-| Requirement changes are small and easy to track in-place | Requirement deltas are complex and need explicit change framing |
+Use an explicit human checkpoint when the user requests one, requirements remain ambiguous, risk is material, or the next action is difficult to reverse. Otherwise, a documented self-review may satisfy approval.
 
-Reference (informational): [https://openspec.dev/](https://openspec.dev/)
-
----
+Record the chosen approval policy in the spec. Do not assume every environment supports interactive checkpoints.
 
 ## Spec Structure
 
-A practical spec includes:
-
-- `Why`: problem and urgency.
-- `What`: concrete deliverable.
-- `Constraints`: `MUST`, `MUST NOT`, out-of-scope boundaries.
-- `Current State`: relevant code context.
-- `Tasks`: small implementation units with verify steps.
-- `Validation`: full feature checks after all tasks.
-
-For existing features with behavior changes, use a delta format (`ADDED`, `MODIFIED`, `REMOVED`) instead of rewriting everything.
-
----
+A practical spec contains:
 
-## When to Use Delta vs Full Spec
+- `Why`: problem and value.
+- `What`: concrete, testable deliverable.
+- `Constraints`: enforceable `MUST`, `SHOULD`, `MAY`, and `MUST NOT` statements.
+- `Out of Scope`: explicit boundaries.
+- `Current State`: verified context and integration points.
+- `Approval Policy`: checkpoint or self-review rule.
+- `Tasks`: small units with scenarios, capabilities, files, verify steps, and done definitions.
+- `Progress`: task state and evidence.
+- `Validation`: end-to-end checks.
+- `Change Log`: requirement or scope changes that affect execution.
 
-| Use Full Spec | Use Delta Spec |
-| --- | --- |
-| New feature with no previous spec | Behavior change to an existing feature |
-| Greenfield implementation | Bug fix or requirement adjustment |
-| No requirement baseline exists | Existing requirements already exist |
+### Task Contract
 
-## Archive Behavior
+Each task MUST define:
 
-When archiving a delta spec, apply changes to the base specification:
+```markdown
+### T1: Title
 
-- `ADDED`: append new requirements.
-- `MODIFIED`: replace the previous requirement text.
-- `REMOVED`: delete the requirement and keep a short reason in commit history.
-
-Then move work from `.sdd/active/<feature-name>/` to `.sdd/archive/<feature-name>/`.
-
-## Task Design Principles
-
-- Keep task scope small: if a task touches more than 3 files or needs more than about 30 minutes, split it.
-- Keep verification fast: each task should be verifiable in 2 minutes or less.
-- Keep completion explicit: each task must have a one-sentence definition of done.
+**What:** Observable outcome.
+**Required Capabilities:** Semantic needs, or `none`.
+**Files:** Expected scope, or `discover` when not yet known.
+**Scenario:** GIVEN / WHEN / THEN, when behavior is involved.
+**Verify:** Project-discovered command or concrete manual check.
+**Done:** One sentence describing completion.
+```
 
-## Decision Tree: When to Break Tasks Smaller
+Capabilities describe needs such as test design, accessibility review, or security analysis. They MUST NOT require a particular skill, agent, vendor, or service. Resolve them against what is actually available at execution time.
 
-```text
-Does the task touch > 3 files?
-  YES -> split it
+## Full vs Delta Spec
 
-Will the task take > 30 minutes?
-  YES -> split it
+Use a full spec for new work without an existing requirement baseline. Use a delta spec for changes to established behavior.
 
-Can the task be verified in <= 2 minutes?
-  NO -> add a tighter verify step
+- `ADDED`: new requirement and scenarios.
+- `MODIFIED`: complete replacement requirement plus previous behavior reference.
+- `REMOVED`: removed requirement plus reason.
 
-Can "done" be described in one sentence?
-  NO -> task is too vague; split it
-```
+Before archiving a delta, reconcile it with the maintained requirement baseline when one exists. If no baseline exists, archive the delta as the historical record.
 
-## Common Mistakes to Avoid
+## Task Sizing
 
-### 1) Vague Constraints
+Prefer tasks that:
 
-```text
-WRONG:
-Must use best practices.
+- Have one observable outcome.
+- Touch a small, related file set.
+- Can be completed without hidden dependencies.
+- Have a fast, deterministic verify step.
+- Have a one-sentence definition of done.
 
-RIGHT:
-MUST use existing auth middleware.
-MUST NOT add new runtime dependencies.
-```
+Split a task when its concerns, dependencies, or verification cannot be explained independently. File counts and time estimates are heuristics, not universal gates.
 
-### 2) Oversized Tasks
+## Change Control
 
-```text
-WRONG:
-T1: Build the whole authentication feature.
+When requirements change during execution:
 
-RIGHT:
-T1: Add token verification middleware.
-T2: Add login endpoint behavior.
-T3: Add integration test for login flow.
-```
+1. Stop the affected task at a stable point.
+2. Record the change and reason in `Change Log`.
+3. Update affected constraints, scenarios, tasks, and validation.
+4. Mark invalidated evidence as superseded.
+5. Reapply the approval policy before continuing.
 
-### 3) Missing Verification
+Do not silently stretch a task to absorb new behavior.
 
-```text
-WRONG:
-Verify: It works.
+## Verification and Review
 
-RIGHT:
-Verify: npm test -- src/auth/login.test.ts
-```
+Verification checks behavior against the spec, not against implementation intent.
 
-### 4) Mixed Concerns in One Task
+- Run every task verify step using project-discovered commands.
+- Check every `MUST` and `MUST NOT` constraint explicitly.
+- Separate automated evidence, manual evidence, warnings, and blockers.
+- Perform a final structured review using an available review capability or the fallback checklist in `agents/verify.md`.
+- A missing optional integration is not a failure when the local fallback was completed.
 
-```text
-WRONG:
-T1: Create component and migrate all pages to it.
+## Archive Invariants
 
-RIGHT:
-T1: Create component.
-T2: Migrate page A.
-T3: Migrate page B.
-```
+Archive to `.sdd/archive/<YYYY-MM-DD>-<work-name>/` only when:
 
-Use the full preflight and pre-archive checks in [assets/validation-checklist.md](assets/validation-checklist.md).
+- All tasks are `DONE`.
+- Validation passes or approved manual checks are recorded.
+- No blocker is unresolved.
+- Constraint and final-review evidence is present.
+- Delta reconciliation is complete when applicable.
 
----
+Generate the ISO date from the current environment; do not assume a particular shell command or VCS.
 
 ## Modes
 
-Use these mode guides for role-focused execution:
-
-- Planning mode: [agents/plan.md](agents/plan.md)
-- Implementation mode: [agents/apply.md](agents/apply.md)
-- Verification mode: [agents/verify.md](agents/verify.md)
-- Orchestrator mode: [agents/orchestrate.md](agents/orchestrate.md)
-
----
+- Planning: [agents/plan.md](agents/plan.md)
+- Implementation: [agents/apply.md](agents/apply.md)
+- Verification: [agents/verify.md](agents/verify.md)
+- Orchestration: [agents/orchestrate.md](agents/orchestrate.md)
 
 ## Templates
 
-- Feature spec: [assets/spec-template.md](assets/spec-template.md)
+- Full spec: [assets/spec-template.md](assets/spec-template.md)
 - Delta spec: [assets/delta-spec-template.md](assets/delta-spec-template.md)
 - Design decisions: [assets/design-template.md](assets/design-template.md)
 - Validation checklist: [assets/validation-checklist.md](assets/validation-checklist.md)
-
----
-
-## Commands
-
-```bash
-mkdir -p .sdd/active/<feature-name>
-cp .skilly-hand/catalog/spec-driven-development/assets/spec-template.md .sdd/active/<feature-name>/spec.md
-cp .skilly-hand/catalog/spec-driven-development/assets/design-template.md .sdd/active/<feature-name>/design.md
-```