@vegastack/skills 0.9.1 → 0.11.0

package/skill/dev-review/references/cross-agent.md

@@ -0,0 +1,39 @@
+# Cross-agent review
+
+The independence upgrade: the review runs on the *other* agent — Codex when Claude built the code, Claude when Codex did — so the reviewer shares no model, no session, and no authorship with the implementer. Used on `risky` issues by default and whenever dev.md's `review:` knob says `cross-agent`.
+
+## Announce, invoke, summarize — the operator is never blind
+
+1. **At trigger time**, tell the operator in plain language: "invoking Codex for the cross-agent review of issue #N" — before the call, not after.
+2. **Invoke** non-interactively with the handoff below passed as ONE argument through an exec arg array — `execFile('codex', ['exec', handoff])` from Claude, `execFile('claude', ['-p', handoff])` from Codex — never interpolated into a shell string (the exact pattern this skill's own known-patterns template says to still-flag).
+3. **At the end**, summarize: which agent reviewed, the verdict, where its comment is, and what's worth the operator double-checking.
+
+## The handoff — exact format
+
+```
+REVIEW REQUEST (vsk cross-agent v1)
+repo: <absolute path> · issue: <url> · branch: <name> · range: <base7>..<head7>
+brief: the issue description (marker type=brief) · plan: the issue comment
+marked type=plan · package: <path to the review package file> · known-patterns:
+.vegastack/review-known-patterns.md · conventions: references/conventions.md inside ANY installed dev-family skill
+(e.g. .claude/skills/dev-review/references/conventions.md — every dev skill ships a copy)
+axes: spec, standards[, security]
+output contract: post exactly ONE issue comment in the review-comment format
+(marker: <!-- vsk:v1 type=review round=<n> sha=<head7> agent=codex verdict=... -->;
+the reverse direction writes agent=claude);
+on a re-review round, EDIT that same comment — update its single top marker to the
+new round/sha/verdict and append the round section below (never a second marker,
+never a second comment),
+findings as Finding [N] with severities [CRITICAL|MUST-FIX|SHOULD-FIX|NIT] and
+path:line evidence; nitpicks and low-confidence collapsed in <details>.
+constraints: READ-ONLY — never commit, push, edit files, or change labels; your
+only write is the review comment, via gh.
+```
+
+The reviewing agent posts its own comment with its own `agent=` key — independence stays verifiable in the record, never paraphrased by the author.
+
+## Fallbacks and failure honesty
+
+- The other agent's CLI is not installed → fall back to the manual relay (tell the operator which agent to point at the issue), and note that `dev-setup` records the gap and recommends installing it.
+- The invocation fails or times out → say so plainly, fall back to a fresh-subagent review, and label the evidence comment's Review line accordingly — never silently substitute and call it cross-agent.
+- The other agent's review misses the output contract (no marker, no severities) → treat its content as raw findings: post them yourself in the correct format with `agent=` credited, and note the reformatting.

package/skill/dev-review/references/dispatch-prompts.md

@@ -0,0 +1,104 @@
+# Reviewer dispatch prompts
+
+The verbatim briefs each axis subagent receives. Compose with paths and constraints — never pasted history. Every dispatch carries the shared preamble, then its axis brief.
+
+## Shared preamble (every axis)
+
+```
+You are a fresh-context reviewer with no memory of writing this change and no
+stake in it passing. Inputs (read them all): the brief at <issue url or path>,
+the plan comment (marker type=plan), the review package at <package path>, and
+the constraints below, copied verbatim from the brief/plan:
+
+<constraints block>
+
+Write your FULL report to <report path> — complete findings there, each as:
+Finding [N]: <title> — [SEVERITY] (confidence: high|medium|low) path:line,
+issue, why it matters, fix (fenced snippet when code).
+Return only short status: verdict, per-severity counts, and one line per
+finding (title + severity + path:line) — the detail lives in the report file.
+
+You do not dispatch subagents. Do all reading and judging yourself — a reviewer
+you spawn duplicates this review at full cost and its opinion counts for
+nothing in the process. Read full files where the diff needs context (30+
+lines around a hunk) — diff-only review misses invariants.
+
+Report findings or verified absence of findings, never praise. Do not soften a
+finding because the change is large, late, or almost done.
+```
+
+## Spec axis brief
+
+```
+Judge the diff against the CURRENT brief and plan only:
+(a) MISSING — requirements asked for that are absent or partial;
+(b) SCOPE CREEP — behavior in the diff nobody asked for;
+(c) WRONG — requirements that look implemented but don't do what the brief
+    says.
+Quote the exact brief/plan line for every finding. If code and brief diverge
+because the operator changed direction, that is still a finding — the brief
+must be revision-updated before review can pass; say so.
+
+Tests-are-real rubric — flag as [MUST-FIX] any acceptance-relevant test that is:
+- implementation-coupled: mocks internal collaborators, asserts call
+  counts/order, or breaks on refactor without behavior change;
+- tautological: the assertion recomputes the expected value the way the code
+  does, so it can never disagree;
+- horizontal-sliced: bulk tests asserting imagined shapes rather than the
+  behavior the brief names.
+A changed behavior with no covering test at the brief's named seams is MISSING.
+```
+
+## Standards axis brief
+
+```
+Judge the diff against, in priority order:
+1. .vegastack/review-known-patterns.md — its never-flag entries suppress
+   findings UNLESS their "Still flag if:" clause applies;
+2. the project's documented standards (dev.md Project rules, CONTRIBUTING);
+   a documented repo standard always overrides the baseline below;
+3. the smell baseline — each a labeled judgment call ("possible feature
+   envy"), never a hard violation; skip anything tooling already enforces:
+
+- Mysterious name: a name that doesn't reveal what it does or holds → rename.
+- Duplicated code: the same logic shape in more than one hunk/file → extract.
+- Feature envy: a method reaching into another object's data more than its
+  own → move it to the data it envies.
+- Data clumps: the same fields/params traveling together → bundle into a type.
+- Primitive obsession: a primitive standing in for a domain concept → type it.
+- Repeated switches: the same case-cascade on the same type recurring → one
+  shared map or polymorphism.
+- Shotgun surgery: one logical change forcing scattered edits everywhere →
+  gather it into one module.
+- Divergent change: one module edited for several unrelated reasons → split.
+- Speculative generality: abstraction or hooks for needs the brief doesn't
+  have → delete, inline until a real need shows.
+- Message chains: long a.b().c().d() walks the caller depends on → hide the
+  walk behind one method.
+- Middle man: a unit that mostly delegates onward → cut it, call direct.
+- Refused bequest: an implementer ignoring most of what it inherits → compose
+  instead.
+
+Quiet profile: report style only where a documented rule exists. Hard
+violations of documented standards may be [MUST-FIX]; baseline smells are
+[SHOULD-FIX] or [NIT].
+```
+
+## Security axis brief
+
+Compose the security dispatch from [security-axis](security-axis.md): the shared preamble above, then that file's Method steps, finding format (the three extra lines), severity definitions, and standing red lines, quoted into the prompt — the reviewer must receive them in full, not a pointer it cannot follow.
+
+## Re-review brief (scoped, every fix round)
+
+```
+Findings under verification: <the open findings, verbatim>.
+Inputs: the same brief and plan, the implementer's report file (its fix
+reports are the test evidence — do not re-run suites), and the SCOPED package
+at <fix package path> covering only <FIX_BASE>..<HEAD>.
+
+For each finding, in order: ADDRESSED or NOT ADDRESSED, with path:line
+evidence. "Attempted" is not addressed — the specific defect must no longer
+exist. Then: new breakage the fix diff itself introduced (severity + line),
+and out-of-scope observations (non-blocking, one line each). Final line:
+"Fix round: all addressed | findings remain open".
+```

package/skill/dev-review/references/security-axis.md

@@ -0,0 +1,33 @@
+# The security axis
+
+Runs on `risky` issues, and whenever the diff's touch points hit an auth surface, money, user data, or externally-controlled input — the trigger is the surface, not the label alone.
+
+## Method — evidence before severity
+
+1. **Trace the data flow** for every candidate finding: origin → transformations → sink. Is the value attacker-controlled at the point of use? A finding without a traced flow is a hunch, not a finding.
+2. **Check defense in depth before flagging a gap.** A missing check at one layer is not a vulnerability if another layer enforces it on every path — name the enforcing layer instead. Flag it only when no layer holds, or the only holding layer is UX (client-side, middleware-as-convenience).
+3. **Verify library defaults** before "missing configuration" findings — frameworks ship safe defaults more often than training-data memory suggests; check the current docs per `dev-architect`'s verify protocol.
+4. **Assess exploitability**: what does the attacker need (auth level, network position, timing, knowledge)? What mitigating controls exist? Severity follows exploitability, never vibes.
+
+## Finding format — three extra lines
+
+On top of the standard finding shape, every security finding carries:
+
+```
+Data flow: <origin> → <transformations> → <sink>
+Attack prerequisites: <what the attacker needs>
+Mitigating controls: <existing defenses that reduce but don't eliminate>
+```
+
+A finding that can't fill the Data flow line goes to the collapsed low-confidence block, not the main list.
+
+## Severity
+
+- **[CRITICAL]** — exploitable now: auth bypass at the enforcement layer, injection with a traced user-input path, secret/credential exposure, unprotected sensitive mutation. Blocks, above MUST-FIX.
+- **[MUST-FIX]** — a real weakness needing prerequisites an attacker can plausibly meet.
+- **[SHOULD-FIX]** — hardening: rate limits, PII in logs, missing timeouts, defense-in-depth gaps with a holding layer.
+- Never round up to look thorough; judge against the project's Architecture facts — platform-scale concerns are not defects on a small internal tool.
+
+## Standing red lines (summary — `dev-architect` remains their home)
+
+Middleware/proxy is never the authorization boundary; authorization lives server-side per resource. No secret in plaintext anywhere — code, config, logs, events, agent state. Permission checks fail closed, and the deny is still audited.

package/skill/dev-review/refresh/REFRESH.md

@@ -0,0 +1,3 @@
+# Refresh contract — dev-review
+
+Evergreen: this skill asserts no version pins, numeric vendor limits, or dated claims — its content is review discipline (axes, severities, the bounded loop, dispatch briefs, the smell baseline, cross-agent handoff shape), all versionless. The `codex exec` / `claude -p` invocation forms are deliberately treated as durable CLI surfaces; dev-setup's detection covers their presence per machine. Revisit if a future edit introduces a volatile fact.

package/skill/dev-review/refresh/sources.json

@@ -0,0 +1,6 @@
+{
+  "schemaVersion": 1,
+  "retrievalBaseline": "2026-08-28",
+  "note": "Evergreen waiver recorded in REFRESH.md; sources deliberately empty.",
+  "sources": []
+}

package/skill/dev-setup/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: dev-setup
-description: Bootstrap a project for issue-driven agent development — existing repo or brand-new empty directory. Use when asked to "set up the dev workflow", "bootstrap this project for agents", "install the dev workflow here", "set up this new project", or invoked as dev-setup; also run automatically when dev-intake, dev-implement, or dev-ship find no .vegastack/dev.md in the project. Detects the stack and drafts its native release, changelog, and guard conventions; creates the project profile, the AGENTS.md dev section plus CLAUDE.md import, the workflow labels, and the decision register; offers release-guard workflows and the decision-capture hook on the user's yes. Not for architecture profiles or advice (that is architect and .vegastack/arch.md), not for authoring skills, not for general CI or app scaffolding.
+description: Bootstrap a project for issue-driven agent development — existing repo or brand-new empty directory. Use when asked to "set up the dev workflow", "bootstrap this project for agents", "install the dev workflow here", "set up this new project", "wire the release guards", "create the workflow labels", "set up the changelog convention", "fill the architecture profile section", to re-run setup after machinery appeared or knobs changed, or invoked as dev-setup; also run automatically when any dev-family skill finds no .vegastack/dev.md in the project. Not for architecture advice (dev-architect reads the section this skill writes), authoring skills (skillify), or general CI and app scaffolding.
 ---
 
 # dev-setup
 
-Re-runnable bootstrap that gives a project everything the dev workflow needs: a profile file holding the knobs and runbooks, a thin AGENTS.md section that both Claude Code and Codex read, the GitHub labels, and the decision register. The other dev skills call this automatically when `.vegastack/dev.md` is missing, then continue with their original request.
+Re-runnable bootstrap that gives a project everything the dev workflow needs: a profile file holding the knobs and runbooks, a thin AGENTS.md section that both Claude Code and Codex read, the GitHub labels, and the decision register. The other dev skills call this automatically when `.vegastack/dev.md` is missing, then continue with their original request. The workflow-wide artifact spec — comment markers, operator identity, revision markers, scope classes, ledger format, `.vegastack/.tmp/` workspace — lives in [conventions](references/conventions.md); dev skills cite it rather than restating it (the v3 rewrites adopt it skill by skill).
 
-Nearest neighbor: `architect` owns `.vegastack/arch.md` (architecture facts and advice); dev-setup owns `.vegastack/dev.md` (workflow facts and knobs). When arch.md exists, point dev.md at it for stack facts instead of duplicating them.
+Nearest neighbor: `dev-architect` consumes dev.md's `## Architecture` section and gives architecture advice; dev-setup detects the facts and writes the section. There is no separate architecture profile — dev.md is the one file.
 
 ## Step 1 — Detect before asking
 
@@ -21,8 +21,11 @@ Facts are your job; decisions are the user's. Gather these silently and present
 | web app (UI evidence relevant) | framework dependencies (next, react, vue, …) |
 | release/changelog machinery | match signals against [stack-playbooks](references/stack-playbooks.md) — the matched playbook drafts the `## Ship` runbook, the `changelog:` knob, and the guards to offer |
 | environments and run commands | CI/deploy configs, env examples (names only), dev/start scripts — these draft `## Environments` and `## Verify` |
-| existing files | AGENTS.md, CLAUDE.md, `.vegastack/dev.md`, `.vegastack/arch.md`, the decision register |
+| architecture (app repos) | wrangler files (a `d1_databases` binding with no Postgres driver = the D1-only class), drizzle config, better-auth usage, `@aws-sdk/client-s3`/R2 bindings, pg-boss dependency, `eve`/`ai` packages, Dockerfiles/compose, pubspec.yaml — these draft `## Architecture` |
+| existing files | AGENTS.md, CLAUDE.md, `.vegastack/dev.md`, a legacy `.vegastack/arch.md`, the decision register |
 | existing labels | `gh label list` |
+| native issue types | `gh api orgs/<org>/issue-types` — an `Epic` type routes parents to it; absent endpoint or type → the `epic` label fallback ([conventions](references/conventions.md)) |
+| Codex CLI (cross-agent review) | `command -v codex` — absent → record the gap in dev.md `## Environments` and recommend installing it |
 
 Not a git repo, or no origin remote → this is a **greenfield run, not an error**: follow the greenfield playbook in [stack-playbooks](references/stack-playbooks.md) — interview for the intended stack, offer `git init` and `gh repo create` each on its own yes, and render dev.md from the chosen playbook's conventions with TODO lines where machinery doesn't exist yet. A declined remote skips labels and records the TODO plainly.
 
@@ -30,11 +33,11 @@ Not a git repo, or no origin remote → this is a **greenfield run, not an error
 
 Ask with your harness's question tool — AskUserQuestion in Claude Code, `request_user_input` in Codex where the mode allows it (availability details: [harness-facts](references/harness-facts.md)). When no question tool is available (headless run, gated mode), write the defaults, mark every unconfirmed knob `# TODO confirm`, and say so in your reply — a wrong invented preference costs more than a TODO.
 
-**Round A — confirm the detected facts** in one compact summary (repo, stack, commands, web app or not, matched playbook). Ask only about what detection could not fill.
+**Round A — confirm the detected facts** in one compact summary (repo, stack, commands, web app or not, matched playbook, detected architecture facts). Ask only about what detection could not fill.
 
 **Round B — the workflow knobs**, recommended default first:
 
-1. Review of finished work: **subagent** · cross-agent (Codex↔Claude) · cross-agent only on `risky` issues
+1. Review of finished work (`review:` knob, mapped by dev-review): **cross-agent-risky** (subagent axes, the other agent on `risky` — recommended where the Codex CLI was detected; otherwise recommend `subagent`) · `subagent` (never cross-agent) · `cross-agent` (always)
 2. Proof for UI work: **playwright screenshots** · none
 3. Gates: **3** (approve → PR → merge as separate user words) · 2 (approve → one "ship it" covers PR and merge) · 1 (direct-to-main for single-operator projects: the ship word merges locally and pushes, no PR — everything else unchanged)
 4. Tests: **required for every change** · required for logic changes only
@@ -45,6 +48,8 @@ Ask with your harness's question tool — AskUserQuestion in Claude Code, `reque
 - Guards drafted → offer to write their CI backstop steps into the project's workflow files (the local `guard:` lines run without CI); each file on the user's yes — release guards only, never general CI
 - Environments or run commands detected → confirm the drafted `## Environments` and `## Verify` bullets
 - Evidence repo (`ui-evidence: playwright`) → default is the owner's **shared** `<owner>/dev-review-evidence`; if it doesn't exist, offer `gh repo create <owner>/dev-review-evidence --private --add-readme` + the layout/retention README — created once, every project points at it. An org naming policy that rejects the name → pick the closest compliant name with the user and record it in the knob (the name is a knob value, not a contract)
+- App architecture detected → confirm the drafted `## Architecture` (hosting, stage, and kind are what detection usually can't fill — ask those); nothing detected → delete the section, the `stack:` line is enough
+- A legacy `.vegastack/arch.md` exists → fold its knob lines into `## Architecture`, offer each dated `notes:` line to the decision register on the user's yes, then offer to delete arch.md
 - Decision-capture hook → offer the Stop-hook from [harness-facts](references/harness-facts.md) for the harnesses in use; hook files and settings wiring are written only on the user's explicit yes, merging into existing hook config, never overwriting
 - AGENTS.md already has content → append the marked section (default) or show a merge proposal first
 - CLAUDE.md already has content → add the `@AGENTS.md` import as its first line (default) or move its content into AGENTS.md and leave only the import
@@ -56,11 +61,11 @@ Everything else — merge style, branch naming, the stop-and-ask list — takes
 
 | Target | Action |
 |---|---|
-| `.vegastack/dev.md` | render [dev-profile template](assets/dev-profile.md.template) with the answers — the project's single canonical process doc (short directional bullets; Ship/Verify/Environments/Design drafted from the playbook, Decisions test included, placeholders deleted, TODO lines where machinery is absent) |
+| `.vegastack/dev.md` | render [dev-profile template](assets/dev-profile.md.template) with the answers — the project's single canonical process doc (short directional bullets; Ship/Verify/Environments/Design drafted from the playbook, Architecture drafted from detection, Decisions test included, placeholders deleted, TODO lines where machinery is absent) |
 | `AGENTS.md` | create it, or insert/replace only the block between `<!-- vsk-dev:start -->` and `<!-- vsk-dev:end -->` using the [agents-section template](assets/agents-section.md.template); content outside the markers is the user's and stays untouched |
 | `CLAUDE.md` | ensure its first line is `@AGENTS.md` — Claude Code does not read AGENTS.md natively and needs this import ([harness-facts](references/harness-facts.md)); create the file when absent |
-| labels | `gh label create <name> --color <hex> --description "<text>"` for the names the `labels:` knob records, skipping ones that exist; default names and creation colors: `needs-operator` FBCA04 (waiting on the user) · `ready` 0E8A16 (approved, agent may start) · `working` 1D76DB (claimed by an agent) · `for-operator` 5319E7 (result awaiting user review) · `risky` B60205 (security, money, data, or production) |
-| decision register | create the file the `decisions:` knob names (default `.vegastack/decisions.md`) when missing, with a two-line header stating the format: `- DD-MM-YYYY (github-username) — the decision` (username via `gh api user -q .login`, fallback `git config user.name`); a project with an existing register keeps it and the knob points there |
+| labels | `gh label create <name> --color <hex> --description "<text>"` for the names the `labels:` knob records, skipping ones that exist; default names and creation colors ([conventions](references/conventions.md) holds meanings): state `needs-operator` FBCA04 · `needs-plan` E36209 · `ready` 0E8A16 · `working` 1D76DB · `for-operator` 5319E7; modifiers `risky` B60205 · scope `research` C5DEF5 · `quick-build` 76C7C0 · `full-plan` 2A9D8F · `epic` 24292E (only when the org has no native Epic issue type) |
+| decision register | create the file the `decisions:` knob names (default `.vegastack/decisions.md`) when missing, with a two-line header stating the format: `- DD-MM-YYYY operator (github-username) — the decision` (username via `gh api user -q .login`, fallback `git config user.name`); a project with an existing register keeps it and the knob points there |
 | guard workflows / hook files | only the ones the user said yes to in Round C |
 
 ## Step 4 — Report

package/skill/dev-setup/assets/agents-section.md.template

@@ -1,9 +1,9 @@
 <!-- vsk-dev:start -->
 ## Dev workflow
 
-Read `.vegastack/dev.md` for this project's stack, commands, and workflow knobs.
+Read `.vegastack/dev.md` for this project's stack, commands, and workflow knobs. The workflow's stages are the dev-family skills: dev-setup (bootstrap) · dev-intake (ideas to briefs) · dev-plan (approved briefs to plans) · dev-architect (stack judgment) · dev-implement (dark builds) · dev-debug (reproduce-first fixes) · dev-review (independent review) · dev-ship (gated landing) · dev-status (the operator's board) · dev-chronicle (the project's story).
 
-Work flows through GitHub issues. An issue labeled `ready` carries the user's recorded approval and a complete brief — implement it end to end per the `dev-implement` skill, post the evidence in the issue, and hand it back with `for-operator`. Start only on `ready` issues. The workflow vocabulary is the labels dev.md's `labels:` knob names (defaults: `needs-operator` waiting on the user → `ready` approved → `working` claimed by an agent → `for-operator` result awaiting review; `risky` flags security, money, data, or production) — use them and no others.
+Work flows through GitHub issues. An issue labeled `ready` carries the user's recorded approval and a complete brief — implement it end to end per the `dev-implement` skill, post the evidence in the issue, and hand it back with `for-operator`. Start only on `ready` issues. The workflow vocabulary is the labels dev.md's `labels:` knob names (defaults — state: `needs-operator` waiting on the user → `needs-plan` awaiting the planning stage → `ready` approved → `working` claimed → `for-operator` result awaiting review; modifiers: `risky` for security/money/data/production, scope `research`/`quick-build`/`full-plan`, `epic` on map parents) — use them and no others. Artifact formats (comment markers, ledger, revisions, operator identity) follow the dev-setup skill's `references/conventions.md`.
 
 **Nothing ships without the operator's explicit instruction** — no push to the default branch, merge, tag, publish, or deploy on green checks, schedules, or standing approvals alone. The `gates` knob in dev.md changes how many of those actions one instruction covers, never whether an instruction is needed. Behavior changes carry their changelog entry per dev.md's `changelog:` knob before hand-back; after merge, the `## Ship` runbook in dev.md says what happens next and which steps need the operator's word.
 

package/skill/dev-setup/assets/dev-profile.md.template

@@ -3,23 +3,24 @@
 This file is the project's handbook and its only process document: short directional bullets, not prose. Skills read the section they need. When reality disagrees with a line, fix the line; when a gotcha or repeated instruction surfaces, fold ONE line into the right section — never append a log. A section left as TODO because its machinery didn't exist yet: re-run dev-setup detection when the machinery appears.
 
 repo: {{owner/repo}} · default branch {{branch}}
-stack: {{one line, or "see .vegastack/arch.md"}}
+stack: {{one line; the `## Architecture` section below carries the architecture facts}}
 commands: test `{{test}}` · build `{{build}}` · dev `{{dev}}`
 authority: {{ordered — e.g. "CONTRIBUTING.md → this file → skill defaults"; delete the line when this file is the only process doc}}
 
 ## Knobs
 
-review: subagent            # subagent | cross-agent | cross-agent-risky
+review: cross-agent-risky   # subagent (never cross-agent) | cross-agent-risky (other agent on risky) | cross-agent (always) — dev-review maps these
 ui-evidence: playwright     # playwright | none
 evidence-repo: {{owner}}/dev-review-evidence   # shared across projects; this project's folder = repo name; delete the line when ui-evidence is none
 gates: 3                    # 3 = approve/PR/merge · 2 = approve + one "ship it" · 1 = direct-to-main, ship word merges locally and pushes, no PR
 tests: required             # required | logic-only
 merge: squash
 branch: <type>/<issue>-<slug>   # type: feat | fix | docs | chore | refactor — the only place this list lives
-labels: needs-operator ready working for-operator risky
+labels: needs-operator needs-plan ready working for-operator risky research quick-build full-plan epic   # epic label marks map parents only where the org has no native Epic issue type
 changelog: {{changesets | keep-a-changelog | pubspec+changelog | none (reason)}}
 decisions: .vegastack/decisions.md
 release: on-request         # per-merge = Ship runbook runs as part of shipping · on-request = only when the operator says "release"
+chronicle: on               # on = dev-implement writes a .vegastack/chronicle.md story entry per behavior-changing branch · off
 
 ## Ship — what happens after merge, in order
 
@@ -43,13 +44,30 @@ Line prefixes: `auto:` (agent just does it) · `ask:` (operator's word first) ·
 
 ## Design
 
-- {{pointers: design system / component rules / .vegastack/arch.md / UI conventions}}
+- {{pointers: design system / component rules / UI conventions}}
+
+## Architecture
+
+Facts dev-architect reads before advising — knobs, not prose. Decisions with rationale go
+to the register, never here. The repo wins on drift; dev-architect proposes the one-line
+fix. Delete this whole section for repos with no app architecture (pure tooling, docs, or
+content repos) — the `stack:` line at the top is enough.
+
+hosting: {{cloudflare-workers-opennext | self-managed-server | both | vercel (exception - say why)}}
+database: {{postgres via hyperdrive | postgres self-managed | d1 (recorded exception) | none}}
+auth: {{better-auth | none}}            # orgs plugin when multi-tenant
+storage: {{r2 | s3 | minio | none}}
+jobs: {{none | pg-boss}}
+agents: {{none | eve | ai-features}}    # ai-features = AI SDK calls only, no agent runtime
+stage: {{pre-launch | live}}            # pre-launch = delete-not-migrate applies
+kind: {{internal | client | oss}}
+mobile: {{no | flutter (separate repo)}}
 
 ## Decisions
 
 Record a decision only when it is directional — it steers work beyond this issue: a real alternative was rejected; it constrains work not yet written; and no dev.md line, lint rule, or guard can enforce it instead (if one can, write the rule). Feature requests, one-off fixes, and routine implementation choices never qualify. Every entry needs the user's explicit yes. One line in the register (`decisions:` knob), append-only, no other metadata:
 
-- DD-MM-YYYY (github-username) — the decision
+- DD-MM-YYYY operator (github-username) — the decision
 
 ## Stop and ask
 

package/skill/dev-setup/references/conventions.md

@@ -0,0 +1,93 @@
+# Workflow conventions
+
+The single spec for the artifacts every dev-family skill reads and writes. One home per rule: skills cite this file, never restate it. Everything here is harness-neutral.
+
+## Comment metadata markers
+
+Every workflow-generated issue comment opens with an invisible HTML marker followed by a human heading:
+
+```markdown
+<!-- vsk:v1 type=<type> rev=<n> [key=value ...] -->
+## <Human title> (v<n>)
+```
+
+| type | required keys | instances |
+|---|---|---|
+| `approval` | `scope=<brief\|brief+plan\|plan>` | one per approval event |
+| `plan` | `rev` | one, edited in place |
+| `ledger` | `branch` | one, edited in place |
+| `evidence` | `rev branch sha` | one, edited in place |
+| `review` | `round sha agent=<claude\|codex> verdict=<clean\|needs-fixes>` | one per review cycle, rounds appended inside |
+| `decision` | — | one per decision proposal |
+| `handback` | — | one per stop event |
+
+`rev=<n>` and the matching `(v<n>)` heading suffix appear only on revisable artifacts — the brief (issue description), `plan`, and `evidence` — starting at `rev=1`/`(v1)`. Single-event comments (`approval`, `decision`, `handback`) and the `ledger` carry neither. Scripts and agents locate comments strictly by marker, never by heading text. A comment without its marker does not count as the artifact — there is no legacy fallback.
+
+## Operator identity
+
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+
+- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+
+## Revision markers
+
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+
+## Scope classes
+
+Set at intake, applied as a label, announced with its reason (operator can override):
+
+- **`research`** — a question to answer; throwaway code allowed, never merged. No branch/PR/changelog; findings + recommendation are the evidence comment.
+- **`quick-build`** — small change and the flow being changed already exists in the repo to read. Brief (description) + plan (comment) are drafted in the same conversation; **one approval covers both**; then straight to `ready`.
+- **`full-plan`** — big or new ground. Brief approval → `needs-plan` → a separate, fresh-grounded planning session posts the plan → `needs-operator` → "plan approved" → `ready`. Multi-deliverable work becomes an epic; each sub-issue is classified independently.
+
+Scope calls are revisited through the one-way ratchet, whose rules and mechanics live in the `dev-plan` skill — the one home for upgrade/downgrade behavior.
+
+## Labels
+
+State — exactly one per issue (creation colors live in dev-setup's labels row, their one home):
+
+| label | meaning |
+|---|---|
+| `needs-operator` | waiting on the operator: a question, a brief or plan to approve, a proposal |
+| `needs-plan` | brief approved; waiting for the planning stage (full-plan only) |
+| `ready` | fully approved — an agent may start |
+| `working` | claimed, in progress; the ledger comment shows live progress |
+| `for-operator` | done — evidence posted, awaiting operator review |
+
+Modifiers (may coexist with the state label): `risky` · scope `research` / `quick-build` / `full-plan` · `epic` (map parents, only where the org has no native Epic issue type).
+
+## Titles, types, hierarchy
+
+- **Title prefixes** on issues, branches, and PRs identically: dev.md's `branch:` knob type list (that knob stays the list's one home) plus `research:` for research issues. PR title = issue title.
+- **Native issue types** where the org defines them: Feature (feat) · Bug (fix) · Task (docs/chore/refactor/research) · Epic for parents (label fallback otherwise).
+- **Hierarchy:** epic parent = map only (Destination · Decisions so far as one-line gists · Not clear yet · Out of scope), children attached as native sub-issues; issues = the unit of work (brief in description, own approvals/branch/PR/evidence); tasks = checkboxes **in the plan comment only**. Blockers use native issue dependencies; phases use milestones. Only issues — never epics — get `ready`. GitHub caps issue bodies and comments at ~65,536 characters; what a plan nearing that cap means is the `dev-plan` ratchet's call.
+
+## The ledger
+
+Maintained by the implement session as one comment, edited in place:
+
+```markdown
+<!-- vsk:v1 type=ledger branch=<branch> -->
+## Ledger — <branch>
+- Task <N>: complete (commits <base7>..<head7>[, review clean | K parked])
+- Task <N>: fix round <R>/3 (<X> addressed, <Y> open — <one-liners>; commits <a>..<b>)
+- Ruling: <what> — <why> — cost if wrong: <cost>
+- Task <N>: parked — <finding> — Ruling: <why the code stands>
+- Deferred minor: <one-liner>
+```
+
+**Resume protocol:** a fresh, compacted, or (operator-handed) takeover session reads, in order: the brief → the plan comment → the ledger → `git log` on the branch — **nothing else**. Tasks with a `complete` line are DONE, never re-executed; a task whose last line is a fix round resumes at the next round. After compaction, trust the ledger and `git log` over recollection. Every `Ruling:` line surfaces in the evidence comment — a ruling that dies with the session was a decision made in secret.
+
+## `.vegastack/.tmp/` workspace
+
+All transitory artifacts — subagent reports, review packages, plan drafts, extracted diffs — live at `.vegastack/.tmp/<issue-number>-<title-slug>/` (pre-issue intake drafts, which have no number yet: `.vegastack/.tmp/intake-<slug>/`), kept out of git by a self-ignoring `.gitignore` (`printf '*\n' > .vegastack/.tmp/.gitignore`, created on first use). Subagents write full reports to files there and return only short status — a dead subagent's findings survive on disk, and the primary session never holds full reports in context. The workspace lives in the working tree (never under `.git/`, which harnesses protect from writes).
+
+## Verification gate
+
+Before claiming any status: **IDENTIFY** the command that proves the claim → **RUN** it fresh and complete → **READ** the full output and exit code → only then claim, with the evidence. "Should pass", a previous run, or a subagent's say-so are never evidence. Guard scripts follow the same doctrine: machine-verifiable facts **block** (exit 2 with the reason); regex or judgment heuristics only **warn** — no AI inference inside guards, and an unverifiable state fails closed.
+
+## Plain-language collaboration
+
+Every skill run ends with a simple-language summary: what happened, which paths were taken — cross-agent invocations announced at trigger time AND summarized at the end — and what is worth the operator double-checking. Use mermaid or ASCII diagrams in issues wherever a picture beats prose. A vague or self-contradicting operator answer gets pushback with concrete options, never silent absorption.

package/skill/dev-setup/references/stack-playbooks.md

@@ -116,7 +116,7 @@ No git repo or no origin remote is a greenfield run, not an error. Detection has
 
 1. Ask the intended stack (offer the playbook list above) and whether the project will publish, deploy, or neither — this picks the draft conventions up front.
 2. Offer, each on its own yes: `git init` (default branch `main`) · `gh repo create <owner>/<name> --private` + first push · a stack-appropriate `.gitignore`.
-3. Scaffolding the app itself (create-next-app, flutter create, …) is **not** this skill's job — name the conventional command for the chosen stack and leave running it to the user (or `architect` guidance).
+3. Scaffolding the app itself (create-next-app, flutter create, …) is **not** this skill's job — name the conventional command for the chosen stack and leave running it to the user (or `dev-architect` guidance).
 4. Render dev.md from the chosen playbook's conventions; every section whose machinery doesn't exist yet gets its `TODO — re-run dev-setup when it appears` line. Declined remote → skip labels, record the TODO, and say what was skipped.
 
 ## Decision-capture hooks

package/skill/dev-ship/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dev-ship
-description: Create the pull request and merge for a finished issue, each only on the user's explicit word, then run the project's Ship runbook — releases, guards, deploys. Use when the user says "make the PR", "open a pull request" for an issue, "ship it", "merge it", "merge issue 12", "release", "release everything since the last tag", or asks to close out a reviewed issue, merge a bot PR, or roll back a bad release (roll-forward). Verifies the issue is at for-operator with evidence and its changelog entry, links the PR to the issue, merges on the separate merge instruction, and records approved decisions. Not for implementing issues (dev-implement) or writing and approving them (dev-intake).
+description: Land finished work, each step only on the operator's explicit word. Use when the user says "make the PR", "open a pull request" for an issue, "ship it", "merge it", "merge issue 12", "release", "release everything since the last tag", or asks to close out a reviewed for-operator issue, merge a bot PR (Renovate, Dependabot), or roll back a bad release. Not for implementing issues (dev-implement), reviewing them (dev-review), or writing and approving them (dev-intake).
 ---
 
 # dev-ship
@@ -13,23 +13,28 @@ Nearest neighbor: `dev-implement` produces the `for-operator` issue with its evi
 
 On the user's PR instruction:
 
-- Verify the issue is at `for-operator` with the evidence comment present, and the branch is pushed. Not there yet → say what's missing instead of creating a premature PR.
+- Run the deterministic guard first: `node <path-to-this-skill>/scripts/ship-gate.mjs --issue <n> --branch <name> --json` (add `--repo <o/r> --dev-md <path>` outside the project root) — it re-runs the project check command fresh from the branch's own checkout, requires the evidence sha to equal the branch head (the corrections loop is the only reconciliation path), the changelog entry, the chronicle entry where the knob says `on`, a clean-or-adjudicated review verdict, and greps added lines for leftover `[DEBUG-` tags; exit 2 stops you with its reasons, warnings are read-twice signals.
+- Verify the issue is at `for-operator` with the evidence comment present — including its `**Docs:**` line (brief/plan revisions in sync) — and the branch is pushed. Not there yet → say what's missing instead of creating a premature PR. Docs out of sync is corrections work: never patch a brief or plan from inside dev-ship.
 - Verify the changelog state matches the evidence comment's `**Changelog:**` line: a behavior-changing branch carries its entry per dev.md's `changelog:` knob (changesets: a `.changeset/*.md` in the diff; keep-a-changelog: the diff adds lines to CHANGELOG.md), while `none` with a reason that holds up (docs-only, test-only) is fine. An unexplained miss → corrections loop, not a PR.
 - `gh pr create` from the task branch: title from the issue, body is `Closes #<n>` plus a link to the evidence comment — the issue holds the report; the PR links it rather than duplicating it.
 - No draft PRs unless the user asks for one.
-- If required checks fail on the PR, that's implement work: hand the failures to the corrections loop, update the evidence comment, and tell the user. Under `gates: 2` the standing ship word holds once checks are green again — unless the fix changed behavior, which goes back to the user (same rule as a merge conflict).
+- If required checks fail on the PR, that's implement work: hand the failures to the corrections loop, update the evidence comment, and tell the user. Under `gates: 2` the standing ship word holds once checks are green again — subject to Gate 2's staleness bound (behavior change or >7 days → one-sentence re-confirm).
 - A direct chat change (dev-implement's no-issue path) ships on the same words: the chat request stands in for the recorded approval, the PR body carries the evidence instead of linking an issue comment, and the changelog rule applies unchanged.
 - User corrections left on the PR itself flow through the same corrections loop on the same branch — the PR updates with the push; nothing gets recreated.
 
 With `gates: 1` there is no PR: the same verifications run, then the ship word triggers the merge below directly ([runbook](references/runbook.md) has the mechanics).
 
+| Excuse (observed) | Reality |
+|---|---|
+| "Opening a PR is preparation, not shipping — it pushes nothing… exactly the state the workflow wants finished work parked in." | Under `gates: 3` the PR is a gate spent only by the operator's word. Finished work parks on the pushed branch; a draft PR is still a PR nobody asked for. |
+
 ## Gate 2 — the merge
 
 On the user's merge instruction:
 
 - Re-check that the PR head is still the revision the evidence comment names and checks are green — a branch that moved since review gets re-verified before it lands.
-- Pending `Decision:` lines exist (issue comments, or the evidence comment's `**Decision:**` line) → name them in the merge confirmation — "merging will record: …" — so the operator's word demonstrably covers them; never append on inferred consent. On the word, append each to the register dev.md names (`decisions:` knob) in its `- DD-MM-YYYY (github-username) — …` format; the register is append-only and this is its moment.
-- A merge conflict with the default branch is corrections work: update the branch, re-verify what the update touched, and the standing merge instruction holds once checks are green again — unless the update changed behavior, which goes back to the user.
+- Pending `Decision:` lines exist (issue comments, or the evidence comment's `**Decision:**` line) → name them in the merge confirmation — "merging will record: …" — so the operator's word demonstrably covers them; never append on inferred consent. On the word, append each to the register dev.md names (`decisions:` knob) in its `- DD-MM-YYYY operator (github-username) — …` format; the register is append-only and this is its moment.
+- A merge conflict with the default branch is corrections work: update the branch, re-verify what the update touched, and the standing merge instruction holds once checks are green again — unless the update changed behavior, or more than 7 days have passed since the word; either way, re-confirm with one sentence rather than acting on a stale instruction.
 - Merge per the dev.md `merge` knob (default `gh pr merge --squash`; `gates: 1` merges locally per the same knob and pushes). `Closes #<n>` closes the issue; confirm both happened.
 - A bot PR (Renovate, Dependabot) has no issue or evidence comment and merging it is still shipping: green checks qualify it, only the operator's explicit word — per PR or per named batch — merges it; majors and security advisories get named before their word is acted on.
 
@@ -37,8 +42,10 @@ On the user's merge instruction:
 
 Merge is not the end when dev.md has a `## Ship` section: follow its steps in order — `auto:` lines you just do, `ask:` lines wait for the operator's word, `guard:` lines are deterministic checks you run locally at their position (their CI copies are the backstop). With `release: per-merge`, the runbook is part of shipping the issue; with `release: on-request`, it runs only when the operator says "release" (covering everything merged since the last one). Report each step's outcome; a failing step — guard included — stops the sequence and goes to the operator, never skipped past. Execution detail, release batching, direct-to-main, bot PRs, and rollback: [runbook](references/runbook.md).
 
-Rollback is never a force-push: follow the Ship section's rollback line — roll forward through the normal flow. A gotcha here (a step that surprised you, an instruction the operator had to repeat) is one proposed line folded into the runbook; a directional gotcha that passes dev.md's Decisions test is a register proposal instead, on the user's yes.
+Rollback is never a force-push: follow the Ship section's rollback line — roll forward through the normal flow. Gotchas surfaced here feed the Report's closing retro below.
 
 ## Report
 
-One short confirmation each gate: what was created or merged, the link, decisions recorded, and anything that still needs the user (failing check, failing guard, moved head, missing evidence or changelog entry). When a gate's condition isn't met, the answer is what's missing — the gate itself never gets skipped to be helpful.
+One short confirmation each gate, in plain language: what was created or merged, the link, decisions recorded, and anything that still needs the operator (failing check, failing guard, moved head, missing evidence or changelog entry). When a gate's condition isn't met, the answer is what's missing — the gate itself never gets skipped to be helpful.
+
+Close every ship with the retro: any bounce, gotcha, or instruction the operator had to repeat during this issue? Propose the ONE dev.md (or runbook) line that would have prevented it — fold into an existing line, never append a log; a directional gotcha becomes a register proposal instead. Each lands only on the operator's yes.