Donchitos · ai-hustle-bro · Jun 5, 2026 · Jun 5, 2026
@@ -98,6 +98,7 @@ For each story, determine:
   - `Status: Proposed` → set story `Status: Blocked` with note: "BLOCKED: ADR-NNNN is Proposed — run `/architecture-decision` to advance it"
   - **Multiple ADRs apply**: List all governing ADRs in the story's `Governing ADRs:` field. Designate the one most directly controlling the implementation pattern as primary (first in the list). Others are listed as secondary references.
   - **No ADR applies at all**: Write `ADR: N/A — [brief reason, e.g. "pure data configuration, no architectural pattern required"]` in the story's ADR field. Do NOT leave the field blank — a blank ADR field means "not checked", not "not applicable".
+- **ADR Version**: for the primary governing ADR, embed the ADR file's last commit date next to the ADR reference. Use `git log -1 --format=%cs -- docs/architecture/[adr-file].md`. If the ADR has no git history yet, write `ADR Version: uncommitted` and note that `/dev-story` will fall back to targeted ADR section reads.
 - **Story Type**: from Step 3 classification
 - **Engine risk**: from the ADR's Knowledge Risk field
 
@@ -199,6 +200,7 @@ For each story, write `production/epics/[epic-slug]/story-[NNN]-[slug].md`:
 *(Requirement text lives in `docs/architecture/tr-registry.yaml` — read fresh at review time)*
 
 **ADR Governing Implementation**: [ADR-NNNN: title]
+**ADR Version**: [last commit date from `git log -1 --format=%cs -- docs/architecture/[adr-file].md`, or `uncommitted`]
 **ADR Decision Summary**: [1-2 sentence summary of what the ADR decided]
 
 **Engine**: [name + version] | **Risk**: [LOW / MEDIUM / HIGH]

@@ -1,6 +1,6 @@
 ---
 name: dev-story
-description: "Read a story file and implement it. Loads the full context (story, GDD requirement, ADR guidelines, control manifest), routes to the right programmer agent for the system and engine, implements the code and test, and confirms each acceptance criterion. The core implementation skill — run after /story-readiness, before /code-review and /story-done."
+description: "Read a story file and implement it. Loads the implementation context (story, GDD requirement, story-embedded ADR guidance, control manifest), routes to the right programmer agent for the system and engine, implements the code and test, and confirms each acceptance criterion. The core implementation skill — run after /story-readiness, before /code-review and /story-done."
 argument-hint: "[story-path]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Bash, Task, AskUserQuestion
@@ -39,7 +39,7 @@ If not found, ask: "Which story are we implementing?" Glob
 
 ---
 
-## Phase 2: Load Full Context
+## Phase 2: Load Implementation Context
 
 **Before loading any context, verify required files exist.** Extract the ADR path from the story's `ADR Governing Implementation` field, then check:
 
@@ -51,16 +51,18 @@ If not found, ask: "Which story are we implementing?" Glob
 
 If the TR registry or governing ADR is missing, set the story status to **BLOCKED** in the session state and do not spawn any programmer agent.
 
-Read all of the following simultaneously — these are independent reads. Do not start implementation until all context is loaded:
+Read all of the following simultaneously — these are independent reads. Do not start implementation until all required context is loaded:
 
 ### The story file
 Extract and hold:
 - **Story title, ID, layer, type** (Logic / Integration / Visual/Feel / UI / Config/Data)
 - **TR-ID** — the GDD requirement identifier
 - **Governing ADR** reference
 - **Manifest Version** embedded in story header
+- **ADR Version** embedded beside the governing ADR, if present
 - **Acceptance Criteria** — every checkbox item, verbatim
-- **Implementation Notes** — the ADR guidance section in the story
+- **ADR Decision Summary** — the distilled decision embedded by `/create-stories`
+- **Implementation Notes** — the ADR guidance section embedded by `/create-stories`
 - **Out of Scope** boundaries
 - **Test Evidence** — the required test file path
 - **Dependencies** — what must be DONE before this story
@@ -71,11 +73,44 @@ Read the current `requirement` text — this is the source of truth for what the
 GDD requires now. Do not rely on any inline text in the story file (may be stale).
 
 ### The governing ADR
-Read `docs/architecture/[adr-file].md`. Extract:
-- The full Decision section
-- The Implementation Guidelines section (this is what the programmer follows)
-- The Engine Compatibility section (post-cutoff APIs, known risks)
-- The ADR Dependencies section
+Do **not** read the full ADR by default. `/create-stories` already embeds the
+ADR Decision Summary and Implementation Notes into the story; those embedded
+sections are the primary implementation brief for the programmer.
+
+Use targeted ADR reads only for validation and gap filling:
+
+1. Check the ADR header/status first. If `Status:` is not `Accepted`, output
+   **BLOCKED** and recommend `/architecture-decision`.
+2. Check the ADR version if the story includes `ADR Version:`. Compute the
+   current ADR version with `git log -1 --format=%cs -- docs/architecture/[adr-file].md`.
+   - **Match**: proceed to the embedded-guidance check below.
+   - **Mismatch**: use `AskUserQuestion` before implementation:
+     - Prompt: "Story was written against ADR v[story-adr-version]. Current ADR is v[current-adr-version]. Embedded ADR guidance may be stale. How do you want to proceed?"
+     - Options:
+       - `[A] Refresh embedded ADR guidance from targeted ADR section reads (Recommended)`
+       - `[B] Proceed with existing embedded guidance - I accept the ADR staleness risk`
+       - `[C] Stop here - I want to review the ADR diff first`
+     - If [A]: read only the smallest needed ADR sections (`Decision`,
+       `Implementation Guidelines`, `Engine Compatibility`, or
+       `ADR Dependencies`), update `ADR Version:`, `ADR Decision Summary`, and
+       `Implementation Notes` in the story before spawning the programmer.
+     - If [B]: leave the stale `ADR Version:` unchanged and add
+       `ADR-Version-Note: Proceeded with stale embedded ADR guidance on [date] - staleness risk accepted for ADR v[current-adr-version].` to the story header. Note this under "Deviations" in the Phase 6 summary.
+     - If [C]: stop. Do not spawn any agent.
+   - **Absent or `uncommitted`**: treat as a legacy/unversioned story and fall
+     back to targeted ADR section reads if the embedded guidance could be stale.
+3. If the story has a non-empty `ADR Decision Summary` and non-empty
+   `Implementation Notes`, treat them as the ADR-derived implementation
+   guidance. Do not re-read the full Decision or Implementation Guidelines.
+4. If either embedded section is missing, clearly stale, or ambiguous, read only
+   the smallest relevant ADR section(s): `Decision`, `Implementation
+   Guidelines`, `Engine Compatibility`, or `ADR Dependencies`.
+5. For large ADRs that exceed the Read tool limit, use `Grep`/heading searches
+   and offset/limit reads around the needed headings. Do not retry full-file
+   reads.
+
+Only pass full ADR content to a sub-agent when the story's embedded guidance is
+insufficient and you can explain exactly which section was needed.
 
 ### The control manifest
 Read `docs/architecture/control-manifest.md`. Extract the rules for this story's layer:
@@ -180,7 +215,7 @@ Brief the agent with file paths and targeted reading instructions — do not ser
 
 1. **Story file**: `[story-path]` — read in full
 2. **GDD requirement**: look up TR-ID `[TR-XXX-NNN]` in `docs/architecture/tr-registry.yaml` — use the `requirement` field as source of truth
-3. **ADR**: `docs/architecture/[adr-file].md` — read the **Decision** and **Implementation Guidelines** sections only
+3. **ADR guidance**: verify the story's **ADR Version** against the current ADR commit date, then use the embedded **ADR Decision Summary** and **Implementation Notes** first when the version matches. Read `docs/architecture/[adr-file].md` only for status validation, version-mismatch refresh, or targeted missing sections; do not read the full ADR by default.
 4. **Control manifest**: `docs/architecture/control-manifest.md` — read rules for the **[layer]** layer only
 5. **Engine preferences**: `.claude/docs/technical-preferences.md` — read naming conventions and performance budgets
 6. **Test file path**: `[path from story's Test Evidence section]` — this file must be created as part of implementation

@@ -27,6 +27,7 @@ Verified automatically by `/skill-test static` — no fixture needed.
 - [ ] Has a next-step handoff at the end (`/story-readiness`, `/dev-story`)
 - [ ] Documents story Status: Blocked when governing ADR is Proposed
 - [ ] Documents QL-STORY-READY gate: active in full mode, skipped in lean/solo
+- [ ] Embeds ADR Version from the governing ADR's last commit date so `/dev-story` can detect stale story guidance deterministically
 
 ---
 
@@ -59,13 +60,13 @@ In `solo` mode: QL-STORY-READY is skipped with equivalent notes.
 **Expected behavior:**
 1. Skill reads EPIC.md, GDD, governing ADRs, control manifest, and TR registry
 2. Classifies each requirement into a story type (Logic / Integration / Visual/Feel / UI / Config/Data)
-3. Drafts 3 story files with correct frontmatter schema
+3. Drafts 3 story files with correct frontmatter schema, including ADR Version beside the governing ADR
 4. QL-STORY-READY is skipped (lean mode) — noted in output
 5. Asks "May I write" before writing each story file
 6. Writes all 3 story files after approval
 
 **Assertions:**
-- [ ] Each story's frontmatter contains: Title, Epic, Layer, Priority, Status, TR-ID, ADR reference, Acceptance Criteria, DoD
+- [ ] Each story's frontmatter contains: Title, Epic, Layer, Priority, Status, TR-ID, ADR reference, ADR Version, Acceptance Criteria, DoD
 - [ ] Story types are correctly classified (at least one Logic type in fixture)
 - [ ] "May I write" is asked per story (not once for the entire batch)
 - [ ] QL-STORY-READY skip is noted in output
@@ -176,6 +177,7 @@ In `solo` mode: QL-STORY-READY is skipped with equivalent notes.
 - [ ] "May I write" asked per story (not once for the entire batch)
 - [ ] Blocked stories flagged before write approval — not discovered after writing
 - [ ] TR-IDs reference the registry — requirement text is not embedded inline in story files
+- [ ] ADR Version is embedded from `git log -1 --format=%cs -- [adr-file]` when an ADR governs the story
 - [ ] Control manifest rules quoted per-story from the manifest, not invented
 - [ ] Ends with next-step handoff: `/story-readiness` → `/dev-story`
 

@@ -2,11 +2,14 @@
 
 ## Skill Summary
 
-`/dev-story` reads a story file, loads all required context (referenced ADR,
-TR-ID from the registry, control manifest, engine preferences), implements the
-story, verifies that all acceptance criteria are met, and marks the story
-Complete. The skill routes implementation to the correct specialist agent based
-on the engine and file type — it does not write source code directly.
+`/dev-story` reads a story file, loads all required context (TR-ID from the
+registry, story-embedded ADR guidance, control manifest, engine preferences),
+implements the story, verifies that all acceptance criteria are met, and marks
+the story Complete. It validates the referenced ADR status with targeted reads,
+but does not re-read full ADR files by default when `/create-stories` already
+embedded the Decision Summary and Implementation Notes. The skill routes
+implementation to the correct specialist agent based on the engine and file
+type — it does not write source code directly.
 
 In `full` review mode, an LP-CODE-REVIEW gate runs before marking the story
 Complete. In `lean` or `solo` mode, LP-CODE-REVIEW is skipped and the story is
@@ -26,6 +29,9 @@ Verified automatically by `/skill-test static` — no fixture needed.
 - [ ] Has a next-step handoff at the end (`/story-done`)
 - [ ] Documents LP-CODE-REVIEW gate: active in full mode, skipped in lean/solo
 - [ ] Notes that implementation is delegated to specialist agents (not done directly)
+- [ ] Uses story-embedded ADR Decision Summary / Implementation Notes as the primary implementation brief
+- [ ] Avoids full ADR reads by default; uses targeted ADR section reads only for validation or missing/stale guidance
+- [ ] Checks story ADR Version against the current ADR last-commit date before trusting embedded ADR guidance
 
 ---
 
@@ -49,6 +55,7 @@ In `solo` mode: LP-CODE-REVIEW is skipped with equivalent notes.
 - A story file exists at `production/epics/[layer]/story-[name].md` with:
   - `Status: Ready`
   - A TR-ID referencing a registered requirement
+  - `ADR Version:` matching the current governing ADR last commit date
   - At least 2 Given-When-Then acceptance criteria
   - A test evidence path
 - Referenced ADR has `Status: Accepted`
@@ -59,8 +66,8 @@ In `solo` mode: LP-CODE-REVIEW is skipped with equivalent notes.
 **Input:** `/dev-story production/epics/[layer]/story-[name].md`
 
 **Expected behavior:**
-1. Skill reads the story file and all referenced context
-2. Skill verifies the ADR is Accepted (no block)
+1. Skill reads the story file and all required context
+2. Skill verifies the ADR is Accepted using a targeted status read (no block)
 3. Skill routes implementation to the correct specialist agent
 4. All acceptance criteria are verified as met
 5. LP-CODE-REVIEW gate spawns and returns APPROVED
@@ -70,6 +77,8 @@ In `solo` mode: LP-CODE-REVIEW is skipped with equivalent notes.
 **Assertions:**
 - [ ] Skill reads story before spawning any agent
 - [ ] ADR status is checked before implementation begins
+- [ ] ADR Version is compared against the governing ADR's current last-commit date before embedded guidance is trusted
+- [ ] Skill uses the story's embedded ADR Decision Summary and Implementation Notes instead of re-reading the full ADR
 - [ ] Implementation is delegated to a specialist agent (not done inline)
 - [ ] All acceptance criteria are confirmed before LP-CODE-REVIEW
 - [ ] LP-CODE-REVIEW appears in output as a completed gate
@@ -88,7 +97,7 @@ In `solo` mode: LP-CODE-REVIEW is skipped with equivalent notes.
 
 **Expected behavior:**
 1. Skill reads the story file
-2. Skill resolves the TR-ID and reads the governing ADR
+2. Skill resolves the TR-ID and reads enough of the governing ADR to verify status
 3. ADR status is Proposed — skill outputs a BLOCKED message
 4. Skill names the specific ADR blocking the story
 5. Skill recommends running `/architecture-decision` to advance the ADR
@@ -184,10 +193,35 @@ In `solo` mode: LP-CODE-REVIEW is skipped with equivalent notes.
 
 ---
 
+### Case 6: Stale ADR Version - Skill prompts before implementation
+
+**Fixture:**
+- Story has `ADR Version: 2026-01-15`
+- Governing ADR's current `git log -1 --format=%cs -- [adr-file]` date is `2026-03-10`
+- Story has embedded ADR Decision Summary and Implementation Notes
+
+**Input:** `/dev-story production/epics/[layer]/story-[name].md`
+
+**Expected behavior:**
+1. Skill reads the story file and detects the ADR Version mismatch
+2. Skill asks whether to refresh targeted ADR guidance, proceed with stale guidance, or stop
+3. Implementation does NOT begin until the user chooses a path
+4. If refresh is chosen, the skill reads only targeted ADR sections and updates embedded story guidance before spawning a programmer
+
+**Assertions:**
+- [ ] Skill does not trust matching-looking embedded ADR guidance when ADR Version is stale
+- [ ] User is prompted before implementation
+- [ ] Refresh path uses targeted ADR section reads, not a full ADR read by default
+- [ ] Proceed-with-risk path records an ADR-Version-Note in the story header without rewriting the stale ADR Version
+
+---
+
 ## Protocol Compliance
 
 - [ ] Does NOT write source code directly — delegates to specialist agents
-- [ ] Reads all context (story, TR-ID, ADR, manifest, engine prefs) before implementation
+- [ ] Reads all context (story, TR-ID, story-embedded ADR guidance, manifest, engine prefs) before implementation
+- [ ] Does not perform unbounded full-file ADR reads unless embedded guidance is missing, stale, or ambiguous
+- [ ] Verifies ADR Version freshness before relying on story-embedded ADR guidance
 - [ ] "May I write" asked before updating story status and before writing code files
 - [ ] Skipped gates noted by name and mode in output
 - [ ] Updates `production/session-state/active.md` after story completion