Command rename

.agents/skills/devspec-grooming.md → .agents/skills/devspec-refine.md

@@ -1,5 +1,5 @@
 ---
-name: devspec-grooming
+name: devspec-refine
 description: Make one draft story buildable through scoped review and material questions.
 ---
-Read and execute `devspec/contracts/devspec.grooming.md`.
+Read and execute `devspec/contracts/devspec.refine.md`.

.claude/skills/devspec-grooming/SKILL.md → .claude/skills/devspec-refine/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: devspec-grooming
+name: devspec-refine
 description: Make one draft story buildable through scoped review and material questions.
 ---
-Read and execute `devspec/contracts/devspec.grooming.md`.
+Read and execute `devspec/contracts/devspec.refine.md`.

.cursor/rules/devspec-workflow.mdc

@@ -2,4 +2,4 @@
 description: Devspec Lite workflow
 alwaysApply: false
 ---
-For `devspec.extract`, `devspec.projectcontext`, `devspec.techstack`, `devspec.codebase-structure`, `devspec.coding-standards`, `devspec.rules`, `devspec.story`, `devspec.grooming`, `devspec.clarify`, `devspec.changerequest`, `devspec.finalize`, `devspec.tasks`, `devspec.implement`, `devspec.review`, `devspec.diagram`, `devspec.quickfix`, read the matching `devspec/contracts/` file and listed protocols. For a clear continuation, resolve per-worktree current context and run only the saved next action; ask before switching stories.
+For `devspec.extract`, `devspec.projectcontext`, `devspec.techstack`, `devspec.codebase-structure`, `devspec.coding-standards`, `devspec.rules`, `devspec.story`, `devspec.refine`, `devspec.clarify`, `devspec.changerequest`, `devspec.finalize`, `devspec.tasks`, `devspec.implement`, `devspec.review`, `devspec.diagram`, `devspec.quickfix`, read the matching `devspec/contracts/` file and listed protocols. For a clear continuation, resolve per-worktree current context and run only the saved next action; ask before switching stories.

.gemini/commands/devspec/grooming.toml → .gemini/commands/devspec/refine.toml

@@ -1,2 +1,2 @@
 description = "Make one draft story buildable through scoped review and material questions."
-prompt = "Read and execute devspec/contracts/devspec.grooming.md"
+prompt = "Read and execute devspec/contracts/devspec.refine.md"

.github/agents/devspec.grooming.agent.md → .github/agents/devspec.refine.agent.md

@@ -1,6 +1,6 @@
 ---
-name: devspec.grooming
+name: devspec.refine
 description: Make one draft story buildable through scoped review and material questions.
 user-invocable: true
 ---
-Execute `devspec/contracts/devspec.grooming.md`.
+Execute `devspec/contracts/devspec.refine.md`.

.github/prompts/devspec.refine.prompt.md

@@ -0,0 +1,3 @@
+# devspec.refine
+
+Execute `devspec/contracts/devspec.refine.md`. Use only its listed protocols.

AGENTS.md

@@ -9,7 +9,7 @@ Use Git-tracked `devspec/` artifacts as canonical state. For a clear work-item c
 - `devspec.coding-standards`: read `devspec/contracts/devspec.coding-standards.md`.
 - `devspec.rules`: read `devspec/contracts/devspec.rules.md`.
 - `devspec.story`: read `devspec/contracts/devspec.story.md`.
-- `devspec.grooming`: read `devspec/contracts/devspec.grooming.md`.
+- `devspec.refine`: read `devspec/contracts/devspec.refine.md`.
 - `devspec.clarify`: read `devspec/contracts/devspec.clarify.md`.
 - `devspec.changerequest`: read `devspec/contracts/devspec.changerequest.md`.
 - `devspec.finalize`: read `devspec/contracts/devspec.finalize.md`.

README.md

@@ -33,7 +33,7 @@ Before a framework upgrade, inspect drift with `devspec diff --target .` and pre
 
 ![Delivery route for quickfix and work items](docs/assets/delivery-routes.svg)
 
-Use the [developer workflow guide](docs/workflows.md) for concrete quickfix, grooming, clarification, and change-request examples.
+Use the [developer workflow guide](docs/workflows.md) for concrete quickfix, refinement, clarification, and change-request examples.
 
 ## How to
 

devspec/README.md

@@ -2,7 +2,7 @@
 
 New repository foundation: `projectcontext → techstack → codebase-structure → coding-standards → rules`. Existing repository baseline: `extract` completes the foundation, prepares the applicable diagram list, and asks whether to generate all or selected diagrams. Rare durable cross-work-item principles live in `constitution.md` with stable `CP-###` IDs. `extract` records candidates from evidence; `projectcontext` promotes or retires them only on explicit input.
 
-Work item: `story → grooming → finalize → tasks → implement → review`. Grooming is the default step after intake; skip it only when the intake source itself carried explicit acceptance criteria and story.md lists no open requirement gap. Story intake accepts one manual request or, when an authenticated MCP connector is available, one read-only provider work-item reference.
+Work item: `story → refine → finalize → tasks → implement → review`. Every work item goes through refinement after intake, even when the source carried acceptance criteria. Story intake accepts one manual request or, when an authenticated MCP connector is available, one read-only provider work-item reference.
 After `story` selects a work item, use the normal work-item commands without repeating its ID. Per-worktree private context resolves the selected story and its recorded `next` action; use an ID only to switch or disambiguate stories.
 
 Use `clarify` only for an active blocker and `quickfix` only for localized, low-risk changes. See `lifecycle.md` for all command transitions.

devspec/command-registry.md

@@ -10,15 +10,15 @@ Purpose and next route are the contract's own `<purpose>` and `<transition next>
 | `devspec.codebase-structure` | Capture or customize owned source roots, repository layouts, module boundaries, integrations, and repository access. | `devspec.coding-standards`, `return-to-caller`, `devspec.clarify` |
 | `devspec.coding-standards` | Capture concise, reusable coding conventions, followable examples, and anti-patterns from source evidence or developer-defined standards. | `devspec.rules`, `return-to-caller`, `devspec.clarify` |
 | `devspec.rules` | Capture non-negotiable engineering, security, compliance, delivery, and accessibility rules. | `devspec.story`, `return-to-caller`, `devspec.clarify` |
-| `devspec.story` | Create one concise work-item intake from a request or provider reference. | `devspec.grooming`, `devspec.finalize`, `devspec.clarify` |
-| `devspec.grooming` | Make one draft story buildable through scoped review and material questions. | `devspec.finalize`, `devspec.clarify` |
+| `devspec.story` | Create one concise work-item intake from a request or provider reference. | `devspec.refine`, `devspec.clarify` |
+| `devspec.refine` | Make one draft story buildable through scoped review and material questions. | `devspec.finalize`, `devspec.clarify` |
 | `devspec.clarify` | Resolve one active blocker and resume its originating stage. | `resume-origin` |
-| `devspec.changerequest` | Append one related post-finalization requirement without rewriting history. | `devspec.finalize`, `devspec.clarify` |
-| `devspec.finalize` | Produce a concise readiness brief and validation plan. | `devspec.tasks`, `devspec.clarify` |
+| `devspec.changerequest` | Append one related post-finalization requirement without rewriting history. | `devspec.refine` |
+| `devspec.finalize` | Produce a concise readiness brief and validation plan. | `devspec.tasks`, `devspec.refine`, `devspec.clarify` |
 | `devspec.tasks` | Create ordered, independently verifiable implementation tasks. | `devspec.implement`, `devspec.clarify` |
 | `devspec.implement` | Implement pending ready tasks with focused checkpoints and validation. | `devspec.review`, `devspec.clarify` |
 | `devspec.review` | Review changed work against readiness, tasks, and validation evidence. | `none`, `devspec.implement`, `devspec.clarify` |
 | `devspec.diagram` | Create one evidence-backed diagram with duplicate checks and durable queue state. | `return-to-caller`, `devspec.clarify`, `none` |
 | `devspec.quickfix` | Implement and validate one localized, low-risk enhancement or bug fix. | `none`, `devspec.clarify`, `devspec.story` |
 
-Work-item IDs are optional for `grooming`, `finalize`, `tasks`, `implement`, `review`, `clarify`, and `changerequest`. Without an ID, resolve the private per-worktree current context and run only the work item's recorded `next` action. Use an explicit ID to switch stories; when several eligible work items exist, ask the developer to choose.
+Work-item IDs are optional for `refine`, `finalize`, `tasks`, `implement`, `review`, `clarify`, and `changerequest`. Without an ID, resolve the private per-worktree current context and run only the work item's recorded `next` action. Use an explicit ID to switch stories; when several eligible work items exist, ask the developer to choose.

devspec/contracts/devspec.changerequest.md

@@ -18,8 +18,9 @@ Invocation: `/devspec.changerequest [work-item-id] Add JSON export`
   <input>An optional work-item ID and one related missing requirement.</input>
   <rules>
     <rule>Append the next CR-### entry and CR-scoped criteria; never rewrite baseline evidence.</rule>
+    <rule>List every requirement gap the change leaves open in story.md's Open Requirement Gaps table, raised by its CR-### ID, and ask none of them; devspec.refine owns those questions.</rule>
     <rule>Mark the earlier finalization, task, implementation, and review sections superseded when the revision increments, preserving their recorded evidence unchanged.</rule>
-    <rule>Ask one material classification question when it is unclear whether the request is related or a new linked work item.</rule>
+    <rule>Ask one material classification question when it is unclear whether the request is related or a new linked work item. Until the request is classified related, leave the work item's stage and next action unchanged: route an independent request to devspec.story as a linked work item, and when the developer cannot answer yet, stop with the question unanswered in decisions.md.</rule>
   </rules>
   <entry>Related requirement for a finalized-or-later work item with an active current scope revision; reject independent, blocked, or pre-finalization requests.</entry>
   <outputs>
@@ -32,8 +33,6 @@ Invocation: `/devspec.changerequest [work-item-id] Add JSON export`
     <artifact path="devspec/work-items/&lt;id&gt;/review.md" />
   </outputs>
   <transitions>
-    <transition outcome="related-change-accepted" stage="finalization" run="active" next="devspec.finalize" />
-    <transition outcome="classification-blocked" stage="finalization" run="blocked" next="devspec.clarify" />
-  </transitions>
+    <transition outcome="related-change-accepted" stage="refinement" run="active" next="devspec.refine" />  </transitions>
   <closure>Append the CR and record the classification that justified it.</closure>
 </workflow>

devspec/contracts/devspec.finalize.md

@@ -7,30 +7,31 @@ Invocation: `/devspec.finalize [work-item-id]`
 <workflow command="devspec.finalize">
   <purpose>Produce a concise readiness brief and validation plan.</purpose>
   <protocols>
-    <protocol ref="ask" queue="single-blocker" />
+    <protocol ref="ask" />
     <protocol ref="run" />
     <protocol ref="state" />
     <protocol ref="current-work-item" />
     <protocol ref="revision" />
     <protocol ref="work" />
     <protocol ref="security" />
   </protocols>
-  <scope>Use to decide whether the current scope revision is buildable and to record its brief and validation plan. This command plans readiness only; devspec.tasks sequences the work and devspec.implement changes code.</scope>
-  <input>An optional work-item ID or a groomed current draft.</input>
+  <scope>Use to decide whether the current scope revision is buildable and to record its brief and validation plan. This command plans readiness only; devspec.refine owns requirements, devspec.tasks sequences the work, and devspec.implement changes code.</scope>
+  <input>An optional work-item ID or a refined current draft.</input>
   <rules>
-    <rule>Read only the current-revision story and decisions, the current-revision task statuses when a correction is requested from the tasks stage, the finalization traces' direct sources in coding standards, codebase structure, rules, workflow rules, constitution, and the architecture queue or overview. Do not scan unrelated work items, unrelated code areas, or historical revisions beyond the superseded sections of this work item.</rule>
-    <rule>devspec.grooming owns the requirement questions. Ask nothing whose answer it should already have recorded; when a requirement is still missing, record one blocker and route it rather than re-opening grooming's queue.</rule>
-    <rule>Check only material readiness gaps, judging buildability and verifiability rather than re-deriving requirements: whether the recorded scope and criteria can be built and validated as written, and the data, integration, security, compliance, validation, and delivery constraints that decide it. Those last are this command's own, and the security protocol's gate applies here rather than in grooming.</rule>
-    <rule>Reject the work item when story.md's Open Requirement Gaps table still holds an entry that is neither resolved nor explicitly skipped with its reason; record one blocker naming the open entries and route back through devspec.clarify to grooming.</rule>
-    <rule>Mark ready only when the remaining gaps cannot materially change implementation or validation; a gap that can becomes one material blocker question. Record every gap judged immaterial in the brief's Assumptions and Open Items section with its basis, impact if wrong, and status, rather than discarding it.</rule>
+    <rule>Read only the current-revision story and decisions, the code areas story.md's Affected Areas table records and their direct interfaces, the current-revision task statuses when a correction is requested from the tasks stage, the finalization traces' direct sources in coding standards, codebase structure, rules, workflow rules, constitution, and the architecture queue or overview. Do not scan unrelated work items, code areas the Affected Areas table does not record, or historical revisions beyond the superseded sections of this work item. At a tasks-stage correction of a story that predates the Affected Areas table, read the areas the current brief names instead.</rule>
+    <rule>devspec.refine owns every requirement question; ask none. At the finalization stage, check story.md's Open Requirement Gaps table before any other reading. Return the work item to devspec.refine when an entry is neither resolved nor explicitly skipped with its reason, or when the readiness check exposes a requirement gap: a missing behavior, criterion, edge case, compatibility requirement, or behavior-changing constraint, or an area the brief needs that the Affected Areas table does not record. Append each exposed gap to that table as raised by devspec.finalize before returning. This is a routing outcome, not a blocker: write no ready brief, leave `finalized_revision` unchanged, and record the open gap IDs in meta.md `last`.</rule>
+    <rule>Check only material readiness gaps, judging buildability and verifiability rather than re-deriving requirements. Build on what devspec.refine recorded and own the design and the proof: for data and integration, the schemas, migrations, contracts, and rollout order; for validation, the plan and evidence for each acceptance criterion; handling for the edge cases story.md records, and only those; the rollout and compatibility plan for the compatibility story.md requires; and foundation trace entries for the recorded technical constraints. A missing refine-owned item is a requirement gap for devspec.refine, never a design decision this command makes silently. Security, compliance, and delivery constraints are this command's own, and the security protocol's gate applies here rather than in refinement.</rule>
+    <rule>Run the ask protocol's discovery only across this command's own topics: security, compliance, and delivery constraints, the buildability of the recorded scope, and the confirmation the security protocol requires for each suspected false-positive or not-applicable finding. Ask them one at a time, resolve each answer into finalize.md or decisions.md, and record a material blocker for devspec.clarify only when the developer cannot answer yet.</rule>
+    <rule>Mark ready only when no remaining gap can materially change implementation or validation. Record every gap judged immaterial in the brief's Assumptions and Open Items section with its basis, impact if wrong, and status, rather than discarding it. Reference a gap devspec.refine skipped by its Open Requirement Gaps ID instead of restating or re-judging it; when that skipped gap turns out to change buildability, append a new entry that cites it, raised by devspec.finalize, and return the work item to devspec.refine.</rule>
     <rule>Accept a correction request re-entered from the tasks stage only while `implemented_revision` is behind `scope_revision` and no task is in-progress or complete. Rewrite the brief in place at the same scope revision, set its Status to revised, record what changed and why in decisions.md, mark the superseded task list `superseded`, and reset `planned_revision` to none so devspec.tasks re-plans against the corrected brief. This is a correction, not a change request: reject a new or widened requirement and route it to devspec.changerequest, which increments the revision instead.</rule>
     <rule>Classify every accepted material decision as work-item-local or reusable. Promote a reusable business or validation decision to devspec/foundation/workflow-rules.md with a stable rule ID and source decision link; promote a reusable engineering constraint to devspec/foundation/rules.md. Record the resulting canonical rule link in decisions.md.</rule>
     <rule>Record one compact foundation trace for the relevant coding conventions, owned areas and boundaries, canonical rules, applicable active `CP-###` principles, and the OWASP categories the change touches. Record a separate architecture and diagram trace for relevant overview entries, completed diagrams, or queued candidates, including implementation and validation impact; no diagram is required.</rule>
     <rule>Write a concise implementation brief and validation plan, not implementation code. Write the brief under its template sections so a developer can review the plan section by section, recording a section as not applicable with its reason rather than omitting it, and name the concrete components, interfaces, contracts, schemas, and migrations the work will touch instead of describing them in general terms.</rule>
   </rules>
-  <entry>Active work item at finalization with a complete current-revision story, or at tasks when the developer asks to correct the current-revision brief before implementation has begun; reject stale finalization, blocked work, incomplete draft scope, and a correction request once any task for the current revision is in-progress or complete.</entry>
+  <entry>Active work item at finalization with a current-revision story, or at tasks when the developer asks to correct the current-revision brief before implementation has begun; return a story whose Open Requirement Gaps table is not closed to devspec.refine, and reject stale finalization, blocked work, and a correction request once any task for the current revision is in-progress or complete.</entry>
   <outputs>
     <artifact path="devspec/work-items/&lt;id&gt;/finalize.md" />
+    <artifact path="devspec/work-items/&lt;id&gt;/story.md" />
     <artifact path="devspec/work-items/&lt;id&gt;/meta.md" />
     <artifact path="devspec/work-items/&lt;id&gt;/decisions.md" />
     <artifact path="devspec/work-items/&lt;id&gt;/tasks.md" />
@@ -39,6 +40,7 @@ Invocation: `/devspec.finalize [work-item-id]`
   </outputs>
   <transitions>
     <transition outcome="ready" stage="tasks" run="active" next="devspec.tasks" />
+    <transition outcome="requirement-gaps-open" stage="refinement" run="active" next="devspec.refine" />
     <transition outcome="material-blocker" stage="finalization" run="blocked" next="devspec.clarify" />
   </transitions>
   <closure>Stamp the readiness brief with the current scope revision. Preserve earlier revision sections as superseded history.</closure>