@vegastack/vegafactory 0.19.0

package/skill/dev-implement/references/changelog-and-chronicle.md

@@ -0,0 +1,21 @@
+# Changelog and chronicle
+
+The mechanics behind dev-implement's hand-back rule: every behavior-changing branch carries its changelog entry and, when dev.md says `chronicle: on`, its story entry — both on the branch, so they land atomically with the merge. The body owns the rule; this file owns how each knob value is satisfied.
+
+## Per knob
+
+dev.md's `changelog:` knob names the convention; the entry is always written directly, never through an interactive tool.
+
+| `changelog:` value | What to write |
+|---|---|
+| `changesets` | `.changeset/<slug>.md`, written as a file — never the interactive CLI |
+| `keep-a-changelog` / `pubspec+changelog` | one bullet under `## [Unreleased]` in CHANGELOG.md; when the file is absent, create it in the same branch with the `# Changelog` + `## [Unreleased]` skeleton |
+| `none` | nothing — the project keeps no changelog |
+
+## The first line
+
+A changeset entry's first line is **one plain sentence** naming the change in behavior terms; detail follows after a blank line as sub-bullets, one line each. The published changelog and the release notes that lead with it reproduce the entry verbatim, so a single 1,000-character sentence ships as a wall of text.
+
+## Chronicle
+
+When dev.md says `chronicle: on`, the story entry is prepended to `.vegastack/chronicle.md` in the format the `dev-chronicle` skill owns (title, what, why, how it went, what changed, decisions; voice per dev.md's `chronicle-style:` and `emoji:` knobs). It is written on the branch alongside the changelog entry, so the merge carries both or neither.

package/skill/dev-implement/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.

package/skill/dev-implement/references/ledger-and-resume.md

@@ -0,0 +1,52 @@
+# Using the ledger
+
+`references/conventions.md`, authored by `dev-setup` and shipped with every dev skill, defines the ledger format and resume order: brief → plan → ledger → `git log` → targeted source reconciliation. This file defines how dev-implement uses that recovery map and live progress view.
+
+## When to checkpoint
+
+Create the ledger comment as the session's **first write after claiming** — before any code — with the marker, the heading, and the branch's worktree path, so a resuming session reads brief → plan → ledger → `git log` in the right checkout rather than the main one. Then checkpoint, editing in place:
+
+- **After each plan task completes** — and tick the matching `[x]` in the plan comment in the same pass. That box is a second write, to a different comment, that your own resume path never reads — so it is the one that silently lags reality, while the operator's progress view depends on it. The hand-back guard (`evidence-check --issue`) compares immutable task IDs in both directions; equal counts do not prove agreement. Record the task's base sha *before* starting it, so the `complete` line's commit range is exact.
+- **After each review fix round**, with the addressed/open counts.
+- **At every dark-mode judgment call.** A ruling is any decision the brief/plan didn't make for you that a reviewer or the operator could reasonably question. Rulings are cheap; unrecorded decisions are debt.
+- **On findings deferred or parked at review**, per dev-review's adjudication lines.
+
+Never batch checkpoints "for later" — the ledger's value is exactly that a crash between checkpoints loses one task, not the map. Under concurrent edits, last-writer-wins on one comment is accepted (single-operator workflow); note a clobber if you ever see one.
+
+Within a live managed run, `vegafactory dispatch --checkpoint-task ISSUE-TN --run-id RUN_ID --once --json` runs the configured check from the approved base and retains an immutable task-only completion receipt. Preview is the default without `--once`. The exact canonical task must be checked, source committed and clean, and current run/owner/approval unchanged. Replaying an existing verified completion retains its original check rather than running it again; a plan checkbox alone never skips work.
+
+A checkpoint retains what a compaction summary must retain: difficulties and their resolutions; options tried or set aside, and why; anything decided, ruled out, or established as a constraint, stated exactly; where things stand; what is open; exact names, numbers, links — the operator's words near-verbatim, the agent's reasoning condensed.
+
+The ledger's edit time is also this claim's **heartbeat** — the only liveness signal an agent session exposes. dev-status reads a ledger silent past the orphan threshold (6h) as a *possibly-orphaned* claim: the session likely died before hand-back. A session that runs for days but keeps checkpointing never trips it; a dead one's ledger freezes. A single long task can legitimately go quiet — so checkpoint at rulings within it too, keeping the pulse alive — and the flag is always the operator's to act on (check, resume, or reclaim), never an automatic reset.
+
+## Resuming — dev-implement's additions to the protocol
+
+- Automatically resume only verified outstanding work within unchanged approved scope, current policy and ownership. Another machine additionally needs exact stop proof, a verified available source checkpoint, the original qualified harness/model/account/effort and the shared owner's single conditional transfer. Offline status and elapsed time cannot prove stopped execution.
+- A schemaVersion3 packet names exact brief/plan bindings, canonical `approvalBindings`, separate audit-only `recordBinding`, task IDs, source-bound completed entries, commit, findings, rulings, comment cursor, pending runs and bounded lessons. Missing legacy fields require reconstruction from verified sources, never inferred approval.
+- Re-read the complete current authority history and all authoritative comments even when their IDs predate the cursor; old comments can be edited. Inspect newer operator constraints and corrections. Missing pages, changed scope, contradictory current evidence or missing commit ancestry produce explicit reconciliation, retaining prior packets and completed work.
+- Reconcile task identities, not counts. Preserve earlier failed attempts as history when later verified work supersedes them. Completed tasks never rerun merely because handback or telemetry delivery remains pending.
+- Retry delivery through its original runtime/transport owner and exact durable payload identity. Typed telemetry can remain pending without blocking otherwise safe source transfer; ambiguous code/control effects do block. Unavailable old-host payload stays visibly pending.
+- Preserve original parent/child bindings, failed children and incomplete joins. A prepared or locally applied join cannot become accepted merely because a source branch exists. Never reset original dirty tails or borrow an old parent's owner token. Current ownership permission and historical receipt facts are distinct.
+- Recover a retained parent/direct-child group only as one complete same-head set. Persist and read back one local operation/member/material intent before the conditional succession; bind each concurrent group to its own verifier/private-read context, then freshly re-read every member's source, authority, dependencies, policy, exact checkpoint, stop/effect evidence and original launch/check/join context before CAS and again after receipt/current-owner readback. A lost response reuses the same intent, operation, receipt, tokens and request IDs; it never transfers again. Construct remote-only attempts through the verified group-receiving constructor and same-home attempts through verified continuation, read back every local member before starting, then let the recovery controller acknowledge the parent first and only unfinished `recovery-queued` children. The child gateway accepts only the exact receiving-group provenance or deterministic same-home continuation plus immutable start receipt, and never starts either twice. Re-resolve current machine enrollment before every later start, process and effect. Accepted results and joins are historical evidence to reuse, never work to replay.
+- Keep a recovered child's parent integration/execution request separate from its exact child checkpoint request/action through inspection, reconstruction and effect or join validation. The parent branch, a saved passing check, checkpoint ref, plan checkbox or parent `source-checkpoint` cannot replace current `child-source-checkpoint` authority.
+- A terminal execution already captured as `runId:terminal:0` cannot be reopened by changing that event's result. Quota waiting before terminal capture retains its original same-setup path. Generic same-home recovery uses the runtime owner's verified continuation constructor and a new terminal segment while preserving the logical run. Receiving-home recovery uses the exact handoff predecessor and current claimed owner; receiving-group recovery additionally binds the complete succession receipt, parent/child role and predecessor bytes before creating a private attempt. Missing old elapsed/reporting context stays unknown and reporting remains held; it is never reconstructed from foreign PIDs or guessed ordinals.
+- A receiving run establishes a new complete observed source set. Preserve exact current source references and name unresolved operator constraints. Original unpublished notes and learning remain unavailable; their absence does not imply prior acknowledgement or an empty history. Retained completion receipts are rechecked against the actual pinned handoff predecessor and source ancestry.
+- Subscription waits preserve harness/model/account/effort and progress without a cumulative task time cap. Current policy freshness, bounded I/O and explicitly approved trial allowances still apply.
+
+## Preparation within a parent
+
+A consolidated scope approval may select exact preparation task IDs. The parent ledger records `mode=preparation`, canonical source and requested-record pins, plan digest, task files and satisfied task-specific contracts. `readTaskPrerequisites` reads the approved task's Interfaces/Consumes mapping and carries the evaluated canonical tuple unchanged. Accepted integration is proved by exact review/source/parent ancestry and immutable accepted-scope receipts; comment hashes alone cannot manufacture acceptance.
+
+Full issue execution keeps every native blocker. Preparation does not mutate ready labels, mark live tasks complete or grant publication, deployment, credential work, merge or release. A preparation prerequisite can require another exact preparation contract; it never implies that prerequisite's whole issue is implemented or operationally complete.
+
+## Learning from ordinary work
+
+Keep at most 32 active lessons/16 KiB in the existing packet. A lesson binds repo/task/scope/source, bounded statement, real check/review/measurement references, target paths and exact undo commit. Passing unrelated checks, a fabricated `passed:true`, model confidence or an installed hook are insufficient. Require a relevant failure-to-pass, measured improvement or the same independent review finding resolved across the before/after source, authorized reversible change and required independent review. Protected handbook/org/decision rules and provider changes remain visible proposals.
+
+Ordinary work prepares observations through the owned `stageLesson` adapter. Check references identify actual normal acceptance processes; measurement references use their monotonic elapsed values, and review references bind exact opposite-harness source comments retained by the recovery source reader. A review-based improvement requires an open finding on the prior source and the same finding resolved by a clean review on current source. The owned CLI offers `learning checkpoint --run-id ID --json`, `inspect --run-id ID --json` and `revert --run-id ID --id ID --dry-run|--apply --json`. Checkpoint flushes prepared records only; no background experiments or model calls. Exact inverse-patch undo preserves unrelated edits. Reverted/superseded evidence stays in existing history; it is not silently erased.
+
+SessionStart resolves the registered private owned session, reloads current local policy, checks source and evidence, and supplies at most three relevant lessons within 2 KiB. Missing/stale context yields silence. Stop/SessionEnd preserve the existing durable capture/deduplication consumer before flushing prepared learning. An internal ready/start/validated/flush/finish handshake keeps module startup and read-only registry/session/current-policy validation inside the one-second cap measured from entry. A trusted callback then obtains one 500 ms grant covering every claim, write, release, ACK and learning mutation; the 350 ms/64 KiB input bound is unchanged. Read-only validation disables optional Git index locks. It terminates only its owned child process group on either deadline and requires finish plus exit 0 before rendering context. A timeout is no acknowledgment; startup/recovery retries retained work. Never read, import, generate or modify Claude/Codex native memory or transcripts.
+
+## Surfacing — rulings never die in the dark
+
+Every `Ruling:` line lands on the evidence comment's `**Review:**` line at hand-back, in the order made. The operator reads that list and reverses anything wrong — a ruling that only ever lived in the ledger was a decision made in secret.

package/skill/dev-implement/references/parallel-children.md

@@ -0,0 +1,35 @@
+# Parallel children
+
+A registered parent can run the exact independent groups in its current approved plan. Each group owns disjoint literal files and one child issue. Ordinary work stays sequential; overlap, ambiguous ownership or unavailable prerequisites refuse parallel admission.
+
+## Commands
+
+```text
+plan-lint --file <approved-parent-plan> --groups --json > groups.json
+vegafactory children run --parent <n> --groups groups.json --repo <o/r> --write --json
+vegafactory children join --parent <n> --groups groups.json --repo <o/r> --write --json
+```
+
+Without `--write` the CLI previews. It compares the supplied group report with the canonical approved plan; a local JSON file is not approval. The command runs inside its registered parent process/session. The private version 2 child record retains the group-origin parent binding and one immutable launch-parent binding per child; a version 1 record stays readable evidence and upgrades only after its exact bytes and actual shared parent facts are preserved. The standalone `children.mjs plan` remains a non-executing helper. Legacy launch/join entrypoints and the shipped compatibility workflow direct callers to the CLI and do not spawn a fallback executor. Existing user workflow copies are not overwritten and may still contain the older executor; those copies are not the supported CLI execution route.
+
+## Execution
+
+Both supported harness routes use the shared launch table and owned runtime. Child preparation reuses ordinary include-copy, setup and trust handling, with required setup/includes and effective managed hooks checked before spawn. Missing qualification or unsupported effective configuration remains a refusal; configuration fixtures do not qualify a real vendor. Every child retains the selected subscription account, harness, model and effort. No API fallback is used.
+
+The default gateway reads the parent’s pinned consolidated record and complete current history at every execution boundary. Exactly one selected `code` child, its complete selected task/file scope and one local edit action form the execution request; a separately selected exact `child-source-checkpoint` action forms the checkpoint request for the real child branch and ref. The child has no native or synthetic approval, and a parent checkpoint, branch pattern or successful parent evaluation cannot substitute for either request. Missing, ambiguous, changed or revoked source retains prepared local work and permits no process or checkpoint effect.
+
+The approved parent limit is at most three active qualified child processes across machines, also bounded by host policy. Shared task/resource ownership is separate from process capacity: a stopped child does not become a completed issue. Unknown termination and unresolved ownership retain their reservations. A stopped group changes coordinator only as one complete same-head parent/direct-child set through one conditional shared-owner succession. The production tick persists one exact operation/member/material intent first, binds concurrent groups to separate verifier and private-read contexts, and repeats current source, authority, dependency, policy, checkpoint, stop/effect and original launch/check/join checks before CAS and after immutable receipt/current-owner readback. Lost response recovery reuses that intent, receipt, tokens and per-member request IDs; it never treats a response alone as launch authority or performs a second transfer. Every remote-only private attempt is built by the verified group-receiving constructor, every same-home attempt by verified continuation, and all attempts are read back before the controller starts the parent. Only then are unfinished `recovery-queued` children acknowledged within capacity; their normal gateway consumes the exact running receiving-group provenance or deterministic same-home continuation and its immutable start receipt without starting it again. Each later start, process and effect re-resolves current machine enrollment and task ownership. Accepted results and joins are reused without rerunning a vendor process, check or merge, and original launch bindings never change. Healthy approved work has no cumulative task timeout. Parent cancellation or owner loss cancels only owned child processes; restart resolves saved run IDs rather than launching duplicates.
+
+## Acceptance and integration
+
+The child result binds schema version, run ID, issue/repository, original base, exact head and branch, scope digest, terminal cause, machine/session/shared generation and checkpoint identity. Its acceptance command comes from the recorded parent source and actually executes at that head. A printed command, existing branch, exit zero or source backup alone is not a result. No-change needs positive acceptance too.
+
+The CLI checks clean source, immutable commits, original base and all changed paths before each declared-order integration. It requires current explicit integration action authority and the original parent owner. A failed child keeps its source while independent verified siblings may join. Conflict or failed assembled-parent acceptance preserves prior successes and stops subsequent integration.
+
+Before changing Git, the controller persists source-bound child acceptance and a prepared join receipt. The private run ledger records child run/generation, original source SHA, parent before/after and acceptance. Published child history is never rewritten. After a crash, exact Git ancestry and receipts are reconciled before another join or check.
+
+Typed remote child acceptance requires the separately authorized immutable child checkpoint, freshly checked before preparation and delivery. Remote accepted joins also require the resulting parent checkpoint. Unavailable source or delivery remains prepared/partial evidence; it is never relabeled completed. The recovery controller must reconstruct original approval/run/launch context before cross-host consumption. Already accepted child and join receipts retain their original run, generation and source and are consumed without repeating a check or merge; prepared or ambiguous joins still reconcile exact Git facts. After exact child review and an authorized accepted join, the CLI writes an immutable AcceptedScopeSnapshot receipt, reads back its known commit/blob and conditionally links it without changing parent state. Only then does acceptedDeliveries project implemented task IDs with child/parent heads and scope digest. Preparation, unchecked tasks and pending receipt links emit no implemented rows. Historical receipts prove prior accepted scope after public edits; they grant no future authority. Whole-parent review and remote merge/release permission remain separate.
+
+## Retention
+
+Child and parent branches survive failures and interrupted joins. Cleanup needs its own operator instruction. Ordinary removal cannot delete a parent checkout while a serial child occupies it; the parent directory remains until its own PR merges. See [worktrees](worktrees.md) for preparation, integration and removal details.

package/skill/dev-implement/references/worktrees.md

@@ -0,0 +1,63 @@
+# One feature, one worktree
+
+The main checkout never leaves the default branch and never carries uncommitted work. Every branch — feature, epic parent, trivial chat fix, research spike, release — is checked out at `.vegastack/.worktrees/<n>-<slug>/` on `<type>/<n>-<slug>`, per `references/conventions.md`. All of it is decided by `scripts/worktree.mjs`, with `vegafactory worktree …` wrapping its create, restore, remove, list, prune, and `status --json` commands; anything destructive remains a dry run until `--write`, and every verb exits `0` pass · `1` warn · `2` blocked.
+
+## Scenario matrix
+
+| Scenario | What happens |
+|---|---|
+| New issue, no parent | `worktree.mjs create --issue <n> --write` — the slug and type come off the issue title (`<type>:` prefix, the rest slugified; `--slug`/`--type` override, and GitHub being unreachable blocks rather than guesses) — fetches `origin/<default>`, `git worktree add` on a new branch, copies dev.md's `worktree-include:` files, runs `commands: setup`, adds the Codex trust entry. The ledger's first line records the path. |
+| Epic parent | Branch `<type>/<parent-n>-<slug>`, one worktree, created when the **first child** is claimed. The parent never gets `ready`. |
+| Sub-issue of an epic | `create --parent <parent-branch>`: `git switch -c` from the parent branch **inside the parent's worktree**. One child at a time; ordinary removal cannot delete that parent directory while it holds a serial child branch. Independent children use the CLI contract below. |
+| Resume | Same branch, same worktree, reused. The resume read-order — brief → plan → ledger → `git log` — runs *there*, and the ledger names which "there" that is. |
+| Corrections / reclaim | Reuse the worktree. Directory gone but branch alive → `restore --issue <n> --write`, which finds the branch carrying the number (`--slug` picks one when several do), re-adds the checkout and re-runs include-copy, setup and trust. `restore` never creates a branch: a missing branch means the work is elsewhere. |
+| Ship, PR | `ship-gate.mjs` resolves the branch's worktree itself (`--worktree <path>` overrides) and runs its git calls, its dev.md read and the fresh check command there, so the checkout test passes by construction. |
+| Ship, merge | After the merge: `worktree.mjs remove --issue <n> --write`. That removes the **directory only** — deleting the local branch and the remote branch are separate operator words. A parent's worktree goes only when the parent PR merges. |
+| Rebase onto the default branch | Done inside the worktree; re-verify whatever the rebase touched. |
+| Direct chat trivial fix | `<type>/<slug>` in its own worktree too — the main checkout stays clean even for a one-liner. |
+| Research | `research/<n>-<slug>` worktree only when code is actually written; removed at hand-back, never merged. |
+| Release | `chore/release-<version>` in its own worktree. |
+| Cross-agent review | Read-only, in the same worktree; a reviewer never switches the branch under it. |
+| Abandoned issue | Branch and worktree are removed only on the operator's word. |
+
+## Verified independent children
+
+Inside a registered, currently owned parent session, pass the canonical `plan-lint --groups --json` report to `vegafactory children run --parent <n> --groups <file> --repo <o/r> --write --json`. Without `--write` it previews. The CLI revalidates original parent and child approval, preserves the selected subscription setup, prepares both harnesses through `createChildWorktree`, and executes through the common owned runtime. Failed setup, required includes, effective hooks or native prerequisites refuse; unsupported effective harness inspection never becomes qualification. The standalone helper plans and validates, and directs execution and integration to the CLI.
+
+At most three qualified child processes run for a parent across machines, also bounded by each host's policy. Literal file/resource overlap refuses parallel admission. Original parent claim identity and child run IDs are saved before reservation; a replaced owner, unknown termination or unfinished original run cannot start a duplicate. Parent cancellation cancels only its owned children. Healthy execution has no cumulative task time limit.
+
+`vegafactory children join` takes the same parent/groups/repo flags. It requires a current explicit integration action, successful durable child execution, clean exact source, the original base and branch, full changed-path scope, and the check command from the recorded parent base actually passing at the produced commit. No-change requires that positive acceptance too. It merges immutable local commits in declared order without rewriting published child branches. Missing/failed children remain reported; independent verified siblings can still join. A merge conflict or failed assembled-parent check retains source and prior successes and stops subsequent integration.
+
+The private run ledger and immutable shared receipts bind child run/generation, source SHA, parent before/after and acceptance. Prepared intent precedes Git changes. Restart reconciles receipts with exact Git facts before another join. Typed remote child acceptance requires its verified checkpoint; an accepted remote join additionally requires the resulting parent checkpoint. Missing backup or unresolved delivery leaves prepared/partial evidence, never remote completion. Cross-host reconstruction belongs to the recovery controller and must supply original approval, run and launch context; current-owner guessing is refused. Whole-parent review and remote merge/release permission remain separate.
+
+## Lifecycle states
+
+Derived from git plus GitHub on every read, never stored — a second source of truth is what drifts. Precedence is top to bottom:
+
+| State | Derivation |
+|---|---|
+| `orphan-dir` | The directory exists, its branch does not. |
+| `branch-only` | The branch exists, its directory does not — what `restore` fixes. |
+| `active` | A session holds it: `git worktree lock`, or the dispatcher's lock. |
+| `merged` | The branch is on the remote **and** on `origin/<default>` — by ancestry, or by content when a squash or rebase merge rewrote the commits: its whole diff against the merge base, or every one of its commits, has a patch-id already there. A never-pushed branch cannot have merged: the default branch is reached through a PR. |
+| `abandoned` | The issue is closed and the branch never merged. |
+| `parked` | The residue: issue open, no session. |
+
+## Safe to remove — all must hold
+
+1. `git status --porcelain` is empty.
+2. `git rev-list <remote>/<branch>..<branch>` is empty, and the remote branch exists. Missing or behind → push first, then re-check (`--push` does exactly that).
+3. Merged into `origin/<default>` — `remove` and `prune` fetch it first, because the merge lands on the server — **or** `--force` with the operator's word.
+4. Not locked.
+
+`--force` lifts only rule 3. Uncommitted, unpushed and locked are never lifted — those are the three ways real work disappears. Failing any rule keeps the worktree and reports which rule failed.
+
+**Retention.** `worktree-retention:` (default `14d`) measured from the **later** of the last commit and the last ledger edit. `prune` proposes only `parked` worktrees past the window and is dry-run until `--write`. On `--write` it pushes an unpushed candidate's branch first — that half protects the work and happens whatever else is wrong — then re-runs the safe-to-remove test with the window standing in for rule 3 (parked means unmerged, and the pushed branch plus `restore` bring the checkout back), so a candidate that is still dirty, unpushed or locked keeps its worktree and says why. The branch always survives; branch deletion and `--force` on `remove` take the operator's word.
+
+## Harness facts that bear on a worktree run
+
+- **Claude Code hooks:** the `CLAUDE_PROJECT_DIR` variable (written with the usual shell-expansion sigils, omitted here because they trip SkillSpector's bounded parser) stays at the launch root, while the hook input's `cwd` follows the worktree — hooks that need to know where the work is read `cwd`.
+- **Claude Code permissions:** an approval granted inside a worktree is written to the **main checkout's** `.claude/settings.local.json` and applies everywhere. Approving in one worktree approves for all of them.
+- **`claude -p` runs never clean up worktrees.** Cleanup belongs to the factory (dev-ship after merge, `prune` after retention), not to the harness.
+- **Codex:** an untrusted path skips `.codex/` hooks, rules and project config, so each worktree path is added to `~/.codex/config.toml` as `[projects."<abs path>"]` / `trust_level = "trusted"` at create and restore time. `codex` absent from `PATH` makes this a warning, not a block.
+- **Claude Code's own `--worktree` / `EnterWorktree` is deliberately not used:** its location (`.claude/worktrees/<name>`) and branch (`worktree-<name>`) differ from ours, and it exists on one harness only. Plain `git worktree add` works for Claude, Codex and Hermes alike.

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

@@ -0,0 +1,3 @@
+# Refresh contract — dev-implement
+
+Evergreen: this skill asserts no version pins, vendor mechanism names beyond long-stable `gh` subcommands and the GitHub contents API shape (deliberately treated as durable), numeric vendor limits, or dated facts — its content is workflow discipline (preflight, claiming, dark-mode bounds, review modes, the evidence-comment contract), all versionless. Harness mechanics are tracked by `dev-setup`'s registry. Revisit if a future edit introduces a volatile fact.

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

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