gspec 1.13.2 → 1.14.0

package/commands/gspec.architect.md

@@ -29,7 +29,7 @@ Before generating the architecture document, read **all** existing gspec documen
 4. **`gspec/practices.md`** — Development standards. Use this to align file organization, testing patterns, and code structure with team conventions.
 5. **`gspec/features/*.md`** — Individual feature requirements and dependencies. Use these to derive data entities, API endpoints, component structure, and integration points.
 
-All of these provide essential context. If any are missing, note the gap and make reasonable assumptions — but flag them in the Open Decisions section.
+All of these provide essential context. If any are missing, note the gap and ask the user to clarify before proceeding. If the user explicitly defers, make reasonable assumptions and record them in the Assumptions sub-section of the Technical Gap Analysis.
 
 ---
 
@@ -339,8 +339,9 @@ Examples of gaps to look for:
 - Technical decisions that were inferred rather than explicitly specified in existing specs
 
 ### 10. Open Decisions
-- Areas where the architecture may need to evolve as features are implemented
-- Questions that should be resolved before or during implementation
+- **All technical questions and decisions must be resolved by asking the user before the document is saved.** Do not save the architecture with unresolved questions.
+- If the user explicitly defers a decision, record it here with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
+- Areas where the architecture may need to evolve as features are implemented may be noted, but these must be acknowledged evolution points — not unresolved questions.
 
 ---
 

package/commands/gspec.feature.md

@@ -163,8 +163,8 @@ This separation — combined with the portability principles above — allows th
 
 ### 6. Assumptions & Risks
 - Assumptions (what we're taking as true)
-- Open questions — **only** unknowns that genuinely cannot be answered until implementation or real-world usage begins (e.g., performance thresholds pending benchmarking, exact rate limits pending load testing). Questions about scope, users, priorities, or feature design must be asked and resolved in the chat before the spec is written. If there are no open questions, omit this sub-section.
 - Key risks and mitigations (brief bullet points — focus on risks that could affect implementation scope or approach)
+- **No open questions** — All questions must be resolved by asking the user in the chat before the spec is saved. If the user explicitly defers a question, record it as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit the sub-section entirely. Never embed unresolved questions in the document by default.
 
 ### 7. Success Metrics
 - 2-4 measurable outcomes that define whether this feature is working

package/commands/gspec.research.md

@@ -154,7 +154,7 @@ After writing `gspec/research.md`, ask the user:
    - Scope (in-scope goals, out-of-scope items, deferred ideas)
    - Capabilities (with P0/P1/P2 priority levels, using **unchecked checkboxes** `- [ ]` for each capability, each with 2-4 **acceptance criteria** as a sub-list)
    - Dependencies (on other features or external services)
-   - Assumptions & Risks (assumptions, open questions, key risks and mitigations)
+   - Assumptions & Risks (assumptions, key risks and mitigations — all questions must be resolved in the chat before saving; only record explicitly deferred decisions)
    - Success Metrics
    - Implementation Context (standard portability note)
    - Begin the file with YAML frontmatter: `---\nspec-version: <<<SPEC_VERSION>>>\n---`

package/commands/gspec.stack.md

@@ -47,13 +47,8 @@ You should:
 - Deployment target (cloud, on-premise, hybrid)
 - Scale and performance requirements
 
-### 2. Open Questions & Clarifications
-**List any critical questions that need answers before finalizing technology choices**
-- Missing requirements that impact stack decisions
-- Unclear constraints or preferences
-- Team expertise or existing infrastructure questions
-- Budget or licensing considerations
-- **Mark as "None" if all information is clear**
+### 2. Clarifications
+**All questions that impact technology choices must be resolved by asking the user in the chat before the document is saved.** Do not save the stack spec with unresolved questions. If the user explicitly defers a decision, record it here as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
 
 ### 3. Core Technology Stack
 

package/dist/antigravity/gspec-architect/SKILL.md

@@ -34,7 +34,7 @@ Before generating the architecture document, read **all** existing gspec documen
 4. **`gspec/practices.md`** — Development standards. Use this to align file organization, testing patterns, and code structure with team conventions.
 5. **`gspec/features/*.md`** — Individual feature requirements and dependencies. Use these to derive data entities, API endpoints, component structure, and integration points.
 
-All of these provide essential context. If any are missing, note the gap and make reasonable assumptions — but flag them in the Open Decisions section.
+All of these provide essential context. If any are missing, note the gap and ask the user to clarify before proceeding. If the user explicitly defers, make reasonable assumptions and record them in the Assumptions sub-section of the Technical Gap Analysis.
 
 ---
 
@@ -344,8 +344,9 @@ Examples of gaps to look for:
 - Technical decisions that were inferred rather than explicitly specified in existing specs
 
 ### 10. Open Decisions
-- Areas where the architecture may need to evolve as features are implemented
-- Questions that should be resolved before or during implementation
+- **All technical questions and decisions must be resolved by asking the user before the document is saved.** Do not save the architecture with unresolved questions.
+- If the user explicitly defers a decision, record it here with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
+- Areas where the architecture may need to evolve as features are implemented may be noted, but these must be acknowledged evolution points — not unresolved questions.
 
 ---
 

package/dist/antigravity/gspec-feature/SKILL.md

@@ -168,8 +168,8 @@ This separation — combined with the portability principles above — allows th
 
 ### 6. Assumptions & Risks
 - Assumptions (what we're taking as true)
-- Open questions — **only** unknowns that genuinely cannot be answered until implementation or real-world usage begins (e.g., performance thresholds pending benchmarking, exact rate limits pending load testing). Questions about scope, users, priorities, or feature design must be asked and resolved in the chat before the spec is written. If there are no open questions, omit this sub-section.
 - Key risks and mitigations (brief bullet points — focus on risks that could affect implementation scope or approach)
+- **No open questions** — All questions must be resolved by asking the user in the chat before the spec is saved. If the user explicitly defers a question, record it as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit the sub-section entirely. Never embed unresolved questions in the document by default.
 
 ### 7. Success Metrics
 - 2-4 measurable outcomes that define whether this feature is working

package/dist/antigravity/gspec-research/SKILL.md

@@ -159,7 +159,7 @@ After writing `gspec/research.md`, ask the user:
    - Scope (in-scope goals, out-of-scope items, deferred ideas)
    - Capabilities (with P0/P1/P2 priority levels, using **unchecked checkboxes** `- [ ]` for each capability, each with 2-4 **acceptance criteria** as a sub-list)
    - Dependencies (on other features or external services)
-   - Assumptions & Risks (assumptions, open questions, key risks and mitigations)
+   - Assumptions & Risks (assumptions, key risks and mitigations — all questions must be resolved in the chat before saving; only record explicitly deferred decisions)
    - Success Metrics
    - Implementation Context (standard portability note)
    - Begin the file with YAML frontmatter: `---\nspec-version: v1\n---`

package/dist/antigravity/gspec-stack/SKILL.md

@@ -52,13 +52,8 @@ You should:
 - Deployment target (cloud, on-premise, hybrid)
 - Scale and performance requirements
 
-### 2. Open Questions & Clarifications
-**List any critical questions that need answers before finalizing technology choices**
-- Missing requirements that impact stack decisions
-- Unclear constraints or preferences
-- Team expertise or existing infrastructure questions
-- Budget or licensing considerations
-- **Mark as "None" if all information is clear**
+### 2. Clarifications
+**All questions that impact technology choices must be resolved by asking the user in the chat before the document is saved.** Do not save the stack spec with unresolved questions. If the user explicitly defers a decision, record it here as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
 
 ### 3. Core Technology Stack
 

package/dist/claude/gspec-architect/SKILL.md

@@ -34,7 +34,7 @@ Before generating the architecture document, read **all** existing gspec documen
 4. **`gspec/practices.md`** — Development standards. Use this to align file organization, testing patterns, and code structure with team conventions.
 5. **`gspec/features/*.md`** — Individual feature requirements and dependencies. Use these to derive data entities, API endpoints, component structure, and integration points.
 
-All of these provide essential context. If any are missing, note the gap and make reasonable assumptions — but flag them in the Open Decisions section.
+All of these provide essential context. If any are missing, note the gap and ask the user to clarify before proceeding. If the user explicitly defers, make reasonable assumptions and record them in the Assumptions sub-section of the Technical Gap Analysis.
 
 ---
 
@@ -344,8 +344,9 @@ Examples of gaps to look for:
 - Technical decisions that were inferred rather than explicitly specified in existing specs
 
 ### 10. Open Decisions
-- Areas where the architecture may need to evolve as features are implemented
-- Questions that should be resolved before or during implementation
+- **All technical questions and decisions must be resolved by asking the user before the document is saved.** Do not save the architecture with unresolved questions.
+- If the user explicitly defers a decision, record it here with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
+- Areas where the architecture may need to evolve as features are implemented may be noted, but these must be acknowledged evolution points — not unresolved questions.
 
 ---
 

package/dist/claude/gspec-feature/SKILL.md

@@ -168,8 +168,8 @@ This separation — combined with the portability principles above — allows th
 
 ### 6. Assumptions & Risks
 - Assumptions (what we're taking as true)
-- Open questions — **only** unknowns that genuinely cannot be answered until implementation or real-world usage begins (e.g., performance thresholds pending benchmarking, exact rate limits pending load testing). Questions about scope, users, priorities, or feature design must be asked and resolved in the chat before the spec is written. If there are no open questions, omit this sub-section.
 - Key risks and mitigations (brief bullet points — focus on risks that could affect implementation scope or approach)
+- **No open questions** — All questions must be resolved by asking the user in the chat before the spec is saved. If the user explicitly defers a question, record it as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit the sub-section entirely. Never embed unresolved questions in the document by default.
 
 ### 7. Success Metrics
 - 2-4 measurable outcomes that define whether this feature is working

package/dist/claude/gspec-research/SKILL.md

@@ -159,7 +159,7 @@ After writing `gspec/research.md`, ask the user:
    - Scope (in-scope goals, out-of-scope items, deferred ideas)
    - Capabilities (with P0/P1/P2 priority levels, using **unchecked checkboxes** `- [ ]` for each capability, each with 2-4 **acceptance criteria** as a sub-list)
    - Dependencies (on other features or external services)
-   - Assumptions & Risks (assumptions, open questions, key risks and mitigations)
+   - Assumptions & Risks (assumptions, key risks and mitigations — all questions must be resolved in the chat before saving; only record explicitly deferred decisions)
    - Success Metrics
    - Implementation Context (standard portability note)
    - Begin the file with YAML frontmatter: `---\nspec-version: v1\n---`

package/dist/claude/gspec-stack/SKILL.md

@@ -52,13 +52,8 @@ You should:
 - Deployment target (cloud, on-premise, hybrid)
 - Scale and performance requirements
 
-### 2. Open Questions & Clarifications
-**List any critical questions that need answers before finalizing technology choices**
-- Missing requirements that impact stack decisions
-- Unclear constraints or preferences
-- Team expertise or existing infrastructure questions
-- Budget or licensing considerations
-- **Mark as "None" if all information is clear**
+### 2. Clarifications
+**All questions that impact technology choices must be resolved by asking the user in the chat before the document is saved.** Do not save the stack spec with unresolved questions. If the user explicitly defers a decision, record it here as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
 
 ### 3. Core Technology Stack
 

package/dist/codex/gspec-architect/SKILL.md

@@ -34,7 +34,7 @@ Before generating the architecture document, read **all** existing gspec documen
 4. **`gspec/practices.md`** — Development standards. Use this to align file organization, testing patterns, and code structure with team conventions.
 5. **`gspec/features/*.md`** — Individual feature requirements and dependencies. Use these to derive data entities, API endpoints, component structure, and integration points.
 
-All of these provide essential context. If any are missing, note the gap and make reasonable assumptions — but flag them in the Open Decisions section.
+All of these provide essential context. If any are missing, note the gap and ask the user to clarify before proceeding. If the user explicitly defers, make reasonable assumptions and record them in the Assumptions sub-section of the Technical Gap Analysis.
 
 ---
 
@@ -344,8 +344,9 @@ Examples of gaps to look for:
 - Technical decisions that were inferred rather than explicitly specified in existing specs
 
 ### 10. Open Decisions
-- Areas where the architecture may need to evolve as features are implemented
-- Questions that should be resolved before or during implementation
+- **All technical questions and decisions must be resolved by asking the user before the document is saved.** Do not save the architecture with unresolved questions.
+- If the user explicitly defers a decision, record it here with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
+- Areas where the architecture may need to evolve as features are implemented may be noted, but these must be acknowledged evolution points — not unresolved questions.
 
 ---
 

package/dist/codex/gspec-feature/SKILL.md

@@ -168,8 +168,8 @@ This separation — combined with the portability principles above — allows th
 
 ### 6. Assumptions & Risks
 - Assumptions (what we're taking as true)
-- Open questions — **only** unknowns that genuinely cannot be answered until implementation or real-world usage begins (e.g., performance thresholds pending benchmarking, exact rate limits pending load testing). Questions about scope, users, priorities, or feature design must be asked and resolved in the chat before the spec is written. If there are no open questions, omit this sub-section.
 - Key risks and mitigations (brief bullet points — focus on risks that could affect implementation scope or approach)
+- **No open questions** — All questions must be resolved by asking the user in the chat before the spec is saved. If the user explicitly defers a question, record it as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit the sub-section entirely. Never embed unresolved questions in the document by default.
 
 ### 7. Success Metrics
 - 2-4 measurable outcomes that define whether this feature is working

package/dist/codex/gspec-research/SKILL.md

@@ -159,7 +159,7 @@ After writing `gspec/research.md`, ask the user:
    - Scope (in-scope goals, out-of-scope items, deferred ideas)
    - Capabilities (with P0/P1/P2 priority levels, using **unchecked checkboxes** `- [ ]` for each capability, each with 2-4 **acceptance criteria** as a sub-list)
    - Dependencies (on other features or external services)
-   - Assumptions & Risks (assumptions, open questions, key risks and mitigations)
+   - Assumptions & Risks (assumptions, key risks and mitigations — all questions must be resolved in the chat before saving; only record explicitly deferred decisions)
    - Success Metrics
    - Implementation Context (standard portability note)
    - Begin the file with YAML frontmatter: `---\nspec-version: v1\n---`

package/dist/codex/gspec-stack/SKILL.md

@@ -52,13 +52,8 @@ You should:
 - Deployment target (cloud, on-premise, hybrid)
 - Scale and performance requirements
 
-### 2. Open Questions & Clarifications
-**List any critical questions that need answers before finalizing technology choices**
-- Missing requirements that impact stack decisions
-- Unclear constraints or preferences
-- Team expertise or existing infrastructure questions
-- Budget or licensing considerations
-- **Mark as "None" if all information is clear**
+### 2. Clarifications
+**All questions that impact technology choices must be resolved by asking the user in the chat before the document is saved.** Do not save the stack spec with unresolved questions. If the user explicitly defers a decision, record it here as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
 
 ### 3. Core Technology Stack
 

package/dist/cursor/gspec-architect.mdc

@@ -33,7 +33,7 @@ Before generating the architecture document, read **all** existing gspec documen
 4. **`gspec/practices.md`** — Development standards. Use this to align file organization, testing patterns, and code structure with team conventions.
 5. **`gspec/features/*.md`** — Individual feature requirements and dependencies. Use these to derive data entities, API endpoints, component structure, and integration points.
 
-All of these provide essential context. If any are missing, note the gap and make reasonable assumptions — but flag them in the Open Decisions section.
+All of these provide essential context. If any are missing, note the gap and ask the user to clarify before proceeding. If the user explicitly defers, make reasonable assumptions and record them in the Assumptions sub-section of the Technical Gap Analysis.
 
 ---
 
@@ -343,8 +343,9 @@ Examples of gaps to look for:
 - Technical decisions that were inferred rather than explicitly specified in existing specs
 
 ### 10. Open Decisions
-- Areas where the architecture may need to evolve as features are implemented
-- Questions that should be resolved before or during implementation
+- **All technical questions and decisions must be resolved by asking the user before the document is saved.** Do not save the architecture with unresolved questions.
+- If the user explicitly defers a decision, record it here with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
+- Areas where the architecture may need to evolve as features are implemented may be noted, but these must be acknowledged evolution points — not unresolved questions.
 
 ---
 

package/dist/cursor/gspec-feature.mdc

@@ -167,8 +167,8 @@ This separation — combined with the portability principles above — allows th
 
 ### 6. Assumptions & Risks
 - Assumptions (what we're taking as true)
-- Open questions — **only** unknowns that genuinely cannot be answered until implementation or real-world usage begins (e.g., performance thresholds pending benchmarking, exact rate limits pending load testing). Questions about scope, users, priorities, or feature design must be asked and resolved in the chat before the spec is written. If there are no open questions, omit this sub-section.
 - Key risks and mitigations (brief bullet points — focus on risks that could affect implementation scope or approach)
+- **No open questions** — All questions must be resolved by asking the user in the chat before the spec is saved. If the user explicitly defers a question, record it as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit the sub-section entirely. Never embed unresolved questions in the document by default.
 
 ### 7. Success Metrics
 - 2-4 measurable outcomes that define whether this feature is working

package/dist/cursor/gspec-research.mdc

@@ -158,7 +158,7 @@ After writing `gspec/research.md`, ask the user:
    - Scope (in-scope goals, out-of-scope items, deferred ideas)
    - Capabilities (with P0/P1/P2 priority levels, using **unchecked checkboxes** `- [ ]` for each capability, each with 2-4 **acceptance criteria** as a sub-list)
    - Dependencies (on other features or external services)
-   - Assumptions & Risks (assumptions, open questions, key risks and mitigations)
+   - Assumptions & Risks (assumptions, key risks and mitigations — all questions must be resolved in the chat before saving; only record explicitly deferred decisions)
    - Success Metrics
    - Implementation Context (standard portability note)
    - Begin the file with YAML frontmatter: `---\nspec-version: v1\n---`

package/dist/cursor/gspec-stack.mdc

@@ -51,13 +51,8 @@ You should:
 - Deployment target (cloud, on-premise, hybrid)
 - Scale and performance requirements
 
-### 2. Open Questions & Clarifications
-**List any critical questions that need answers before finalizing technology choices**
-- Missing requirements that impact stack decisions
-- Unclear constraints or preferences
-- Team expertise or existing infrastructure questions
-- Budget or licensing considerations
-- **Mark as "None" if all information is clear**
+### 2. Clarifications
+**All questions that impact technology choices must be resolved by asking the user in the chat before the document is saved.** Do not save the stack spec with unresolved questions. If the user explicitly defers a decision, record it here as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
 
 ### 3. Core Technology Stack
 

package/dist/opencode/gspec-architect/SKILL.md

@@ -34,7 +34,7 @@ Before generating the architecture document, read **all** existing gspec documen
 4. **`gspec/practices.md`** — Development standards. Use this to align file organization, testing patterns, and code structure with team conventions.
 5. **`gspec/features/*.md`** — Individual feature requirements and dependencies. Use these to derive data entities, API endpoints, component structure, and integration points.
 
-All of these provide essential context. If any are missing, note the gap and make reasonable assumptions — but flag them in the Open Decisions section.
+All of these provide essential context. If any are missing, note the gap and ask the user to clarify before proceeding. If the user explicitly defers, make reasonable assumptions and record them in the Assumptions sub-section of the Technical Gap Analysis.
 
 ---
 
@@ -344,8 +344,9 @@ Examples of gaps to look for:
 - Technical decisions that were inferred rather than explicitly specified in existing specs
 
 ### 10. Open Decisions
-- Areas where the architecture may need to evolve as features are implemented
-- Questions that should be resolved before or during implementation
+- **All technical questions and decisions must be resolved by asking the user before the document is saved.** Do not save the architecture with unresolved questions.
+- If the user explicitly defers a decision, record it here with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
+- Areas where the architecture may need to evolve as features are implemented may be noted, but these must be acknowledged evolution points — not unresolved questions.
 
 ---
 

package/dist/opencode/gspec-feature/SKILL.md

@@ -168,8 +168,8 @@ This separation — combined with the portability principles above — allows th
 
 ### 6. Assumptions & Risks
 - Assumptions (what we're taking as true)
-- Open questions — **only** unknowns that genuinely cannot be answered until implementation or real-world usage begins (e.g., performance thresholds pending benchmarking, exact rate limits pending load testing). Questions about scope, users, priorities, or feature design must be asked and resolved in the chat before the spec is written. If there are no open questions, omit this sub-section.
 - Key risks and mitigations (brief bullet points — focus on risks that could affect implementation scope or approach)
+- **No open questions** — All questions must be resolved by asking the user in the chat before the spec is saved. If the user explicitly defers a question, record it as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit the sub-section entirely. Never embed unresolved questions in the document by default.
 
 ### 7. Success Metrics
 - 2-4 measurable outcomes that define whether this feature is working

package/dist/opencode/gspec-research/SKILL.md

@@ -159,7 +159,7 @@ After writing `gspec/research.md`, ask the user:
    - Scope (in-scope goals, out-of-scope items, deferred ideas)
    - Capabilities (with P0/P1/P2 priority levels, using **unchecked checkboxes** `- [ ]` for each capability, each with 2-4 **acceptance criteria** as a sub-list)
    - Dependencies (on other features or external services)
-   - Assumptions & Risks (assumptions, open questions, key risks and mitigations)
+   - Assumptions & Risks (assumptions, key risks and mitigations — all questions must be resolved in the chat before saving; only record explicitly deferred decisions)
    - Success Metrics
    - Implementation Context (standard portability note)
    - Begin the file with YAML frontmatter: `---\nspec-version: v1\n---`

package/dist/opencode/gspec-stack/SKILL.md

@@ -52,13 +52,8 @@ You should:
 - Deployment target (cloud, on-premise, hybrid)
 - Scale and performance requirements
 
-### 2. Open Questions & Clarifications
-**List any critical questions that need answers before finalizing technology choices**
-- Missing requirements that impact stack decisions
-- Unclear constraints or preferences
-- Team expertise or existing infrastructure questions
-- Budget or licensing considerations
-- **Mark as "None" if all information is clear**
+### 2. Clarifications
+**All questions that impact technology choices must be resolved by asking the user in the chat before the document is saved.** Do not save the stack spec with unresolved questions. If the user explicitly defers a decision, record it here as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
 
 ### 3. Core Technology Stack
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "gspec",
-    "version": "1.13.2",
+    "version": "1.14.0",
     "description": "Install gspec specification commands for Claude Code, Cursor, and other AI tools",
     "main": "bin/gspec.js",
     "type": "module",

package/templates/spec-sync.md

@@ -8,19 +8,21 @@ These specs define what the product is, how it should look, what technology it u
 
 1. **Read the specs first** — Before making non-trivial changes, read the relevant gspec documents to understand existing decisions and constraints. At minimum, scan `gspec/profile.md` and any feature PRDs in `gspec/features/` related to your work.
 
-2. **Update feature checkboxes** — When you implement a capability defined in a feature PRD (`gspec/features/*.md`), change its checkbox from `- [ ]` to `- [x]`.
+2. **Spec before you build** — If the user asks for a feature or capability that isn't covered by an existing feature PRD in `gspec/features/`, run the `gspec-feature` command to create a new feature PRD before implementing it. Every feature should be specified before it's built — don't skip straight to code.
 
-3. **Update specs that your changes contradict** — If your code change makes a spec statement incorrect (e.g., you changed the data model, switched a dependency, altered a UI pattern, or added a new API endpoint), update the spec to reflect reality. Common candidates:
+3. **Update feature checkboxes** — When you implement a capability defined in a feature PRD (`gspec/features/*.md`), change its checkbox from `- [ ]` to `- [x]`.
+
+4. **Update specs that your changes contradict** — If your code change makes a spec statement incorrect (e.g., you changed the data model, switched a dependency, altered a UI pattern, or added a new API endpoint), update the spec to reflect reality. Common candidates:
    - `gspec/architecture.md` — project structure, data model, API routes, component hierarchy
    - `gspec/stack.md` — dependencies, frameworks, infrastructure
    - `gspec/style.md` — design tokens, component styling, visual conventions
    - `gspec/practices.md` — coding standards, testing conventions, workflows
    - `gspec/profile.md` — product scope, target users, value proposition (rarely changes)
 
-4. **Be surgical** — Change only what is necessary. Preserve the existing voice, structure, and formatting of each spec document. Do not rewrite sections that are still accurate.
+5. **Be surgical** — Change only what is necessary. Preserve the existing voice, structure, and formatting of each spec document. Do not rewrite sections that are still accurate.
 
-5. **Announce spec updates** — When you update a spec, briefly mention what changed and why in your response. Never silently modify specs.
+6. **Announce spec updates** — When you update a spec, briefly mention what changed and why in your response. Never silently modify specs.
 
-6. **Preserve frontmatter** — gspec files use YAML frontmatter with a `spec-version` field. Preserve it when editing. If a file lacks frontmatter, leave it as-is.
+7. **Preserve frontmatter** — gspec files use YAML frontmatter with a `spec-version` field. Preserve it when editing. If a file lacks frontmatter, leave it as-is.
 
-7. **Don't create new foundation specs** — Only update existing spec files. If you believe a new spec document is needed, suggest it to the user rather than creating it yourself.
+8. **Don't create new foundation specs** — Only update existing spec files. If you believe a new spec document is needed, suggest it to the user rather than creating it yourself.