gsd-antigravity-kit 1.32.0 → 2.0.0

package/.agent/skills/gsd/references/docs/thinking-models-research.md

@@ -0,0 +1,50 @@
+# Thinking Models: Research Cluster
+
+Structured reasoning models for the **researcher** and **synthesizer** agents. Apply these at decision points during research and synthesis, not continuously. Each model counters a specific documented failure mode.
+
+Source: Curated from [thinking-partner](https://github.com/mattnowdev/thinking-partner) model catalog (150+ models). Selected for direct applicability to GSD research workflow.
+
+## Conflict Resolution
+
+**First Principles and Steel Man both expand scope** -- run First Principles FIRST (decompose the problem), then Steel Man (strengthen alternatives). Don't run simultaneously.
+
+## 1. First Principles Thinking
+
+**Counters:** Accepting surface-level explanations without decomposing into fundamental components.
+
+Before accepting any technology recommendation or architectural pattern, decompose it to its fundamental constraints: What problem does this solve? What are the non-negotiable requirements? What are the physical/logical limits? Build your recommendation UP from these constraints rather than DOWN from conventional wisdom. If you cannot explain WHY a recommendation is correct from first principles, flag it as `[LOW]` regardless of source count.
+
+## 2. Simpson's Paradox Awareness
+
+**Counters:** Synthesizer aggregating conflicting research without checking for confounding splits.
+
+When combining findings from multiple research documents that show contradictory results, check whether the contradiction disappears when you split by a hidden variable: framework version, deployment target, project scale, or use case category. A library that benchmarks faster overall may be slower for YOUR specific workload. Before resolving contradictions by majority vote, ask: "Is there a subgroup split that explains why both findings are correct in their own context?"
+
+## 3. Survivorship Bias
+
+**Counters:** Only finding successful examples while missing failures and abandoned approaches.
+
+After gathering evidence FOR a recommended approach, actively search for projects that ABANDONED it. Check GitHub issues for "migrated away from", "replaced X with", or "problems with X at scale". A technology with 10 success stories and 100 quiet failures looks great until you check the graveyard. Weight negative evidence (migration-away stories, deprecation notices, unresolved issues) MORE heavily than positive evidence -- failures are underreported.
+
+## 4. Confirmation Bias Counter
+
+**Counters:** Searching for evidence that confirms initial hypothesis while ignoring disconfirming evidence.
+
+After forming your initial recommendation, spend one full research cycle searching AGAINST it. Use search terms like "{technology} problems", "{technology} alternatives", "why not {technology}", "{technology} vs {competitor}". For each piece of disconfirming evidence found, either (a) refute it with higher-confidence sources, or (b) add it as a caveat to your recommendation. If you cannot find ANY criticism of your recommendation, your search was too narrow -- widen it.
+
+## 5. Steel Man
+
+**Counters:** Dismissing alternative approaches without giving them their strongest possible form.
+
+Before recommending against an alternative technology or approach, construct its STRONGEST possible case. What would a passionate advocate say? What use cases does it serve better than your recommendation? What trade-offs favor it? Present the steel-manned alternative alongside your recommendation with an honest comparison. If the steel-manned alternative is competitive, flag the decision as `[NEEDS DECISION]` rather than making a unilateral recommendation.
+
+---
+
+## When NOT to Think
+
+Skip structured reasoning models when the situation does not benefit from them:
+
+- **Locked decisions from CONTEXT.md** -- If the user already decided "use library X", do not run Steel Man analysis on alternatives or First Principles decomposition of the choice. Research how to use X well, not whether X is the right choice.
+- **Standard stack lookups** -- If you are simply checking the latest version of a well-known library or reading its API docs, do not invoke Survivorship Bias or Confirmation Bias Counter. These models are for evaluating contested recommendations, not for factual lookups.
+- **Single-technology phases** -- If the phase involves one technology with no alternatives to evaluate (e.g., "add ESLint rule X"), skip comparative models (Steel Man, Confirmation Bias Counter). Just research the implementation.
+- **Codebase-only research** -- If the research is purely internal (understanding existing code patterns, finding where a function is called), structured reasoning models add no value. Use grep and read the code.

package/.agent/skills/gsd/references/docs/thinking-models-verification.md

@@ -0,0 +1,55 @@
+# Thinking Models: Verification Cluster
+
+Structured reasoning models for the **verifier** and **plan-checker** agents. Apply these during verification passes, not continuously. Each model counters a specific documented failure mode.
+
+Source: Curated from [thinking-partner](https://github.com/mattnowdev/thinking-partner) model catalog (150+ models). Selected for direct applicability to GSD verification workflow.
+
+## Conflict Resolution
+
+**Inversion** and **Confirmation Bias Counter** both look for failures but serve different purposes. Run them in sequence:
+
+1. **Inversion FIRST** (brainstorm): generate 3 ways this could be wrong
+2. **Confirmation Bias Counter SECOND** (structured check): find one partial requirement, one misleading test, one uncovered error path
+
+Inversion generates the list; Confirmation Bias Counter is the discipline to verify items on it.
+
+## 1. Inversion
+
+**Counters:** Verifiers confirming success rather than finding failures.
+
+Instead of checking what IS correct, list 3 specific ways this implementation could be WRONG despite passing tests: missing edge cases, silent data loss, race conditions, unhandled error paths. For each, write a concrete check (grep for pattern, test with specific input, verify error handling exists). Additionally, check whether any documented DEVIATION in SUMMARY.md changes the meaning or applicability of a must-have. If a must-have was written assuming approach A but the executor used approach B, the must-have may need reinterpretation, not literal checking.
+
+## 2. Chesterton's Fence
+
+**Counters:** Flagging purposeful code as dead or unnecessary.
+
+Before flagging any existing code as dead, redundant, or overcomplicated, determine WHY it was written that way. Check git blame, comments, test cases, and the PLAN.md that created it. If the reason is unclear, flag as "purpose unknown -- recommend keeping with WARNING, not removing" and include the git blame hash for the commit that introduced it.
+
+## 3. Confirmation Bias Counter
+
+**Counters:** Verifiers primed by SUMMARY.md claims to see success.
+
+After your initial verification pass, do a DISCONFIRMATION pass: (1) find one requirement that is only partially met, (2) find one test that passes but does not actually test the stated behavior, (3) find one error path that has no test coverage. Report these even if overall verification passes.
+
+## 4. Planning Fallacy Calibration
+
+**Counters:** Accepting over-scoped plans as reasonable (plan-checker).
+
+For each task estimated as "simple" or "small", check: does it touch more than 2 files? Does it require understanding an unfamiliar API? Does it modify shared infrastructure? If yes to any, flag as likely underestimated. Plans with >5 tasks or tasks touching >4 files per task are over-scoped.
+
+## 5. Counterfactual Thinking
+
+**Counters:** Plans that assume success at every step with no error recovery (plan-checker).
+
+For each plan, ask: "What would happen if the executor followed this plan EXACTLY as written but encountered a common failure: dependency version mismatch, API returning unexpected format, file already modified by prior plan?" If the plan has no contingency path and the `<action>` steps assume success at every point, flag as WARNING: "No error recovery path for task T{n}."
+
+---
+
+## When NOT to Think
+
+Skip structured reasoning models when the situation does not benefit from them:
+
+- **Re-verification of previously passed items** -- When in re-verification mode, items that passed the initial check only need a quick regression check (existence + basic sanity), not the full Inversion + Confirmation Bias Counter treatment.
+- **Binary existence checks** -- If a must-have is "file X exists with >N lines" and the file clearly exists with substantive content, do not run Counterfactual Thinking on it. Reserve models for ambiguous or wiring-dependent must-haves.
+- **Straightforward test results** -- If `<verify>` commands produce clear pass/fail output (e.g., test suite exits 0 with all tests passing), accept the result. Only invoke models when test results are ambiguous or when you suspect the tests do not actually test what they claim.
+- **INFO-level issues** -- Do not apply structured reasoning to decide whether an INFO-level observation is actually a BLOCKER. INFO items are informational by definition and never trigger gates.

package/.agent/skills/gsd/references/docs/thinking-partner.md

@@ -0,0 +1,96 @@
+# Thinking Partner Integration
+
+Conditional extended thinking at workflow decision points. Activates when `features.thinking_partner: true` in `.planning/config.json` (default: false).
+
+---
+
+## Tradeoff Detection Signals
+
+The thinking partner activates when developer responses contain specific signals indicating competing priorities:
+
+**Keyword signals:**
+- "or" / "versus" / "vs" connecting two approaches
+- "tradeoff" / "trade-off" / "tradeoffs"
+- "on one hand" / "on the other hand"
+- "pros and cons"
+- "not sure between" / "torn between"
+
+**Structural signals:**
+- Developer lists 2+ competing options
+- Developer asks "which is better" or "what would you recommend"
+- Developer reverses a previous decision ("actually, maybe we should...")
+
+**When NOT to activate:**
+- Developer has already made a clear choice
+- The "or" is rhetorical or trivial (e.g., "tabs or spaces" — use project convention)
+- Simple yes/no questions
+- Developer explicitly asks to move on
+
+---
+
+## Integration Points
+
+### 1. Discuss Phase — Tradeoff Deep-Dive
+
+**When:** During `discuss_areas` step, after a developer answer reveals competing priorities.
+
+**What:** Pause the normal question flow and offer a brief structured analysis:
+```
+I notice competing priorities here — {X} optimizes for {A} while {Y} optimizes for {B}.
+
+Want me to think through the tradeoffs before we decide?
+[Yes, analyze tradeoffs] / [No, I've decided]
+```
+
+If yes, provide a brief (3-5 bullet) analysis covering:
+- What each approach optimizes for
+- What each approach sacrifices
+- Which aligns better with the project's stated goals (from PROJECT.md)
+- A recommendation with reasoning
+
+Then return to the normal discussion flow.
+
+### 2. Plan Phase — Architectural Decision Analysis
+
+**When:** During step 11 (Handle Checker Return), when the plan-checker flags issues containing architectural tradeoff keywords.
+
+**What:** Before sending to the revision loop, analyze the architectural decision:
+```
+The plan-checker flagged an architectural tradeoff: {issue description}
+
+Brief analysis:
+- Option A: {approach} — {pros/cons}
+- Option B: {approach} — {pros/cons}
+- Recommendation: {choice} because {reasoning aligned with phase goals}
+
+Apply this recommendation to the revision? [Yes] / [No, let me decide]
+```
+
+### 3. Explore — Approach Comparison (requires #1729)
+
+**When:** During Socratic conversation, when multiple viable approaches emerge.
+**Note:** This integration point will be added when /gsd-explore (#1729) lands.
+
+---
+
+## Configuration
+
+```json
+{
+  "features": {
+    "thinking_partner": true
+  }
+}
+```
+
+Default: `false`. The thinking partner is opt-in because it adds latency to interactive workflows.
+
+---
+
+## Design Principles
+
+1. **Lightweight** — inline analysis, not a separate interactive session
+2. **Opt-in** — must be explicitly enabled, never activates by default
+3. **Skippable** — always offer "No, I've decided" to bypass
+4. **Brief** — 3-5 bullets max, not a full research report
+5. **Aligned** — recommendations reference PROJECT.md goals when available

package/.agent/skills/gsd/references/docs/universal-anti-patterns.md

@@ -0,0 +1,58 @@
+# Universal Anti-Patterns
+
+Rules that apply to ALL workflows and agents. Individual workflows may have additional specific anti-patterns.
+
+---
+
+## Context Budget Rules
+
+1. **Never** read agent definition files (`agents/*.md`) -- `subagent_type` auto-loads them. Reading agent definitions into the orchestrator wastes context for content automatically injected into subagent sessions.
+2. **Never** inline large files into subagent prompts -- tell agents to read files from disk instead. Agents have their own context windows.
+3. **Read depth scales with context window** -- check `context_window_tokens` in `.planning/config.json`. At < 500000: read only frontmatter, status fields, or summaries. At >= 500000 (1M model): full body reads permitted when content is needed for inline decisions. See `references/context-budget.md` for the complete table.
+4. **Delegate** heavy work to subagents -- the orchestrator routes, it does not build, analyze, research, investigate, or verify.
+5. **Proactive pause warning**: If you have already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider checkpointing progress."
+
+## File Reading Rules
+
+6. **SUMMARY.md read depth scales with context window** -- at context_window_tokens < 500000: read frontmatter only from prior phase SUMMARYs. At >= 500000: full body reads permitted for direct-dependency phases. Transitive dependencies (2+ phases back) remain frontmatter-only regardless.
+7. **Never** read full PLAN.md files from other phases -- only current phase plans.
+8. **Never** read `.planning/logs/` files -- only the health workflow reads these.
+9. **Do not** re-read full file contents when frontmatter is sufficient -- frontmatter contains status, key_files, commits, and provides fields. Exception: at >= 500000, re-reading full body is acceptable when semantic content is needed.
+
+## Subagent Rules
+
+10. **NEVER** use non-GSD agent types (`general-purpose`, `Explore`, `Plan`, `Bash`, `feature-dev`, etc.) -- ALWAYS use `subagent_type: "gsd-{agent}"` (e.g., `gsd-phase-researcher`, `gsd-executor`, `gsd-planner`). GSD agents have project-aware prompts, audit logging, and workflow context. Generic agents bypass all of this.
+11. **Do not** re-litigate decisions that are already locked in CONTEXT.md (or PROJECT.md ## Context section) -- respect locked decisions unconditionally.
+
+## Questioning Anti-Patterns
+
+Reference: `references/questioning.md` for the full anti-pattern list.
+
+12. **Do not** walk through checklists -- checklist walking (asking items one by one from a list) is the #1 anti-pattern. Instead, use progressive depth: start broad, dig where interesting.
+13. **Do not** use corporate speak -- avoid jargon like "stakeholder alignment", "synergize", "deliverables". Use plain language.
+14. **Do not** apply premature constraints -- don't narrow the solution space before understanding the problem. Ask about the problem first, then constrain.
+
+## State Management Anti-Patterns
+
+15. **No direct Write/Edit to STATE.md or ROADMAP.md for mutations.** Always use `gsd-tools.cjs` CLI commands (`state update`, `state advance-plan`, `roadmap update-status`) for mutations. Direct Write tool usage bypasses safe update logic and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template is allowed.
+
+## Behavioral Rules
+
+16. **Do not** create artifacts the user did not approve -- always confirm before writing new planning documents.
+17. **Do not** modify files outside the workflow's stated scope -- check the plan's files_modified list.
+18. **Do not** suggest multiple next actions without clear priority -- one primary suggestion, alternatives listed secondary.
+19. **Do not** use `git add .` or `git add -A` -- stage specific files only.
+20. **Do not** include sensitive information (API keys, passwords, tokens) in planning documents or commits.
+
+## Error Recovery Rules
+
+21. **Git lock detection**: Before any git operation, if it fails with "Unable to create lock file", check for stale `.git/index.lock` and advise the user to remove it (do not remove automatically).
+22. **Config fallback awareness**: Config loading returns `null` silently on invalid JSON. If your workflow depends on config values, check for null and warn the user: "config.json is invalid or missing -- running with defaults."
+23. **Partial state recovery**: If STATE.md references a phase directory that doesn't exist, do not proceed silently. Warn the user and suggest diagnosing the mismatch.
+
+## GSD-Specific Rules
+
+24. **Do not** check for `mode === 'auto'` or `mode === 'autonomous'` -- GSD uses `yolo` config flag. Check `yolo: true` for autonomous mode, absence or `false` for interactive mode.
+25. **Always use `gsd-tools.cjs`** (not `gsd-tools.js` or any other variant) -- GSD uses CommonJS for Node.js CLI compatibility.
+26. **Plan files MUST follow `{padded_phase}-{NN}-PLAN.md` pattern** (e.g., `01-01-PLAN.md`). Never use `PLAN-01.md`, `plan-01.md`, or any other variation -- gsd-tools detection depends on this exact pattern.
+27. **Do not start executing the next plan before writing the SUMMARY.md for the current plan** -- downstream plans may reference it via `@` includes.

package/.agent/skills/gsd/references/docs/user-profiling.md

@@ -523,7 +523,7 @@ When a specific dimension has insufficient data (even if total messages exceed t
 
 - Set confidence to `UNSCORED`
 - Set summary to: "Insufficient data -- no clear signals detected for this dimension."
-- Set claude_instruction to a neutral fallback: "No strong preference detected. Ask the developer when this dimension is relevant."
+- Set antigravity_instruction to a neutral fallback: "No strong preference detected. Ask the developer when this dimension is relevant."
 - Set evidence_quotes to empty array `[]`
 - Set evidence_count to `0`
 
@@ -566,7 +566,7 @@ The profiler agent must return JSON matching this exact schema, wrapped in `<ana
         }
       ],
       "summary": "One to two sentence description of the observed pattern",
-      "claude_instruction": "Imperative directive for Antigravity: 'Match structured communication style' not 'You tend to provide structured context'"
+      "antigravity_instruction": "Imperative directive for Antigravity: 'Match structured communication style' not 'You tend to provide structured context'"
     },
     "decision_speed": {
       "rating": "fast-intuitive|deliberate-informed|research-first|delegator",
@@ -575,7 +575,7 @@ The profiler agent must return JSON matching this exact schema, wrapped in `<ana
       "cross_project_consistent": true,
       "evidence_quotes": [],
       "summary": "string",
-      "claude_instruction": "string"
+      "antigravity_instruction": "string"
     },
     "explanation_depth": {
       "rating": "code-only|concise|detailed|educational",
@@ -584,7 +584,7 @@ The profiler agent must return JSON matching this exact schema, wrapped in `<ana
       "cross_project_consistent": true,
       "evidence_quotes": [],
       "summary": "string",
-      "claude_instruction": "string"
+      "antigravity_instruction": "string"
     },
     "debugging_approach": {
       "rating": "fix-first|diagnostic|hypothesis-driven|collaborative",
@@ -593,7 +593,7 @@ The profiler agent must return JSON matching this exact schema, wrapped in `<ana
       "cross_project_consistent": true,
       "evidence_quotes": [],
       "summary": "string",
-      "claude_instruction": "string"
+      "antigravity_instruction": "string"
     },
     "ux_philosophy": {
       "rating": "function-first|pragmatic|design-conscious|backend-focused",
@@ -602,7 +602,7 @@ The profiler agent must return JSON matching this exact schema, wrapped in `<ana
       "cross_project_consistent": true,
       "evidence_quotes": [],
       "summary": "string",
-      "claude_instruction": "string"
+      "antigravity_instruction": "string"
     },
     "vendor_philosophy": {
       "rating": "pragmatic-fast|conservative|thorough-evaluator|opinionated",
@@ -611,7 +611,7 @@ The profiler agent must return JSON matching this exact schema, wrapped in `<ana
       "cross_project_consistent": true,
       "evidence_quotes": [],
       "summary": "string",
-      "claude_instruction": "string"
+      "antigravity_instruction": "string"
     },
     "frustration_triggers": {
       "rating": "scope-creep|instruction-adherence|verbosity|regression",
@@ -620,7 +620,7 @@ The profiler agent must return JSON matching this exact schema, wrapped in `<ana
       "cross_project_consistent": true,
       "evidence_quotes": [],
       "summary": "string",
-      "claude_instruction": "string"
+      "antigravity_instruction": "string"
     },
     "learning_style": {
       "rating": "self-directed|guided|documentation-first|example-driven",
@@ -629,7 +629,7 @@ The profiler agent must return JSON matching this exact schema, wrapped in `<ana
       "cross_project_consistent": true,
       "evidence_quotes": [],
       "summary": "string",
-      "claude_instruction": "string"
+      "antigravity_instruction": "string"
     }
   }
 }
@@ -644,7 +644,7 @@ The profiler agent must return JSON matching this exact schema, wrapped in `<ana
 - **`messages_analyzed`**: Total number of genuine user messages processed
 - **`message_threshold`**: Which threshold mode was triggered (`full`, `hybrid`, `insufficient`)
 - **`sensitive_excluded`**: Array of excluded sensitive content types with counts (empty array if none found)
-- **`claude_instruction`**: Must be written in imperative form directed at Antigravity. This field is how the profile becomes actionable.
+- **`antigravity_instruction`**: Must be written in imperative form directed at Antigravity. This field is how the profile becomes actionable.
   - Good: "Provide structured responses with headers and numbered lists to match this developer's communication style."
   - Bad: "You tend to like structured responses."
   - Good: "Ask before making changes beyond the stated request -- this developer values bounded execution."

package/.agent/skills/gsd/references/docs/verification-overrides.md

@@ -0,0 +1,227 @@
+# Verification Overrides
+
+Mechanism for intentionally accepting must-have failures when the deviation is known and acceptable. Prevents verification loops on items that will never pass as originally specified.
+
+<override_format>
+
+## Override Format
+
+Overrides are declared in the VERIFICATION.md frontmatter under an `overrides:` key:
+
+```yaml
+---
+phase: 03-authentication
+verified: 2026-04-05T12:00:00Z
+status: passed
+score: 5/5
+overrides_applied: 2
+overrides:
+  - must_have: "OAuth2 PKCE flow implemented"
+    reason: "Using session-based auth instead — PKCE unnecessary for server-rendered app"
+    accepted_by: "dave"
+    accepted_at: "2026-04-04T15:30:00Z"
+  - must_have: "Rate limiting on login endpoint"
+    reason: "Deferred to Phase 5 (infrastructure) — tracked in ROADMAP.md"
+    accepted_by: "dave"
+    accepted_at: "2026-04-04T15:30:00Z"
+---
+```
+
+### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `must_have` | string | The must-have truth, artifact description, or key link being overridden. Does not need to be an exact match — fuzzy matching applies. |
+| `reason` | string | Why this deviation is acceptable. Must be specific — not just "not needed". |
+| `accepted_by` | string | Who accepted the override (username or role). Required. |
+| `accepted_at` | string | ISO timestamp of when the override was accepted. Required. |
+
+</override_format>
+
+## When to Use
+
+Overrides apply when a phase intentionally deviated from the original plan during execution — for example, a requirement was descoped, an alternative approach was chosen, or a dependency changed.
+
+Without overrides, the verifier reports these as FAIL even though the deviation was intentional. Overrides let the developer mark specific items as `PASSED (override)` with a documented reason.
+
+Overrides are appropriate when:
+- A requirement changed after planning but ROADMAP.md hasn't been updated yet
+- An alternative implementation satisfies the intent but not the literal wording
+- A must-have is deferred to a later phase with explicit tracking
+- External constraints make the original must-have impossible or unnecessary
+
+## When NOT to Use
+
+Overrides are NOT appropriate when:
+- The implementation is simply incomplete — fix it instead
+- The must-have is unclear — clarify it instead
+- The developer wants to skip verification — that undermines the process
+- Multiple must-haves are failing for the same phase — if more than 2-3 items need overrides, revisit the plan instead of overriding in bulk
+
+<matching_rules>
+
+## Matching Rules
+
+Override matching uses **fuzzy matching**, not exact string comparison. This accommodates minor wording differences between how must-haves are phrased in ROADMAP.md, PLAN.md frontmatter, and the override entry.
+
+### Matching Algorithm
+
+1. **Normalize both strings:** case-insensitive comparison — lowercase both strings, strip punctuation, collapse whitespace
+2. **Token overlap:** split into words, compute intersection
+3. **Match threshold:** 80% token overlap in EITHER direction (override tokens found in must-have, OR must-have tokens found in override)
+4. **Key noun priority:** nouns and technical terms (file paths, component names, API endpoints) are weighted higher than common words
+
+### Examples
+
+| Must-Have | Override `must_have` | Match? | Reason |
+|-----------|---------------------|--------|--------|
+| "User can authenticate via OAuth2 PKCE" | "OAuth2 PKCE flow implemented" | Yes | Key terms `OAuth2` and `PKCE` overlap, 80% threshold met |
+| "Rate limiting on /api/auth/login" | "Rate limiting on login endpoint" | Yes | `rate limiting` + `login` overlap |
+| "Chat component renders messages" | "OAuth2 PKCE flow implemented" | No | No meaningful token overlap |
+| "src/components/Chat.tsx provides message list" | "Chat.tsx message list rendering" | Yes | `Chat.tsx` + `message` + `list` overlap |
+
+### Ambiguity Resolution
+
+If an override matches multiple must-haves, apply it to the **most specific match** (highest token overlap percentage). If still ambiguous, apply to the first match and log a warning.
+
+</matching_rules>
+
+<verifier_behavior>
+
+## Verifier Behavior with Overrides
+
+### Check Order
+
+The override check happens **before marking a must-have as FAIL**. The flow is:
+
+1. Evaluate must-have against codebase (Steps 3-5 of verification process)
+2. If evaluation result is FAIL or UNCERTAIN:
+   a. Check `overrides:` array in VERIFICATION.md frontmatter for a fuzzy match
+   b. If override found: mark as `PASSED (override)` instead of FAIL
+   c. If no override found: mark as FAIL as normal
+3. If evaluation result is PASS: mark as VERIFIED (overrides are irrelevant)
+
+### Output Format
+
+Overridden items appear with distinct status in all verification tables:
+
+```markdown
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | User can authenticate | VERIFIED | OAuth session flow working |
+| 2 | OAuth2 PKCE flow | PASSED (override) | Override: Using session-based auth — accepted by dave on 2026-04-04 |
+| 3 | Chat renders messages | FAILED | Component returns placeholder |
+```
+
+The `PASSED (override)` status must be visually distinct from both `VERIFIED` and `FAILED`. In the evidence column, include the override reason and who accepted it.
+
+### Impact on Overall Status
+
+- `PASSED (override)` items count toward the passing score, not the failing score
+- A phase with all items either VERIFIED or PASSED (override) can have status `passed`
+- Overrides do NOT suppress `human_needed` items — those still require human testing
+
+### Frontmatter Score
+
+The score and override count in frontmatter reflect applied overrides:
+
+```yaml
+score: 5/5  # includes 2 overrides
+overrides_applied: 2
+```
+
+</verifier_behavior>
+
+<creating_overrides>
+
+## Creating Overrides
+
+### Interactive Override Suggestion
+
+When the verifier marks a must-have as FAIL and the failure looks intentional (e.g., alternative implementation exists, or the code explicitly handles the case differently), the verifier should suggest creating an override:
+
+```markdown
+### F-002: OAuth2 PKCE flow
+
+**Status:** FAILED
+**Evidence:** No PKCE implementation found. Session-based auth used instead.
+
+**This looks intentional.** The codebase uses session-based authentication which achieves the same goal differently. To accept this deviation, add an override to VERIFICATION.md frontmatter:
+
+```yaml
+overrides:
+  - must_have: "OAuth2 PKCE flow implemented"
+    reason: "Using session-based auth instead — PKCE unnecessary for server-rendered app"
+    accepted_by: "{your name}"
+    accepted_at: "{current ISO timestamp}"
+```
+
+Then re-run verification to apply.
+```
+
+### Override via gsd-tools
+
+Overrides can also be managed through the verification workflow:
+
+1. Run `/gsd-verify-work` — verification finds gaps
+2. Review gaps — determine which are intentional deviations
+3. Add override entries to VERIFICATION.md frontmatter
+4. Re-run `/gsd-verify-work` — overrides are applied, remaining gaps shown
+
+</creating_overrides>
+
+<override_lifecycle>
+
+## Override Lifecycle
+
+### During Re-verification
+
+When a phase is re-verified (e.g., after gap closure):
+- Existing overrides carry forward automatically
+- If the underlying code now satisfies the must-have, the override becomes unnecessary — mark as VERIFIED instead
+- Overrides are never removed automatically; they persist as documentation
+
+### At Milestone Completion
+
+During `/gsd-audit-milestone`, overrides are surfaced in the audit report:
+
+```
+### Verification Overrides ({count} across {phase_count} phases)
+
+| Phase | Must-Have | Reason | Accepted By |
+|-------|----------|--------|-------------|
+| 03 | OAuth2 PKCE | Session-based auth used instead | dave |
+```
+
+This gives the team visibility into all accepted deviations before closing the milestone.
+
+### Cleanup
+
+Stale overrides (where the must-have was later implemented or removed from ROADMAP.md) can be cleaned up during milestone completion. They are informational — leaving them causes no harm.
+
+</override_lifecycle>
+
+## Example VERIFICATION.md
+
+```markdown
+---
+phase: 03-api-layer
+verified: 2026-04-05T12:00:00Z
+status: passed
+score: 3/3
+overrides_applied: 1
+overrides:
+  - must_have: "paginated API responses"
+    reason: "Descoped — dataset under 100 items, pagination adds complexity without value"
+    accepted_by: "dave"
+    accepted_at: "2026-04-04T15:30:00Z"
+---
+
+## Phase 3: API Layer — Verification
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | REST endpoints return JSON | VERIFIED | curl tests confirm |
+| 2 | Paginated API responses | PASSED (override) | Descoped — see override: dataset under 100 items |
+| 3 | Authentication middleware | VERIFIED | JWT validation working |
+```

package/.agent/skills/gsd/references/docs/workstream-flag.md

@@ -20,7 +20,7 @@ Antigravity/Codex instances are active on the same repo at the same time. One se
 silently repoint another session's `STATE.md`, `ROADMAP.md`, and phase paths.
 
 GSD now prefers a session-scoped pointer keyed by runtime/session identity
-(`GSD_SESSION_KEY`, `CODEX_THREAD_ID`, `CLAUDE_CODE_SSE_PORT`, terminal session IDs,
+(`GSD_SESSION_KEY`, `CODEX_THREAD_ID`, `ANTIGRAVITY_SSE_PORT`, terminal session IDs,
 or the controlling TTY). This keeps concurrent sessions isolated while preserving
 legacy compatibility for runtimes that do not expose a stable session key.
 
@@ -29,7 +29,7 @@ legacy compatibility for runtimes that do not expose a stable session key.
 When GSD resolves the session-scoped pointer in step 3 above, it uses this order:
 
 1. Explicit runtime/session env vars such as `GSD_SESSION_KEY`, `CODEX_THREAD_ID`,
-   `CLAUDE_SESSION_ID`, `CLAUDE_CODE_SSE_PORT`, `OPENCODE_SESSION_ID`,
+   `ANTIGRAVITY_SESSION_ID`, `ANTIGRAVITY_SSE_PORT`, `OPENCODE_SESSION_ID`,
    `GEMINI_SESSION_ID`, `CURSOR_SESSION_ID`, `WINDSURF_SESSION_ID`,
    `TERM_SESSION_ID`, `WT_SESSION`, `TMUX_PANE`, and `ZELLIJ_SESSION_NAME`
 2. `TTY` or `SSH_TTY` if the shell/runtime already exposes the terminal path

package/.agent/skills/gsd/references/mapping.md

@@ -6,27 +6,17 @@ When converting from a standard GSD installation to an Antigravity Skill, paths
 
 | Source GSD Path | Target Skill Path | Purpose |
 |-----------------|-------------------|---------|
-| `.antigravity/commands/gsd/` | `references/commands/` | Interactive slash commands |
-| `.antigravity/get-shit-done/references/` | `references/docs/` | Static domain knowledge and guides |
-references/workflows/` | `references/workflows/` | Multi-step procedural logic |
-references/agents/` | `references/agents/` | Specialized sub-agent system prompts |
-assets/templates/` | `assets/templates/` | File boilerplate (PROJECT.md, etc.) |
-
-## String Replacements (Regex)
-
-The conversion script performs the following replacements within `.md` and `.json` files:
-
-1. **File Inclusion Syntax (`@`)**
-   - `@references/commands/` -> `@references/commands/`
-   - `@references/docs/` -> `@references/docs/`
-   - `@references/workflows/` -> `@references/workflows/`
-   - `@assets/templates/` -> `@assets/templates/`
-   - `@references/agents/` -> `@references/agents/`
-
-2. **Programmatic Paths (e.g., in `Task()` calls)**
-references/agents/` -> `references/agents/`
-assets/templates/` -> `assets/templates/`
-references/workflows/` -> `references/workflows/`
+| `.claude/commands/gsd/` | `references/commands/` | Interactive slash commands |
+| `.claude/get-shit-done/references/` | `references/docs/` | Static domain knowledge and guides |
+| `.claude/get-shit-done/workflows/` | `references/workflows/` | Multi-step procedural logic |
+| `.claude/get-shit-done/contexts/` | `references/agents/profiles/` | Project-specific context profiles |
+| `.claude/agents/` | `references/agents/` | Specialized sub-agent system prompts |
+| `.claude/get-shit-done/templates/` | `assets/templates/` | File boilerplate (PROJECT.md, etc.) |
+| `.claude/get-shit-done/bin/` | `bin/` | Internal GSD CLI tools |
+| `.claude/hooks/` | `bin/hooks/` | Lifecycle and guard hooks |
 
 ## Project Context
 References to `@.planning/` are **preserved**, as these refer to the active project's local planning directory, not the skill's own resources.
+
+---
+*Generated by gsd-converter on 2026-04-08*