Merge remote-tracking branch 'origin/main' into jeffhorn/27-reinforce-durable-artifact-gates

jeffhorn-nava · jeffhorn-nava · commit 0e927fcee1be · 2026-07-10T19:12:42.000-04:00
# Conflicts:
#	README.md
diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md
@@ -9,6 +9,8 @@ labels: bug
 
 - [ ] Reviewed by human engineer
 - [ ] Issue refinement complete
+- [ ] All open questions answered
+- [ ] Post-refinement changes reviewed by human
 - [ ] Ready for work
 
 ## What happened
diff --git a/.github/ISSUE_TEMPLATE/chore.md b/.github/ISSUE_TEMPLATE/chore.md
@@ -9,6 +9,8 @@ labels: chore
 
 - [ ] Reviewed by human engineer
 - [ ] Issue refinement complete
+- [ ] All open questions answered
+- [ ] Post-refinement changes reviewed by human
 - [ ] Ready for work
 
 ## What and why
diff --git a/.github/ISSUE_TEMPLATE/epic.md b/.github/ISSUE_TEMPLATE/epic.md
@@ -9,6 +9,8 @@ labels: epic
 
 - [ ] Reviewed by human engineer
 - [ ] Issue refinement complete
+- [ ] All open questions answered
+- [ ] Post-refinement changes reviewed by human
 - [ ] Ready for work
 
 ## Goal
diff --git a/.github/ISSUE_TEMPLATE/spike.md b/.github/ISSUE_TEMPLATE/spike.md
@@ -9,6 +9,8 @@ labels: spike
 
 - [ ] Reviewed by human engineer
 - [ ] Issue refinement complete
+- [ ] All open questions answered
+- [ ] Post-refinement changes reviewed by human
 - [ ] Ready for work
 
 ## Question to answer
diff --git a/.github/ISSUE_TEMPLATE/story.md b/.github/ISSUE_TEMPLATE/story.md
@@ -9,6 +9,8 @@ labels: story
 
 - [ ] Reviewed by human engineer
 - [ ] Issue refinement complete
+- [ ] All open questions answered
+- [ ] Post-refinement changes reviewed by human
 - [ ] Ready for work
 
 ## What and why
diff --git a/.github/ISSUE_TEMPLATE/technical-task.md b/.github/ISSUE_TEMPLATE/technical-task.md
@@ -9,6 +9,8 @@ labels: technical-task
 
 - [ ] Reviewed by human engineer
 - [ ] Issue refinement complete
+- [ ] All open questions answered
+- [ ] Post-refinement changes reviewed by human
 - [ ] Ready for work
 
 ## What we decided
diff --git a/.github/workflows/generate-docs.yml b/.github/workflows/generate-docs.yml
@@ -1,6 +1,6 @@
 name: Generate Strata Docs
 # Full regeneration is a deliberate, maintainer-run action — manual dispatch only.
-# Routine drift refresh + new-source pickup lives in update-docs.yml (cron + manual).
+# Routine drift refresh + new-source pickup lives in update-docs.yml.
 on:
   workflow_dispatch:
 
diff --git a/AGENTS.md b/AGENTS.md
@@ -93,11 +93,13 @@ Use the template that best fits the work; GitHub surfaces these on new-issue.
 For `technical-task.md`, fill "Starting point" and "Constraints and gotchas" thoroughly; those are
 what an agent or new developer needs to pick up work cold.
 
-The `create-issue` skill guides choosing the template, wording, labeling, reviewing, and filing.
+The `create-issue` skill guides checking for duplicates, choosing the template, wording, labeling, reviewing, and filing.
+After initial human review, the `refine-issue` skill pressure-tests an existing issue for sprint
+readiness.
 
 ## Architecture and CI
 
-Deep reference lives in two rule files under `rules/` at the repo root. Claude Code auto-loads each
+Deep reference lives in rule files under `rules/` at the repo root. Claude Code auto-loads each
 when you touch a path its `paths:` frontmatter matches; other tools do not, so open the relevant file
 directly when working the paths noted below.
 
@@ -106,6 +108,8 @@ directly when working the paths noted below.
   `skills/generate-strata-docs/`, or anything under `docs/`.
 - `rules/ci.md`: the lint pipeline and the doc-generation workflows. Applies when editing
   `.github/workflows/` or doc frontmatter.
+- `rules/subagent-model-tiers.md`: which Claude model to give a sub-agent that a skill dispatches
+  via the `Agent`/Task tool. Applies when editing anything under `skills/`.
 
 ## Conventions and gotchas
 
@@ -118,8 +122,8 @@ directly when working the paths noted below.
   `.claude/settings.local.json` is per-user and not committed. See `rules/architecture.md`.
 - `docs/INDEX.md` and `docs/graph.json` are generated by `build_graph`; never hand-edit them.
 - `docs/.verification/` and `docs/.curation/` are the audit trail; never delete them.
-- Other pipeline-internal conventions (the shared `scripts/frontmatter.py` parser, the
-  `docs/superpowers/` design spec and `§` references) live in `rules/architecture.md`.
+- Other pipeline-internal conventions (the shared `scripts/frontmatter.py` parser) live in
+  `rules/architecture.md`.
 
 ## Documentation maintenance
 
@@ -131,7 +135,7 @@ Keep these current as the project evolves; update before closing the PR.
 | New source type | Profile in `skills/generate-strata-docs/references/profiles/` and `sources.md` |
 | New registry key | The relevant registry file, before any doc references it |
 | New issue template or workflow convention | `CONTRIBUTING.md` and Workflow above |
-| Architecture change | `rules/architecture.md`, and `docs/superpowers/specs/` if the design spec is affected |
+| Architecture change | `rules/architecture.md` |
 | CI workflow change | `rules/ci.md` |
 
 If a change makes a section stale, update it in the same PR. Do not leave documentation that
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -5,8 +5,13 @@
 The short version of how a change moves through this repo:
 
 1. **Start from an issue.** File one with the template that fits the work (epic, story, bug,
-   technical-task, spike, or chore). The `create-issue` skill walks you through choosing a template,
-   wording it for its audience, reviewing it, labeling it, and filing it.
+   technical-task, spike, or chore). The `create-issue` skill walks you through checking for
+   duplicates, choosing a template, wording it for its audience, reviewing it, labeling it, and filing it.
+   Every template opens with an "Issue readiness state" checklist that tracks the issue's lifecycle: reviewed by a human
+   engineer, refinement complete, all open questions answered, post-refinement changes reviewed by
+   a human, and ready for work. Tick the boxes as the issue advances; the `refine-issue` skill
+   manages the middle three and requires the initial human review (at least one human comment on
+   the issue) before it will run.
 2. **Branch.** Use the naming shape in [Branching](#branching) below.
 3. **Make your changes.** Keep commits terse and explain why, not what. Wire up the commit template
    (see [Commit message template](#commit-message-template)).
diff --git a/README.md b/README.md
@@ -25,7 +25,7 @@ sources, producing a linked, agent-queryable knowledge base.
 
 - **Locally:** open this repo in Claude Code and invoke the `generate-strata-docs` skill
   (uses your own Claude auth; needs git access to the source repos and Python 3.13).
-- **In CI:** the `Generate Strata Docs` Action (manual, weekly, or on `sources.md` change)
+- **In CI:** the `Generate Strata Docs` Action (manual)
   runs the skill and opens a PR.
   Requires the `ANTHROPIC_API_KEY` and `SOURCES_READ_TOKEN` secrets.
 
@@ -43,8 +43,6 @@ in `.claude/settings.json`) that nudge `gh pr create` / `gh issue create` toward
 create-issue skills and list the staged set before `git commit`. They only remind, never block; see
 `rules/architecture.md`.
 
-See `docs/superpowers/specs/2026-06-18-strata-documentation-engine-design.md` for the design.
-
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow, branch naming, commit
diff --git a/rules/architecture.md b/rules/architecture.md
@@ -86,5 +86,3 @@ committed.
 - `docs/.verification/` and `docs/.curation/` are audit trail. Keep them.
 - `scripts/frontmatter.py` is the shared YAML parser for linter and graph builder. Change it in one
   place.
-- The design spec and plan live in `docs/superpowers/{specs,plans}/`; section references like `§3.3`
-  in code and the skill point back to that spec.
diff --git a/rules/subagent-model-tiers.md b/rules/subagent-model-tiers.md
@@ -0,0 +1,22 @@
+---
+paths:
+  - "skills/**"
+---
+
+# Sub-agent model tiers
+
+Which Claude model to give a sub-agent when a skill dispatches one via the `Agent`/Task tool.
+Auto-loaded by Claude Code when you edit anything under `skills/`. Choose by the kind of work the
+sub-agent does. This rule covers model choice only, not effort level.
+
+- **Tier 1, Opus.** Sub-agents that reason at length, hold large context, ask probing questions,
+  debate, or make thoughtful judgment calls. Examples: a product-versus-engineering debate,
+  reviewing a draft against its sources, adjudicating whether a change is warranted.
+- **Tier 2, Sonnet.** Sub-agents doing everyday, well-scoped work: synthesis, drafting from an
+  already-decided set of inputs, routine transforms.
+- **Tier 3, Haiku.** Sub-agents that only execute an already-decided plan, following instructions
+  authored by a higher tier. No open-ended reasoning.
+
+In practice: `review-draft` keeps its parallel reviewers on a cheap tier and its adjudication in a
+more capable model; `refine-issue` runs its debate, review, and adjudication roles on Opus and its
+planner on Sonnet. Neither skill sets effort.
diff --git a/scripts/lint_docs.py b/scripts/lint_docs.py
@@ -37,12 +37,12 @@ def _parse_fenced_keys(path):
 
 
 def load_feature_keys(path):
-    """Canonical SDK feature keys from feature-keys.md (cross-link anchor, §3.3)."""
+    """Canonical SDK feature keys from feature-keys.md (cross-link anchor)."""
     return _parse_fenced_keys(path)
 
 
 def load_platform_components(path):
-    """Canonical platform component ids from platform-components.md (cross-link anchor, §3.3b)."""
+    """Canonical platform component ids from platform-components.md (cross-link anchor)."""
     return _parse_fenced_keys(path)
 
 
diff --git a/skills/create-issue/SKILL.md b/skills/create-issue/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: create-issue
-description: Guides filing a new GitHub issue: picks the right template, writes it in the right register, applies the matching label, reviews the draft, and files it. Use when opening a new issue for this repo.
+description: Guides filing a new GitHub issue: checks for duplicates, picks the right template, writes it in the right register, applies the matching label, reviews the draft, and files it. Use when opening a new issue for this repo.
 ---
 
 # Create Issue
@@ -16,7 +16,40 @@ sure which template fits or how technical the wording should be.
 
 ## Steps
 
-### 1. Choose the template
+### 1. Check for duplicates
+
+Before choosing a template or writing anything, search existing issues for one that already tracks
+this work. Search open and closed together, since a `wontfix` or already-closed duplicate changes
+whether to file at all:
+
+```bash
+gh search issues --repo navapbc/strata-documentation-engine --include-prs "<keywords>"
+```
+
+Omit `--state` so the search spans open and closed; `--include-prs` widens it to pull requests,
+since a PR may already be doing the work. (`gh issue list` never returns PRs, whatever its `--state`.)
+
+Judge by the work, not the topic: two issues that merely mention the same subject are not
+duplicates. A duplicate tracks the same change or investigation. Then:
+
+- **A near-duplicate is open** → comment on or update it instead of filing, and stop here.
+- **A new issue is still warranted** → proceed, and note in the body why it is not a duplicate of the
+  ones you found (link them).
+- **You still intend to file over a plausible duplicate** → surface it to the person at the keyboard
+  and get their explicit confirmation before continuing. Never file silently over a known potential
+  duplicate.
+
+When resolving this means closing an issue as a duplicate of another, confirm with the person at the
+keyboard first (closing and commenting publicly is an outward-facing action), then close it with the
+`duplicate` label:
+
+```bash
+gh issue close <n> --repo navapbc/strata-documentation-engine --reason "not planned" \
+  --comment "Duplicate of #<m>."
+gh issue edit <n> --repo navapbc/strata-documentation-engine --add-label duplicate
+```
+
+### 2. Choose the template
 
 Pick the template that matches the work. Templates live in `.github/ISSUE_TEMPLATE/`.
 
@@ -32,7 +65,7 @@ Pick the template that matches the work. Templates live in `.github/ISSUE_TEMPLA
 If two seem to fit, prefer the less technical one for anything a non-engineer might file (`story`
 over `technical-task`, `bug` over `technical-task`).
 
-### 2. Write in the right register
+### 3. Write in the right register
 
 - **Product templates** (`epic`, `story`): plain, outcome-oriented language. Describe user value and
   what success looks like, not the implementation.
@@ -48,18 +81,18 @@ it is optional.
 Write the body one line per paragraph; do not hard-wrap it. See "Formatting issue and PR bodies" in
 `CONTRIBUTING.md` for why.
 
-### 3. Apply the matching label
+### 4. Apply the matching label
 
 Each template declares its label (`epic`, `story`, `bug`, `technical-task`, `spike`, `chore`). Apply
 that label when filing. If the label does not exist yet, create it first.
 
-### 4. Review the draft
+### 5. Review the draft
 
 Run the `review-draft` skill on the issue body before filing. It checks quality, template adherence,
 voice, punctuation (no em dashes), formatting (no hard-wrapped body), and house style. Apply the
 findings you agree with.
 
-### 5. File
+### 6. File
 
 Present the final draft for approval, then file it. Pass the body via a file so multi-line markdown
 survives the shell:
diff --git a/skills/generate-strata-docs/SKILL.md b/skills/generate-strata-docs/SKILL.md
@@ -118,7 +118,7 @@ Summarize: docs generated per source, sources **skipped** (with reason), docs ma
 run), any **orphaned** sources (docs whose source left `sources.md`), and any `source_delta`
 **warnings**.
 In CI the
-Action opens/updates the PR, **committing each doc with its `distillation_note` (§3.6) in the
+Action opens/updates the PR, **committing each doc with its `distillation_note` in the
 commit message** for an auditable history; the temp `.logs/` are not committed. Locally, leave
 `docs/**` in the working tree for the developer to review and commit.
 
@@ -127,5 +127,5 @@ commit message** for an auditable history; the temp `.logs/` are not committed.
 - One model per source / one verify-fix loop per doc. **full mode** rebuilds every source;
   **update mode** (via `scripts/source_delta.py`) re-documents only new + changed sources, skips
   unchanged ones, and throttles drifted sources whose docs are less than a week old.
-- This skill commits to the `Workflow` tool (spec §8, no fallback). If `Workflow` is
+- This skill commits to the `Workflow` tool (no fallback). If `Workflow` is
   unavailable in the runtime, stop and escalate — do not silently substitute another dispatch.
diff --git a/skills/generate-strata-docs/references/agents/source-doc.md b/skills/generate-strata-docs/references/agents/source-doc.md
@@ -29,7 +29,7 @@ never talk to a user.
    `YYYY-MM-DD`) in every doc's frontmatter. Update mode uses it to throttle re-documentation of
    frequently-changing sources — a drifted source is re-documented only once its docs are at least
    a week old. If no run date was provided, omit the field rather than guessing a date.
-4. Write a **distillation log** to `.logs/<id>.distillation.md` (spec §3.6): which files/symbols
+4. Write a **distillation log** to `.logs/<id>.distillation.md`: which files/symbols
    you read and which you skipped, the judgment calls you made (what to document/drop/ambiguous),
    gaps or weak spots in the source, and a short per-doc distillation note (one line each)
    suitable for that doc's commit message.
diff --git a/skills/refine-issue/SKILL.md b/skills/refine-issue/SKILL.md
