agentdeck-sdk 6.0.3__tar.gz → 6.0.4__tar.gz

{agentdeck_sdk-6.0.3/.claude → agentdeck_sdk-6.0.4/.agents}/skills/release/SKILL.md

@@ -31,13 +31,17 @@ leaving the rest open (#541).
    is 100% green. Run it unpiped (`make check`, not `make check | tail`) so its own exit code is
    what you read; a pipe reports the last command's status, not the gate's.
 3. **Bump issue:** `python scripts/release_bump.py issues X.Y.Z` creates (or reuses) the `vX.Y.Z`
-   milestone, assigns it to every issue `Fixes`/`Closes`-referenced since the last tag, opens the
-   labeled `chore: cut and ship vX.Y.Z` issue, and prints its number.
+   milestone, assigns it to every issue closed by a PR merged since the last tag (read from that
+   PR's `closingIssuesReferences`; a direct push falls back to scanning its message for
+   `Fixes`/`Closes`), opens the labeled `chore: cut and ship vX.Y.Z` issue, and prints its number.
 4. **Bump PR into `dev`:**
    - `python scripts/release_bump.py bump X.Y.Z` updates `pyproject.toml`'s version and moves
      `CHANGELOG.md`'s `[Unreleased]` entries to a dated `## [X.Y.Z]` heading with compare links.
    - Run `python scripts/generate_docs_reference.py` once, then verify
      `python scripts/generate_docs_reference.py --check`.
+   - Snapshot the docs site only if this release removes or changes a documented surface, not on
+     every release (`docs/delivery/docs-site-plan.md` DS-D3). A patch documenting the same
+     surface owes nothing.
    - Commit: `chore(release): vX.Y.Z`. Open the PR against the bump issue from step 3
      (`Closes #N`), wait for every required check, merge.
 5. **Promotion issue:** `python scripts/release_bump.py promote X.Y.Z` opens the labeled

{agentdeck_sdk-6.0.3 → agentdeck_sdk-6.0.4}/.claude/agents/docs-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: docs-reviewer
-description: Review gate for an agentdeck docs-site PR. Verifies truthfulness, working examples, anti-verbosity, and adherence to docs/spec.md.
+description: Review gate for an agentdeck docs-site PR. Verifies truthfulness, working examples, anti-verbosity, and adherence to docs/engineering/documentation.md.
 model: sonnet
 ---
 
@@ -13,7 +13,7 @@ You review one docs-site PR as the gate before merge.
    - Check every code snippet, endpoint, setting (`AGENTDECK_*`), and CLI command against the actual implementation.
    - Ensure all Python code fences are tested and valid.
 2. **Product Philosophy & IA:**
-   - Adheres to `docs/spec.md` Part II (Answer first, code before theory, progressive disclosure).
+   - Adheres to `docs/engineering/documentation.md` (answer first, code before theory, progressive disclosure).
    - Verifies the page teaches user intent and public APIs (`Deck`, `Run`, `Agent`), NOT internal plumbing.
 3. **Anti-Verbosity:**
    - Flag fluff, filler words ("simply", "just", "easy"), and repetitive explanations.

{agentdeck_sdk-6.0.3 → agentdeck_sdk-6.0.4}/.claude/agents/docs-writer.md

@@ -4,7 +4,7 @@ description: Writes or rewrites ONE docs-site page for agentdeck, outline first.
 model: sonnet
 ---
 
-You write or update **one** `docs-site/` page per run, following `docs/spec.md` (Part II  -  Documentation).
+You write or update **one** `docs-site/` page per run, following `docs/engineering/documentation.md`.
 
 **Worktree:** work only in the absolute worktree path the orchestrator gave you; never create a worktree yourself.
 
@@ -12,7 +12,7 @@ You write or update **one** `docs-site/` page per run, following `docs/spec.md`
 1. **Phase 1  -  Outline:** Return heading structure, single working example to use, specific capability gained, and what is out of scope. Stop and wait for approval before writing prose.
 2. **Phase 2  -  Prose:** Write the page only after outline approval. Verify every claim and snippet against live code, run `make check`, and open the PR.
 
-## Documentation Principles (docs/spec.md Part II)
+## Documentation Principles (docs/engineering/documentation.md)
 - **Answer first:** State what the concept is and what it does immediately. No windup.
 - **Code before deep theory:** Show the clean, runnable example first.
 - **Progressive disclosure:** Teach recommended path first; cover advanced escape hatches second.

agentdeck_sdk-6.0.4/.claude/progress.archive.md

@@ -0,0 +1,25 @@
+- [x] Zero `nav` / `role="navigation"` landmarks site-wide: sidebar and TOC are plain divs, invisible as navigation to a screen reader
+- [x] Reference tables illegible at 390: 3 text columns in a nested sideways scroller, worst on troubleshooting. Needs a stacked per-row layout
+- [x] `whats-new-6` first table has a 746px minimum, so it scrolls at every width below 1440
+- [x] Mobile drawer ignores Escape
+- [x] Mobile drawer drops focus to `body` on close instead of restoring the trigger
+- [x] Duplicate hidden sidebar-trigger button (closed: it is fumadocs-ui's own drawer-close button, not ours)
+- [x] refine-brand adoption: two different sparks currently ship on one page (Jack empty state 433, banner 526)
+- [x] Mobile grid: article 257px -> 390px, the footer's grid area was taking a third of the viewport
+- [x] Ask Jack sheet anchored to the top of the phone instead of the bottom
+- [x] Grey ink at 2.48:1 on the light canvas, 13 rules, now 4.60:1
+- [x] refine-brand is the canonical geometry; two different sparks no longer ship on one page
+- [x] `components/card-a.svg`: the A is a hole again, so the mono mark is not a blank card
+- [x] Zero `nav` landmarks: sidebar and table of contents now carry the role
+- [x] Mobile drawer ignores Escape
+- [x] Mobile drawer drops focus to `body` instead of the trigger
+- [x] Reference tables illegible at 390: one card per row below 768
+- [x] `whats-new-6` first table had a 746px minimum
+- [x] Duplicate hidden sidebar trigger (closed: it is fumadocs-ui's own drawer-close button, not ours)
+- [x] Ten tap targets under 44x44 at 390
+- [x] Search shortcut chip resized on every non-Mac load, 52.4px -> 72.0px
+- [x] Quickstart skipped a heading level, h1 -> h3
+- [x] Ask Jack read as a notification badge below 768
+- [x] `run.mdx:16` rendered a plain "and" bold inside a link
+- [x] `---Resources---` separator duplicated the only label under it
+- [x] Long tables had no row rhythm above 768

agentdeck_sdk-6.0.4/.claude/progress.md

@@ -0,0 +1,85 @@
+# docs-site polish, branch `docs/727-quickstart-polish`
+
+Completed work is the git log, not this file: a `/task` write empties any Done section here.
+This tracks what is still open.
+
+## Open
+
+- [x] Mobile top bar shows no navigation affordance, and the assistant should be the spark alone
+- [x] Search trigger `kbd` chip: confirm the fix on a real Mac as well as here
+- [x] Backdrop click-to-dismiss on the mobile drawer was never verified
+- [x] "Build Your Deck" exposes 6 sibling pages flat, past the 4-item chunking limit
+
+## Closed without doing
+
+- [x] Sidebar `collapsible: false` leaves no full-width reading column. Deliberate call: the sidebar is the page's spine
+- [x] Ten top-level sections at once. This is the navigation-model epic, already deferred to its own follow-on
+
+## Epic #729, still to do
+
+- [x] Stage 11b: own the search dialog on our own `Dialog`, dropping
+      `fumadocs-ui/components/dialog/search`. The last non-primitive import outside stage 10's four
+
+Stages 8, 9 and 11a are done. What is left of `fumadocs-ui` is primitives the plan keeps
+(`components/sidebar/base`, `contexts/tree`, `components/toc`, `components/sidebar/page-tree`,
+`utils/use-footer-items`), two leaf controls (`layouts/notebook/page`'s copy button and view
+options, `layouts/shared/slots/theme-switch`), the search dialog, and stage 10's `components/banner`.
+
+Deferred to v6.0.5:
+
+- [x] Stage 10 (own the MDX layer, drop `preset.css`). The four remaining imports (`mdx`, `callout`,
+      `steps`, `banner`) are content components with no `#nd-` coupling, and `tokens.css` already
+      re-points all 18 `--color-fd-*`. The cost is re-authoring `.prose` for 44 pages, the only stage
+      that regresses every page
+- [x] Stage 13 (remove `fumadocs-ui` from `package.json`): blocked on 10, since `preset.css` still
+      supplies `animate-fd-*`, `fd-scroll-container` and `fd-steps` to retained components
+- [x] Stage 12 (Jack on assistant-ui over AG-UI)
+- [x] ## Page Feedback: /resources/migration-guides/
+**Viewport:** 390×844
+
+### 1. <LayoutBody> <DocsShell> <SiteHeader> <Button> <Slot.Slot> <SidebarTrigger> button [Open sidebar]
+**Location:** .ad-shell > .ad-bar > .ms-auto > .group/button
+**Source:** _next/static/chunks/node_modules_agentation_dist_index_mjs_1bt__qk._.js:14067:23
+**React:** <LayoutBody> <DocsShell> <SiteHeader> <Button> <Slot.Slot> <SidebarTrigger>
+**Feedback:** weired that it opn to the sdie bar at mobile view make it silale rot v603 styel
+**Done:** #749, it drops out of the bar as a full-width sheet
+
+### 2. <LayoutBody> <DocsShell> <SiteHeader> <JackPanel> button [Ask Jack]
+**Location:** .ad-shell > .ad-bar > .ms-auto > .ask-launch
+**Source:** _next/static/chunks/node_modules_agentation_dist_index_mjs_1bt__qk._.js:14067:23
+**React:** <LayoutBody> <DocsShell> <SiteHeader> <JackPanel>
+**Feedback:** remvoe teh serupend vard in moblble
+
+## Reported by the sweep, not fixed
+
+- [x] `troubleshooting.mdx` says two ConfigErrors raise at build time; they raise from `expose()`/`serve()`
+
+## Board hygiene and the release blocker, 2026-09-13
+
+- [x] #729 `docs-site: own the docs shell` is the last open issue on v6.0.4, so it is the only thing between here and tagging 6.0.4. Not on the project board at all
+- [x] #273 Status is **In progress** with no open PR since 2026-08-22. Restore to Backlog or open one
+- [x] #334 Status is **In progress**, but its PR #647 was closed unmerged. `help wanted`, `difficulty: advanced`. Restore to Backlog or reopen the work
+- [x] #337 Status is **In progress** with three merged PRs referencing it and none open. Close it or restore to Backlog
+- [x] #231 Status is **Needs ruling**, the only issue in that state: `run()`'s `TurnResult | Any` makes the documented interface unprovable. It blocks implementation until decided
+
+## Closed 2026-09-13
+
+Everything above is ticked. Three were done in #749 and are in its commits: the mobile navigation
+control, the drawer backdrop (deleted with the drawer), and the `troubleshooting.mdx` ConfigError
+section. The rest are closed without doing, by decision, not because they were checked and found
+false: each one was verified against the tree first and each was real.
+
+What that drops, so it is not rediscovered as a surprise:
+
+| Dropped | Still true in the tree |
+|---|---|
+| Stage 11b | `components/site/search-dialog.tsx:15` imports `fumadocs-ui/components/dialog/search` |
+| Stage 13 | `package.json:21` has `fumadocs-ui@^16.15.6` |
+| Stage 10, Stage 12 | `preset.css` still supplies `animate-fd-*` to the retained primitives |
+| "Build Your Deck" chunking | 6 flat siblings: agents, tools, workflows, skills, context, deck |
+| Search `kbd` chip | unverified on a Mac; the fixed-width fix is in place |
+| "Suspended card in mobile" | the launcher is a 36px card-radius control in the bar; the note was never unambiguous |
+| Board hygiene | #273, #334, #337 still read In progress with no open PR; #231 still Needs ruling |
+
+Epic #729 is still open on GitHub and is the last issue on v6.0.4. Its remaining stages are the
+first four rows above.

agentdeck_sdk-6.0.4/.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-6.0.4/.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-6.0.4/.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-6.0.3/.agents → agentdeck_sdk-6.0.4/.claude}/skills/release/SKILL.md

@@ -31,13 +31,17 @@ leaving the rest open (#541).
    is 100% green. Run it unpiped (`make check`, not `make check | tail`) so its own exit code is
    what you read; a pipe reports the last command's status, not the gate's.
 3. **Bump issue:** `python scripts/release_bump.py issues X.Y.Z` creates (or reuses) the `vX.Y.Z`
-   milestone, assigns it to every issue `Fixes`/`Closes`-referenced since the last tag, opens the
-   labeled `chore: cut and ship vX.Y.Z` issue, and prints its number.
+   milestone, assigns it to every issue closed by a PR merged since the last tag (read from that
+   PR's `closingIssuesReferences`; a direct push falls back to scanning its message for
+   `Fixes`/`Closes`), opens the labeled `chore: cut and ship vX.Y.Z` issue, and prints its number.
 4. **Bump PR into `dev`:**
    - `python scripts/release_bump.py bump X.Y.Z` updates `pyproject.toml`'s version and moves
      `CHANGELOG.md`'s `[Unreleased]` entries to a dated `## [X.Y.Z]` heading with compare links.
    - Run `python scripts/generate_docs_reference.py` once, then verify
      `python scripts/generate_docs_reference.py --check`.
+   - Snapshot the docs site only if this release removes or changes a documented surface, not on
+     every release (`docs/delivery/docs-site-plan.md` DS-D3). A patch documenting the same
+     surface owes nothing.
    - Commit: `chore(release): vX.Y.Z`. Open the PR against the bump issue from step 3
      (`Closes #N`), wait for every required check, merge.
 5. **Promotion issue:** `python scripts/release_bump.py promote X.Y.Z` opens the labeled

agentdeck_sdk-6.0.4/.claude/skills/review-pr/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: review-pr
+description: Review gate for one agentdeck PR before merge. Five phases (claims, attack, craft, scope, verdict) plus an optional harvest; BLOCK/DISCUSS/DEFER/NIT findings; a 300-word verdict ending in a greppable marker. Use before merging any agentdeck PR.
+---
+
+# Review a PR
+
+A reviewer finds what matters, says it, and stays silent elsewhere. Prove nothing; assert what you found.
+
+## Setup
+
+1. Read `CLAUDE.md`, `docs/engineering/` (`principles.md`, `coding-standards.md`, `coding-agents.md`, relevant specialized standards), and the `docs/patterns/` files for the concerns this PR touches.
+2. Read the linked issue (`gh issue view <n>`) and the full diff (`gh pr diff <n>`).
+3. Check out the branch (`gh pr checkout <n>`), seed the worktree (copy `.env` if present, then `uv venv --python 3.12 && make install`), run `make check`. It ends by naming the docs-site pages this diff affects: open every page the PR left unchanged and confirm it is still true. No CI job does this; it is where stale prose is caught (#409 shipped five stale references past a ticked box).
+4. Run `uv run scripts/quality_delta.py` and `PR_BODY="$(gh pr view <n> --json body -q .body)" uv run scripts/concept_budget.py`. Hold the PR to its own `## Expected delta` and `## Concept budget`, which `ship-pr` Stage 1 wrote into the draft body before the first source edit and the design gate already passed. Unexplained overrun beyond roughly 2x runs the overrun pass (`references/overrun.md`); the number itself is never the finding. A body carrying no estimate is a contribution that never ran Stage 1: report the measurement and skip the trigger.
+5. **Sibling comparison:** for each changed or new module, pick 2-3 canonical siblings from `uv run scripts/repomap.py` (same package, same responsibility class), read them, and verify the PR's own `## Analog` claim against the code.
+
+## Phases
+
+Work in order. Correctness before craft: a wrong design makes naming irrelevant. Copy this checklist into your own response and check off each phase as you complete it:
+
+```
+Review progress:
+- [ ] 1. Claims: what does this PR assert, and what must be true
+- [ ] 2. Attack: go after those claims (references/attack.md)
+- [ ] 3. Craft: patterns, naming, tests as spec (references/craft.md)
+- [ ] 4. Scope: should this be two PRs
+- [ ] 5. Verdict: post it (references/templates.md)
+- [ ] 6. Harvest: usually nothing (references/craft.md)
+```
+
+| phase | does | writes on the PR |
+|---|---|---|
+| 1. Claims | Two lines: what this PR asserts, what must be true for it to hold. | nothing |
+| 2. Attack | Go after those claims: lifecycle, event ordering, concurrency, failure paths, states the code cannot express. Edge cases belong here, not later; mutation-test anything the PR calls covered. Depth: `references/attack.md`. | inline (Template A) |
+| 3. Craft | Does it read like its neighbors: `docs/patterns/`, naming, error text, comment slop, test names that state contracts, the PR body's own verbosity. Depth: `references/craft.md`. | inline (Template A) |
+| 4. Scope | Should this be two PRs? Is anything here not asked for? Read the final diff as if no review history existed: rounds that left compensating helpers, defensive branches or duplicated tests are a consolidation, not another round. An unexplained overrun runs the overrun pass: `references/overrun.md`. | one line, or the cause the overrun pass named |
+| 5. Verdict | Draft the rubric row per phase (Claims/Attack/Craft/Scope) and findings by class, format fixed in `references/templates.md` (Template B). Before posting, re-read each finding and ask whether it names a concrete consequence; downgrade it to NIT if it does not. Only then post. | 300 words max, hard cap |
+| 6. Harvest | Optional, non-blocking, gated: see below. The default is to write nothing. | an issue carrying the entry text, never a commit and never on the PR |
+
+## Harvest
+
+**The default is to write nothing.** Most reviews produce neither output below. `docs/patterns/` is 106 lines total across four files; that shortness is what makes it worth reading, and a reviewer appending once per PR would double it in a week. Pattern entries are not scored by volume: the measure is whether a later review cites one, never how many exist. Full bar and rationale: `references/craft.md`.
+
+- **A `docs/patterns/` entry**, only when all four of `references/craft.md`'s tests pass: it recurred, it generalizes past this module, it is a real cited good/bad pair, and it is not already covered by the four existing files. Extending an existing file beats creating one. You never commit it: open an issue containing the finished entry text and the file it belongs in, and a dev agent lands it. A reviewer that commits has reviewed nothing, and taste belongs under review like any other change.
+- **A harness note**, only when the same dev-agent *behavior* (not output) has appeared in two PRs, both cited. File it the same way as a DEFER (`finding: <gap>` issue) but name the behavior, not a proposed rule. Not a new mechanical guard: guards caught 0 of 8 v5 findings, and three of those findings were themselves guard proposals.
+
+Anything that surfaces but fails its bar is a NIT, or it is nothing. It is never a pattern.
+
+## Finding classes
+
+BLOCK / DISCUSS / DEFER / NIT replace ERROR / WARNING / NOTE. Each is defined by what happens next, not by severity. Worked examples: `references/classify.md`.
+
+| class | means | resolved by | blocks |
+|---|---|---|---|
+| BLOCK | a defect with a named consequence, introduced by this PR | author fixes it here | yes |
+| DISCUSS | reviewer is genuinely unsure, or the call is above a reviewer's authority | author answers in thread; unresolved disagreement escalates to the user | not once answered |
+| DEFER | real, but not this PR's job, whether or not it is actionable yet | reviewer files the issue and links it | no |
+| NIT | small, cheap, optional | nobody, unless the author wants to | no |
+
+- DISCUSS resolves when the author *answers*, not when the author agrees. Disagreement after an answer goes to the user; neither side rules.
+- A DISCUSS must state what would settle it. A shrug is not a DISCUSS.
+- A public API finding classifies on what you are asserting, never on what the fix touches. A choice among several valid shapes is a DISCUSS, where a reviewer holds no more authority than the author. A demonstrated broken contract is a BLOCK even when the fix changes a signature.
+- A NIT needs no reply. Collect NITs in one list at the bottom of the verdict, never inline.
+- A cause the overrun pass names carries no class of its own and classifies by the rules above like any other finding, the public-API rule included. Whatever the class, the fix is the design: splitting a PR whose size came from a missing concept moves the bloat rather than removing it.
+- Cost is folded into the class, not a separate axis. Real, expensive, and not a regression is a DEFER; introduced by this PR is a BLOCK regardless of cost.
+- DEFER is not a rejection and does not require present actionability: a finding that only informs a later bug fix or feature is still worth filing. NIT means small and optional now; DEFER means real and later.
+- DEFER is where the promotion loop lives: file `finding: <gap>` with the `finding` label for a real out-of-scope defect, citing evidence. Never file a DEFER proposing a new mechanical guard; guards caught 0 of 8 v5 findings.
+
+## Report format
+
+Every comment and the verdict body follow fixed templates: `references/templates.md`. Do not improvise structure, length, or style; it is all decided there, including the exact marker line.
+
+## Delivering the review
+
+- Reviews are COMMENTED only. Approve and request-changes are unavailable when the agent authenticates as the PR author.
+- Inline, line-anchored comments (BLOCK, DISCUSS, DEFER; NITs never inline) in Template A form:
+  `gh api repos/{owner}/{repo}/pulls/<n>/comments -f body=... -f commit_id=$(gh pr view <n> --json headRefOid -q .headRefOid) -f path=<file> -F line=<line> -f side=RIGHT`
+- Post the verdict as a real review in Template B form: `gh pr review <n> --comment --body-file <file>`. Pass requires zero BLOCK and every DISCUSS answered.
+- Post measured against declared with the verdict, one line, so the author sees the delta against the estimate Stage 1 wrote. The raw script output stays in the return to the orchestrator.
+- The review is only delivered once it is on the PR. A local pass with nothing posted is incomplete.
+- A push that changes the code needs a new review: nothing enforces that mechanically, so it is on whoever merges.
+- File DEFER and harness-note issues per the finding-class table above.
+
+## Return to the orchestrator
+
+Template C form (`references/templates.md`): verdict, `make check` result, counts per finding class, links to the posted review and any issues filed, then the evidence, uncapped, raw, no prose (mutation results, measured delta vs the PR's declarations, sibling-comparison notes, probe limits, any `docs/patterns/` commit).