@opengsd/gsd-core 1.2.0-rc.1

package/get-shit-done/references/user-story-template.md

@@ -0,0 +1,58 @@
+# User Story Template (MVP Mode)
+
+> Used by `mvp-phase` workflow and `gsd-planner` agent when `MVP_MODE=true`. Defines the canonical "As a / I want to / So that" format and the rules for converting it into the `**Goal:**` line in ROADMAP.md.
+
+## Canonical format
+
+```
+As a [user role], I want to [capability], so that [outcome].
+```
+
+Three required components:
+
+| Slot | Question | Examples |
+|---|---|---|
+| `[user role]` | Who is the actor? | "new user", "admin", "signed-in customer", "API consumer" |
+| `[capability]` | What can they do? | "register and log in", "upload a CSV", "see my dashboard" |
+| `[outcome]` | Why does it matter? | "I can access my account", "I can bulk-import contacts", "I can see at a glance what needs attention" |
+
+All three must be present. Refuse to assemble a partial story.
+
+## How it lands in ROADMAP.md
+
+The full user story replaces the existing `**Goal:**` line in the phase section:
+
+**Before:**
+```
+### Phase 1: User Auth MVP
+**Goal:** Users can register and log in
+```
+
+**After:**
+```
+### Phase 1: User Auth MVP
+**Goal:** As a new user, I want to register and log in, so that I can access my dashboard.
+**Mode:** mvp
+```
+
+Two structural rules:
+1. The `**Goal:**` line stays on a single line (no line breaks inside the story). If the story is longer than ~120 chars, it should be split into multiple phases via SPIDR (see `spidr-splitting.md`).
+2. The `**Mode:** mvp` line is added immediately below `**Goal:**`. If `**Mode:**` already exists, it is replaced (not duplicated).
+
+## How it lands in PLAN.md
+
+The `gsd-planner` agent (with MVP_MODE=true) emits the user story as the first content under the phase header in `PLAN.md`:
+
+```markdown
+## Phase Goal
+
+**As a** new user, **I want to** register and log in, **so that** I can access my dashboard.
+
+## Acceptance Criteria
+- [ ] ...
+
+## MVP Slice Tasks
+...
+```
+
+Note the bold-keyword formatting (`**As a**`, `**I want to**`, `**so that**`) is for the PLAN.md emit only. The ROADMAP.md `**Goal:**` line uses prose form (the keywords are not bolded inside the goal line, since the goal is itself a single bolded label).

package/get-shit-done/references/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 |
+```