astack-skills 0.7.0 → 0.7.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "astack",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Skills for Claude Code and Codex that take product work from the thread to a proven, live release.",
   "author": {
     "name": "Andrew Wilkinson",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "astack",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Skills for Claude Code and Codex that take product work from the thread to a proven, live release.",
   "author": {
     "name": "Andrew Wilkinson",

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.7.1
+
+- Keep coupled work in one agent context and load skills as needed. Independent review now depends on risk, unresolved judgment and repository requirements.
+- Shorten skill descriptions while preserving tested routing cues. Context gathering stops when remaining unknowns cannot change the next step.
+- Reuse existing delivery authority and preserve explicit targets. Skills do not create permission to send, publish or bypass a repository gate.
+- Reject incomplete routing evals and report individual improvements and regressions, including when aggregate scores tie.
+
 ## 0.7.0
 
 Review gates and video from LangChain's open-source design agent, [Content Studio](https://github.com/langchain-ai/design-agent) (Apache-2.0), credited where they are used. Its idea is that the model makes the creative calls and code renders, measures and refuses.

package/README.md

@@ -40,15 +40,15 @@ Two ways in, depending on whether you're watching.
 astack this: add annual pricing to the billing page. phones matter most
 ```
 
-`astack` takes it to a PR you'd be happy to merge. It reads the context, plans, builds, uses the thing like a customer, adds tracking, cleans up the slop, gets a second agent to check the work, and stops there for you.
+`astack` takes it to a PR you'd be happy to merge. It reads the context, plans, builds, uses the thing like a customer, adds relevant tracking, cleans up the diff, and verifies the result. A separate reviewer joins when the risk or judgment calls for one.
 
 ```text
 oneshot this: add annual pricing and get it live
 ```
 
-`oneshot` is for when you're not watching. Same work, then it merges, deploys, proves production is serving it and tells the team. It only runs when you ask for it by name.
+`oneshot` is for when you're not watching. Same work, then it merges, deploys, proves production is serving it and sends any authorized update. It only runs when you ask for it by name.
 
-Both pull in the other skills as they need them.
+Both keep one working context and load other skills only when their procedure helps the next step. Required repository checks and delivery proof still apply.
 
 ## Skills
 
@@ -63,7 +63,7 @@ Both pull in the other skills as they need them.
 | [instrument](skills/instrument/SKILL.md) | "can we measure this" | Tracking that fires once, on real success, and a query you can actually trust. |
 | [discoverability](skills/discoverability/SKILL.md) | "why doesn't ChatGPT mention us" | Checks what Google and AI crawlers really see, fixes it, measures before and after. |
 | [dogfood](skills/dogfood/SKILL.md) | "use it like a customer" | Walks the real journeys signed in, fixes what breaks and goes round again. |
-| [ship](skills/ship/SKILL.md) | "ship it" | Clears CI and review comments, gets an independent check, deploys, and proves production is serving it. Also checks other people's "it's shipped". |
+| [ship](skills/ship/SKILL.md) | "ship it" | Clears CI and review comments, verifies the affected behavior, deploys, and proves production is serving it. Also checks other people's "it's shipped". |
 | [launch](skills/launch/SKILL.md) | "we launch tomorrow" | Share cards, page checks, posts for X and Show HN, a tracker and how you'll read the results. |
 
 Each one has a short guide in [docs/skills](docs/skills/).

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "astack-skills",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "private": false,
   "description": "Skills for Claude Code and Codex that take product work from the thread to a proven, live release.",
   "license": "MIT",
   "repository": "https://github.com/ADWilkinson/astack",
   "packageManager": "bun@1.4.2",
   "scripts": {
-    "check": "bun scripts/check.ts && bun test",
+    "check": "bun scripts/check.ts && bun test tests/package.test.ts tests/install.test.ts && bun scripts/smoke.ts",
+    "smoke": "bun scripts/smoke.ts",
+    "test": "bun test",
     "validate": "bun scripts/check.ts",
     "metadata": "bun scripts/metadata.ts",
     "pack": "bun scripts/pack.ts",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "astack",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Skills for Claude Code and Codex that take product work from the thread to a proven, live release.",
   "author": {
     "name": "Andrew Wilkinson",

package/skills/astack/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: astack
-description: Take a product task from "here's the idea" to a pull request that is proven, green and ready for review, covering context, plan, build, real use, measurement and cleanup, without being walked through each step. Use when the user says "astack this", "take this end to end", "do this properly", or hands over a feature, fix, page or experiment and expects it finished rather than planned. Stops before merge; for all the way to production use oneshot.
+description: "Own context, planning, implementation, real use, measurement and checks through a review-ready PR. Use for \"astack this\", \"own this\" or a product task to finish end to end. Load further procedures only as needed. Honor an explicit delivery target."
 ---
 
 # astack
 
-You own the outcome up to a PR the user can review and merge with confidence. Nobody should have to come back and ask "did you check mobile", "is the event firing" or "did CI pass".
+By default, own the outcome up to a PR the user can review and merge with confidence. Honor an explicit target and existing authority. Nobody should have to come back and ask "did you check mobile", "is the event firing" or "did CI pass".
 
 `<skill-dir>` means this skill's folder. Run its scripts from the project root.
 
-## Start by writing the stages into your todo list
+## Own the work in one loop
 
-Copy these eight lines into your todo list before any task-specific items. Close each one with its proof, or leave it in the list as `skip: <one-line reason>`. A stage that silently disappears is a stage you didn't do.
+Keep context, decisions and execution in the main agent. Load another skill or reference only when its procedure changes the next step; the names below are options, not a required chain. Small fixes need only the relevant checks. For sustained work, track the acceptance criteria and their evidence in the existing plan or PR.
 
 1. **Context**: outcome, decisions already made, starting state, the one unknown that could change the approach. (`context`)
 2. **Plan**: every requirement has a change, a proof and a target. Measurement and delivery are in it. ([planning](references/plan.md); small fixes need three lines)
@@ -19,23 +19,25 @@ Copy these eight lines into your todo list before any task-specific items. Close
 4. **Use it**: the real journey, in a browser or runtime, to the real outcome; fix and replay. (`dogfood`)
 5. **Measure**: the success action fires once, on real success, and arrives. (`instrument`, when there is a success action)
 6. **Clean**: `deslop` scan on changed copy, UI and code; every medium or high hit fixed or dismissed with a reason.
-7. **Verify independently**: a fresh agent that did not write the change exercises it and returns PASS or FAIL with evidence. For visual work it also scores its own renders with `web-design`'s review rubric and gives ship, fix or rework. (`ship`; docs-only or trivial changes may skip)
+7. **Verify**: run the repo's required checks and exercise the affected behavior. Use an independent reviewer when subjective quality, security, money, migrations or unresolved uncertainty warrants a separate perspective. Give it acceptance criteria and source evidence, not your conclusions. For visual work, inspect renders against the product's design and the user's references.
 8. **PR ready**: `node <skill-dir>/scripts/pr-state.mjs` reports no blockers on the current head; the PR body says what changed, how it was proven, and what was not verified. (`ship`)
 
-For visual changes, capture 390 and 1440 in light and dark with [`scripts/shoot.mjs`](scripts/shoot.mjs) and look at the images. Use [completion checks](references/completion-checks.md) as the final gate.
+For visual changes, capture 390 and 1440 with [`scripts/shoot.mjs`](scripts/shoot.mjs) and inspect the images, including the themes and states the product supports. Read [completion checks](references/completion-checks.md) when reconciling a larger change before delivery.
+
+Delegate when parallel work needs independent context, reading would crowd out the main task, or an independent verdict matters. Keep ownership separate and return evidence, limitations and affected files. A specialist name alone is no reason to start another agent.
 
 ## What you may do without asking
 
-Invoking astack is the permission for everything reversible that the stages need: create a branch, run the app and dev servers, drive a browser, take screenshots, run any test method, install dev dependencies the repo already declares, push the branch, open or update the PR, reply to review threads with fixes, and re-run CI after a diagnosis.
+Within the user's authorized task and target: create a branch, run the app and dev servers, drive a browser, take screenshots, run tests, install dev dependencies the repo already declares, push the branch, open or update the PR, and re-run CI after a diagnosis. External replies still need authority for that destination. A skill describes procedure; it does not expand the user's grant.
 
 ## Ask only when
 
 - you cannot find a way to prove a change;
 - the goal is ambiguous in a way that changes the result;
-- the next step is outside the grant: merging, deploying to production, deleting data, spending money, messaging people, changing anything outside the repo;
+- the next step is outside the existing grant, such as merging, production deployment, deleting data, spending money or messaging people;
 - another PR or decision makes this one obsolete.
 
-Ask with the harness's question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex), not in a normal message, or the thread looks finished. Put the context and your recommendation in the question. If no tool exists or nobody answers, take the safe path: leave the work on its branch or open PR, and start your final message with the question. Decide everything else yourself and list those decisions in the report.
+Reuse authority already given for the same action and target. If a material decision remains, use the client's available question mechanism and explain what it changes. Continue independent work while waiting. Without required authority, leave the result concrete and reviewable at the authorized target. Decide routine implementation details yourself.
 
 ## Do not stop early
 
@@ -43,9 +45,9 @@ Ending your turn while checks or reviews are pending ends the work, because nobo
 
 ## Finish
 
-- **Outcome**: one sentence, at the PR-ready target.
-- **Proof**: PR link, checks, the independent verdict, screenshots or queries, each with how it was observed.
+- **Outcome**: one sentence at the agreed target, defaulting to PR-ready.
+- **Proof**: PR link, verification method and any independent verdict, screenshots or queries, each with how it was observed.
 - **Decisions you made** for the user.
 - **Not verified**: the exact gap and next step, if any.
 
-To take it further (merge, deploy, verify live, tell the team) the user says `oneshot`.
+Further delivery follows the user's explicit target and existing authority; `oneshot` requests the full path.

package/skills/astack/agents/openai.yaml

@@ -1,3 +1,3 @@
-interface: 
+interface:
   display_name: astack
   short_description: "Own a product task up to a proven, review-ready PR"

package/skills/context/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: context
-description: Gather what actually changes a task before starting it, from Slack threads, issues, PRs, docs, git history, the live product and analytics, and reconcile it into a short brief. Use when picking up a ticket, a Slack ask, a half-finished branch, "look into X", or any task where earlier decisions, corrections or numbers live somewhere other than the prompt.
+description: "Reconcile prior decisions and current evidence into a brief that changes the next step. Use when picking up a ticket, thread or unfinished branch whose scope depends on history outside the prompt."
 ---
 
 # Context
@@ -21,7 +21,7 @@ Search for those answers. Stop reading sources that answer nothing on the list.
 
 If the task touches existing code, anchor first: the files and line ranges involved, `git blame` on them, the last commits and the PRs those commits came from (`gh pr view <n> --json title,body,comments,reviews`). That anchor tells you which threads and decisions to look for.
 
-Then go through each kind of evidence that is available: code history, the issue tracker, docs, team chat, error tracking, analytics. One that has nothing relevant is still a finding; write "searched, nothing" rather than skipping it silently. One you cannot reach is a gap; say so.
+Follow the sources most likely to settle the named unknowns: code history, the issue tracker, docs, team chat, error tracking or analytics. Stop when the next action is clear. Report an unreachable source when it leaves a material question unresolved; an exhaustive source sweep is not a completion requirement.
 
 Use the connected tools; prefer the original over a summary of it. Commands that pay off:
 
@@ -34,10 +34,10 @@ git log -p --follow -- path/to/file | head -200
 git blame -L 120,160 path/to/file
 ```
 
-- **Slack / chat**: read the whole thread including late replies; the correction is usually at the bottom. Search with the channel and date bounds (`in:#channel after:2026-01-01 "keyword"`), then open each hit in context.
-- **Docs and specs**: check the date and whether later code or chat superseded them.
-- **Live product**: open the real page or call the real endpoint. What it does today beats what a doc says it does.
-- **Analytics**: read the definition (event, filters, window) before reading the number. A number without its definition is not context.
+- Slack / chat: read the whole thread including late replies; the correction is usually at the bottom. Search with the channel and date bounds (`in:#channel after:2026-01-01 "keyword"`), then open each hit in context.
+- Docs and specs: check the date and whether later code or chat superseded them.
+- Live product: open the real page or call the real endpoint. What it does today beats what a doc says it does.
+- Analytics: read the definition (event, filters, window) before reading the number. A number without its definition is not context.
 
 See [source selection](references/source-selection.md) for which source wins when they disagree, and for multi-source tasks.
 

package/skills/context/agents/openai.yaml

@@ -1,3 +1,3 @@
-interface: 
+interface:
   display_name: Context
   short_description: Gather and reconcile what changes the task

package/skills/context/references/source-selection.md

@@ -22,7 +22,7 @@
 
 ## Signs the context is wrong
 
-- The brief has no "Open" line. Something is always uncertain; find it.
+- A material unknown is hidden. If no remaining uncertainty changes the next step, say "Open: none material" and proceed.
 - The brief repeats the prompt. You read nothing that changed the work.
 - A number appears without project, population, filter and window.
 - A "decided" item has no link or date.

package/skills/deslop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: deslop
-description: Strip the tells of generated work from copy, UI and code, such as inflated vocabulary, "not just X but Y", staged reveals, em-dash rhythm, emoji bullets, gradient-and-glass UI, narrating comments and defensive clutter, while keeping facts, behaviour and voice. Use when the user says deslop, "this sounds like AI", "make it sound human", "tighten this", before publishing copy or merging UI, or when writing anything public. Also builds a voice profile from someone's real writing.
+description: "Write or revise public copy, UI and code without generated tells, preserving facts and voice. Use for \"deslop\", \"sounds like AI\", tightening prose, user emails, removing generic UI or learning a voice from real writing."
 ---
 
 # Deslop

package/skills/deslop/agents/openai.yaml

@@ -1,3 +1,3 @@
-interface: 
+interface:
   display_name: Deslop
   short_description: "Strip AI tells from copy, UI and code"

package/skills/discoverability/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: discoverability
-description: Find out why the right people do not find or choose a product through Google, Bing and AI answer engines (ChatGPT, Claude, Perplexity, AI Overviews), fix the cause, and measure the result. Use for SEO audits, "why aren't we ranking", "does ChatGPT recommend us", GEO/AEO, indexing problems, canonical/robots/sitemap issues, comparison and alternatives pages, or before and after a content push.
+description: "Diagnose and fix why Google, Bing or AI answers miss or misdescribe a product. Use for SEO/GEO/AEO, ranking or indexing problems, canonical/robots/sitemap checks and search-focused content."
 ---
 
 # Discoverability

package/skills/discoverability/agents/openai.yaml

@@ -1,3 +1,3 @@
-interface: 
+interface:
   display_name: Discoverability
   short_description: Fix why search and AI answers miss the product

package/skills/dogfood/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dogfood
-description: Use the product like a real user, signed in, with real data, through to the result they came for, then fix what breaks and repeat until the journeys pass. Use for "test this end to end", "QA the app", "use it like a customer", "find what's broken", pre-launch checks, after a big change, or for AI features whose answers need repeated real trials. Fixes as it goes when fixes are authorised.
+description: "Walk real product journeys, fix authorized problems and replay through the outcome. Use for end-to-end QA, signed-in mobile checks, pre-launch testing and repeated trials of AI features. Review-only requests produce findings."
 ---
 
 # Dogfood

package/skills/dogfood/agents/openai.yaml

@@ -1,3 +1,3 @@
-interface: 
+interface:
   display_name: Dogfood
   short_description: "Use the product for real, fix what breaks"

package/skills/instrument/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: instrument
-description: Add product analytics that answer a real question, such as events, funnels, conversion and activation metrics, and prove them end to end, so the event fires once on real success, arrives in the right project with clean properties and identity, and a saved query reads it. Use when adding tracking, "can we measure this", setting up PostHog/Amplitude/Mixpanel/GA events, building a funnel, when a dashboard number looks wrong or changed suddenly, or before shipping a feature whose impact matters.
+description: "Add or diagnose product analytics and prove events arrive once on real success with safe properties. Use for tracking, conversion funnels, PostHog/GA events or dashboard numbers that look wrong or change suddenly."
 ---
 
 # Instrument

package/skills/instrument/agents/openai.yaml

@@ -1,3 +1,3 @@
-interface: 
+interface:
   display_name: Instrument
   short_description: Track the outcome and prove the event arrives

package/skills/launch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: launch
-description: Get a product or feature ready to be seen in public and put it in front of people, covering share cards and metadata, a launch-ready landing page, demo media, announcement posts, changelog, directory and community listings with a tracker, and launch-week measurement. Use for "launch this", "prepare a launch kit", "write the launch post", "submit to directories", "make an OG image", Product Hunt / Show HN / X launches, or before telling the public about anything new.
+description: "Prepare a product launch, share cards, OG images, demo clips, announcement copy, changelog or community listings, with a distribution tracker and measurement. Use for launch kits, X/Show HN posts and directory submissions."
 ---
 
 # Launch
@@ -44,7 +44,7 @@ Specific, verifiable, in the product's voice. Lead with what someone can do now.
 
 ## 4. Distribute deliberately
 
-Order the tracker by fit, not by count: the communities where the product's users already are come first. Respect each place's rules (self-promotion limits, required formats, no voting rings). Posting, submitting and messaging go out under the user's accounts: draft everything, and send or submit only with their go-ahead for each destination. Update the tracker with status and the live URL as each goes out.
+Order the tracker by fit, not by count: the communities where the product's users already are come first. Respect each place's rules (self-promotion limits, required formats, no voting rings). Draft the material, then send or submit within the user's authority for each destination; reuse authority already given for that action and target. Update the tracker with status and the live URL as each goes out.
 
 ## 5. Measure the week
 

package/skills/launch/agents/openai.yaml

@@ -1,3 +1,3 @@
-interface: 
+interface:
   display_name: Launch
   short_description: "Ready the page, kit, posts and tracker for launch"

package/skills/oneshot/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: oneshot
-description: Trigger this only when the user says "oneshot" (or "oneshot this", "full send"). The user is not watching and wants the task taken all the way, from idea to merged, deployed, verified live in production and reported to the team, with no further prompting.
+description: "Use only when explicitly requested as \"oneshot\" or \"full send\": implement, merge, deploy and verify live within the user's scope, then send any authorized delivery update."
 disable-model-invocation: true
 ---
 
 # oneshot
 
-The user said oneshot because they are not watching this thread. Your updates and final message go unread until long after you stop. You own the work from its current state to a change that is live, proven and announced.
+Own the work from its current state to the authorized live result, with serving proof and any authorized delivery update.
 
 If the user did not clearly ask for oneshot, do not assume this level of autonomy; use `astack` instead.
 
@@ -14,28 +14,28 @@ If the user did not clearly ask for oneshot, do not assume this level of autonom
 
 ## The grant
 
-Saying oneshot gives you permission, for this task only, to:
+An explicit oneshot request sets the end-to-end delivery intent for this task. Follow the user's actual scope, repository gates and any narrower authority. The delivery path may include:
 
 - do everything `astack` may do without asking;
 - merge the PR once the merge gate passes, with the repo's merge method;
 - force-push the PR's own branch with `--force-with-lease` after a rebase;
 - deploy through the repo's documented pipeline to the target the user named, or to production when the repo deploys on merge;
-- post the delivery update to the channel or thread where the work was requested;
-- use any test method the proof needs, including browsers, simulators and running the app, even where project files say to ask first. Rules about *how* to test still apply.
+- post a delivery update when the user authorized that destination;
+- use proportionate test methods, including browsers, simulators and running the app, within the task's existing testing authority.
 
 It does not cover: deleting data, spending money, changing secrets or permissions, touching other repos or other people's branches, or messaging anyone else. A harness approval prompt still applies.
 
 ## Steps
 
-Copy these into your todo list first. Close each with proof or `skip: <reason>`.
+Keep one working plan with the acceptance criteria and evidence. Load supporting skills only for procedures the current step needs.
 
-1. **Run the astack stages** 1 to 7: context, plan, build, use it, measure, clean, independent verification. Read `astack`'s SKILL.md if it is installed; the stages are listed there.
+1. **Implement and verify**: settle context that changes the work, build in the repo's conventions, exercise the real journey, verify relevant measurement and clean the diff. Required checks and affected behavior decide whether the change works. Add independent review when risk, subjective quality or repository rules call for it.
 2. **Open the PR** and get it to no blockers with `ship`: CI classified and fixed, every review thread fixed or answered with a reason.
-3. **Merge gate.** All true on the latest head: proof covers every change in the diff; required checks green; the independent verdict is PASS for this head; review bots finished and each finding fixed or dismissed with a reason; no human review requesting changes; branch up to date and mergeable. `git fetch` and re-read the PR immediately before merging. Never `--admin` or any bypass.
+3. **Merge gate.** All true on the latest head: proof covers every change in the diff; required checks green; any required independent review covers this head with no unresolved defects; review bots finished and each finding fixed or dismissed with a reason; no human review requesting changes; branch up to date and mergeable. `git fetch` and re-read the PR immediately before merging. Never `--admin` or any bypass.
 4. **Merge, then read it back.** A queued merge or armed auto-merge is not a merge; stay until GitHub reports the PR merged.
 5. **Deploy and prove it.** Deploy the way the repo deploys, then `node <skill-dir>/scripts/verify-live.mjs` must find the deployed commit or the changed content at the real URL, and you exercise the changed behaviour there.
-6. **Tell the team** in the thread or channel where the work was requested: what users can now do, the word that is true (live, merged, blocked), and the PR and live links, in two or three lines. Check the thread for an earlier update about the same change first, scan the text for secrets and private data, send once, read it back and keep the permalink.
-7. **Report** in your final message: outcome, PR and merge commit, live proof, the independent verdict, decisions you made, anything not verified.
+6. **Send an authorized update** to the destination the user approved: what users can now do, the state that is true (live, merged, blocked), and the PR and live links. Check for an earlier update about the same change, scan for secrets and private data, send once, read it back and keep the permalink. If no destination is authorized, report here.
+7. **Report** in your final message: outcome, PR and merge commit, live proof, verification method and any independent verdict, decisions you made, anything not verified.
 
 ## Never stop early
 
@@ -43,7 +43,7 @@ Ending your turn while checks, reviews, a merge queue or a deploy are pending en
 
 ## Asking the user
 
-A normal message goes unseen. Use the harness's question tool, with the PR link, what blocks you, and the options with your recommendation first. Ask only when:
+Use the client's available question mechanism with the PR link, the blocker and your recommendation. Reuse existing authority. Ask only when:
 
 - you cannot prove a change;
 - the merge gate cannot pass and you cannot fix it yourself;

package/skills/oneshot/agents/openai.yaml

@@ -1,5 +1,5 @@
-interface: 
+interface:
   display_name: oneshot
   short_description: "Idea to merged, deployed, verified live and announced"
-policy: 
+policy:
   allow_implicit_invocation: false

package/skills/ship/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ship
-description: Get a change across the line to its agreed target, whether a reviewed PR, a merge, staging or production, by working through review comments, failing CI, conflicts and visual checks, then prove the target is serving it. Use for "ship it", "get this merged", "fix CI", "address the review comments", "babysit this PR", "deploy and verify", or whenever work is done locally but not delivered.
+description: "Deliver an existing change to its agreed PR, merge, staging or production target. Use for failing CI, review comments, conflicts, babysitting a PR, deployment verification or checking someone else's \"it shipped\" claim."
 ---
 
 # Ship
@@ -43,7 +43,7 @@ Work in this order, batching every known fix into one push: **conflicts, then re
 
 - Read the first real error in the log (`gh run view <id> --log-failed | head -200`), not the last line, and reproduce it locally with the command CI runs.
 - A failure in code the diff never touched usually means a stale base: check with `git merge-base --is-ancestor origin/main HEAD` and rebase rather than retry.
-- Evidence of infrastructure trouble (runner died, network, registry down) earns **one** fresh run. An identical second failure means it was never a flake: read the logs properly.
+- Evidence of infrastructure trouble (runner died, network, registry down) can justify a fresh run. If the failure repeats, diagnose it before another retry; repetition alone does not establish the cause.
 - Only a failure in the diff's own code gets a code change.
 
 **Review threads: verify, then fix or decline.**
@@ -67,11 +67,11 @@ It prints one line per change (a check finishing, a new review comment, the head
 
 Never game a gate: no skipping, deleting or loosening tests, no raising timeouts or thresholds, no `--no-verify`, no disabling a check to get green. See [review and release](references/review-and-release.md) for the full list and for CI diagnosis.
 
-## 4. Get an independent verdict
+## 4. Choose verification for the risk
 
-The author is the worst judge of their own change. Before calling a PR ready (or merging it), have a fresh agent that did not write the code exercise it the way a user would: run the app, follow the changed journey, try the edge cases, and return **PASS**, **PASS with notes** or **FAIL**, with evidence (screenshots, commands, output). Give it the PR, the acceptance criteria and how to run the app; not your conclusions.
+Run required checks and exercise the affected behavior. A routine change with decisive deterministic evidence needs no extra model loop. Use a fresh reviewer for subjective quality, security, money, migrations or uncertainty that the checks do not settle; preserve any repository requirement for review. Give it the PR, acceptance criteria and how to run the app, without your conclusions. It should return **PASS**, **PASS with notes** or **FAIL**, with source evidence and any limits.
 
-A verdict covers one head commit. Any later push needs a fresh one. Docs-only and trivial changes may skip it; say so in the PR. If subagents are not available, say the verdict is self-assessed.
+A verdict covers the head it examined. After a later push, refresh checks and review for the affected paths. Report whether verification used deterministic checks, an independent reviewer or self-assessment; never label the author's check independent.
 
 ## 5. Check the experience
 
@@ -104,7 +104,7 @@ When asked whether a claimed release is real (before support tells a customer, b
 4. **Is review finished?** Unresolved threads, including outdated ones: check each against the code that shipped.
 5. **Was the user's case exercised on the target?** The specific scenario (account size, browser, data) that was failing, run where the user is.
 
-Then give: the verdict, each failed gate with its evidence, the ordered steps to make the claim true (fix, re-run checks on the deployed commit, verify serving, exercise the case), and an honest holding line for the person waiting.
+Then give: the verdict, each failed gate with its evidence, the ordered steps to make the claim true (fix, re-run checks on the deployed commit, verify serving, exercise the case), and an honest holding line for the person waiting. Scope claims to the evidence supplied: a missing passing run is not proof none ever existed, and a cached older SHA does not establish what the origin serves now.
 
 ## 7. Report
 

package/skills/ship/agents/openai.yaml

@@ -1,3 +1,3 @@
-interface: 
+interface:
   display_name: Ship
   short_description: "Get to green, merge, deploy and prove it is live"

package/skills/web-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: web-design
-description: Design and build web interfaces that look like a specific product made them, not a template, including their animation and transitions. Use for new pages, redesigns, landing pages, brand refreshes, component work, "make this look better", "this looks AI-generated", "animate this", "make it feel smoother", "the animation is janky", "it feels wrong on my phone", "try it with long names", or any UI change where hierarchy, typography, colour, layout, motion or responsive behaviour matter. Keeps a DESIGN.md so the direction survives between sessions.
+description: "Design product-specific web UI, responsive layouts and motion; keep the direction in DESIGN.md. Use for new pages, redesigns, generic-looking UI, janky animation, awkward phone behavior or layouts stressed by long or empty data."
 ---
 
 # Web design

package/skills/web-design/agents/openai.yaml

@@ -1,3 +1,3 @@
-interface: 
+interface:
   display_name: Web design
   short_description: "Design UI and motion that look like this product, not AI"

package/skills/web-graphics/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: web-graphics
-description: Make bespoke graphics for the web, such as isometric scenes, animated sticker icons, flat illustrations, ASCII and halftone art, diagrams, icons, mascots, social cards and hero images, as editable code-built assets that hold up in the actual page. Use when asked for an illustration, a hero graphic, an explainer visual, an icon set, animated or Lottie-style icons, onboarding or empty-state art that moves, an OG image, "make a graphic for", or when a page needs visual identity beyond layout.
+description: "Build editable web illustrations, isometric scenes, animated stickers or Lottie-style icons, ASCII/halftone art, diagrams, mascots and social cards. Use for hero graphics, favicons, app icon sets, moving empty-state art or sticker exports."
 ---
 
 # Web graphics

package/skills/web-graphics/agents/openai.yaml

@@ -1,3 +1,3 @@
-interface: 
+interface:
   display_name: Web graphics
   short_description: "Build bespoke isometric, flat and ASCII graphics"