agentshore 0.3.2__tar.gz

agentshore-0.3.2/.agents/skills/agentshore-calibrate-alignment/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: agentshore-calibrate-alignment
+description: "Action slot 18 — Calibrate Alignment. Cross-references open/merged GitHub PRs against the beads task graph, updates in-progress and closed task states, and outputs updated epic closure ratios."
+argument-hint: []
+disable-model-invocation: true
+allowed-tools: Read, Bash(gh:*, git:*, bd:*)
+---
+
+# agentshore-calibrate-alignment
+
+You are a AgentShore skill agent. AgentShore is a pure RL scheduler — not an LLM.
+It invoked you with no parameters — this skill is self-contained.
+
+## Inputs
+
+None. All data is sourced from the beads project graph (`bd` CLI) and GitHub PRs.
+
+## Forbidden mutations
+
+Do **not** create, modify, delete, or rename any of the following:
+
+- `.github/workflows/**` or any CI/CD configuration
+- Source code files, test files, or configuration files
+- `package.json`, `pyproject.toml`, or any dependency manifest
+- GitHub issues (do not create, edit, or close issues)
+
+This skill only updates **beads task states** — nothing else.
+
+## Step 1 — Pre-flight
+
+1. Read `.agentshore/context.json` if it exists. Extract `repo`, `owner`, and session context.
+2. Confirm the beads graph is initialised by checking `.beads/` exists, then run
+   `bd list --all --json --limit 0`. If this fails or returns no epic beads, emit
+   `success: false` with error `"beads not initialised or no epics"` and stop.
+3. Record the working directory as `REPO_ROOT=$(pwd)`.
+
+## Step 2 — Load current beads state
+
+1. Fetch the full beads graph, including closed tasks:
+   ```
+   bd list --all --json --limit 0
+   ```
+   Parse epics, stories, tasks, `parent`, `parent_id`, and `dependencies` entries where
+   `type == "parent-child"`. Resolve every task to its owning epic through the parent chain.
+   Record this as the **before** snapshot.
+
+2. Compute closure from all task beads:
+   - `total_tasks`: every bead with `type == "task"`, including closed tasks.
+   - `closed_tasks`: task beads with `status == "closed"`.
+   - `closure_ratio`: `closed_tasks / total_tasks`, or `0.0` when an epic has no tasks.
+   For each task, record its `id`, `title`, `status`, parent chain, owning epic, and `external_ref`
+   (format `gh-N` means it mirrors GitHub issue #N).
+
+## Step 3 — Fetch GitHub state
+
+1. Fetch open and recently closed GitHub issues:
+   ```
+   gh issue list --state open --limit 200 --json number,title,state
+   gh issue list --state closed --limit 200 --json number,title,state,closedAt
+   ```
+   Build `closed_issue_numbers` from the closed issue list. This is the authoritative source
+   for closing mirrored beads.
+
+2. Fetch all open PRs:
+   ```
+   gh pr list --state open --limit 200 --json number,title,body,headRefName,author
+   ```
+
+3. Fetch recently merged PRs for context and reporting:
+   ```
+   gh pr list --state merged --limit 100 --json number,title,body,headRefName,mergedAt
+   ```
+
+4. For each PR (open and merged), extract referenced issue numbers from the body.
+   Scan for these patterns (case-insensitive):
+   - `Closes #N`
+   - `Fixes #N`
+   - `Resolves #N`
+   - `Close #N`
+   - `Fix #N`
+   - `Resolve #N`
+
+   Build a map: `issue_number → list of (pr_number, pr_state)` where `pr_state` is
+   `"open"` or `"merged"`.
+
+## Step 4 — Update task states
+
+For each open bead task with an `external_ref` of the form `gh-N`:
+
+1. Extract `N` (the GitHub issue number).
+2. Compare GitHub issue and PR state:
+   - If issue `N` is in `closed_issue_numbers`:
+     - The issue is done. Mark the bead task `closed`:
+       ```
+       bd close <bead_id> --reason "GitHub issue #N is closed"
+       ```
+     - Record this as a `closed` update.
+   - Else if any open PR references this issue:
+     - Work is in progress. Mark the bead task `in_progress` (only if it is currently `open`
+       or `blocked`; do not downgrade a task already `in_progress` or `closed`):
+       ```
+       bd update <bead_id> --status in_progress
+       ```
+     - Record this as an `in_progress` update.
+   - Else (no PR references this issue):
+     - Leave the task state unchanged. Record as `unchanged`.
+
+For tasks **without** an `external_ref` (not mirrored from GitHub): skip — beads-native
+tasks are managed directly and must not be auto-closed by this skill.
+
+## Step 5 — Recompute epic closure ratios
+
+After updating task states, re-fetch the full graph:
+
+```
+bd list --all --json --limit 0
+```
+
+Parse it using the same all-task calculation from Step 2. Record this as the **after** snapshot.
+
+Compute the delta for each epic:
+```
+ratio_delta = after.closure_ratio - before.closure_ratio
+```
+
+## Step 6 — Validate
+
+1. Confirm that only tasks with `external_ref` matching `gh-N` were modified.
+2. Confirm no task was moved to a state lower than its current state
+   (e.g., `closed` → `in_progress` must not happen).
+3. Confirm the `after` epic closure ratios are >= the `before` ratios (calibration
+   can only increase or maintain closure — it never decrements closed counts).
+
+If validation fails for any reason, set `success: false` and describe the violation in `error`.
+
+## Result
+
+Output a fenced JSON block exactly like this:
+
+```json
+{
+  "success": true,
+  "artifacts": [
+    {
+      "epic_id": "bd-001",
+      "epic_title": "Core capture pipeline",
+      "closure_ratio_before": 0.40,
+      "closure_ratio_after": 0.60,
+      "ratio_delta": 0.20
+    }
+  ],
+  "tasks_updated": [
+    {
+      "bead_id": "bd-042",
+      "external_ref": "gh-17",
+      "old_status": "open",
+      "new_status": "in_progress",
+      "pr_number": 34,
+      "pr_state": "open"
+    },
+    {
+      "bead_id": "bd-019",
+      "external_ref": "gh-9",
+      "old_status": "in_progress",
+      "new_status": "closed",
+      "pr_number": 28,
+      "pr_state": "merged"
+    }
+  ],
+  "tasks_unchanged": 12,
+  "error": null
+}
+```
+
+Fields:
+- `artifacts`: one entry per epic with non-zero delta. Epics with `ratio_delta == 0` may be omitted.
+- `tasks_updated`: every task whose state changed, with old/new status and the triggering PR.
+- `tasks_unchanged`: count of tasks skipped (no PR reference or state already correct).
+
+If any step fails, set `"success": false` and populate `"error"`.
+Do not omit the result block under any circumstances.

agentshore-0.3.2/.agents/skills/agentshore-cleanup/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: agentshore-cleanup
+description: "Action slot 13 — Cleanup. Detects the project's toolchain, runs auto-fixers (formatter, lint --fix), re-checks types and tests, opens a PR with any cleanup commits, and files deduplicated issues for unfixable failures. Language-agnostic via manifest detection."
+disable-model-invocation: true
+allowed-tools: Read, Grep, Glob, Bash(*)
+---
+
+# agentshore-cleanup
+
+You are a AgentShore skill agent invoked with parameters in `$ARGUMENTS`.
+
+## Forbidden mutations
+
+Never create, edit, restore, or delete: `.github/workflows/**`, `.github/actions/**`, `.gitlab-ci.yml`, `.circleci/**`, `azure-pipelines.yml`, `Jenkinsfile`, `bitbucket-pipelines.yml`, or tests that assert their existence. If any auto-fixer would touch a forbidden path, exit with `"success": false` and `"error": "ci-change requested but forbidden by skill policy"` and leave all files untouched.
+
+## Inputs
+
+`$ARGUMENTS` — optional target branch name. Empty = default branch (typically `main`).
+
+## Step 1 — Pre-flight
+
+Run cleanup in an isolated worktree pinned to the target branch. Never `git stash`, never `git checkout` in the main worktree, never `git fetch` or `git merge` to advance the branch.
+
+1. Read `.agentshore/context.json` — repo, owner, learnings.
+2. Read project-level config (`CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`) — conventions.
+3. Record the main project directory: `MAIN_REPO=$(pwd)`.
+4. Resolve the target branch: if `$ARGUMENTS` is set, `TARGET="$ARGUMENTS"`; otherwise `TARGET=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@refs/remotes/origin/@@')` (default `main`).
+5. Compute the worktree path: `CLEANUP_WORKTREE="$MAIN_REPO/.agentshore/worktrees/cleanup-$TARGET"`. Remove any stale worktree: `git worktree remove --force "$CLEANUP_WORKTREE" 2>/dev/null || rm -rf "$CLEANUP_WORKTREE"`.
+6. Create the worktree and switch into it:
+   ```
+   git worktree add --detach "$CLEANUP_WORKTREE" "$TARGET"
+   cd "$CLEANUP_WORKTREE"
+   ```
+   Stop with `success: false` if `$TARGET` does not resolve locally.
+
+## Step 2 — Detect toolchain
+
+Project docs are authoritative. Fall back to manifest inspection. Record `tools_detected` and `tools_skipped`. A repo may match multiple ecosystems; run all that are present.
+
+| Ecosystem | Manifest | Manager |
+|---|---|---|
+| Python | `pyproject.toml`, `setup.py` | `uv`, `pip` |
+| JS/TS | `package.json` (+`tsconfig.json`) | `npm`/`npx` |
+| Rust | `Cargo.toml` | `cargo` |
+| Go | `go.mod` | `go` |
+| Ruby | `Gemfile` | `bundle` |
+| Java/Kotlin | `pom.xml`, `build.gradle*` | `./mvnw`, `./gradlew` |
+| C# | `*.csproj`, `*.sln` | `dotnet` |
+| Swift | `Package.swift` | `swift` |
+| C/C++ | `CMakeLists.txt`, `Makefile` | `cmake`/`make` |
+| PHP | `composer.json` | `vendor/bin/...` |
+| Elixir | `mix.exs` | `mix` |
+
+## Step 3 — Auto-fix pass
+
+Run one tool at a time to avoid lockfile / cache contention. Only invoke tools that exist (`command -v <tool>` or `which <tool>`). Record every command executed.
+
+**Python:**
+- `command -v ruff` → `uv run ruff check --fix . && uv run ruff format .` (or `ruff` directly if uv absent)
+- If ruff absent: `command -v black` → `black .`; `command -v isort` → `isort .`
+
+**JS/TS:**
+- If `package.json` has a `lint` script → `npm run lint -- --fix` (attempt; skip if it exits non-zero due to missing `--fix` support)
+- `command -v prettier` or `prettier` in devDependencies → `npx prettier --write .`
+- `command -v eslint` → `npx eslint --fix .`
+
+**Rust:**
+- `cargo fmt`
+- `command -v cargo-clippy` → `cargo clippy --fix --allow-dirty --allow-staged 2>&1`
+
+**Go:**
+- `gofmt -w .`
+- `command -v golangci-lint` → `golangci-lint run --fix 2>&1`
+
+**Ruby:**
+- `bundle exec rubocop -A 2>&1` (only if Gemfile contains `rubocop`)
+
+**Other ecosystems:** record `auto_fix: skipped` — no language-agnostic auto-fixer available.
+
+After all fixers run, check `git diff --stat` inside the worktree to determine whether any files were modified.
+
+## Step 4 — Re-validate (report-only, no auto-fix)
+
+Run the type-checker and test suite for each detected ecosystem. These gates determine `success` but never mutate files.
+
+| Ecosystem | Type check | Test suite |
+|---|---|---|
+| Python | `uv run mypy src/` (or `mypy src/`) | `uv run pytest` (or `pytest`) |
+| JS/TS | `npm run typecheck` or `npx tsc --noEmit` | `npm test` |
+| Rust | `cargo check` | `cargo test` |
+| Go | `go vet ./...` | `go test ./...` |
+| Ruby | *(none)* | `bundle exec rspec` or `bundle exec rake test` |
+| Other | *(skip)* | *(skip)* |
+
+Capture pass/fail, error counts, and first 10 lines of failure output for each tool.
+
+## Step 5 — Commit and open PR
+
+If Step 3 produced a non-empty diff:
+
+1. Create branch `chore/cleanup-$(date +%Y%m%d-%H%M%S)` from the target branch ref:
+   ```
+   git checkout -b chore/cleanup-$(date +%Y%m%d-%H%M%S)
+   ```
+2. Stage modified files only (never `git add -A` — do not stage untracked files):
+   ```
+   git add -u
+   ```
+3. Commit:
+   ```
+   git commit -m "chore: automated code-quality cleanup
+
+   Tools applied: <comma-separated list>
+   Files changed: <N>
+   Fixes applied: <N lint/format fixes>"
+   ```
+4. Push and open a PR:
+   ```
+   gh pr create \
+     --title "chore: cleanup (<tools>)" \
+     --label "agentshore/cleanup" \
+     --body "<per-tool diff summary with file counts>"
+   ```
+   Capture the PR number from the output.
+
+If `git diff --stat` was empty after Step 3, skip this step entirely. Emit `"pr_created": null`.
+
+## Step 6 — File issues for unfixable failures
+
+For each type-check or test failure from Step 4, check for an existing open issue before creating:
+```
+gh issue list --search "<summary>" --label "agentshore/cleanup" --state all --json number,title,state
+```
+
+Skip creation if an open issue already covers the same root problem. Group failures by root cause (e.g., 50 mypy errors from one config gap = one issue). Create using:
+```
+gh issue create \
+  --title "Cleanup: <description>" \
+  --label "agentshore/cleanup" \
+  --body "<Failure type, evidence (file:line), reproduction command, branch>"
+```
+
+## Step 7 — Remove worktree
+
+```
+cd "$MAIN_REPO"
+git worktree remove --force "$CLEANUP_WORKTREE"
+```
+
+## Result
+
+```json
+{
+  "success": true,
+  "artifacts": [
+    {"type": "format", "status": "pass", "files_changed": 12},
+    {"type": "lint_fix", "status": "pass", "fixes_applied": 47},
+    {"type": "typecheck", "status": "pass", "errors": 0},
+    {"type": "test", "status": "pass", "passed": 124, "failed": 0}
+  ],
+  "tools_detected": ["ruff", "mypy", "pytest"],
+  "tools_skipped": ["typescript", "rust"],
+  "pr_created": 215,
+  "issues_created": [],
+  "issues_existing": [],
+  "branch": "main",
+  "error": null
+}
+```
+
+Set `"success": false` only for catastrophic failures: worktree creation failure, push refused after retry, or forbidden-mutation breach. Type-check / test failures keep `"success": true` but populate `"issues_created"`. Always emit the result block.

agentshore-0.3.2/.agents/skills/agentshore-code-review/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: agentshore-code-review
+description: "Action slot 5 — Code Review. Reviews a PR for correctness, safety, test coverage, and code quality, then submits a structured GH review. Creates follow-up issues for non-blocking findings."
+argument-hint: [pr_number]
+disable-model-invocation: true
+allowed-tools: Read, Bash(gh:*, git:*)
+---
+
+# agentshore-code-review
+
+You are a AgentShore skill agent invoked with parameters in `$ARGUMENTS`.
+
+## Inputs
+
+`$ARGUMENTS` — PR number to review (required).
+
+## Step 1 — Pre-flight
+
+1. Read `.agentshore/context.json` — coding standards, review criteria, learnings, known pitfalls.
+2. Read project-level config (`CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`) for coding conventions.
+3. `gh pr view $ARGUMENTS --json number,title,body,baseRefName,headRefName,headRefOid,author,labels,isDraft,reviewDecision,statusCheckRollup,additions,deletions,changedFiles`
+4. **Skip** immediately if: draft PR; label `do-not-merge`/`needs-human-review`; open review requesting changes; or `changedFiles == 0`. For zero-diff, fetch `headRefOid` first, then return:
+
+   ```json
+   {"success": true, "verdict": "SKIP", "error": "zero-diff PR; no review needed", "head_sha": "<sha>",
+    "artifacts": [{"type": "review", "number": $ARGUMENTS, "head_sha": "<sha>", "verdict": "SKIP"}],
+    "findings_count": {"blocking": 0, "non_blocking": 0}, "issues_created": [], "issues_existing": []}
+   ```
+
+5. Note linked issue (`Closes #N`, `Fixes #N`). Record head SHA. If a prior
+   `AGENTSHORE_CODE_REVIEW` comment exists for this SHA, parse its `status:` and
+   `blocking_findings:` lines, then return:
+
+   ```json
+   {"success": true, "verdict": "SKIP", "error": "already reviewed at <sha>", "head_sha": "<sha>",
+    "artifacts": [{"type": "review", "number": $ARGUMENTS, "head_sha": "<sha>", "verdict": "SKIP"}],
+    "prior_verdict": "PASS", "prior_findings_count": {"blocking": 0}, "issues_created": [], "issues_existing": []}
+   ```
+
+   Omit `prior_verdict`/`prior_findings_count` if the comment is unparseable.
+
+## Step 2 — Hard safety checks (auto-BLOCK on any failure)
+
+1. **Diff size** > 2500 lines.
+2. **Credentials** — API keys, tokens, passwords, `.env` additions, `BEGIN PRIVATE KEY`.
+3. **Dangerous patterns** — `unsafe` (Rust); `eval()`/`exec()`/`__import__` (Python); `dangerouslySetInnerHTML`/`eval` (JS/TS); SQL string concatenation; `--no-verify`/`verify=False`.
+4. **New dependencies** — unfamiliar or unvetted packages.
+
+## Step 3 — Fetch and analyze the diff
+
+`gh pr diff $ARGUMENTS` and `gh pr diff $ARGUMENTS --name-only`. Categorize changes (source/tests/config/docs/deps). Flag files with >200 changed lines for extra scrutiny.
+
+## Step 4 — Read changed files in full context
+
+For each changed source file, read it in full — understand callers, surrounding patterns, test coverage. For deps: check version pins, vulnerabilities, license.
+
+## Step 5 — Spec compliance (before code quality)
+
+Verify against the actual diff, not the PR description. Flag: missing requirements, extra unrelated work, misinterpretation of the issue. Any spec failure is blocking.
+
+## Step 6 — Code quality review
+
+Flag each finding with file + line range + reason:
+
+1. **Logic** — does the code do what the linked issue requires?
+2. **Happy-Path Bias** — missing null-checks, unhandled errors, ignored edge cases, empty-collection boundary conditions.
+3. **Naming** — clear and consistent with the codebase.
+4. **Shadow Utilities** — reimplements an existing helper; check `utils/`, `helpers/`, and shared modules first.
+5. **N+1 Trap** — DB queries, API calls, or file reads inside loops.
+6. **Brute-Force Algos** — O(n²) nested loops where a HashMap/set lookup suffices.
+7. **Scope** — PR stays within the linked issue's bounds; no unrelated refactors or features.
+8. **Logic Bloat** — redundant code, overly-verbose patterns, meta-comments restating the next line.
+9. **Type Cowardice** — `Any` (Python) or `any`/`as` casts (TypeScript) bypassing the type system.
+10. **Async/Sync Friction** — blocking calls (`time.sleep`, sync I/O) inside `async` functions.
+11. **Lazy Cloning** — excessive `.clone()`/`.copy()` calls to avoid thinking about ownership.
+12. **Ghost Dependencies** — importing a heavy library for a task covered by stdlib or native ES6+.
+13. **Property Drilling** — props passed through 5+ component layers without Context/State.
+
+## Step 7 — Test coverage
+
+New behavior must have tests. Edge cases from Steps 5–6 must be covered. Tests must not be tautological (testing mocks, not behavior).
+
+## Step 8 — Security
+
+Check for: injection, hardcoded secrets, unsafe deserialization, path traversal, improper access control, unvalidated user input, untrusted new dependencies.
+
+## Step 9 — Classify findings
+
+**Blocking** (must fix before merge): bugs, regressions, security, credential exposure, hard-check failures, spec failures, missing tests for critical paths.
+
+**Non-blocking** (should not delay merge): style, naming, optional perf, doc gaps, follow-up refactors.
+
+## Step 10 — Submit the review
+
+Verdict: **APPROVE** (zero blocking), **REQUEST_CHANGES** (any blocking), **COMMENT** (non-blocking only; use sparingly).
+
+```
+gh pr review $ARGUMENTS --<approve|request-changes|comment> --body "<review body>"
+```
+
+Review body must follow this structure:
+
+```
+AGENTSHORE_CODE_REVIEW
+head_sha: <sha>
+status: PASS|BLOCK
+spec_compliance: PASS|BLOCK
+blocking_findings: <integer>
+non_blocking_findings: <integer>
+
+## Summary
+<one-line verdict>
+
+## Blocking
+<numbered list, or "None">
+
+## Suggestions
+<numbered list, or "None">
+
+For each finding: file, line range, description, suggested fix.
+```
+
+## Step 11 — Apply labels (best-effort; never block on failure)
+
+`PASS`: add `agentshore/approved`, remove `blocked`. `BLOCK`: add `blocked`, remove `agentshore/approved`.
+
+```
+gh pr edit $ARGUMENTS --add-label agentshore/approved 2>/dev/null || true
+```
+
+## Step 12 — Follow-up issues
+
+For each non-blocking improvement: `gh issue create --title "Follow-up: <desc>" --body "Identified during review of PR #$ARGUMENTS.\n\n<details>" --label "agentshore/review"`. Reference in review comment.
+
+## Step 13 — Validate
+
+`gh pr view $ARGUMENTS --json reviews` — confirm review submitted. Confirm follow-up issues created.
+
+## Result
+
+```json
+{
+  "success": true,
+  "artifacts": [{"type": "review", "pr": 42, "verdict": "APPROVE", "head_sha": "abc123"}],
+  "issues_created": [{"number": 55, "title": "Follow-up: add input validation", "url": "https://github.com/owner/repo/issues/55"}],
+  "findings_count": {"blocking": 0, "non_blocking": 2},
+  "spec_compliance": "PASS",
+  "hard_checks": {"diff_size": "pass", "credentials": "pass", "dangerous_patterns": "pass", "dependencies": "pass"},
+  "error": null
+}
+```
+
+Valid `verdict` values: `"APPROVE"`, `"REQUEST_CHANGES"`, `"COMMENT"`, `"SKIP"`. On skip: `"success": true`, `"error"` = reason. On irrecoverable failure: `"success": false`, `"error"` = description. Never omit the result block.

agentshore-0.3.2/.agents/skills/agentshore-design-audit/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: agentshore-design-audit
+description: "Action slot 9 — Design Audit. Reviews project design files, specs, PRDs, ADRs, and related docs against source/tests/GitHub/beads, then creates or links GitHub issues and beads tasks for every concrete unmet requirement."
+argument-hint: []
+disable-model-invocation: true
+allowed-tools: Read, Bash(bd:*, gh:*, git:*)
+---
+
+# agentshore-design-audit
+
+You are a AgentShore skill agent. AgentShore invoked you with parameters in `$ARGUMENTS`.
+
+This play is a focused design/spec gap audit. Do not implement code. Your job is to find concrete
+requirements from project design files that are not implemented and not already represented as open
+work, then create trackable GitHub issues and beads tasks for those gaps.
+
+## Inputs
+
+- Play context: `.agentshore/context.json` or the play-specific context path named in the prompt.
+- Design/spec sources: seed file from context, `docs/PRD.md`, `docs/design/**/*.md`,
+  `docs/specs/**/*.md`, `docs/**/*.md`, `ADR*.md`, `AGENTS.md`, `CLAUDE.md`, `README.md`, and other
+  repo-local planning docs discovered by `git ls-files`.
+- GitHub issues: all open issues plus recently closed issues.
+- Beads graph: `bd list --all --json --limit 0`.
+- Source/tests/docs evidence from the repository.
+
+## Success Condition
+
+Before returning `"success": true`, every concrete requirement you audited must be one of:
+
+- `verified_done`: source/tests/docs evidence shows the requirement exists.
+- `represented_open`: an open GitHub issue and open beads task already track the work.
+- `gap_filled`: this play created or linked an open GitHub issue and open beads task.
+
+Closed GitHub issues, closed beads tasks, or PR titles are not proof. If implementation evidence is
+missing, treat the requirement as unmet and make open work for it.
+
+If any concrete requirement remains without implementation evidence and without open tracking, return
+`"success": false`.
+
+## Workflow
+
+1. Read the play context first and verify the GitHub identity:
+   ```
+   gh api user --jq .login
+   ```
+   If context includes `assigned_github_identity`, compare after lowercasing/casefolding both
+   strings.
+2. Read design/spec files and build a requirement inventory. Each item needs a short title, source
+   file/heading, expected behavior, and acceptance criteria.
+3. Read relevant source/tests/docs to verify implementation. Prefer concrete evidence paths over
+   assumptions.
+4. Fetch GitHub issues:
+   ```
+   gh issue list --state open --json number,title,body,labels --limit 200
+   gh issue list --state closed --json number,title,body,labels --limit 100
+   ```
+5. Read the beads graph:
+   ```
+   bd list --all --json --limit 0
+   ```
+6. For each unmet requirement:
+   - If an open GitHub issue and open beads task already track it, mark `represented_open`.
+   - If only an open GitHub issue exists, create or link a beads task with `external_ref="gh-<N>"`.
+   - If no open GitHub issue exists, create one with source references and acceptance criteria.
+   - If a related issue is closed but implementation evidence is missing, create a follow-up issue.
+7. Link each new or existing gap issue into beads:
+   ```
+   bd create task "<issue title>" --description "Closes gh-<issue_number>" --external-ref "gh-<issue_number>"
+   bd link <task-id> <story-id>
+   ```
+   Use the best matching existing story. If no story fits, create a concise story and link it to the
+   relevant epic. Do not duplicate tasks already linked by `external_ref`.
+8. Re-run `bd list --all --json --limit 0` and verify every gap issue has a matching open beads task.
+
+## Issue Requirements
+
+New GitHub issues must include:
+
+- Source file and heading for the requirement.
+- Why current evidence is insufficient.
+- Acceptance criteria that an implementer can test.
+- Any likely source/test areas to inspect.
+
+Use labels conservatively: `enhancement` by default, plus existing project labels only when clearly
+appropriate.
+
+## Forbidden Mutations
+
+- Do not edit product code, tests, docs, or CI files.
+- Do not close or reopen GitHub issues.
+- Do not delete beads nodes.
+- Do not create duplicate issues for already-open tracked work.
+
+## Result
+
+Output a fenced JSON block exactly like this:
+
+```json
+{
+  "success": true,
+  "artifacts": [
+    {
+      "type": "design_audit",
+      "requirements_scanned": 18,
+      "gaps_found": 3,
+      "issues_created": 2,
+      "issues_linked": 1,
+      "unresolved_gaps": 0,
+      "unknown_requirements": 0,
+      "gap_issue_numbers": [212, 213, 214],
+      "requirement_samples": [
+        {"title": "Render preview cancellation", "status": "gap_filled", "issue": 212},
+        {"title": "Status command JSON output", "status": "verified_done", "evidence": "src/... + tests/..."}
+      ]
+    }
+  ],
+  "issues_created": [212, 213],
+  "issues_linked": [214],
+  "tasks_linked": ["tlc-abc.1", "tlc-def.2"],
+  "error": null
+}
+```
+
+If a GitHub or beads mutation fails, set `"success": false`, include the failed requirement in
+`"error"`, and keep any successfully created issue/task numbers in the result.