feat(design): strengthen DOCS story criteria

design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design
-version: 0.14.0
+version: 0.15.0
 description: >-
   Design-and-decompose workflow that takes a PRD, researches the problem space,
   drafts a technical design document with a requirement-anchored testplan,

design/decomposition-review.md

@@ -63,19 +63,33 @@ expected and should not be flagged as a clarity problem.
 ## Evaluation Criteria
 
 Evaluate the decomposition against these categories, prioritized by
-impact:
+impact. Coverage and completeness checks (criteria 1–8) apply to
+effectively active artifacts only. A story is effectively active
+when it has no `status: removed` marker and its parent epic is also
+active. An epic is effectively active when it has no `status:
+removed` marker. Epic-level checks (criteria 2, 4) evaluate active
+epics; story-level checks evaluate effectively active stories.
+Retained removed files are available for identity and traceability
+audit (criterion 9) but do not satisfy or violate active coverage
+requirements.
 
 1. **Requirement Coverage** — Does the coverage matrix (`07-coverage.md`)
-   map every FR and NFR from the PRD? Do story acceptance criteria
+   map every FR and NFR from the PRD to effectively active stories? A
+   story is effectively active when it has no `status: removed` marker
+   and its parent epic is also active; stories with `status: removed`
+   and unmarked children of removed epics are retained for identity
+   audit but do not satisfy coverage. Do story acceptance criteria
    collectively cover the PRD's acceptance criteria, not just the FR/NFR
    descriptions? Are there stories without PRD traceability — and if so,
    are they justified (e.g., infrastructure prerequisites)? Has any
    requirement been silently dropped, deferred to "v2", or reduced in
    scope?
 
-2. **Epic Structure** — Is each epic organized around user value, not
-   technical layers? Does each epic deliver complete functionality
-   independently? Are T-shirt sizes assigned and consistent with the sizing rubric
+2. **Epic Structure** — Evaluate active epics only (those with no
+   `status: removed` marker). Is each active epic organized around
+   user value, not technical layers? Does each active epic deliver
+   complete functionality independently? Are T-shirt sizes assigned
+   and consistent with the sizing rubric
    (`../_shared/sizing-rubric.md`)? Does each epic's size match its scope
    — story count, component breadth, integration surface? Are any epics
    suspiciously uniform in size when their scope clearly varies? No epic
@@ -99,10 +113,10 @@ impact:
    functionality AND testing (or, for a justified behavior-preserving
    prerequisite, preserved-behavior tests)? Do `[QE]` stories define concrete e2e test
    scenarios that validate user-facing behavior, not duplicate
-   unit/integration tests from `[DEV]` stories? Does each epic with
-   e2e-testable surface include at least one `[QE]` story? Does any
-   story fall back to "manual validation" or "document procedure for QE"
-   where an automated test could be written?
+   unit/integration tests from `[DEV]` stories? Does each active epic
+   with e2e-testable surface include at least one `[QE]` story?
+   Does any story fall back to "manual validation" or "document
+   procedure for QE" where an automated test could be written?
 
 5. **Implementation Traceability** — Do stories correctly reference the
    interface changes they implement and the test cases that validate
@@ -144,15 +158,39 @@ impact:
    as gaps. Do not reject a legitimate prerequisite for adding no new
    feature behavior — that is its nature.
 
-8. **Documentation** — Do `[DOCS]` stories use the `[DOCS]` template
-   (Documentation Scope and Documentation Inputs instead of
-   Implementation Guidance and Testing Approach)? Does the Documentation
-   Scope describe what the reader needs to understand without prescribing
-   how to write or organize the documentation? Does the Documentation
-   Inputs section inventory all user-facing artifacts from the
-   implementation stories it references? Is the inventory detailed enough
-   for a documentation author to know what to look for in the
-   implementation?
+8. **Documentation** — Do `[DOCS]` stories satisfy the `[DOCS]` story
+   quality criteria from the decompose skill that the reviewer can
+   evaluate from its available inputs (PRD and decomposition artifacts)?
+   Specifically: does the title include searchable product/feature/
+   command terms (not just `[DOCS] Feature documentation`)? Does the
+   persona/goal/benefit name the actual reader and a concrete task? Are
+   acceptance criteria reader-verifiable documentation outcomes (not
+   implementation artifacts)? Does the Documentation Scope describe what
+   the reader needs to understand without prescribing how to write or
+   organize the documentation? Does the Documentation Inputs section
+   inventory user-facing artifacts from the contributing `[DEV]`/`[UI]`
+   stories? Are `[Assumption]` and `[Open: §9.N]` markers present on
+   items that appear speculative or unresolved? Does the Design
+   Reference include a `Contributing stories` line consistent with the
+   Documentation Inputs headers? Are the contributing story references
+   complete? Note: the reviewer cannot verify whether unmarked
+   Documentation Inputs items are truly derived from the design
+   document or PRD — that provenance check belongs to the decomposer
+   (see the provenance verification in `/decompose`). Flag items that
+   appear speculative or unresolved from the PRD and artifact context
+   alone.
+
+9. **Identity consistency** — Are story and epic IDs, filenames,
+   and directory paths self-consistent across the decomposition
+   artifacts? Do Dependencies, Contributing stories, Documentation
+   Inputs, and the coverage matrix reference story IDs that exist in
+   the actual artifact files? Do any instructions or comments
+   explicitly propose renaming, renumbering, moving, or reusing a
+   story/epic identity? Flag proven inconsistencies (e.g., a
+   referenced Story 2.03 with no corresponding file) or explicit
+   rename/reuse proposals. Absence of historical baseline does not
+   prove identity violation — do not invent allocation history or
+   require the sync manifest.
 
 ## Finding Format
 
@@ -179,9 +217,9 @@ Reference section.
 
 | Severity | Meaning | Action |
 |----------|---------|--------|
-| CRITICAL | Would cause incorrect implementation — missing requirements, contradictory acceptance criteria, broken dependency chain, scope reduction, stories referencing non-existent ICs or TCs, ICs with no implementing story, prerequisite story without justification or dependency declaration | Must fix before presenting |
-| HIGH | Would cause rework — story too large to review in a single PR, missing testing commitment, integration gap between stories, `[QE]` story duplicating `[DEV]` test scope, stories missing Interface Changes or Validated by references, prerequisite story missing preserved-behavior tests | Should fix before presenting |
-| MEDIUM | Would reduce clarity — vague acceptance criteria, imprecise implementation guidance or documentation scope, sizing concerns, minor coverage matrix inconsistencies, minor IC or TC reference inconsistencies | Fix if it adds value |
+| CRITICAL | Would cause incorrect implementation — missing requirements, contradictory acceptance criteria, broken dependency chain, scope reduction, stories referencing non-existent ICs or TCs, ICs with no implementing story, prerequisite story without justification or dependency declaration, `[DOCS]` story missing contributing stories or with Documentation Inputs that omit user-facing artifacts from referenced implementation stories | Must fix before presenting |
+| HIGH | Would cause rework — story too large to review in a single PR, missing testing commitment, integration gap between stories, `[QE]` story duplicating `[DEV]` test scope, stories missing Interface Changes or Validated by references, prerequisite story missing preserved-behavior tests, `[DOCS]` story with generic title or unidentified reader/task, explicit proposal to rename, renumber, move, or reuse a story/epic identity that would break sync idempotency | Should fix before presenting |
+| MEDIUM | Would reduce clarity — vague acceptance criteria, imprecise implementation guidance or documentation scope, sizing concerns, minor coverage matrix inconsistencies, minor IC or TC reference inconsistencies, `[DOCS]` story with Documentation Inputs items that appear speculative or unresolved from PRD and artifact context but lack `[Assumption]` or `[Open: §9.N]` markers (items verifiable against the PRD need no marker; the decomposer verifies design-derived provenance separately in the provenance sub-step of Step 9) | Fix if it adds value |
 | LOW | Structural improvements — naming consistency, ordering suggestions, documentation clarity | Fix only if clearly valuable |
 
 ## Validation Rules

design/guidelines.md

@@ -30,6 +30,8 @@ artifacts and published output from this workflow.
 - No Jira modifications without explicit user approval and a dry-run preview first.
 - **No scope reduction.** Never silently simplify, defer to "v2", use "placeholder", or say "future enhancement" to reduce scope. If scope won't fit, propose a split — don't reduce.
 - Locked decisions from PRD clarification are binding. No phase may contradict a locked decision without explicit user override.
+- **Identity stability.** Once an epic or story file is created, its number, filename, and containing path are fixed. Do not rename, renumber, or move artifact files. New stories append above the highest existing number in their epic (including removed files); new epics append above the highest existing epic number. Gaps are allowed; retired numbers must not be reused. Title and content may change without renaming the file.
+- **Retirement encoding.** Retirement is encoded as `status: removed` in YAML frontmatter — the `---`-delimited block at the very start of the file. The sync helper's `read_frontmatter` only recognizes this format; a plain Markdown body line `status: removed` is not detected. Merge into existing frontmatter without clobbering other fields; add a valid `---` block before the first heading if none exists.
 - No committing to `main` directly. Use feature branches for `/publish`.
 
 ## Safety

design/references/sync-helper-usage.md

@@ -42,6 +42,9 @@ your responsibility.
 | `render-description <file> <manifest> --type epic\|story [options]` | Render Jira-ready description with resolved refs |
 | `update-manifest <manifest> --operation create\|update\|close --file <f> --jira-key <K> --content-hash <H> [--item-type epic\|story] [--epic-file <E>] [options]` | Record one successful Jira operation (`--epic-file` required for stories) |
 | `compute-hash <file>` | Print SHA-256 of file content |
+| `plan-creation-order <artifacts-dir>` | Plan dependency-first creation order for new stories; output JSON with `ordered`, `blocked`, `errors`, `satisfied_keys`. Exit 0 if plan is valid; exit 1 if `errors` is non-empty (JSON is still printed). Fatal I/O or manifest errors also exit 1 but print only to stderr with no JSON. |
+| `check-ref-availability <artifacts-dir> <story-qid>...` | Check whether stories' referenced stories/epics have Jira keys; output JSON with `ready` and `blocked` lists. Exit 0 if all stories are ready; exit 1 if any story is blocked (JSON is still printed). Fatal manifest/I/O errors also exit 1 with stderr only and no JSON. |
+| `compute-cascade-closures <artifacts-dir> [--close-orphans]` | Compute cascade child closures for parent epic closures (Step 3 preview). Output JSON with `cascades` list: manifest-active children under closing parents not already individually categorized as removed. Add `--close-orphans` when user selected option (a) for orphans in Step 1. |
 | `migrate-manifest <manifest>` | Upgrade v1 manifest to v2 in place |
 
 The `prepare` subcommand is preferred over separate `compute-hash` +
@@ -60,10 +63,12 @@ Jira keys from the manifest:
 - `Stories 1.01, 2.01, 3.01` → resolve each → `EDM-XXXX, EDM-AAAA, EDM-BBBB`
 
 The manifest is built incrementally: each issue's key is recorded
-immediately after creation.  Since epics are created first and stories
-are created in epic order (Epic 1 stories before Epic 2 stories),
-dependencies — which reference earlier stories — are always resolvable
-by the time they're needed.
+immediately after creation.  Epics are created first (Step 5), then
+all new stories are created in a feature-wide dependency-first order
+planned by `plan-creation-order` (Step 6a) — each story's required
+keys are available from the manifest by the time it is created. The
+local numeric identifiers (Epic 1, Story 1.01) are
+stable artifact identities, not creation readiness indicators.
 
 If a reference cannot be resolved (the referenced item hasn't been
 created yet or failed to create), the helper leaves the local
@@ -213,3 +218,59 @@ select the terminal/done-category transition.  If multiple terminal
 transitions are available, prefer "Done" over "Closed."  If no terminal
 transition is available from the current status, report the error and
 let the user handle it in Jira.
+
+## Reference-Availability Guard
+
+Before calling `prepare` for a story in Steps 6a or 6b, verify that
+every required reference has a Jira key.  Run `check-ref-availability`
+with the story's qualified ID:
+
+```bash
+REF_ERR=$(mktemp) || { echo "FATAL: cannot create temp file" >&2; exit 1; }
+REF_EXIT=0
+REF_CHECK=$(python3 "$SYNC_HELPER" check-ref-availability \
+  .artifacts/design/{issue-key}/ \
+  "story-{N}.{NN}" 2>"$REF_ERR") || REF_EXIT=$?
+REF_ERR_TEXT=$(cat "$REF_ERR")
+rm -f "$REF_ERR"
+```
+
+The `|| REF_EXIT=$?` idiom captures a nonzero exit without aborting
+under `set -e`.  The two lines after the helper call read stderr text
+and remove the temp file immediately — before branch interpretation
+— so cleanup cannot be forgotten on any exit path.  Apply the
+three-branch interpretation from `../skills/sync.md` Step 6a (ready → proceed;
+blocked → skip; catch-all → stop and report `REF_ERR_TEXT`).
+
+The subcommand accepts one or more qualified IDs.  For each story it:
+
+1. Reloads the manifest fresh from `sync-manifest.json`
+2. Reads the story's artifact file and extracts Dependencies (Story and
+   Epic refs) and Contributing stories (for `[DOCS]` stories only)
+3. Checks that native Jira keys are treated as available (external)
+4. Verifies the owning epic (`epic-{N}`) has a Jira key in the manifest
+5. Returns JSON with `ready` and `blocked` lists
+
+**Exit code:** 0 when all stories are ready; 1 when any story is
+blocked.
+
+**JSON output:**
+
+```json
+{
+  "ready": [
+    {"qid": "story-1.01", "refs": {"story-2.01": "EDM-201"}}
+  ],
+  "blocked": [
+    {"qid": "story-1.02", "missing": ["epic-3"], "reason": "..."}
+  ]
+}
+```
+
+**Invariants:**
+
+- Never mutates the manifest or source files
+- Contributing stories affect creation ORDER but do NOT add native Jira
+  blocking relationships
+- Keys recorded by `update-manifest` earlier in this run are immediately
+  visible (manifest is reloaded from disk on each call)