@vegastack/vegafactory 0.19.0

package/skill/vegafactory-setup/assets/control-room/group.md.template

@@ -0,0 +1,44 @@
+# {{group}} — group defaults
+
+One default for every knob a group can decide for a repo's `.vegastack/dev.md` — the per-repo facts (`repo:`, `skill-scan:`, `board:`, `control-room:`, the detected org types and fields) stay in the repo — so a repo that answers nothing else still gets a complete profile. Ordinary explicit repo values beat group defaults, which beat ordinary org defaults. Organization locks require exact org delegation; this file cannot grant it or appoint admins. Precedence and the read path: the vegafactory-setup skill's `references/control-room.md`.
+
+policy-schema: 2
+
+## Knobs
+
+review: cross-agent-risky   # subagent | cross-agent-risky | cross-agent
+gates: 3                    # 3 = approve/PR/merge · 2 = approve + one "ship it" · 1 = direct-to-main
+merge: rebase               # rebase | squash | merge
+branch: <type>/<slug>       # type: feat | fix | docs | chore | refactor
+labels: needs-operator needs-plan ready working for-operator risky research quick-build full-plan epic
+workflow-labels: {"needsOperator":"needs-operator","needsPlan":"needs-plan","ready":"ready","working":"working","forOperator":"for-operator"}   # custom names need explicit mapping; if labels: remains, both must agree
+tests: required             # required | best-effort | none
+ui-evidence: playwright     # playwright | none
+worktree-retention: 14d     # how long a parked worktree survives with no session
+skillspector-update: auto   # off | notify | auto
+sync-max-age: 30m           # how stale the local control-room clone may be before a session refreshes it — <n>m or <n>h
+changelog: changesets       # changesets | keep-a-changelog | pubspec+changelog | none
+release: on-request         # on-request | per-merge
+chronicle: on               # on | off
+chronicle-style: plain      # plain | story | witty
+emoji: none                 # none | sparing
+evidence-repo: {{org}}/{{evidence-repo}}   # where UI screenshots and run evidence are pushed
+architect: {{architect}}    # the architecture owner dev-architect speaks to
+operators: {{operators}}    # csv of logins from people.csv who own issues in this group
+
+## Harness policy
+
+harness-policy: intake {{intake-harness}} {{intake-model}} {{intake-effort}} · plan {{plan-harness}} {{plan-model}} {{plan-effort}} · implement {{implement-harness}} {{implement-model}} {{implement-effort}} · review {{review-harness}} {{review-model}} {{review-effort}} · status {{status-harness}} {{status-model}} {{status-effort}} · chronicle {{chronicle-harness}} {{chronicle-model}} {{chronicle-effort}}   # confirm detected supported subscription choices for every stage; placeholders block execution
+
+## Runtime
+
+dispatcher: {{dispatcher-host}}            # the always-on box that turns labels and reactions into headless runs
+ship-environments: preview auto · staging auto · production ask
+design-system: {{design-system}}           # the design layer a repo in this group consumes by default, or `none`
+secrets: {{secret-names}}                  # NAMES of the secrets a repo in this group expects — never values
+gh-floor: 2.97                             # the minimum gh CLI version this group's automation assumes
+stats: inherit                             # inherit | on | off; an org lock needs explicit exact org delegation
+
+## Delegated administration
+
+Admin assignments and group capabilities resolve from org.md, independently of descriptive people.csv rows. A group admin may change only permitted ordinary/delegated defaults and already-authorized members/repositories. Machine settings additionally require previous org fleet.groupDelegations field/range permission; changing enrollment, machine group/repositories, host binding or coordination is org-admin-only. Keep local paths and credentials on the machine. Show the exact diff and verified requester before applying the existing Git delivery rules.

package/skill/vegafactory-setup/assets/control-room/onboarding/dispatcher-box.md.template

@@ -0,0 +1,86 @@
+# Provisioning the dispatcher box for {{org}}/{{repo}}
+
+The always-on Mac mini runs two things: the GitHub Actions runner that executes CI and release, and the `vegafactory dispatch --watch` service that turns labels and 🚀 reactions into headless runs. Every step below is a human's own action on the box or on the org's settings; the skill positions the operator, it never reaches for the credential.
+
+## Accounts
+
+Two macOS accounts, neither an admin of the other:
+
+- `{{runner-user}}` — runs the Actions runner and nothing else.
+- `{{dispatcher-user}}` — runs `vegafactory dispatch`, and owns the `gh`, Claude, and Codex credentials.
+
+The split is the whole point: a CI job runs as `{{runner-user}}` and so **cannot read** the tokens in `{{dispatcher-user}}`'s home — a workflow edited in a pull request gets a repository token and no more. The GitHub App private key is never on this box; it lives in org settings as the secret `VEGAFACTORY_APP_PRIVATE_KEY`.
+
+## Toolchain
+
+Installed system-wide so both accounts see the same versions:
+
+- git and the Xcode command line tools — `xcode-select --install`.
+- bun 1.3.14 — `bun --version` prints exactly `1.3.14`, matching the workspace `packageManager` pin.
+- Node 24 — `node --version` prints a `v24.` line.
+- gh 2.97 or newer — `gh --version`, first line; the board mirror needs that floor.
+- SkillSpector for the dispatcher's review runs — `uv tool install git+https://github.com/NVIDIA/skillspector.git`, then `skillspector --version`.
+
+CI jobs get their own bun and Node from `setup-bun` and `setup-node`, so these copies serve `{{dispatcher-user}}` and stand as the fallback.
+
+## Power and login
+
+- `sudo systemsetup -setcomputersleep Never`
+- `sudo pmset -a sleep 0 disksleep 0 womp 1`
+
+On macOS a per-user LaunchAgent loads only inside that account's GUI session, so exactly one account may rely on auto-login. Give it to `{{runner-user}}`. `{{dispatcher-user}}`'s service is installed by `vegafactory service install` with `RunAtLoad` and `KeepAlive`; its requirement is the reboot drill in `## Verify`, not any particular mechanism.
+
+## Dispatcher ownership and offline recovery
+
+Keep one non-root dispatcher account, `{{dispatcher-user}}`, and one confirmed absolute config path for the host. All service and manual invocations use that path and its single `lockRoot` (default `~/.vegastack/factory/locks`). Inspect the previous root with services stopped before changing it. Separate homes or copied machine configuration do not establish exclusion or enroll another machine.
+
+Local claims have a random token, UID, boot identity and process start identity. Claim mutations use an exclusive directory guard and private owner records. Permission errors, corrupt JSON, symlinks, PID-only legacy files and unverifiable process inspection preserve evidence and refuse. A normal stale lease is replaced under the guard only after proving its process absent or its boot/start identity different. A guard without a valid owner record is never automatically stolen.
+
+For offline recovery, stop all dispatchers under this account, preserve the exact claim and guard, verify the original process and retained runs have stopped, acquire exclusive offline recovery ownership, then re-read and reconcile only the inspected stale token. If stop or ownership is unknown, retain the claim and report the blocker. Never delete worktrees, run records or checkpoints to clear a lock. The two-second guard wait is a contention bound, not an execution deadline.
+
+Shared ownership lives on the explicitly configured existing private state branch. Provisioning that branch and changing enrollment use the separately authorized administration workflow; dispatcher runtime cannot create, reset or repoint it. Machine host binding is a domain-separated digest of the platform OS identity; it detects accidental copied setup, not a malicious cloned OS. Raw platform identifiers and credentials do not belong in the control room.
+
+Before another machine resumes work, verify stop evidence, remotely available checkpoint and original execution identity, current policy/approval, exact owner generation and reconciled effects. A stale heartbeat, unreachable machine or configured guard is insufficient. Independent work can continue while the affected task retains its reservation. Qualification of real macOS/Linux reboot behavior and the selected GitHub conditional provider remains part of the authorized live drill; local fixtures cannot mark it passed.
+
+
+## Grant the group
+
+Org-admin commands, run in an admin's own session (`{{dispatcher-user}}`'s, or any admin's machine) — never as `{{runner-user}}`, whose account holds no `gh` credential by design. The group must exist before the runner registers into it (`config.sh` exits non-zero on an unknown group), and the repository must be granted to it before a job can land. Look the group up first; create it only when the lookup prints no such row:
+
+```sh
+gh api orgs/{{org}}/actions/runner-groups -q '.runner_groups[] | "\(.id) \(.name) \(.visibility)"'
+gh api -X POST orgs/{{org}}/actions/runner-groups -f name={{runner-group}} -f visibility=selected
+gh api -X PUT orgs/{{org}}/actions/runner-groups/<GROUP_ID>/repositories/$(gh api repos/{{org}}/{{repo}} -q .id)
+gh api -X POST orgs/{{org}}/actions/runners/registration-token -q .token   # the registration token for the block below; it expires in an hour
+```
+
+An ungranted group **queues jobs forever with `runner: null` rather than failing** — that is how the 01-09-2026 probe presented, and it is indistinguishable from a slow runner until you read the group. A missing group is the louder failure: registration refuses it on the spot.
+
+## Register the runner
+
+As `{{runner-user}}`, with the registration token from the block above pasted into `RUNNER_TOKEN` — nothing here calls `gh`, because this account is the one that must never hold a credential:
+
+```sh
+set -e
+RUNNER_TOKEN=<paste the registration token here>
+RUNNER_VERSION=$(curl -fsSL https://api.github.com/repos/actions/runner/releases/latest | sed -n 's/.*"tag_name": *"v\([^"]*\)".*/\1/p')
+test -n "$RUNNER_VERSION"
+mkdir -p "$HOME/actions-runner" && cd "$HOME/actions-runner"
+curl -fsSL -o runner.tar.gz \
+  "https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/actions-runner-osx-arm64-${RUNNER_VERSION}.tar.gz"
+tar xzf runner.tar.gz && rm runner.tar.gz
+./config.sh --url "https://github.com/{{org}}" --token "$RUNNER_TOKEN" \
+  --runnergroup {{runner-group}} --name {{runner-name}} --unattended --replace
+./svc.sh install && ./svc.sh start && ./svc.sh status
+```
+
+## Verify
+
+```sh
+gh api orgs/{{org}}/actions/runner-groups/<GROUP_ID>/runners -q '.runners[] | "\(.name) \(.status)"'
+ps -axo user,command | grep '[R]unner.Listener'
+```
+
+The first prints `{{runner-name}} online` — the org endpoint is the one that lists a group's runners, while `repos/{{org}}/{{repo}}/actions/runners` lists repository-level runners. The second prints `{{runner-user}}` and never `{{dispatcher-user}}`.
+
+Then the reboot drill: `sudo reboot`, wait for the box, and run both checks again **without logging anything in by hand**. A box that needs a human at the keyboard after a power cut is not always-on.

package/skill/vegafactory-setup/assets/control-room/onboarding/new-repo.md.template

@@ -0,0 +1,13 @@
+# Onboarding a repo into {{org}}
+
+Run by `vegafactory-setup register <repo>`, then `dev-setup` inside the repo.
+
+1. Confirm the repo's group. `groups/<g>/group.md` is the default set the repo layers on.
+2. Run `dev-setup` in the repo. Every knob the control room already answers is stated as inherited, not asked.
+3. Add the repo's row to `repos.md` — repo, group, board, owner.
+4. Link the board if `boards.md` names one for this group, and add the board-mirror workflow from `templates/`.
+5. Copy `rules/CODEOWNERS` into the repo's `.github/CODEOWNERS`, filled in for its owners.
+6. Create the workflow labels and confirm branch protection on the default branch.
+7. Confirm the repo's `control-room:` knob names this control room and the repo's group.
+
+A step the operator declines is recorded as an unconfirmed line in `org.md`, never quietly skipped.

package/skill/vegafactory-setup/assets/control-room/onboarding/new-teammate.md.template

@@ -0,0 +1,12 @@
+# Onboarding a teammate into {{org}}
+
+Run by `vegafactory-setup onboard <login>`. Every step below is the person's own action on their own machine; the skill positions them and verifies the result, it never reaches for their credentials.
+
+1. `gh auth login` — GitHub CLI, at or above the group's `gh-floor:`.
+2. Install the harnesses the group's `harness-policy:` line names, and sign each one in.
+3. `vegafactory skills add --group dev --global`.
+4. Control-room read access — the operator grants it; confirm with `gh repo view {{org}}/vegafactory-control-room`.
+5. Subscribe to the org's Slack channel through the official GitHub Slack app; notifications are GitHub assignment plus Slack, nothing else.
+6. Add the person's row to `people.csv` — `login,name,role,slack,timezone,groups`.
+
+`role` is recorded only on the operator's word, never inferred from org membership: `lead` gates the people-level statistics views.

package/skill/vegafactory-setup/assets/control-room/org.md.template

@@ -0,0 +1,60 @@
+# {{org}} — org profile
+
+The org's global answers. Everything here applies to everyone, in every group and every repo. Group defaults live in `groups/<g>/group.md`; org locks and administration stay here — layout, precedence, and the read path are the vegafactory-setup skill's `references/control-room.md`.
+
+org: {{org}}
+policy-schema: 2
+
+## Goals
+
+{{goals}}   <!-- one paragraph: what this org is building and for whom -->
+
+## What applies to everyone
+
+- language: {{language}}                  # the language every artifact is written in
+- dates: DD-MM-YYYY                       # the date format in every register, approval, and revision line
+- Nothing ships without the operator's explicit instruction — no push to a default branch, merge, tag, publish, or deploy on green checks, schedules, or standing approvals alone. A repo's gates knob changes how many actions one instruction covers, never whether an instruction is needed.
+- Secrets are named here, never written here. A runbook names `{{secret-name-example}}`; the value lives in the secret store that name points at.
+
+## Statistics policy
+
+Confirm reporting and quality choices for this organization. Ordinary values inherit; mandatory values and exact exceptions are authored in the organization authority object. The legacy stats-override line below remains readable but is not group delegation.
+
+stats: on
+stats-people: off
+stats-override: allowed
+
+## Automation identity
+
+The names of the org's automation identity. Values live in GitHub org settings; nothing here is a secret.
+
+app: VegaFactory   # the public GitHub App every automated write uses; humans still own issues
+app-slug: vegafactory   # GitHub's slug for the App name — confirm it on the App settings page; a bot edit shows the actor <app-slug>[bot]
+app-install: {{installation-id}}   # gh api orgs/{{org}}/installations — filled after the operator installs the App
+app-secrets: variable VEGAFACTORY_APP_ID · secret VEGAFACTORY_APP_PRIVATE_KEY   # names only; the values live in GitHub org settings and nowhere else
+app-permissions: Issues read/write · Projects (organization) read/write · Metadata read · Pull requests read/write · Contents read   # widening any of these is a register line
+
+## Unconfirmed
+
+Lines the operator has not confirmed yet. Each is a question the next run asks again rather than an answer anyone may assume.
+
+- (none)
+
+## Explicit authority
+
+Confirm the org admin login against people.csv and verified requester context before replacing the placeholder. Preserve existing assignments on rerun. The empty locks/delegations below make no hidden house-policy choice; render the organization's confirmed constraints and exact reporting exceptions here.
+
+```vsk-policy
+{
+  "schemaVersion": 2,
+  "locked": {},
+  "delegations": [],
+  "administration": {
+    "orgAdmins": ["{{confirmed-org-admin-login}}"],
+    "groupAdmins": {},
+    "groupAdminCapabilities": {}
+  }
+}
+```
+
+Only org admins appoint/remove admins. Confirm optional group capabilities and machine enrollment through the control-room reference's capability/fleet contract. Render registry entries disabled until qualification, preserving other machines. Local bootstrap coordinates, OS accounts, paths and credentials do not belong in this authority object. Each required unknown field blocks completion; preserve explicit optional declines. Learning settings, if selected, are `learning: normal-work|off` and `learning-adoption: scoped-reversible|propose-only`; verified lessons cannot change approvals, quality/privacy rules or enable native vendor memory.

package/skill/vegafactory-setup/assets/control-room/people.csv.template

@@ -0,0 +1,2 @@
+login,name,role,slack,timezone,groups
+{{login}},{{name}},{{role}},{{slack}},{{timezone}},dev

package/skill/vegafactory-setup/assets/control-room/repos.md.template

@@ -0,0 +1,7 @@
+# Repos
+
+The registry vegafactory-setup writes when a repo is registered. One row per repo; the `group` cell names the `groups/<g>/` whose defaults that repo layers on.
+
+| repo | group | board | owner |
+|---|---|---|---|
+| {{org}}/{{repo}} | dev | {{board}} | {{owner}} |

package/skill/vegafactory-setup/assets/control-room/rules/CODEOWNERS.template

@@ -0,0 +1,6 @@
+# Org CODEOWNERS pattern — copied into each repo's .github/CODEOWNERS at registration.
+# Owners are GitHub logins or teams from people.csv; every path needs one owner who can approve.
+
+*                       @{{org}}/{{default-team}}
+/.vegastack/            @{{architect}}
+/.github/workflows/     @{{architect}}

package/skill/vegafactory-setup/assets/control-room/rules/README.md.template

@@ -0,0 +1,9 @@
+# Org rules
+
+Rules every repo in {{org}} inherits. A repo may add to these; it never silently weakens one.
+
+- `CODEOWNERS` — the org's ownership pattern, copied into each repo's `.github/CODEOWNERS` at registration.
+- `review-known-patterns.md` — review findings the org has dismissed, each with its mandatory "Still flag if:" clause. A repo's own `.vegastack/review-known-patterns.md` concatenates with this one.
+- `security.md` — the org-wide security rules a review's security axis reads before a repo's own.
+
+Add a file here only when the rule genuinely applies org-wide; a rule that fits one repo belongs in that repo.

package/skill/vegafactory-setup/assets/control-room/rules/stats-privacy.md.template

@@ -0,0 +1,44 @@
+# Statistics — what stays local and what is shared
+
+This rule applies to repositories registered in {{org}}. Confirm the organization's reporting policy before enabling exports. VegaStack's selected profile is mandatory private attributed reporting; other organizations choose their own confirmed profile. Repository exceptions require the exact organization delegation accepted by the policy validator. A machine preference or a descriptive `lead` role grants no exception or administration authority.
+
+## Reporting modes and recipients
+
+`stats-export: attributed` permits the closed task/person reporting schema below. `non-attributed` removes execution attribution and suppresses activity and rework snapshots. `off` suppresses every variant, including queued execution reports. `stats: off` also suppresses export. Unknown, stale or unconfirmed policy refuses export. Local recovery remains independent of these reporting modes.
+
+The recipients are readers of the confirmed private control-room Git repository, including existing clones. Dashboard and CLI person views apply current organization/group/person scope before aggregation, but those filters do not restrict direct Git access. Repository/day/model combinations may permit inference; non-attributed is not a promise of anonymity. Git commit metadata uses a neutral transport identity. GitHub actors, access logs, existing Git history and historical copies remain separately visible to their platform/repository readers.
+
+## The exact shared schema
+
+All reports have `schemaVersion: 2`, `metricVersion: 2`, `recordKind`, a random opaque `eventId`, a validated `destination` and `utcDay`. Destination contains exactly `host`, `org`, `repo` and `controlRoom` and binds one registered code repository to its confirmed recipient. Unknown fields or variants refuse; nested objects are closed too.
+
+- **Execution:** `stage`, `harness`, `model`, `mode`, `outcome`, `durationSeconds`, `turns`, `toolCalls`, `subagents`, `tokensIn`, `tokensOut`, `cacheReadTokens`, `cacheWriteTokens`, `costUsd`, `coverage`, `skills`. Only executions count as runs or enter execution usage/cost denominators. The six configured stages are intake, plan, implement, review, status and chronicle; corrections use implement. Outcomes are succeeded, failed, spawn-failed, timed-out, cancelled, interrupted and termination-unconfirmed.
+- **Attributed execution extension:** exactly `taskRef`, `taskOwner`, `agentAccountOwner`, `executionRef`, `attempt`, `startedAt`, `endedAt`, `operatorMinutes`, `apiEquivalentUsd`, `estimateBasis`. Unlinked execution has null taskRef; unknown owners stay null. A private persisted random executionRef is reused across retries, never derived from a local run/session/account identifier. Task owner and account owner are different dimensions.
+- **Activity, attributed only:** exactly `taskRef`, `taskOwner`, `agentAccountOwner`, `activity`, in addition to the common fields. Activity contains `taskRef`, `activityId`, `kind`, `occurredAt`, `deliveryRef`, `sourceRef`. Kinds are implemented, merged, released, review, fix and handback. Repeated `(taskRef, activityId)` observations count once across transport UUIDs. Activities do not add a run or duplicate usage.
+- **Rework snapshot, attributed only:** exactly `taskRef`, `taskOwner`, `reworkSnapshot`, in addition to common fields. The snapshot contains `taskRef`, `asOf`, `sourceRef`, `counterEpoch`, `reviewRounds`, `fixRounds`, `handbacks`, `historyComplete`, `historyStart`. Counters are authoritative as-of values, never additive activity. Counter epoch is the approved-scope SHA-256 plus `:v2`. A difference needs complete boundary history, the same epoch and monotonic counters. Lifetime is the latest authoritative total and its date; expiry makes it unavailable until actual authorized source evidence is reread. Do not redate snapshots to retain identity indefinitely.
+
+TaskRef contains exactly `repo`, positive `issue`, and nullable `taskId`. DeliveryRef contains exactly `repo`, `pr`, `prNodeId`, `acceptedParentHead`, nullable `mergedCommit`. Reporting sourceRef contains exactly `repo`, nullable `issue`, `commentId`, `nodeId`, `bodySha256`; at least one evidence identity is required. Inner and outer task references must agree, and all repository references must match the destination. These are typed GitHub IDs/hashes, not raw evidence text, arbitrary URLs or private recovery pointers.
+
+Measurements are finite nonnegative numbers or explicit null; counters are safe nonnegative integers or null. Unknown is different from zero. Coverage contains exactly the nine execution measurement keys, each with nonnegative integer `known` and `unknown` observation counts. Skills contain at most128 exact `{name,trigger,harness}` entries; triggers are model, typed or mention. Price estimate basis contains exactly `sourceUrl`, `checkedAt`, `priceDigest`, `currency`, `model` and accompanies the API-equivalent estimate. `costUsd` means reported charge. Organization subscription fees are separate verified policy/account facts, never an invented per-task charge.
+
+## Excluded from reports and basic diagnostics
+
+Hostnames, local run/session/capture IDs, filesystem/worktree paths, credentials, prompts, conversations, file contents, raw tool input/output, argv, stdout/stderr and freeform diagnostic text never enter reports. The producer may reduce structured execution output to counters transiently; it does not persist raw output as diagnostics. Legacy hook capture does not read a caller-supplied transcript path by default.
+
+Built-in Claude Code and Codex memory is excluded: no reads, imports, writes, generation, migration or fallback. Vendor hooks are integration points; VegaFactory owns its separately verified lesson records and selection. Existing vendor memory stores are not cleanup candidates.
+
+Private recovery uses the existing closed recovery/acceptance/effect schemas. Original execution/account references, canonical approval source references and nullable recordBinding stay inside those typed private envelopes. They never become reporting fields through object copying. Hashes do not authorize exporting raw source, approval quotes, credentials or logs. Source checkpoints have their code repository's visibility, including public branches; a private recovery pointer does not make public source confidential.
+
+## Delivery, local diagnostics and retention
+
+`stats privacy --json` reports current mode, allowed fields, recipients, pending counts/bytes/age, diagnostic bytes and real disk pressure. `stats export --output <file>` creates a new private scoped file and refuses an existing destination. It applies current policy and read scope; it does not acknowledge remote delivery or upgrade historical non-attributed reports.
+
+Basic local diagnostic directories use0700 and files0600. Their closed records contain event/time, stable reason codes and observed exits; raw log or transcript capture is outside this profile. Durable terminal state and pending capture remain visible after storage failure.
+
+`stats cleanup --dry-run` previews the same local selector used by `--apply` and automatic maintenance. Inactive basic logs expire after14days; acknowledged active report payloads expire after12calendar months from original report observation, with month-end/leap-year clamping. Every candidate is enumerated again under the existing owned guard before removal. Active, undelivered, ambiguous, quarantined, recovery-dependent or unknown references are held. Capture mappings, delivery receipts, attempted hashes, minimal dedup identity, active authority evidence, source checkpoints, branches, worktrees, code, credentials and native memory are not expired by this selector.
+
+Shared active-file removal uses the existing dedicated Git writer, a fresh validated destination/policy, the original acknowledged bytes and a private durable removal intent. Only actual remote absent-path readback permits local payload retirement. Its private removal receipt is separate from the original delivery receipt; deletion never becomes a new reporting acknowledgment. Missing authority, active references, changed remote bytes and unconfirmed pushes remain held/pending. Cleanup does not erase Git history, clones or platform metadata.
+
+Delivery reconciliation checks historical attempted bytes before applying stricter current policy. Proven previous delivery keeps its real receipt and original policy digest; only truly undelivered bytes can be serialized again. A suppressed event receives a private policy-suppressed disposition, never a fabricated remote acknowledgment. Legacy migration previews exact original bytes, requires explicit apply and destination mapping, and preserves original files privately. It never retroactively attributes a historical non-attributed report.
+
+Real filesystem free space below1GiB pauses new launches; capacity resumes at2GiB. A failed probe is unavailable and refuses launch. Pending spool at1GiB warns but does not independently stop work while capacity is safe. Running owned processes use the existing bounded stop protocol on pressure. This reserves shutdown/capture headroom; it cannot prevent another process from exhausting the disk. No automatic code/worktree/credential deletion is authorized to create space.

package/skill/vegafactory-setup/assets/control-room/templates/README.md.template

@@ -0,0 +1,9 @@
+# Templates
+
+Snippets the org prefers over a skill's own defaults. dev-setup reads this directory before falling back to what it ships.
+
+- `hooks/` — hook wiring snippets per harness (ship guard, SessionStart context, Stop heartbeat, decision nudge).
+- `factory-board.yml` — the board-mirror workflow a registered repo receives.
+- `dev-md/` — dev.md section overrides: a file named after a section replaces that section's default text for every repo in the org.
+
+A template here is a default, not a law: a repo may hand-edit what it received, and the precedence rule says the hand edit wins.

package/skill/vegafactory-setup/references/control-room.md

@@ -0,0 +1,149 @@
+# The control room
+
+The org's `vegafactory-control-room` repository: what each file holds, which file wins when two disagree, and how a run reads it. `vegafactory-setup` seeds every file here from `assets/control-room/*.template`; `dev-setup` reads them before it asks a repo anything.
+
+## Layout
+
+```
+org.md                       global only: org name, goals, what applies to everyone (questionnaire)
+people.csv                   login,name,role,slack,timezone,groups
+decisions.md                 org-level register (same line format as repos)
+groups/<g>/group.md          department defaults: one line per knob a group can decide for a repo dev.md
+groups/<g>/people.csv        group-level people (adds to / overrides org)
+groups/<g>/decisions.md      group-level register
+repos.md                     registry: repo, group, board, owner (maintained by this skill)
+boards.md                    project boards and repo -> board mapping
+rules/                       org-wide review known-patterns, security rules, CODEOWNERS pattern
+onboarding/new-repo.md       checklist run by vegafactory-setup, then dev-setup
+onboarding/new-teammate.md   gh auth, harness install, skills install, control-room access, Slack
+templates/                   hook wiring snippets, board workflow, dev.md section overrides
+stats/<owner>__<name>/<MON-YYYY>/<hostname>.jsonl   one record per run or session, written by automation
+stats/<owner>__<name>/<MON-YYYY>.summary.json       regenerated per repo per month
+stats/<owner>__<name>/<MON-YYYY>.timeline.json      regenerated: the month's issue label timelines, read through gh at rollup
+stats/org/<MON-YYYY>.summary.json                   regenerated across every repo
+stats/org/<MON-YYYY>.skills.json                    regenerated: invocations per skill
+```
+
+`stats/` is the one tree automation writes, and the shape is the reason it can. One file per repo, per month, per **machine** means two machines never touch the same file, so a concurrent push is a non-fast-forward — solved by `pull --rebase` and a retry — and never a content conflict needing a human. The repo segment is `<owner>__<name>` so a path stays two levels deep and a repo name can never be mistaken for a month directory. The three summaries are **regenerated**, never appended: a summary that accumulated would drift the first time a record arrived late from a machine that was offline. Records are counts and identifiers only — never prompt text, assistant text, tool arguments, or file contents — and `rules/stats-privacy.md` is where that promise is written down for everyone the org onboards.
+
+`groups/dev/` is the only department seeded today; another department is a new `groups/<g>/` with the same three files.
+
+## Effective policy
+
+Resolve Markdown through dev-setup's `scripts/effective-policy.mjs`. Ordinary explicit values inherit org → group → repo; each harness stage inherits individually. Organization locks require exact organization delegation before a group or repo can change them. Repository `dispatch: local` remains an explicit local opt-in. Repository commands and Ship/Environments lines stay repository facts, not inherited executable instructions. Decision registers concatenate; a lesson or register entry grants no authority.
+
+Use `policy-schema: 2` and one `vsk-policy` fenced JSON object in `org.md`. Its `schemaVersion` is2, with `locked` and `delegations` as shown in the org template. Lockable keys are `stats`, `stats-export`, `gates`, `tests`, `review`, `provider-mode`, `learning`, `learning-adoption`. A delegation names exact groups, canonical repositories and allowed values; wildcards and delegation chains refuse. Attributed reporting requires explicit org authorization. Unknown extension fields remain inert; duplicate keys, bad known values or an unknown schema refuse rather than overwrite.
+
+Legacy version1 ordinary knobs remain readable. An org `stats-override: locked` locks its explicit `stats` value; without that value migration refuses. A group's `stats-override: allowed` is not org delegation. Inspect old/effective/proposed values and sources, retain original files, and approve the concrete authority-changing diff before migration. Other organizations confirm their own quality, reporting and supported subscription harness choices; templates do not select models for them.
+
+## What each file may and may not carry
+
+- `org.md` holds organization policy and stage defaults: the org name, the goals in one paragraph, and what applies to everyone — language, the date format, the "nothing ships without the operator's instruction" stance, and the statistics policy lines `stats:`, `stats-people:`, `stats-override:`. Groups may override ordinary org defaults; mandatory constraints and all administration assignments remain org-owned.
+- `org.md`'s `## Automation identity` block records the org's GitHub App by name, five lines and no more: `app:` the App name, `app-slug:` the slug the actor string and the install URL both follow, `app-install:` the installation id from `gh api orgs/<org>/installations`, `app-secrets:` the two secret **names**, and `app-permissions:` the granted set. The permission table, the mint recipe, rotation and the kill switch live in dev-setup's `references/github-app.md` and are never restated here.
+- `groups/<g>/group.md` carries one default for every knob a group can decide for a `.vegastack/dev.md`, in the same line shape dev.md uses (`harness-policy:` is one line, never six `harness:` lines — the dispatcher reads both files with one parser), so a repo that answers nothing else still gets a complete profile; per-repo facts (`repo:`, `skill-scan:`, `board:`, `control-room:`, detected types and fields) have no group default.
+- `repos.md` and `boards.md` are registries, written when a repo is registered or a board is linked, never hand-curated in parallel with them.
+- **Nothing secret goes in any file — names of secrets only.** A control room is readable by everyone the org onboards, and a name (`NPM_TOKEN`, `CLOUDFLARE_API_TOKEN`) is all a runbook needs; the value lives in the secret store the name points at.
+- Preserve a confirmed optional decline as declined. Keep required unknown fields explicit and resume only those questions; show contradictions with a concrete example before writing. Agent-guided setup prepares a complete scoped diff, preserves unrelated fields and reads back the delivered files.
+
+## The read path
+
+Read a validated immutable control-room snapshot and retain its full source commit. A configured room whose mandatory policy is unavailable, malformed or expired blocks new tasks and external actions. The selected maximum age is an organization choice; a7200-second policy allows age7199 and refuses age7200. Failed fetches never renew validation time. An already-running job may finish reversible local work under pinned policy; pending external delivery revalidates authority. Optional knowledge may remain readable with a stale label and no privilege.
+
+With no room configured, explicit local repository policy still works. Guided first setup may prepare missing answers while access is unavailable, but does not claim unattended readiness. Bootstrap records the verified room repository/remote/branch and local config path; local coordinates never appoint admins or enroll machines. Snapshot persistence, verified same-commit refresh and restore are the sync owner's contract.
+
+## `people.csv`
+
+The header line is exactly:
+
+```
+login,name,role,slack,timezone,groups
+```
+
+`login` is the GitHub username and the row's identity. A row in `groups/<g>/people.csv` with a `login` already present at org level **overrides** that row for that group; a `login` not present at org level **adds** a person to the group. `groups` on an org row is the comma-free list of the groups the person belongs to (use `;` between group names, since the file is comma-separated).
+
+`role` is descriptive and recorded only on the operator's word. Neither a `lead` string nor a group row replacing an org row supplies admin authority. GitHub login keys are resolved against verified requester context and the current org admin map; execution-account identity stays separate.
+
+## Boards
+
+A board is created, field-configured and linked by the operator, never by an agent: **the operator runs these** commands, in this order — every one of them needs the `project` scope, which lives on a human token and never on an agent's:
+
+1. `gh auth refresh -s project` — adds the scope to the operator's own `gh` login; without it every command below 403s.
+2. `gh project create --owner <org> --title "<title>"` — note the number it prints; that number is the `board:` knob and the `number` column of `boards.md`.
+3. `gh project field-list <n> --owner <org> --format json -q '.fields[] | select(.name=="Status") | .id'` — the id of the default Status field.
+4. ``gh project field-delete --id FIELD_ID`` — use the field ID from step3; the default Status options are not the workflow's states.
+5. `gh project field-create <n> --owner <org> --name Status --data-type SINGLE_SELECT --single-select-options "needs-operator,needs-plan,ready,working,for-operator,Done"` — the five state labels plus Done, in that order.
+6. `gh project link <n> --owner <org> --repo <owner/repo>` — one call per repo that mirrors onto this board.
+
+Then, in the project's Workflows UI, switch on the four built-in automations, which have no CLI: auto-add `is:issue is:open`, item closed → Done, PR merged → Done, and auto-archive after 14 days.
+
+The mirror itself is one way. `.github/workflows/factory-board.yml` (dev-setup's `assets/factory-board.yml.template`) writes Status from the issue's single state label with the App token; nothing reads the board back, so a card dragged by hand is cosmetic until the next label change.
+
+## Registers
+
+`decisions.md` at every level uses the register line format defined in dev-setup's `references/conventions.md`, installed beside this file — one dated line per decision, append-only, no other metadata. This file does not restate the format; read it there.
+
+## Administration and people visibility
+
+The org policy object may carry `administration:{orgAdmins:string[],groupAdmins:Record<string,string[]>,groupAdminCapabilities:Record<string,GroupCapability[]>}`. At least one confirmed org admin is required when configured. Missing legacy administration remains unconfigured until reviewed migration; do not promote legacy leads. `GroupCapability` is `group.members.manage`, `group.repos.manage`, `group.defaults.manage` or `group.people.read`. Only org admins appoint/remove admins. Group admins act only inside assigned groups, on preauthorized repo registrations and permitted ordinary/delegated defaults. Membership edits do not grant GitHub access, operator status or shipping permission.
+
+For chat requests, load the previous trusted config and verified human requester, prepare the exact target/diff, then use `authorizeAdministration` before applying configured Git review/delivery rules. A bot can execute an evidenced instruction but cannot supply the human grant. Refuse chat/URL identity claims, self-grants, cross-group targets, last-admin removal and stale authority. Dashboard remains read-only.
+
+`resolveAdministration({orgLayer,peopleByScope,repoGroups})` reads only org assignments; `authorizeAdministration({actor,action,target,administration,policy})` returns allowed/reason. `actor` is `{login,verified:true}` from trusted GitHub context, optionally with separate execution-account evidence. Targets name the exact org/group/repo; proposed settings are `target.changes`, and admin replacement is `target.proposedAdministration`. These APIs are cooperative trusted-host checks, not a new authentication server.
+
+`resolvePeopleReadScope({viewer,subject,requestedRepos,administration,policy,repoGroups})` returns allowedRepos/subject/refusal. Org admins read registered org repos; group admins need `group.people.read` in their assigned groups; people retain their own-data view. Filter records before totals, drill-downs or export. An empty allowedRepos array means no records. One person working in two groups does not let a group admin see the other group's records. Query filters may narrow but never expand scope. Control-room Git readers can still read committed report files; application scopes do not promise per-group storage secrecy.
+
+## Registered machines
+
+The org policy may carry `fleet:{schemaVersion:1,coordination,defaults,groupDefaults,groupDelegations,machines}`. Coordination names the verified private state repository node ID, canonical repository, branch, rootCommit and installation UUID. It is separate from the policy branch and source task branches. Organization admins own coordination identity and enrollment; setup preserves existing registrations and initially enrolls a machine disabled.
+
+`FleetDefaults={pollSeconds,maxRuns,childConcurrent,checkpoints,recovery}`. Suggested selected defaults are120/1/3/task-branch/verified-transfer. Poll seconds must be an integer30–3600, maxRuns a positive safe integer, childConcurrent1–16 (also bounded by the installation's qualified child ceiling), checkpoints `off|task-branch`, recovery `original-host|verified-transfer`. Resolve org defaults → group defaults → explicit machine overrides. Polling is discovery timing; policy freshness and task duration are separate. Ordinary tasks have no cumulative elapsed-time limit.
+
+Each machines key matches `[a-z0-9][a-z0-9-]{0,63}` and contains `{installationId,hostBindingDigest,executionLogin,group,repositories,enabled,overrides}`. Installation IDs are generated UUIDs, host bindings are digests, executionLogin is a confirmed GitHub login, and repositories are canonical registrations backed by verified GitHub node IDs. Credentials, raw host identifiers, shell commands and local paths stay outside this schema. A copied local config cannot match another host's binding or silently enroll it.
+
+`groupDelegations` maps each group to `{fields,maxRunsMax?,childConcurrentMax?,pollSecondsMin?,pollSecondsMax?,checkpointValues?,recoveryValues?}`. Fields name permitted FleetDefaults keys; numeric limits remain inside schema bounds and enum subsets are valid/nonempty. No entry or field permission means org-admin-only. Group admins also need `group.defaults.manage`, and every edit uses the previous trusted delegation/current machine group. Changing repo/group scope, binding, enrollment, coordination or delegation is org-admin-only. Safety predicates cannot be delegated away.
+
+`resolveMachinePolicy({policy,machineId,installationId,hostBindingDigest,executionLogin})` returns ok/machine/blocks. The effective machine includes coordination, resolved defaults, allowedRepositories, repositoryIds and policyDigest. Allowed work intersects registration, current policy/approval and verified GitHub access. A shared/enrolled machine never falls back to local-only locks on failure; no-fleet installations retain an explicit legacy mode.
+
+Recovery `verified-transfer` still requires proof the original execution stopped, a verified checkpoint and task/scope/base/head, reconciled effects, safe shared ownership transfer and the same qualified harness/model/account/effort. A stale heartbeat is not stop proof. Task-branch checkpoints require the approved exact repo/ref/file scope and durable checked delivery intent; they grant no merge/release or arbitrary write authority. Runtime ownership/checkpoint machinery and actual service qualification are separate consumers of these settings.
+
+## Resolver input and source contract
+
+`resolvePolicy({org,group,repo,identity,freshness})` returns `{ok,policy,blocks}`; all three layers are Markdown strings. `identity` supplies `org`, canonical `repo`, `group`, full validated `roomSha`, optional per-layer `paths`, and confirmed `peopleByScope`, `repoGroups`, `repositoryIds`. People scopes map `org`/group IDs to `{login,groups:[]}` rows; repoGroups maps canonical repository to group; repositoryIds maps it to verified GitHub node ID. These are verified registry inputs, not fields a chat requester supplies.
+
+`freshness` supplies configured/validatedAt/now/maxAgeSeconds. Effective schema2 includes resolved values, per-key scope/path/revision diagnostics, administration, fleet and policyDigest. Revisions are full Git SHAs for validated room sources or SHA256 of exact local text. The digest sorts resolved values/sources and authority/registry data and excludes observation time. Consumers must inspect `ok` or refusal before any effect: an effective locked value is useful diagnostic data even when an attempted override is denied.
+
+Validated snapshot readers consume `factory.json` at `controlRooms[org].snapshots[canonicalCodeRepo]`. Each value keeps `{schemaVersion:2,org,group,repository,origin,sourceCommit,policyDigest,validatedAt,contentPath}`; repository is the control room, while the map key binds the code repo. Its digest is the full resolved policy for that repo/profile/group, with canonical relative paths. The reader checks exact origin/HEAD and clean content, reads regular blobs from the recorded Git commit, then recomputes the digest. Changed local policy needs renewed validation. The optional `repository-id` column in repos.md supplies confirmed GitHub node IDs required by fleet registrations. The snapshot owner verifies those IDs during publication; this parser does not turn authored strings into verified network identity.
+
+## Local settings, refresh and recovery
+
+`factory.json` is the single machine-local store. Its supported wire shape is `{schemaVersion:2,revision,controlRooms:{[org]:...},...extensions}`. The transaction API's `orgs` is a view of `controlRooms`, never a second file/map; an existing extension named `orgs` stays inert. Persist confirmed setup answers, optional declines, bootstrap and verified local checkout registrations through `updateSettings(root,mutate)` before attempting sync. `root` contains `factory.json`; services using a different absolute config path call `updateSettingsAtPath(path,mutate)` and pass that same path to readers and refresh. Neither API enrolls the machine or approves Git delivery.
+
+Every mutation rereads under the canonical path's exclusive guard and increments revision. Schema1 converts only after successful mutation/validation, retaining its original bytes in `factory.json.schema1.bak`. Unknown versions, unreadable files and unsafe symlink paths refuse unchanged. An interrupted `.guard` directory is never stolen because its owner appears old; stop participating writers, verify their termination and inspect the owner record before offline recovery. A text editor bypassing this transaction cannot receive its concurrent lost-update guarantee.
+
+`vegafactory sync --dry-run --json` describes refresh/migration without fetching or writing. A real sync verifies the configured connection, fetches a managed candidate (30 seconds per fetch, at most two attempts, 90 seconds for candidate work), validates every configured code-repository profile through the canonical resolver, then publishes all bindings together. Same-commit refresh renews `validatedAt` only after successful fetch and validation. A failed attempt retains last-good source identity and settings. Unconfigured first setup must complete a confirmed code-repository profile before it can publish authority; answers already persisted remain resumable.
+
+Policy reader content lives under the settings directory's `policy-snapshots/<org>/snapshot-*`. The separate `controlRooms[org].path` is the telemetry writer checkout, initialized once from validated content; existing operator edits and unpushed commits are never reset or repointed. Do not write telemetry into `contentPath`. Canonical GitHub owner/name and repository node ID must match the verified connection; a rename needs explicit verified reconciliation. Enrolled machines additionally match the current host binding, installation, account, group and registry scope. Host bindings come from the canonical machine-identity reader, using its versioned platform-separated digest of the validated machine identifier; account identity is checked separately. Copying factory.json to another host is not enrollment.
+
+`status --json` exposes each repo's validation state, full source SHA, policy digest, timestamp, age and refusal. Machine configuration displayed by status is diagnostic, not verified execution-account authority. Dashboard policy reads the same manifest and local profiles; legacy fetch time or directory mtime cannot manufacture freshness. Optional old knowledge carries source/date and a warning; it grants no authority. At the selected two-hour bound, age7199 seconds is fresh and age7200 is stale. Dispatcher polling remains distinct from this bound; running reversible work retains its pinned rules and external actions revalidate.
+
+The source APIs `inspectSnapshots({target,now})` and `restoreSnapshot({target,index,now,apply?})` verify supported schema, exact source/content identity and every backup's per-repo digest. Restore defaults to dry-run. Explicit `apply:true` selects inactive recovery content with its original timestamp and empties the authoritative snapshot map. A successful real sync is required before authority resumes, including when the selected backup was recently validated. Two prior valid pointer sets are retained; immutable directories are not automatically removed, so older active-run pins remain available. Failed candidate directories may remain for inspection.
+
+Until a packaged recovery entrypoint is approved and integrated, these are source-only recovery APIs, not installed CLI subcommands. From the source checkout, inspect the exact configured path without writes:
+
+```sh
+VF_SETTINGS_PATH=/absolute/path/factory.json VF_REPO_PATH=/absolute/path/code-repo bun --eval '
+import {readFile} from "node:fs/promises";
+import {homedir} from "node:os";
+import {join} from "node:path";
+import {readSettingsFile} from "./packages/cli/src/control-room.ts";
+import {resolveTarget,inspectSnapshots} from "./packages/cli/src/sync.ts";
+const settingsPath=process.env.VF_SETTINGS_PATH, repoPath=process.env.VF_REPO_PATH;
+const config=await readSettingsFile(settingsPath);
+const devMdText=await readFile(join(repoPath,".vegastack/dev.md"),"utf8");
+const target=resolveTarget({config,devMdText,home:homedir(),settingsPath,repoPath});
+if(!target) throw new Error("No configured control room");
+console.log(JSON.stringify(await inspectSnapshots({target,now:Date.now()}),null,2));
+'
+```
+
+For a reviewed restoration, use the same resolved target and call `restoreSnapshot({target,index:0,now:Date.now()})` first. Inspect that exact result before explicitly adding `apply:true`; never alter `validatedAt` to bypass the required fresh sync. Packaged recovery availability and final behavioral/provider qualification remain open integration gates.

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

@@ -0,0 +1,113 @@
+# Workflow conventions
+
+Artifact authority.
+
+Defaults resolve repo, group, then org; locks require explicit org delegation. Repository dispatch/commands never inherit; registers concatenate. Policy/migration uses dev-setup's `scripts/effective-policy.mjs` and vegafactory-setup's control-room reference.
+
+## Comment metadata markers
+
+Comments open:
+
+```markdown
+<!-- vsk:v1 type=<type> rev=<n> [key=value ...] -->
+## <Human title> (v<n>)
+```
+
+| type | required keys | instances |
+|---|---|---|
+| `approval` | `scope=<brief\|brief+plan\|plan\|consolidated\|none>` and schema-v2 JSON | one per approval event |
+| `questions` | `rev` | one per ask round; earlier rounds stay as record (dev-setup's `references/ask-route.md`) |
+| `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 `(v<n>)` start at 1 only on brief, plan, questions and evidence; other types have neither. Locate by marker, never heading/legacy fallback.
+
+## Operator identity
+
+Use parenthesized GitHub usernames:
+
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
+
+Approval.mjs’s publisher/relay contract lets current-policy provider-envelope publishers attest listed operators’ session words. Other recorders may only relay independently read identical operator-published scoped grants within complete authority history, without lifecycle mutations. Relays inherit source authority/lifecycle; account attestation cannot authenticate off-platform speech.
+
+## Scoped approval records
+
+Use only dev-implement’s `scripts/lib/approval.mjs` and follow its contract. Refresh current policy and complete GitHub histories. `ArtifactRef={repo,issue,kind,artifactId,rev,digest}` binds brief issue-node or unique plan/protocol comment-node identity, revision and canonical SHA-256.
+
+Post exactly one approval comment: matching scope marker, then one fenced JSON `ApprovalRecord={schemaVersion:2,id,operator,scope,source:{kind,ref,quote},artifacts,supersedes,revokes}`. Exclude outer Markdown fences, future alternatives and unresolved source locators; validate the whole body with approval.mjs's `parseApproval`. Source kind is `session` or `github-comment`, with inspectable words. Reuse valid current grants/relays; avoid counterfactual plan-only or redundant approvals. Scope is `brief`, `plan` or `brief+plan`; planning requires brief, implementation both, research execution also its protocol. Empty-artifact revocations remove exact earlier IDs. Conflicts explicitly supersede; newest never wins.
+
+Preserve legacy comments. Without writes, inventory refusals/current digests and request reconfirmation. For duplicate canonical plans preserve both identities/bodies and request record-preserving reconciliation; never delete to clear ambiguity. Follow approval.mjs’s exact correction schema, operator-publisher and target checks. Only malformed or demonstrably invalid-source targets qualify, never valid authority or unavailable/inconsistent facts. Resolve source facts first; corrections grant no scope. Exact child checkpoint actions bind one selected code child's branch/ref/base/tasks/files; other actions never substitute.
+
+Consolidated parent events bind frozen manifests, canonical artifacts and exact task/action subsets. Use inline UTF-8 or immutable repository/commit/path plus blob hash, never local paths. Canonical `approvalBindings` authorize; requested `recordBinding` only audits. Follow approval.mjs’s preparation/research/recovery provenance, receipts, adapters, counted attempts and fresh admission; retain immutable history and unverified legacy records. Keep checkpoint/private/live/shipping gates separate.
+
+Canonicalization normalizes CRLF; its only exceptions are structural plan checkboxes and one validated JSON `{tasks:[{id,evidenceUrls}]}` block between `<!-- vsk:progress:start -->` / `<!-- vsk:progress:end -->`. IDs must exist; URLs are HTTP(S); unknown fields/duplicates refuse. Stable task IDs/order, interfaces, actions, revisions and all other bytes remain scope. Brief/protocol bodies have no mutable fields; fenced examples stay immutable and grant no authority.
+
+## Revision markers
+
+Scope edits increment marker/heading revisions and append `Revisions: v2 — DD-MM-YYYY: <change>, per (<username>) correction`; preserve earlier lines and obtain fresh approval. Validated progress changes need neither.
+
+## Scope classes
+
+Intake explains scope; operator overrides:
+
+- **`research`** — inquiry; throwaway code allowed, never merged. No branch/PR/changelog; evidence comment contains findings and recommendation.
+- **`quick-build`** — existing flow: draft brief+plan together, approve both, then `ready`.
+- **`full-plan`** — new ground: approve brief, `needs-plan`, separate grounded planning session, `needs-operator`, approve plan, `ready`. Split multiple deliverables into independently classified epic children.
+
+Scope ratchet: `dev-plan`.
+
+## Labels
+
+One state; flips set assignees (colors: dev-setup):
+
+| label | meaning | assignee |
+|---|---|---|
+| `needs-operator` | question, brief or plan approval, proposal | the operator |
+| `needs-plan` | brief approved; awaiting planning (full-plan only) | the operator |
+| `ready` | approved — an agent may start | nobody |
+| `working` | claimed; ledger shows live progress | the runner |
+| `for-operator` | done — evidence posted, awaiting operator review | the operator |
+
+Modifiers coexist with state: `risky` · scope `research` / `quick-build` / `full-plan` · `epic` (map parents without a native Epic type). Boards mirror states one-way.
+
+## Titles, types, hierarchy
+
+- **Title prefixes:** issues, branches and PRs use dev.md's `branch:` types plus `research:`; PR title = issue title.
+- **Native issue types/fields:** Feature (feat) · Bug (fix) · Task (docs/chore/refactor/research) · Epic for parents (else label); intake sets Priority/Effort. Scope classes stay labels.
+- **Hierarchy:** epic parent = map only (Destination · Decisions so far · Not clear yet · Out of scope), with native child sub-issues. Issues are work units (brief, approvals, branch, PR, evidence); tasks are checkboxes **only in the plan comment**. Blockers use dependencies; phases use milestones. Only non-epic issues get `ready`.
+
+## The ledger
+
+One implementation ledger:
+
+```markdown
+<!-- vsk:v1 type=ledger branch=<branch> -->
+## Ledger — <branch>
+- <issue>-T<N>: complete (commits <base7>..<head7>[, review clean | K parked])
+- <issue>-T<N>: fix round <R>/3 (<X> addressed, <Y> open — <one-liners>; commits <a>..<b>)
+- Ruling: <what> — <why> — cost if wrong: <cost>
+- <issue>-T<N>: parked — <finding> — Ruling: <why the code stands>
+- Deferred minor: <one-liner>
+```
+
+
+**Resume protocol:** brief → plan comment → ledger → `git log`; then reconcile task IDs, canonical approval history, edited authority, source/evidence, ownership and delivery effects. Preserve completed work/provenance; stale heartbeat is not stop proof. Preparation never implies issue completion. Dev-implement's ledger reference owns recovery detail.
+
+## `.vegastack/` workspaces
+
+Drafts/reports: `.vegastack/.tmp/<issue-number>-<title-slug>/` (pre-issue: `intake-<slug>`), self-ignored by a `.gitignore` containing `*`. Branch checkouts: root-ignored `.vegastack/.worktrees/<issue-number>-<title-slug>/`; main stays on its default branch. Keep both outside `.git/`. Subagents save full reports and return short status. `<path-to-this-skill>` means SKILL.md’s directory.
+
+## Verification gate
+
+Prove claims with fresh command output and exit codes; report failures and skips. Delegate only substantial independent parallel work, never your own verification; keep spawn counts low. Guards block machine-verifiable failures (exit 2); heuristics warn. Guards contain no AI inference; unverifiable state fails closed.
+
+## Review bindings
+
+One fenced JSON each: `{"reviewBinding":{sha,baseSha,scopeDigest,verdict,findings:[{id,status}]}}` in review; `{"adjudication":{sha,reviewCommentId,operator,source:{kind,ref,quote},findings:[{id,disposition,reason}]}}` in evidence. Use full commit IDs and canonical-plan scopeDigest; status=open/resolved; disposition=accept-risk. Every open finding requires same-review operator acceptance. dev-ship’s README defines source checks. No prose exceptions.
+
+Communicate starts/findings/direction plainly; self-contained outcomes include paths and remaining checks. Avoid invented labels/arrows; visualize usefully. Challenge ambiguity with options; never guess silently.