agentdeck-sdk 5.2.0__tar.gz → 6.0.0__tar.gz

{agentdeck_sdk-5.2.0 → agentdeck_sdk-6.0.0}/.agents/skills/open-issue/SKILL.md

@@ -19,6 +19,12 @@ The clean, user-intent API or behavior with minimal code snippets. Show the simp
 ## Notes
 Constraints, affected modules, existing patterns to follow, related issues/PRs.
 
+## Pitfalls
+Known failure modes, each backed by evidence.
+
+## Must not
+Explicit scope boundaries.
+
 ## Done when
 Checklist of observable, testable behaviors (mapping 1:1 to deterministic tests without live model calls).
 ```

{agentdeck_sdk-5.2.0/.claude → agentdeck_sdk-6.0.0/.agents}/skills/release/SKILL.md

@@ -20,30 +20,42 @@ A release needs two labeled `chore` issues and two PRs, not one of each.
 `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 PR into `dev`:**
-   - Update `version` in `pyproject.toml`.
-   - Move Unreleased entries to `## [X.Y.Z] - YYYY-MM-DD` in `CHANGELOG.md` with compare links.
+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.
+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`.
-   - Commit: `chore(release): vX.Y.Z`. Open the PR against the labeled bump issue
+   - Commit: `chore(release): vX.Y.Z`. Open the PR against the bump issue from step 3
      (`Closes #N`), wait for every required check, merge.
-4. **Promotion PR, `dev` to `main`:** Open it against the labeled promotion issue (`Refs #N`).
+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.
-5. **Tag:** `git tag vX.Y.Z && git push origin vX.Y.Z`. `release.yml` publishes to PyPI on this
+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.
-6. **Deploy:** In the `prod/` worktree (detached on a tag on purpose, so the public only sees
+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`.
-7. **Report:** Return the GitHub release URL.
+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-5.2.0/.claude → agentdeck_sdk-6.0.0/.agents}/skills/ship-issue/SKILL.md

@@ -19,7 +19,7 @@ Read the issue and verify its claims against the tree. **Spec gate first:** if t
 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 runs Stage 0 (Understand) then Stage 1
+Provision the worktree first: `git -C <repo>/dev worktree add <repo>/wrts/<branch> <branch>` (create the branch from its base if it does not exist; on a stack the base is the layer below, otherwise `dev`). Spawn `deck-dev` with the issue number, the brief, the absolute worktree path and the PR base branch. It runs Stage 0 (Understand) then Stage 1
 (Design, posted to the draft PR body), then stops there and reports back rather than continuing
 into Stage 2.
 

{agentdeck_sdk-5.2.0 → agentdeck_sdk-6.0.0}/.claude/agents/deck-cleanup.md

@@ -2,11 +2,12 @@
 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.
 
+**Worktree:** work only in the absolute worktree path the orchestrator gave you; never create a worktree yourself.
+
 ## 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.

{agentdeck_sdk-5.2.0 → agentdeck_sdk-6.0.0}/.claude/agents/deck-dev.md

@@ -1,11 +1,15 @@
 ---
 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.
+description: Implements a GitHub issue (feature or bug fix) for agentdeck end-to-end in the worktree it is given and opens one PR to its named base branch.
 model: sonnet
-isolation: worktree
 ---
 
-You implement one agentdeck GitHub issue end-to-end in an isolated worktree and open a PR.
+You implement one agentdeck GitHub issue end-to-end and open a PR.
+
+**Worktree:**
+- Work only in the absolute worktree path the orchestrator gave you.
+- Never create a worktree yourself.
+- Open the PR against the base branch the orchestrator named.
 
 **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.
 

{agentdeck_sdk-5.2.0 → agentdeck_sdk-6.0.0}/.claude/agents/deck-reviewer.md

@@ -2,11 +2,12 @@
 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.
 
+**Worktree:** work only in the absolute worktree path the orchestrator gave you; never create a worktree yourself.
+
 **First action:** read `.claude/skills/review-pr/SKILL.md` and its `references/`, and follow it. Everything procedural, the phases, the finding classes, the verdict format, the delivery mechanics, lives there. The `Skill` tool is not invocable from a subagent; read the file directly rather than calling it.
 
 **Progress:** say which phase you are entering as you enter it. A silent review reads as a stall.
@@ -17,4 +18,4 @@ You review one agentdeck PR as the merge gate. REVIEW ONLY on the code: never pu
 
 **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.
+Return exactly Template C (`.claude/skills/review-pr/references/templates.md`), which fixes both the order and the evidence it carries.

{agentdeck_sdk-5.2.0 → agentdeck_sdk-6.0.0}/.claude/agents/docs-reviewer.md

@@ -2,11 +2,12 @@
 name: docs-reviewer
 description: Review gate for an agentdeck docs-site PR. Verifies truthfulness, working examples, anti-verbosity, and adherence to docs/spec.md.
 model: sonnet
-isolation: worktree
 ---
 
 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.

{agentdeck_sdk-5.2.0 → agentdeck_sdk-6.0.0}/.claude/agents/docs-writer.md

@@ -2,11 +2,12 @@
 name: docs-writer
 description: Writes or rewrites ONE docs-site page for agentdeck, outline first. Emphasizes clarity, conciseness, and verified code examples.
 model: sonnet
-isolation: worktree
 ---
 
 You write or update **one** `docs-site/` page per run, following `docs/spec.md` (Part II  -  Documentation).
 
+**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.

{agentdeck_sdk-5.2.0 → agentdeck_sdk-6.0.0}/.claude/skills/open-issue/SKILL.md

@@ -19,6 +19,12 @@ The clean, user-intent API or behavior with minimal code snippets. Show the simp
 ## Notes
 Constraints, affected modules, existing patterns to follow, related issues/PRs.
 
+## Pitfalls
+Known failure modes, each backed by evidence.
+
+## Must not
+Explicit scope boundaries.
+
 ## Done when
 Checklist of observable, testable behaviors (mapping 1:1 to deterministic tests without live model calls).
 ```

{agentdeck_sdk-5.2.0/.agents → agentdeck_sdk-6.0.0/.claude}/skills/release/SKILL.md

@@ -20,30 +20,42 @@ A release needs two labeled `chore` issues and two PRs, not one of each.
 `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 PR into `dev`:**
-   - Update `version` in `pyproject.toml`.
-   - Move Unreleased entries to `## [X.Y.Z] - YYYY-MM-DD` in `CHANGELOG.md` with compare links.
+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.
+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`.
-   - Commit: `chore(release): vX.Y.Z`. Open the PR against the labeled bump issue
+   - Commit: `chore(release): vX.Y.Z`. Open the PR against the bump issue from step 3
      (`Closes #N`), wait for every required check, merge.
-4. **Promotion PR, `dev` to `main`:** Open it against the labeled promotion issue (`Refs #N`).
+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.
-5. **Tag:** `git tag vX.Y.Z && git push origin vX.Y.Z`. `release.yml` publishes to PyPI on this
+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.
-6. **Deploy:** In the `prod/` worktree (detached on a tag on purpose, so the public only sees
+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`.
-7. **Report:** Return the GitHub release URL.
+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-5.2.0 → agentdeck_sdk-6.0.0}/.claude/skills/review-pr/SKILL.md

@@ -12,7 +12,7 @@ A reviewer finds what matters, says it, and stays silent elsewhere. Prove nothin
 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` declarations; unexplained overrun beyond roughly 2x is a finding. These numbers go in the return to the orchestrator, never in the PR.
+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
@@ -34,7 +34,7 @@ Review progress:
 | 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? | one line, only if there is something |
+| 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 |
 
@@ -60,8 +60,9 @@ BLOCK / DISCUSS / DEFER / NIT replace ERROR / WARNING / NOTE. Each is defined by
 
 - 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.
-- Anything touching public API shape is a DISCUSS, never a unilateral BLOCK.
+- 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.
@@ -76,6 +77,7 @@ Every comment and the verdict body follow fixed templates: `references/templates
 - 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.

{agentdeck_sdk-5.2.0 → agentdeck_sdk-6.0.0}/.claude/skills/review-pr/references/attack.md

@@ -22,9 +22,22 @@ of shallow everywhere.
 - **Import law:** `import-linter` already gates 3-ring boundaries in `make check`; read its count,
   do not re-derive it by hand.
 - **Invalid states the PR claims are impossible:** try to construct the one it says cannot happen.
-
-A claim with a named consequence you actually reproduced is a BLOCK. Skip the angles that do not
-bear on this PR's claims rather than writing something about each for completeness.
+- **The caller's seat:** when the diff changes a public signature or an idiom the docs teach, run the
+  doc's own snippet through the type checker rather than reading the annotation. #231 (`TurnResult |
+  Any`) read as coherent from inside and did not type-check from outside; two outside reviewers hit
+  it and the gate never did, because no shipped example indexes the value the way a user does on
+  line one.
+- **Docstring truth:** a docstring asserting a guarantee is a claim, so attack it like the others.
+  `slopcheck` measures a docstring's size and shape and never reads what it says. #417, #468 and
+  #423 each shipped a sentence describing a mechanism nobody built, and a human reading found all
+  three.
+
+A claim with a named consequence and evidence behind it is a BLOCK. Reproduce it wherever a
+practical probe discriminates the claim; where none does, the code path is the evidence. #572's
+leak was established by reading `deck.py:784-811` against context-manager semantics and never
+downgraded for it. Mutation testing is untouched by this: a claim that a test covers something is
+settled only by running it. Skip the angles that do not bear on this PR's claims rather than
+writing something about each for completeness.
 
 ## Mutation testing
 

{agentdeck_sdk-5.2.0 → agentdeck_sdk-6.0.0}/.claude/skills/review-pr/references/classify.md

@@ -9,6 +9,16 @@ against a deck whose catalog held `Researcher`. `Writer` with `subagents=["Resea
 consequence, introduced by this PR, verified by reproducing it: BLOCK, not a DISCUSS. The fix
 (`self._agents` is already in scope at that line) is the author's, not the reviewer's.
 
+## BLOCK, not DISCUSS: #231, `run()`'s `TurnResult | Any`
+
+`Deck.run` is annotated `-> TurnResult | Any` (`deck.py:705`), so a checker narrows to the
+`TurnResult` member and rejects `paused["type"] == "interrupt"`, the idiom `concepts/workflows.mdx:100`
+teaches. Two outside reviewers hit it, and no shipped example indexes the value the way a user does
+on line one, so the gate never saw it. The fix changes a public signature, which the old rule read
+as automatically a DISCUSS. It is not: the reviewer is not unsure, the call is not above a
+reviewer's authority, and the consequence is named and reproducible with `pyright`. A demonstrated
+broken contract is a BLOCK; a choice between two workable signatures would have been the DISCUSS.
+
 ## Should have been DISCUSS: #415, "block, narrowly"
 
 A re-review at a later SHA read: "block, narrowly. The ERROR is genuinely fixed... What holds the

{agentdeck_sdk-5.2.0 → agentdeck_sdk-6.0.0}/.claude/skills/review-pr/references/craft.md

@@ -7,6 +7,7 @@ Medium freedom. A preferred pattern exists for each concern below; some variatio
 - Read the `docs/patterns/` file for this PR's concern before judging it (see `docs/patterns/README.md` for the map). A new way of doing something a pattern already covers is a defect, not a style choice.
 - Pick 2-3 canonical siblings from `uv run scripts/repomap.py` (same package, same responsibility class), read them end to end, and compare naming, error handling, dependency usage, structure, typing, and test style.
 - Verify the PR's `## Analog` claim against the actual code, not the PR's description of it.
+- Public API documentation must contain the contract a caller needs. Private helpers must not carry contract details absent from the public callable. SLOP013 detects obvious size inversions; judge semantic sufficiency separately.
 
 ## The Harvest bar
 

agentdeck_sdk-6.0.0/.claude/skills/review-pr/references/overrun.md

@@ -0,0 +1,46 @@
+# Overrun: from size to cause
+
+Size is a trigger, never a finding. A BLOCK on LOC gives the author one move, splitting the diff,
+and a PR whose size came from a missing concept splits into two PRs that are still the wrong shape.
+The number sends you looking. What you find is the finding.
+
+## The trigger
+
+Measured delta exceeds the PR's `## Expected delta` or `## Concept budget` by roughly 2x and the
+body does not explain it. Both were written into the draft body before the first source edit and
+cleared the design gate, so the overrun is against a real prediction. Nothing else fires this pass:
+a large diff landing inside its own declaration is a PR that estimated correctly, and a body with
+no estimate never ran Stage 1, so there is nothing to overrun.
+
+## The pass
+
+Pause line-level review and resume Attack and Craft after: an oversized PR must not end up with
+less correctness review than a small one. Read the issue's `## Proposed shape`, the PR's `## Design`
+and `## Analog`, the `docs/design/` entry if there is one, and the decisions recorded on both. The
+question is not "which lines could go" but "what did this design ask for that cost this much".
+
+| where the overrun sits | inspect for | remedy |
+|---|---|---|
+| one new module | a concept the design never named | name it in the design first |
+| spread evenly across files | a rename or refactor riding along | split |
+| tests grew faster than behavior | the contract is unclear, or the abstraction is wrong | fix the abstraction |
+| many new public symbols | `## Reuse analysis` missed an existing sibling | cite the sibling |
+| growth arrived in later commits | patched through review rounds, never designed | consolidation pass |
+
+Spawning a critic for this pass is fine and it passes `model: "sonnet"` like any other subagent.
+
+## It ends in a smaller design or it ends in nothing
+
+The pass returns the shape the code should have had: which concept was missing, which existing
+abstraction covers it, what the public surface becomes. A pass that returns "too big" has not run.
+If the design holds up and the size is simply what the feature costs, say so and record the number
+against the estimate; the estimate was wrong, not the code.
+
+## Classifying what it finds
+
+The cause carries no class of its own; it classifies under the finding-class table like anything
+else, the public-API rule included. A defect this PR introduced is a BLOCK whose consequence is the
+code the wrong shape produced. A genuine choice between valid shapes, or a call above a reviewer's
+authority, is a DISCUSS carrying the smaller design. Real but out of this PR's reach is a DEFER
+carrying the design question. Never a NIT: a NIT is small and optional, and a design costing 2x its
+estimate is neither. Whatever the class, the fix is the design rather than the split.

{agentdeck_sdk-5.2.0 → agentdeck_sdk-6.0.0}/.claude/skills/review-pr/references/templates.md

@@ -51,9 +51,15 @@ ALWAYS use this exact template structure:
     - `service.py:12` ...
     </details>
 
+    +214 LOC, 3 public symbols, against a declared 150 and 2
+
     0 BLOCK, 1 DISCUSS answered, 1 DEFER #431, 4 NIT
 
-- **300 words maximum**, excluding the rubric table and the collapsed NIT block.
+- **300 words maximum**, excluding the rubric table, the collapsed NIT block and the delta line.
+- The delta line is measured against the PR's `## Expected delta`, one line. It reports; it never
+  argues. A body with no estimate reads `+214 LOC, 3 public symbols, no estimate declared`. When it
+  triggered the overrun pass (`overrun.md`), the cause that pass named appears in a section above,
+  never as commentary on the number.
 - **Per finding: 25 words. A DISCUSS gets 35**, because it carries `Settled by:`.
 - Sections in exactly this order. **An empty section is omitted entirely**, never written as
   "None".

{agentdeck_sdk-5.2.0/.agents → agentdeck_sdk-6.0.0/.claude}/skills/ship-issue/SKILL.md

@@ -19,7 +19,7 @@ Read the issue and verify its claims against the tree. **Spec gate first:** if t
 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 runs Stage 0 (Understand) then Stage 1
+Provision the worktree first: `git -C <repo>/dev worktree add <repo>/wrts/<branch> <branch>` (create the branch from its base if it does not exist; on a stack the base is the layer below, otherwise `dev`). Spawn `deck-dev` with the issue number, the brief, the absolute worktree path and the PR base branch. It runs Stage 0 (Understand) then Stage 1
 (Design, posted to the draft PR body), then stops there and reports back rather than continuing
 into Stage 2.
 

{agentdeck_sdk-5.2.0 → agentdeck_sdk-6.0.0}/.github/workflows/ci.yml

@@ -90,9 +90,6 @@ jobs:
       - uses: astral-sh/setup-uv@v7
         with:
           python-version: ${{ matrix.python-version }}
-          # v6 made this opt-in; without it `uv pip install` below finds no venv, and the
-          # Makefile's `.venv/bin/*` calls have nothing to run.
-          activate-environment: true
           enable-cache: true
           cache-dependency-glob: "uv.lock"
       # postgres pulls in the psycopg driver the Postgres event log's tests need: omitting an
@@ -102,7 +99,9 @@ jobs:
       # #141's keyless-AsyncOpenAI regression shipped green. Install every extra the
       # suite guards on: a narrower gate is a gate that lies.
       - name: Install
-        run: uv pip install -e ".[dev,serve,postgres,observability]"
+        # --locked: fails loudly if `uv.lock` is stale instead of resolving fresh and
+        # leaving the lockfile to drift (#605).
+        run: uv sync --locked --all-extras
       # Two seconds here beats a full suite that skips the half it was meant to prove: if an
       # extra silently failed to install, every test guarding on it turns into a skip and the
       # gate goes green having measured nothing (#33, #142).
@@ -129,11 +128,11 @@ jobs:
             grep -oE 'needs the \[[a-z]+\] extra|no (Postgres|Redis) at [^"]*' /tmp/pytest-results.xml | sort -u
             exit 1
           fi
-      # `Test` already replayed the goldens once; this second, separate process is what
-      # proves the snapshots don't depend on process state (in-process stability has its
-      # own test).
-      - name: Golden replay (second process)
-        run: .venv/bin/pytest tests/golden -q
+      # `Test` already replayed the event-schema snapshots once; this second, separate process
+      # is what proves they don't depend on process state (in-process stability has its own
+      # test). The v1 wire goldens this also covered are deleted with that wire (#550).
+      - name: Snapshot replay (second process)
+        run: .venv/bin/pytest tests/core -q
       - name: Build
         run: uv build
 
@@ -161,7 +160,7 @@ jobs:
   # Skipped on a `main`-based PR: that diff is the whole release cycle since main's last
   # advance, re-flagging lines each contributing PR already passed against `dev` (#536).
   slop:
-    if: github.event_name == 'pull_request' && github.base_ref != 'main'
+    if: github.event_name == 'pull_request' && github.event.pull_request.base.ref != 'main'
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
@@ -169,12 +168,14 @@ jobs:
         with:
           fetch-depth: 0
       - name: Comment slop on lines this PR adds
-        run: python3 scripts/slopcheck.py --changed --base "origin/${{ github.base_ref }}" < /dev/null
+        run: python3 scripts/slopcheck.py --changed --base "origin/${{ github.event.pull_request.base.ref }}" < /dev/null
       - name: Commit metadata has no agent attribution
-        run: python3 scripts/check_commit_hygiene.py "origin/${{ github.base_ref }}"
+        run: python3 scripts/check_commit_hygiene.py "origin/${{ github.event.pull_request.base.ref }}"
       - name: Concept budget honored (new classes/symbols/modules/deps declared)
         env:
           PR_BODY: ${{ github.event.pull_request.body }}
-        run: python3 scripts/concept_budget.py "origin/${{ github.base_ref }}"
+        run: python3 scripts/concept_budget.py "origin/${{ github.event.pull_request.base.ref }}"
       - name: Quality delta
-        run: python3 scripts/quality_delta.py "origin/${{ github.base_ref }}"
+        run: python3 scripts/quality_delta.py "origin/${{ github.event.pull_request.base.ref }}"
+      - name: Changelog entries land under [Unreleased]
+        run: python3 scripts/changelog_position.py "origin/${{ github.event.pull_request.base.ref }}"

{agentdeck_sdk-5.2.0 → agentdeck_sdk-6.0.0}/.github/workflows/release.yml

@@ -58,9 +58,6 @@ jobs:
       - uses: astral-sh/setup-uv@v7
         with:
           python-version: "3.12"
-          # v6 made this opt-in; without it `uv pip install` below finds no venv, and the
-          # Makefile's `.venv/bin/*` calls have nothing to run.
-          activate-environment: true
           enable-cache: true
           cache-dependency-glob: "uv.lock"
       - name: Verify tag matches pyproject version
@@ -73,9 +70,9 @@ jobs:
           fi
       - name: Install and check
         # Same extras as ci.yml: a release build must run the same gate as a merge, not a
-        # narrower one.
+        # narrower one. --locked: fails loudly if `uv.lock` is stale (#605).
         run: |
-          uv pip install -e ".[dev,serve,postgres,observability]"
+          uv sync --locked --all-extras
           .venv/bin/python -c "import fastapi, uvicorn, langfuse, psycopg, redis"
           .venv/bin/ruff check agentdeck/ tests/
           .venv/bin/ty check agentdeck

{agentdeck_sdk-5.2.0 → agentdeck_sdk-6.0.0}/.gitignore

@@ -26,3 +26,4 @@ docs/brand/*.jpg
 
 # make check's per-target logs (worktree-scoped, see Makefile's LOG)
 .make-*.log
+node_modules/

agentdeck_sdk-6.0.0/.import_linter_cache/agentdeck.meta.json

@@ -0,0 +1 @@
+{"agentdeck.mcp": 1788386281.5323403, "agentdeck.authoring": 1788386281.5300634, "agentdeck.adapters.telemetry.langfuse.client": 1788386281.5297182, "agentdeck.adapters.executors.native.executor": 1788386281.527745, "agentdeck.adapters.executors.openai_agents.reconcile": 1788386281.527908, "agentdeck.core.ports.lease": 1788386281.5323403, "agentdeck.core.context": 1788386281.5316947, "agentdeck.adapters.stores.redis": 1788386281.5290263, "agentdeck.adapters.executors.openai_agents.executor": 1788386281.527908, "agentdeck.adapters.control.memory": 1788386281.5273702, "agentdeck.adapters.stores.memory": 1788386281.5288353, "agentdeck.runtime.registry": 1788386281.5329542, "agentdeck.deck": 1788386281.5323403, "agentdeck.adapters.stores.sqlite": 1788386281.5292273, "agentdeck.authoring.runners": 1788386281.5303414, "agentdeck.adapters.control.memory.port": 1788386281.5274227, "agentdeck.adapters.leases.sqlite": 1788386281.5285747, "agentdeck.adapters.tools.mcp.lifecycle": 1788386281.5300634, "agentdeck.adapters.telemetry.langfuse": 1788386281.5296638, "agentdeck.adapters.tools.mcp.transport": 1788386281.5300634, "agentdeck.adapters.executors.openai_agents.sessions": 1788386281.527908, "agentdeck.runtime.discovery": 1788386281.5329542, "agentdeck.adapters.control.sqlite.port": 1788386281.5275404, "agentdeck.cli": 1788386281.5311918, "agentdeck.bindings.terminal": 1788386281.5311918, "agentdeck.adapters.executors.openai_agents": 1788386281.527745, "agentdeck.adapters.bindings.native.binding": 1788386281.5270848, "agentdeck.adapters.tools.mcp": 1788386281.5300107, "agentdeck.runtime.capture": 1788386281.5329542, "agentdeck.core.ports": 1788386281.5316947, "agentdeck.adapters.stores.sqlite.store": 1788386281.529421, "agentdeck.adapters.tools.mcp.wiring": 1788386281.5300634, "agentdeck.adapters.stores.memory.store": 1788386281.5288835, "agentdeck.authoring.agent": 1788386281.5303414, "agentdeck.adapters.bindings.native": 1788386281.526853, "agentdeck.authoring.interrupts": 1788386281.5303414, "agentdeck.core.ports.store": 1788386281.5323403, "agentdeck.authoring.injection": 1788386281.5303414, "agentdeck.adapters.telemetry": 1788386281.529421, "agentdeck.bindings.agui": 1788386281.5311918, "agentdeck.adapters.tools.mcp.source": 1788386281.5300634, "agentdeck.adapters.bindings.terminal": 1788386281.5270848, "agentdeck.composition": 1788386281.5311918, "agentdeck.skills": 1788386281.5329542, "agentdeck.authoring.instructions": 1788386281.5303414, "agentdeck.adapters.telemetry.langfuse.trace": 1788386281.5297182, "agentdeck.core": 1788386281.5311918, "agentdeck.adapters.executors.stub.executor": 1788386281.5283446, "agentdeck.core.events": 1788386281.5316947, "agentdeck.core.ports.control": 1788386281.5323403, "agentdeck.adapters.leases.memory": 1788386281.5284722, "agentdeck.core.ports.sink": 1788386281.5323403, "agentdeck.core.control": 1788386281.5316947, "agentdeck.adapters.stores.postgres": 1788386281.5288835, "agentdeck.adapters.control": 1788386281.5272253, "agentdeck.authoring.skills": 1788386281.5308964, "agentdeck.adapters.executors": 1788386281.5275404, "agentdeck.adapters.stores.redis.store": 1788386281.5292273, "agentdeck.adapters.executors.openai_agents.translate": 1788386281.527908, "agentdeck.authoring.hooks": 1788386281.5303414, "agentdeck.core.ports.tools": 1788386281.5323403, "agentdeck.core.base": 1788386281.5316947, "agentdeck.authoring.tools": 1788386281.5308964, "agentdeck.core.reporting": 1788386281.5323403, "agentdeck.adapters": 1788386281.5266154, "agentdeck.adapters.tools": 1788386281.5297182, "agentdeck.adapters.bindings.agui": 1788386281.5268013, "agentdeck.runtime.dispatch": 1788386281.5329542, "agentdeck.core.ports.executor": 1788386281.5323403, "agentdeck.adapters.control.sqlite": 1788386281.5274227, "agentdeck.adapters.bindings.agui.adapter": 1788386281.526853, "agentdeck.core.workers": 1788386281.5323403, "agentdeck.adapters.executors.stub": 1788386281.527908, "agentdeck.adapters.stores.postgres.store": 1788386281.5290263, "agentdeck.adapters.bindings": 1788386281.5267348, "agentdeck.adapters.bindings.terminal.binding": 1788386281.5272253, "agentdeck.adapters.executors.native": 1788386281.5276952, "agentdeck.authoring.compile": 1788386281.5303414, "agentdeck.adapters.telemetry.langfuse.sink": 1788386281.5297182, "agentdeck.skills.bundle": 1788386281.5343738, "agentdeck.authoring.native": 1788386281.5303414, "agentdeck.bindings.native": 1788386281.5311918, "agentdeck.adapters.leases": 1788386281.5283446, "agentdeck.runtime": 1788386281.5323403, "agentdeck.core.content": 1788386281.5316947, "agentdeck.authoring.runners.agent": 1788386281.5308964, "agentdeck.views": 1788386281.5343738, "agentdeck.runtime.settings": 1788386281.5329542, "agentdeck.testing": 1788386281.5343738, "agentdeck.bindings.binding": 1788386281.5311918, "agentdeck.observers": 1788386281.5323403, "agentdeck.errors": 1788386281.5323403, "agentdeck.runtime.service": 1788386281.5329542, "agentdeck.bindings": 1788386281.5308964, "agentdeck.bindings.gateway": 1788386281.5311918, "agentdeck.adapters.stores": 1788386281.5286853, "agentdeck.bindings.exposure": 1788386281.5311918, "agentdeck.authoring.web_search": 1788386281.5308964, "agentdeck.core.invocable": 1788386281.5316947, "agentdeck.adapters.leases.sqlite.port": 1788386281.5286853, "agentdeck": 1788386281.5266154, "agentdeck.adapters.executors.openai_agents.runconfig": 1788386281.527908, "agentdeck.core.status": 1788386281.5323403, "agentdeck.adapters.bindings.agui.binding": 1788386281.526853, "agentdeck.adapters.leases.memory.port": 1788386281.5285747, "agentdeck.core.errors": 1788386281.5316947}