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

agentdeck_sdk-6.0.4/.agents/skills/release/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: release
+description: Cut an agentdeck release  -  bump version, update CHANGELOG, merge dev to main, and tag vX.Y.Z.
+---
+
+# Release agentdeck
+
+Follow the release process strictly. All work starts on `dev`; `main` is release-only,
+and `dev` is the repository's default branch.
+
+## Two PRs, two issues
+
+A release needs two labeled `chore` issues and two PRs, not one of each.
+
+| PR | base | issue | closing keyword |
+|---|---|---|---|
+| bump | `dev` | its own labeled `chore` issue | `Closes #N`, works: `dev` is default |
+| promotion | `main` | its own labeled `chore` issue | `Refs #N` only, close by hand: `main` is not default, so GitHub never creates the closing reference |
+
+`git push origin dev` is rejected directly ("push declined due to repository rule violations").
+The bump goes through its own PR into `dev`.
+
+A PR body closing more than one issue needs one `Fixes #N` (or `Closes #N`) per line: GitHub's
+closing-keyword parser only recognizes the first reference in a comma-separated list, silently
+leaving the rest open (#541).
+
+## Release Steps
+
+1. **Version:** Confirm SemVer bump (`pyproject.toml` and `CHANGELOG.md`).
+2. **Preflight:** Verify clean working tree, non-empty `[Unreleased]` section, and `make check`
+   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 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
+   `chore: release vX.Y.Z to main` issue in the same milestone and prints its number.
+6. **Promotion PR, `dev` to `main`:** Open it against the promotion issue from step 5 (`Refs #N`).
+   `Issue hygiene`, `slop`, and `Check affected documentation` skip themselves on a `main`-based
+   PR: each already ran the real per-PR version of itself against `dev` at merge time, and this
+   diff is the whole release cycle re-evaluated, not a new change. Wait for `check` and
+   `Build documentation`, then merge and close the promotion issue by hand.
+7. **Tag:** `git tag vX.Y.Z && git push origin vX.Y.Z`. `release.yml` publishes to PyPI on this
+   push; there is no undo once the tag lands.
+8. **Close the milestone:** `python scripts/release_bump.py close-milestone X.Y.Z`, right after
+   the tag push. Every past release skipped this: `v5.0.0` through `v5.1.0` all shipped with 0
+   open issues but stayed open on GitHub.
+9. **Deploy:** In the `prod/` worktree (detached on a tag on purpose, so the public only sees
+   something released), run `./deploy-prod.sh vX.Y.Z`. It rebuilds `docs-site`, restarts
+   `agentdeck-docs-static.service`, and health-checks `127.0.0.1:4321`.
+10. **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-6.0.4/.claude/agents/docs-reviewer.md

@@ -0,0 +1,27 @@
+---
+name: docs-reviewer
+description: Review gate for an agentdeck docs-site PR. Verifies truthfulness, working examples, anti-verbosity, and adherence to docs/engineering/documentation.md.
+model: sonnet
+---
+
+You review one docs-site PR as the gate before merge.
+
+**Worktree:** work only in the absolute worktree path the orchestrator gave you; never create a worktree yourself.
+
+## Review Checks
+1. **Truthfulness against Code:**
+   - 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/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.
+   - Ensure text is dense with signal and gets straight to the point.
+4. **Links & Navigation:**
+   - Check all internal links and navigation entries.
+5. **Gate & Output Style:**
+   - Run `make check` to verify anti-rot tests.
+   - Keep text between tool calls to ≤25 words. Keep final responses to ≤100 words unless more detail is required.
+
+Return: `approve` or `request changes` with a concise, ranked list of confirmed findings (file:line, issue, concrete fix).

agentdeck_sdk-6.0.4/.claude/agents/docs-writer.md

@@ -0,0 +1,30 @@
+---
+name: docs-writer
+description: Writes or rewrites ONE docs-site page for agentdeck, outline first. Emphasizes clarity, conciseness, and verified code examples.
+model: sonnet
+---
+
+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.
+
+## Two-Phase Workflow
+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/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.
+- **Anti-verbosity:** Strip all filler words ("simply", "just", "easily", marketing adjectives). If a concept can be explained in 1–2 sentences, do not use a paragraph. Keep pages concise (about one screen).
+- **Hide internal machinery:** Document user intent and public primitives (`Deck`, `Agent`, `Workflow`, `Skill`, `Run`). Never expose internal plumbing (`core/` internals, stores, resolvers).
+- **Verify every claim:** Run every code snippet and command. Check settings against `AGENTDECK_*`.
+
+## Process & Style
+- Branch `docs/<n>-<slug>`, open draft PR on first commit targeting `dev`, `Closes #<n>`.
+- `make check` must pass cleanly (anti-rot tests validate all code fences).
+- Keep text between tool calls to ≤25 words. Keep final responses to ≤100 words unless more detail is required.
+
+Return:
+- Phase 1: Outline + verified source references.
+- Phase 2: PR URL, verification results, and `make check` status.

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.4/.claude/skills/release/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: release
+description: Cut an agentdeck release  -  bump version, update CHANGELOG, merge dev to main, and tag vX.Y.Z.
+---
+
+# Release agentdeck
+
+Follow the release process strictly. All work starts on `dev`; `main` is release-only,
+and `dev` is the repository's default branch.
+
+## Two PRs, two issues
+
+A release needs two labeled `chore` issues and two PRs, not one of each.
+
+| PR | base | issue | closing keyword |
+|---|---|---|---|
+| bump | `dev` | its own labeled `chore` issue | `Closes #N`, works: `dev` is default |
+| promotion | `main` | its own labeled `chore` issue | `Refs #N` only, close by hand: `main` is not default, so GitHub never creates the closing reference |
+
+`git push origin dev` is rejected directly ("push declined due to repository rule violations").
+The bump goes through its own PR into `dev`.
+
+A PR body closing more than one issue needs one `Fixes #N` (or `Closes #N`) per line: GitHub's
+closing-keyword parser only recognizes the first reference in a comma-separated list, silently
+leaving the rest open (#541).
+
+## Release Steps
+
+1. **Version:** Confirm SemVer bump (`pyproject.toml` and `CHANGELOG.md`).
+2. **Preflight:** Verify clean working tree, non-empty `[Unreleased]` section, and `make check`
+   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 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
+   `chore: release vX.Y.Z to main` issue in the same milestone and prints its number.
+6. **Promotion PR, `dev` to `main`:** Open it against the promotion issue from step 5 (`Refs #N`).
+   `Issue hygiene`, `slop`, and `Check affected documentation` skip themselves on a `main`-based
+   PR: each already ran the real per-PR version of itself against `dev` at merge time, and this
+   diff is the whole release cycle re-evaluated, not a new change. Wait for `check` and
+   `Build documentation`, then merge and close the promotion issue by hand.
+7. **Tag:** `git tag vX.Y.Z && git push origin vX.Y.Z`. `release.yml` publishes to PyPI on this
+   push; there is no undo once the tag lands.
+8. **Close the milestone:** `python scripts/release_bump.py close-milestone X.Y.Z`, right after
+   the tag push. Every past release skipped this: `v5.0.0` through `v5.1.0` all shipped with 0
+   open issues but stayed open on GitHub.
+9. **Deploy:** In the `prod/` worktree (detached on a tag on purpose, so the public only sees
+   something released), run `./deploy-prod.sh vX.Y.Z`. It rebuilds `docs-site`, restarts
+   `agentdeck-docs-static.service`, and health-checks `127.0.0.1:4321`.
+10. **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.