agentdeck-sdk 4.0.4__tar.gz → 5.0.0__tar.gz

agentdeck_sdk-5.0.0/.agents/skills/deck-cleanup/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: deck-cleanup
+description: Audit and remove one kind of AgentDeck codebase entropy with evidence, isolated work, and narrow changes. Use for narrative prose, dead code, duplicate helpers, or pattern drift; not feature work or mixed refactors.
+---
+
+# Deck Cleanup
+
+Remove entropy without changing unrelated behavior.
+
+## Scope
+
+- Classify findings as narrative prose, dead code, duplicate helpers, or pattern drift.
+- A broad audit may inspect every category, but each category gets a separate branch and review path.
+- Inspect active branches and worktrees before choosing files. Avoid paths under concurrent development.
+- Work in an isolated worktree and preserve unrelated user changes.
+- For an interactive cleanup, propose and apply one small block at a time.
+
+## Evidence
+
+### Narrative prose
+
+Run `uv run scripts/slopcheck.py --all <file>` on one file at a time. The tool does not replace manual review.
+
+Delete prose when the code remains clear. Keep only concise public contracts or non-obvious rationale involving correctness, concurrency, security, compatibility, or external-system behavior. Each source file keeps one focused top-level description.
+
+Read [references/narrative-prose.md](references/narrative-prose.md) for the deletion and detection rubric.
+
+### Dead code
+
+Build the symbol map with `uv run scripts/repomap.py`, then verify references outside the definition's module and tests. A symbol is removable only after checking dynamic registration, exports, compatibility migrations, and framework discovery.
+
+### Duplicate helpers
+
+Require evidence of the same responsibility, not merely similar syntax. Prefer the architectural owner named by `docs/engineering/architecture.md`. Do not centralize trivial provider-local helpers or create adapter-to-adapter dependencies.
+
+### Pattern drift
+
+Cite the binding engineering rule and the canonical implementation. Behavior changes require contract tests and a branch separate from prose cleanup.
+
+## Change discipline
+
+- Prefer deletion over rewriting.
+- Keep issue history, removed designs, review arguments, and changelog narration out of code.
+- Add `docs/patterns` guidance only for a repeated implementation shape not already covered by engineering standards.
+- Run focused checks after each file and `make check` before completion.
+- Use a read-only reviewer when an independent audit is requested. The reviewer names patterns and evidence but does not edit.
+- Commit, push, and open a PR only with explicit authorization for each action.
+- Nothing found means no change. Report the scanned scope and evidence.

agentdeck_sdk-5.0.0/.agents/skills/deck-cleanup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Deck Cleanup"
+  short_description: "Remove AgentDeck code entropy with evidence"
+  default_prompt: "Use $deck-cleanup to audit one kind of codebase entropy and propose the smallest evidence-backed cleanup."

agentdeck_sdk-5.0.0/.agents/skills/deck-cleanup/references/narrative-prose.md

@@ -0,0 +1,49 @@
+# Narrative prose rubric
+
+## Deletion test
+
+Remove a comment or docstring when identifiers, types, control flow, or an adjacent test already express it. Rewrite only when deletion would hide a contract or non-obvious reason.
+
+Keep:
+
+- public behavior and failure contracts,
+- concurrency and atomicity invariants,
+- security or privacy rationale,
+- compatibility constraints,
+- surprising database, SDK, protocol, or filesystem behavior.
+
+Cut:
+
+- line-by-line implementation tours,
+- issue numbers and superseded design history,
+- comparisons to other adapters when the local rule stands alone,
+- statements that label code obvious, important, correct, or load-bearing,
+- repeated explanations owned by a public method or binding design document,
+- speculative operator advice and future debugging notes.
+
+## AI-slop patterns
+
+Flag the exact line and name the pattern. Do not score the prose or guess who wrote it.
+
+- Binary contrast: `not X, but Y`, `the file, not this process`.
+- Interpretive metadiscourse: `the key point`, `this distinction matters`, `the whole reason`.
+- Importance puffery: `crucial`, `load-bearing`, `the one corruption`.
+- Faux insight: `the honest answer`, `the whole mechanism`.
+- Dramatic framing or metaphor where a concrete outcome suffices.
+- Robotic repetition of the same rationale across public and private methods.
+- Portability failure: prose that could describe any store, adapter, or project unchanged.
+
+Replace labels with the mechanism or consequence. Prefer one or two lines.
+
+## File descriptions
+
+Keep one focused sentence at the top of each source file. State its responsibility, not its history, implementation tour, or relationship to every neighboring module.
+
+## Review format
+
+For each finding report:
+
+1. `file:line`,
+2. action: delete, retain, tighten, or move,
+3. named pattern or engineering reason,
+4. the minimum replacement when tightening.

{agentdeck_sdk-4.0.4 → agentdeck_sdk-5.0.0}/.agents/skills/open-issue/SKILL.md

@@ -28,5 +28,6 @@ Checklist of observable, testable behaviors (mapping 1:1 to deterministic tests
 - **Title:** Terse and specific: `<area>: <what>` (e.g., `runtime: propagate cancellation to subagents`).
 - **Single concern:** One issue per topic; split unrelated asks.
 - **Check duplicates:** `gh issue list --state open`.
+- **Labels:** Select one type label (`bug`, `enhancement`, `feature`, `chore`, `design`, `documentation`, or `finding`) and the closest `area:*` label from `gh label list`.
 - **Output limits:** Keep text between tool calls to ≤25 words. Keep final responses to ≤100 words unless more detail is required.
-- Create via `gh issue create -t <title> -b <body>` and return the URL.
+- Create via `gh issue create -t <title> -b <body> --label <type> --label <area>` and verify the resulting issue has both labels before returning its URL.

{agentdeck_sdk-4.0.4/.claude → agentdeck_sdk-5.0.0/.agents}/skills/release/SKILL.md

@@ -13,13 +13,12 @@ Follow the release process strictly. All work starts on `dev`; `main` is release
 3. **Bump on `dev`:**
    - Update `version` in `pyproject.toml`.
    - Move Unreleased entries to `## [X.Y.Z] - YYYY-MM-DD` in `CHANGELOG.md` with compare links.
-   - Run `python scripts/generate_docs_reference.py` twice.
+   - Run `python scripts/generate_docs_reference.py` once, then verify `python scripts/generate_docs_reference.py --check`.
    - Commit: `chore(release): vX.Y.Z`.
 4. **Push `dev`:** Wait for CI green.
-5. **Merge to `main`:** Merge `dev` into `main` and push.
+5. **Merge to `main`:** Open a `dev` to `main` PR, wait for every required check, and merge it.
 6. **Tag:** `git tag vX.Y.Z && git push origin vX.Y.Z`.
-7. **Redeploy Docs:** If release worktree exists (`~/prjs/agentdeck-docs-release`), run `./redeploy.sh vX.Y.Z` and verify served output.
-8. **Report:** Return the GitHub release URL.
+7. **Report:** Return the GitHub release URL.
 
 ## Ground Rules
 - Keep text between tool calls to ≤25 words. Keep final responses to ≤100 words unless more detail is required.

agentdeck_sdk-5.0.0/.agents/skills/ship-issue/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: ship-issue
+description: "Run one agentdeck issue through the full pipeline: brief the user, deck-dev implements it, deck-reviewer gates it, findings get fixed, PR merges to dev, board updated."
+---
+
+# Ship an issue
+
+Orchestrate the end-to-end delivery of an issue.
+
+## 0. Brief Before Launching
+Read the issue and verify its claims against the tree. **Spec gate first:** if the issue lacks `Done when` outcomes or scope bounds (what must NOT be added), fix the issue body or ask the user; do not spawn deck-dev against an unbounded spec. Then output a concise 5-point brief (1–2 lines each):
+> **The claim:** What the issue asks for.
+> **What's true now:** Current behavior in the codebase (file:line).
+> **The shape:** Implementation plan in 3–4 concise bullets.
+> **The hard gate:** Invariants that must not break (`tests/golden/`, public API, import law).
+> **Skipped:** What is deliberately out of scope.
+
+## 1. Board Tracking
+Update GitHub Project (`PVT_kwHOBHijkM4BgHFZ`): Set **Status = In progress**, record Start Date, comment with start timestamp.
+
+## 2. Implement
+Spawn `deck-dev` with the issue number and brief. It works in stages (understand, design-in-PR-body, implement, self-review, gate) and posts task progress; poll for stalls.
+If it stops at its own spec gate despite step 0, the issue needs a human decision: set the board back to **Todo**, surface what is missing, stop the pipeline.
+
+## 3. Attach PR
+Verify the draft PR targets `dev`, includes `Closes #<n>`, and its body carries the design sections (`## Reuse analysis`, `## Analog`, `## Concept budget`, `## Expected delta`). Missing sections go back to deck-dev before any review is spent. Set **Status = In review** when marked ready.
+
+## 4. Review
+Spawn `deck-reviewer` on the PR. The reviewer must post a COMMENTED GitHub review; a session-only verdict does not count.
+
+## 5. Address Findings
+The review lands on the PR itself (GitHub review + inline comments); read it there. Route by class: **ERROR** and **WARNING** findings go to `deck-dev` to fix on the branch; **NOTE** findings that will not be fixed now become `finding:`-titled issues via open-issue, never silently dropped. Promotion issues the reviewer filed get scheduled as their own small harness PRs, never implemented by the reviewer.
+
+## 6. Merge
+Merge only when `Agent review` and every other required check are green: `gh pr merge --squash --delete-branch`.
+
+## 7. Complete
+Set **Status = Done**, record Target Date, comment with completion summary and PR link.
+
+## Ground Rules
+- Keep text between tool calls to ≤25 words. Keep final responses to ≤100 words unless more detail is required.

agentdeck_sdk-5.0.0/.claude/agents/deck-cleanup.md

@@ -0,0 +1,28 @@
+---
+name: deck-cleanup
+description: Runs ONE narrow entropy scan over agentdeck (narrative comments, dead code, duplicate helpers, or pattern drift) and opens one small evidence-backed PR.
+model: sonnet
+isolation: worktree
+---
+
+You run ONE cleanup scan over agentdeck and open one small PR. The scan type comes from your prompt; never mix concerns, never do a broad rewrite.
+
+## Scan types
+- **narrative-comments:** slopcheck takes one file at a time (a directory silently reports clean), so loop: `git ls-files 'agentdeck/**/*.py' 'tests/**/*.py' | while read f; do uv run scripts/slopcheck.py --all "$f"; done`. Remove only comments where the code is self-explanatory after deletion; a comment stating rationale or an invariant stays.
+- **dead-code:** Build the symbol list with `uv run scripts/repomap.py`, then grep each public symbol for references outside its own module and tests. Zero references = removal candidate; verify with `make check` after deleting.
+- **duplicate-helpers:** Read the repo map for same-responsibility functions/classes (similar names, similar signatures, overlapping docstrings). Consolidate onto the canonical one; the survivor is the one `docs/engineering/architecture.md` implies.
+- **pattern-drift:** Pick one concept implemented in more than one place (error raising, settings access, lifecycle transitions) and align outliers to the pattern `docs/engineering/` names.
+
+## Rules
+1. Evidence first: every deletion or change in the PR body cites its evidence (slopcheck line, zero-reference grep, the duplicated counterpart).
+2. Smallest change that removes the entropy. No refactors beyond the scan's concern.
+3. Seed worktree: copy `.env` if present, then `uv venv --python 3.12 && make install`.
+4. Gate of record: `make check`, 100% green before marking ready.
+5. Branch `cleanup/<scan-type>`, draft PR to `dev` on first commit, ready when green. No attribution trailers.
+6. Nothing found = no PR; return "clean" with the evidence of what was scanned.
+
+**Progress:** name each phase (scan / change / gate / PR) as you enter it.
+
+**Subagents:** any agent you spawn passes an explicit `model: "sonnet"`. Never omit it, never fable, never opus.
+
+Return: PR URL (or "clean"), findings count, and `make check` status.

agentdeck_sdk-5.0.0/.claude/agents/deck-dev.md

@@ -0,0 +1,20 @@
+---
+name: deck-dev
+description: Implements a GitHub issue (feature or bug fix) for agentdeck end-to-end in an isolated worktree and opens one PR to dev.
+model: sonnet
+isolation: worktree
+---
+
+You implement one agentdeck GitHub issue end-to-end in an isolated worktree and open a PR.
+
+**Objective: implement the issue with the smallest coherent change.** Order of preference: reuse an existing abstraction, modify one, consolidate/delete, and only then create. Your PR will be evaluated on: reuse of existing abstractions, consistency with `docs/patterns/`, minimal new concepts, minimal public surface, no narrating comments, no structural regression.
+
+**First action:** invoke the `ship-pr` skill and follow it. Every stage, the design gate, the self-review questions and the coverage question, the gate commands, live there. Do not rely on description-based auto-triggering here; call it explicitly.
+
+**Progress:** name each stage (Understand / Design / Implement / Self-review / Gate) as you enter it. A silent multi-stage run reads as a stall.
+
+**Subagents:** any agent you spawn passes an explicit `model: "sonnet"`. Never omit it, never fable, never opus.
+
+**Output style:** ≤25 words between tool calls; final response ≤100 words unless more detail is required.
+
+Return: PR URL, one-paragraph summary, `make check` status, and declared-vs-actual concept budget.

agentdeck_sdk-5.0.0/.claude/agents/deck-reviewer.md

@@ -0,0 +1,18 @@
+---
+name: deck-reviewer
+description: Review gate for an agentdeck PR before merge. Verifies correctness, spec compliance, simplicity, conciseness, and test quality against docs/engineering/.
+model: sonnet
+isolation: worktree
+---
+
+You review one agentdeck PR as the merge gate. REVIEW ONLY on the code: never push a commit anywhere. You DO write review artifacts: the PR review itself, inline comments, and any DEFER, harness-note or Harvest issue.
+
+**First action:** invoke the `review-pr` skill and follow it. Everything procedural, the phases, the finding classes, the verdict format, the delivery mechanics, lives there. Do not rely on description-based auto-triggering here; call it explicitly.
+
+**Progress:** say which phase you are entering as you enter it. A silent review reads as a stall.
+
+**Subagents:** any agent you spawn passes an explicit `model: "sonnet"`. Never omit it, never fable, never opus.
+
+**Output style:** keep text between tool calls to ≤25 words. Keep final responses to ≤100 words unless more detail is required.
+
+Return to the orchestrator: verdict, `make check` result, counts per finding class, links to the posted review and any DEFER issues.

agentdeck_sdk-5.0.0/.claude/settings.json

@@ -0,0 +1,36 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "f=\"$CLAUDE_PROJECT_DIR/scripts/slopcheck.py\"; [ -f \"$f\" ] || exit 0; python3 \"$f\" --write"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "f=\"$CLAUDE_PROJECT_DIR/scripts/slopcheck.py\"; [ -f \"$f\" ] || exit 0; python3 \"$f\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "f=\"$CLAUDE_PROJECT_DIR/scripts/slopcheck.py\"; [ -f \"$f\" ] || exit 0; python3 \"$f\" --changed"
+          }
+        ]
+      }
+    ]
+  }
+}

agentdeck_sdk-5.0.0/.claude/skills/milestone-retro/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: milestone-retro
+description: Evaluate the harness after a milestone closes: which CI gates fired, whether the slop guards caught anything, how the dev and review agents performed, and whether the PRs were well shaped. Judges the machinery, not the product. Use when a milestone is finished and before the release is tagged.
+---
+
+# Milestone retro
+
+Judge the machinery: the gates, the guards, the two agents, the shape of the PRs. **Not the product.** Whether the features were right is a different question with a different audience.
+
+Every claim in a retro is a number with a query behind it. An opinion about the harness that nobody measured is how the harness got this way.
+
+## Setup
+
+The milestone is the set of PRs merged to `dev` between two tags, or the PRs closing one milestone's issues. Fix that set first and write it down; every phase below is scoped to it.
+
+```bash
+gh pr list --state merged --limit 200 --json number,title,mergedAt,additions,deletions,changedFiles \
+  --jq '.[] | select(.mergedAt > "<start>") | "\(.number)\t\(.mergedAt)\t+\(.additions)/-\(.deletions)\t\(.changedFiles)f\t\(.title)"'
+```
+
+Where `scripts/agent_scorecard.py` has already recorded a PR, read its record instead of recomputing. This skill covers what the scorecard cannot: the gates, the guards, and judgment.
+
+## Phases
+
+Work in order. Copy this checklist into your own response and check off each phase:
+
+```
+Retro progress:
+- [ ] 1. Gates: which CI checks fired, which never did (references/queries.md)
+- [ ] 2. Guards: what the slop rules actually caught (references/queries.md)
+- [ ] 3. Agents: dev and reviewer, measured (references/queries.md)
+- [ ] 4. PRs: bodies, commits, comment routing (references/queries.md)
+- [ ] 5. Criteria: audit the scorecards themselves (references/judging.md)
+- [ ] 6. Verdict: file the issues (references/judging.md)
+```
+
+| phase | asks | output |
+|---|---|---|
+| 1. Gates | Which required checks failed, and what did each catch? A gate that never fails and a gate that always fails are both broken. | a table: gate, runs, failures |
+| 2. Guards | Did any mechanical guard catch a defect this milestone, or only formatting? Compare against the findings filed. | guard hits against real findings |
+| 3. Agents | Dev: defect at first review, rework ratio, scope creep. Reviewer: escapes, rounds, loop rounds, words per finding. | two scorecards, never merged into one |
+| 4. PRs | Body size against the cap, commit hygiene, whether findings were answered in threads or by growing the body. | per-PR table |
+| 5. Criteria | Are the scorecards measuring the right things? Which metric changed a decision, which rewards the artifact rather than the value, which can be gamed, which cost is unmeasured. The criteria are under review here, not the agents. | metrics kept, killed, added |
+| 6. Verdict | What cost us time, ranked. Each gets an issue or it did not matter. | filed issues |
+
+Phase 5 runs after phase 3 and not before, because a criterion is judged on whether it earned its keep this milestone, and you cannot know that until you have used it. It **proposes**: criteria are policy, and the user rules on keep or kill. Two of its four questions belong at proposal time instead, in the issue that adds a metric; `references/judging.md` says which and why.
+
+## Rules
+
+**CONSTRAINT: every claim carries its query.** A retro that says a gate is noisy without the failure count is an opinion. If you cannot produce the number, say the number is unavailable and why; never estimate it.
+
+**CONSTRAINT: no agent's own report is evidence.** The dev agent declared done on 5 of 5 defective PRs in v5.0.0. Read GitHub, read git, read the diff. An agent's summary is a claim to verify, not a source.
+
+**CONSTRAINT: separate the dev and reviewer scorecards.** Their jobs are opposite: one produces, one detects. A shared metric set measures neither. See `references/judging.md`.
+
+**EXPECTATION: report what went well with the same evidence.** A retro that only finds faults will get the working parts cut. In v5.0.0 the reviewer caught 8 of 8 real defects and the guards caught 0, and the naive conclusion from a fault-only retro would have been to add more guards.
+
+**EXPECTATION: name what you could not measure.** Escape rate is lagging and only resolves weeks later. Agent token and duration figures live in the completion notification and are gone once the session ends. Say so rather than leaving a gap that reads as a zero.
+
+**JUDGMENT: how deep to go.** Default to the five phases above. A milestone under three PRs does not need phase 4.
+
+## Out of scope
+
+- **Product correctness.** Whether the features were the right features, whether the API is good, whether the docs read well. Different question, different retro.
+- **Rewriting the harness in this session.** The retro produces issues. Implementing them is the normal pipeline, and mixing the two means the measurement stops when the first fix starts.
+- **Any metric counted by volume.** Entries written, findings raised, tests added. Volume metrics manufacture volume. `references/judging.md` covers what to use instead.

agentdeck_sdk-5.0.0/.claude/skills/milestone-retro/references/judging.md

@@ -0,0 +1,103 @@
+# Reading the numbers
+
+Contents: what makes a metric honest, the two scorecards, auditing the criteria, what a finding must clear, worked examples from v5.0.0.
+
+## What makes a metric honest
+
+**No agent grades itself.** The dev agent's score is the reviewer's BLOCK count at first review. The reviewer's score is what escaped it, which only later findings reveal. Everything else comes from GitHub, git, and the agent completion record. A self-reported number is a claim, not evidence.
+
+**Every metric needs a counterweight, or it gets gamed in one direction.** Escape rate alone produces a reviewer that blocks everything, so it is read against rounds and words. BLOCK count alone produces a dev agent that ships trivially small PRs, so it is read against scope creep. If a metric has no counterweight, do not ship it.
+
+**Never count by volume.** Patterns entries written, findings raised, tests added. A metric that wants a number up manufactures that number. Measure use instead: a patterns entry counts when a later review cites it, not when it is written.
+
+**Size is a trigger, never a finding.** A diff larger than its shape suggests means look harder at reuse and pattern conformance. What blocks is always a named duplication, a one-caller abstraction, a divergence from the declared analog, or configuration for a value that never changes. "Too big" is uncitable and an author wins that argument by compressing badly. Clean code is smaller as a consequence, so judge the cause.
+
+**Declared against actual is a ceiling, not accuracy.** `concept_budget.py` fails the build when actuals exceed the declaration, and that is all it does. Hitting your own number is not an achievement.
+
+## The two scorecards
+
+They stay separate because the jobs are opposite: one produces, one detects.
+
+**Dev agent, "was it correct when it said done":**
+
+| metric | direction |
+|---|---|
+| BLOCK count at first review | down |
+| rework ratio, commits after `ready_for_review` | down |
+| reuse and pattern BLOCKs | down |
+| scope creep, files touched against files the issue named | down |
+| `make check` green before `ready` | always |
+
+**Reviewer, "did it find what was there, at what cost":**
+
+| group | metric | direction |
+|---|---|---|
+| recall | escape rate | down |
+| value | outcome rate: findings that produced a code change, a picked-up DEFER, or a patterns entry | up |
+| value | words per finding | down |
+| value | percent anchored inline rather than in the verdict body | up |
+| speed | total latency across rounds | down |
+| speed | productive rounds | fast, not few |
+| waste | loop rounds | to zero |
+| learning | patterns entries a later review cited | up |
+
+Only a finding that produced **literally nothing** counts against outcome rate. A DEFER that informs a later fix is a legitimate outcome; it is not a rejection.
+
+## Auditing the criteria (phase 5)
+
+The scorecards are under review here, not the agents. A metric set nobody audits ossifies, and the wrong metric is worse than no metric because it directs work.
+
+Four questions, and they do not all belong here. Two are design questions answerable the moment a metric is proposed; two need a milestone of use behind them.
+
+**Asked when a metric is proposed, in the issue that adds it, never deferred to a retro:**
+
+2. **Can it be gamed in one direction, and does its counterweight still hold?** Name the gaming move and the metric that catches it. A metric whose counterweight you cannot name is not shippable.
+3. **Does it reward the artifact or the value?** Anything counted by volume rewards the artifact. So does any metric scoring an agent against its own declaration.
+
+Both metrics that failed in v5.0.0 failed question 3, and both were catchable at proposal. Asking these late costs a milestone of work pointed the wrong way.
+
+**Asked here, because they need usage:**
+
+1. **Did it change a decision this milestone?** Name the decision. A metric computed, read, and acted on nowhere is dead weight.
+4. **Is it actually obtainable?** A metric that lags by weeks, or whose source vanishes with a session, is not wrong but cannot score a PR at merge. Say which are live and which are retrospective rather than reporting a gap as a zero.
+
+Then the question the four cannot ask: **what cost the milestone real time that no metric saw?** That gap is a finding, and it is usually the most valuable output of this phase.
+
+### Who rules
+
+**The retro proposes; the user decides.** Criteria are policy, not fact, and the agent running the retro may have authored the metrics it is auditing. Present the evidence, recommend keep or kill for each, and stop. Same class as a DISCUSS finding: neither agent rules.
+
+One thing is decidable without judgment, and it is the backstop for criteria nobody gets round to auditing: **a metric that changed zero decisions across two consecutive milestones is flagged for deletion automatically.** State it as a fact in the output, not as a proposal.
+
+The two v5.0.0 kills both came from a person challenging a metric out loud, which is not a mechanism. This section is the mechanism.
+
+Two metrics failed this audit in v5.0.0, both proposed during the retro that created these scorecards:
+
+| metric | why it failed | replaced by |
+|---|---|---|
+| declared against actual LOC, as accuracy | rewards padding: declare +1000, ship +1000, score "exact". Question 3 | reuse and pattern BLOCKs at first review, which measures the cause instead of the symptom |
+| patterns entries per milestone, direction up | manufactures the spam the entry bar exists to prevent. Question 3 | entries a later review cited |
+
+Both survived until someone challenged them out loud. That is the reason this phase exists rather than being left to whoever notices.
+
+## What a finding must clear to be filed
+
+A retro that files everything it noticed produces a backlog nobody works. Each filed issue needs:
+
+1. **Evidence.** A number, a query, or a quoted failure. Not an impression.
+2. **A cost.** What it took from the milestone: a wasted hour, a re-review round, a shipped defect, a check nobody reads. If you cannot name the cost, it did not matter enough to file.
+3. **A bound.** `Done when` outcomes and an explicit `Not in scope`, because the fix is a normal pipeline PR and an unbounded spec produces unbounded code.
+
+Rank by cost before filing. A retro that files ten equal-weight issues has ranked nothing.
+
+## Worked examples from v5.0.0
+
+**A gate that never fires.** The docs build ran 23 times and failed 0, because roughly 21 of those PRs touched no file under `docs-site/`. Not broken, just never asked a question that could have a "no". Fix was a changed-files check, not deletion, because a required check reporting *skipped* does not satisfy branch protection.
+
+**A gate that fires constantly and catches nothing.** Docs-impact failed 19 of 42 runs, because its acknowledgement expired on every push rather than when a new page became impacted. The box then got re-ticked unread, and #409 shipped five stale prose references past a green check. Both halves are findings: the noise, and the fact that the noise made the gate useless.
+
+**Guards against reality.** Eight `finding:` issues were filed during the milestone. Zero could have been caught by any of the eight slop rules; every one was semantic (lifecycle ordering, event ordering, a dead field, a docstring asserting a guarantee the code did not make). Three of the eight findings were themselves proposals for new guards. The conclusion is not "add guards".
+
+**What went well, measured the same way.** The reviewer caught 8 of 8 real defects, mutation-tested its own verdicts rather than reading tests, and once talked itself out of filing an issue with an argument from the code. A fault-only retro would have proposed thinning it.
+
+**A number that was wrong until checked twice.** The dev agent's rework ratio read as 100% on one PR until `authoredDate` replaced `committedDate`; a rebase had rewritten every timestamp. Check any metric that suddenly reads as an extreme.

agentdeck_sdk-5.0.0/.claude/skills/milestone-retro/references/queries.md

@@ -0,0 +1,132 @@
+# Retro queries
+
+Contents: traps that produce wrong numbers, gates, guards, agents (dev and reviewer), PR shape.
+
+## Traps that produce wrong numbers
+
+Read these first. Each one silently returned a wrong answer during the v5.0.0 retro.
+
+| trap | what happens | fix |
+|---|---|---|
+| `gh pr list` default limit | returns 30, or whatever you pass. Querying 60 against a 198-PR repo made 19 branches read as "no PR" and nearly deleted them as dead | always pass `--limit 500` and check the returned count |
+| `committedDate` after a rebase | every commit's timestamp is rewritten, so a rebased PR reads as 100% rework | use `authoredDate` for anything comparing commits to an event |
+| a conflicting PR looks like broken CI | it gets **zero** `pull_request` runs because there is no merge ref, while `pull_request_target` jobs keep firing. Reads as "CI partially vanished", not "you have a conflict" | `gh pr view <n> --json mergeable` first, always |
+| `--log-failed` on a multi-job run | mixes jobs, so one job's failure appears under another's name | resolve the job id, then `gh run view --job <id> --log` |
+| grep for a rule id in a script | finds the definition and its self-test, not its firings | read the CI job's log for what it actually flagged |
+
+## 1. Gates
+
+Runs and failures per workflow, scoped to the milestone:
+
+```bash
+gh run list --limit 200 --json name,conclusion,createdAt \
+  --jq '[.[] | select(.createdAt > "<start>")] | group_by(.name)
+        | map({name: .[0].name, total: length,
+               fail: ([.[] | select(.conclusion=="failure")] | length)})
+        | sort_by(-.total) | .[] | "\(.name)\ttotal=\(.total)\tfail=\(.fail)"'
+```
+
+Both extremes are findings. A gate at 0% has never asked a question that could have a "no". A gate above roughly 30% is either badly shaped or is a lint rule wearing a CI job's clothes, and it trains everyone to ignore it.
+
+For any gate that failed, read one failure and record **what it caught**, not that it fired. A gate can fail often and catch nothing.
+
+Per-job conclusions inside a multi-job workflow:
+
+```bash
+for id in $(gh run list --workflow=<file>.yml --limit 100 --json databaseId,createdAt \
+              --jq '.[]|select(.createdAt>"<start>")|.databaseId'); do
+  gh run view $id --json jobs --jq '.jobs[]|select(.name=="<job>")|.conclusion'
+done | sort | uniq -c
+```
+
+## 2. Guards
+
+What the anti-slop gate actually flagged:
+
+```bash
+jid=$(gh run view <run-id> --json jobs --jq '.jobs[]|select(.name=="slop")|.databaseId')
+gh run view --job "$jid" --log | grep -E "SLOP[0-9]"
+```
+
+Then the question that matters: **cross-reference guard hits against the findings filed during the milestone.** List every `finding:` issue and ask, for each, which guard rule could have caught it. In v5.0.0 the answer was none, for all eight.
+
+```bash
+gh issue list --label finding --state all --limit 100 --json number,title,createdAt \
+  --jq '.[] | select(.createdAt > "<start>") | "\(.number)\t\(.title)"'
+```
+
+Note how many of those findings are themselves requests for new guards. That ratio is the tell.
+
+A guard's silence in CI is not proof it is useless: the write-time hook may be catching things where nothing logs. Say that rather than concluding from CI alone, and fix the observability before proposing a deletion.
+
+Rules still violated in tree, for a guard that only checks added lines:
+
+```bash
+git grep -c '<pattern>' -- . | sort -t: -k2 -rn
+```
+
+An exemplar file that breaks the rule it teaches is a finding on its own.
+
+## 3. Agents: dev
+
+Rework, per PR. This is the honest "was it done when it said done":
+
+```bash
+ready=$(gh api repos/{owner}/{repo}/issues/<n>/timeline \
+          --jq '.[]|select(.event=="ready_for_review")|.created_at' | head -1)
+gh pr view <n> --json commits | jq --arg r "$ready" \
+  '{after: ([.commits[]|select(.authoredDate > $r)]|length), total: (.commits|length)}'
+```
+
+Two things that bite here, both verified: `gh`'s own `--jq` takes no `--arg`, so pipe to real `jq` when the filter needs a variable. And `|` rebinds the input for everything after it, so a second reference to `.commits` must be parenthesized or it evaluates against the piped array instead of the original object.
+
+Declared against actual, from the PR body and the two scripts:
+
+```bash
+PR_BODY="$(gh pr view <n> --json body -q .body)" uv run scripts/concept_budget.py
+uv run scripts/quality_delta.py
+```
+
+Read this as a ceiling check, never as an accuracy score. Hitting your own declared number proves nothing: a PR declaring +1000 and shipping +1000 is unexamined, not precise.
+
+Then read the first review of each PR and record the defect it found, if any. Group the defects by shape. In v5.0.0 all four shared one: the agent tested what it built and not what it changed.
+
+## 3. Agents: reviewer
+
+Verdict rounds, and which of them were productive:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/<n>/reviews --jq '.[]|select(.body|length>200)|"\(.submitted_at) \(.body[0:80])"'
+```
+
+A round is a **loop** if it re-raised a finding already raised, or reviewed a tree unchanged since the last round. It is **productive** if it raised something new about code that changed. Keep them separate: a round that found a defect introduced by the previous round's fix is the system working, and one metric would punish it identically to a wasted re-stamp.
+
+Comment routing, inline against verdict body:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/<n>/comments --jq 'length'
+gh api repos/{owner}/{repo}/issues/<n>/comments --jq 'length'
+```
+
+Review prose against the PR body it judged:
+
+```bash
+gh pr view <n> --json body -q .body | perl -0pe 's/```.*?```/ /gs' | wc -w
+gh api repos/{owner}/{repo}/pulls/<n>/reviews --jq '.[]|select(.body|length>200)|.body' | wc -w
+```
+
+Escape rate: findings filed against a PR after it merged. Match the `finding:` issues from phase 2 to the PR that introduced the code, then divide by PRs reviewed.
+
+## 4. PR shape
+
+```bash
+gh pr view <n> --json commits --jq '.commits[]|.messageHeadline'
+```
+
+Look for duplicate headlines (an amend artifact), merge commits (`update-branch` without `--rebase`), and commits scoped by the review round rather than by what changed. Squash-merge keeps all of this out of `dev`, so it costs review attention rather than permanent record; weight it accordingly.
+
+Body size against the cap, with the same command the caps are defined in terms of:
+
+```bash
+gh pr view <n> --json body -q .body | perl -0pe 's/```.*?```/ /gs' | wc -w
+```

{agentdeck_sdk-4.0.4 → agentdeck_sdk-5.0.0}/.claude/skills/open-issue/SKILL.md

@@ -28,5 +28,6 @@ Checklist of observable, testable behaviors (mapping 1:1 to deterministic tests
 - **Title:** Terse and specific: `<area>: <what>` (e.g., `runtime: propagate cancellation to subagents`).
 - **Single concern:** One issue per topic; split unrelated asks.
 - **Check duplicates:** `gh issue list --state open`.
+- **Labels:** Select one type label (`bug`, `enhancement`, `feature`, `chore`, `design`, `documentation`, or `finding`) and the closest `area:*` label from `gh label list`.
 - **Output limits:** Keep text between tool calls to ≤25 words. Keep final responses to ≤100 words unless more detail is required.
-- Create via `gh issue create -t <title> -b <body>` and return the URL.
+- Create via `gh issue create -t <title> -b <body> --label <type> --label <area>` and verify the resulting issue has both labels before returning its URL.

{agentdeck_sdk-4.0.4/.agents → agentdeck_sdk-5.0.0/.claude}/skills/release/SKILL.md

@@ -13,13 +13,12 @@ Follow the release process strictly. All work starts on `dev`; `main` is release
 3. **Bump on `dev`:**
    - Update `version` in `pyproject.toml`.
    - Move Unreleased entries to `## [X.Y.Z] - YYYY-MM-DD` in `CHANGELOG.md` with compare links.
-   - Run `python scripts/generate_docs_reference.py` twice.
+   - Run `python scripts/generate_docs_reference.py` once, then verify `python scripts/generate_docs_reference.py --check`.
    - Commit: `chore(release): vX.Y.Z`.
 4. **Push `dev`:** Wait for CI green.
-5. **Merge to `main`:** Merge `dev` into `main` and push.
+5. **Merge to `main`:** Open a `dev` to `main` PR, wait for every required check, and merge it.
 6. **Tag:** `git tag vX.Y.Z && git push origin vX.Y.Z`.
-7. **Redeploy Docs:** If release worktree exists (`~/prjs/agentdeck-docs-release`), run `./redeploy.sh vX.Y.Z` and verify served output.
-8. **Report:** Return the GitHub release URL.
+7. **Report:** Return the GitHub release URL.
 
 ## Ground Rules
 - Keep text between tool calls to ≤25 words. Keep final responses to ≤100 words unless more detail is required.