@outerlayer/cli 0.2.0 → 0.4.1

package/skill-pack/template/build/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: build
+description: >
+  Build one approved issue end to end: implement it, review it with a sized panel
+  of agents, run the repository's own checks, open the pull request, and attach
+  the review and criteria reports as evidence. Use when a work item exists for an
+  issue and you want it built. Invoke with OUTERLAYER_WORK=<number> claude "/build".
+disable-model-invocation: true
+---
+
+Build one issue into an evidenced pull request. `/spec` writes and gets
+approval for the issue. This skill builds it. It never writes the spec.
+
+This file holds the phase order and the rules that bind every phase. Each
+phase reads its own reference on entry, never before:
+
+- [references/review-loop.md](references/review-loop.md): the review phase.
+- [references/review-briefs.md](references/review-briefs.md): the reviewer, refuter and mutation briefs.
+- [references/agent-briefs.md](references/agent-briefs.md): the briefs for every other agent.
+- [references/release.md](references/release.md): sync, pull request, CI.
+- [references/criteria-judge.md](references/criteria-judge.md): the brief that judges each criterion.
+- [references/evidence.md](references/evidence.md): manual test and evidence.
+
+Paste a brief verbatim into the agent that runs it. Add only the run's own
+values, such as paths, the branch and the item number.
+
+Every text a person will read follows the writing rule in the repository's
+instructions file, if it has one. Otherwise write for a reader who was not in
+the session: short sentences, the outcome first, and plain words. Paste that
+rule into every agent that writes prose.
+
+## Arguments
+
+`/build` takes no issue number. It builds the work item named by
+`OUTERLAYER_WORK`, the item's number. The launch is:
+
+    OUTERLAYER_WORK=<number> claude "/build"
+
+The item exists because someone ran `outerlayer work build --issue <reference>`.
+Given a request instead of a work item, stop and say:
+
+    Spec it first:  /spec <the request as given>
+
+Optional flag: `--unattended` means no person is present and nothing wakes
+the session after a turn ends. Spawn every agent in the foreground and wait
+for it in the same turn. Run the gate in the foreground with the maximum
+timeout. End the turn only at the final report.
+
+## State rules
+
+These bind the orchestrator in every phase. Rule 5 also binds every spawned agent.
+
+1. **Never end a turn waiting on nothing.** End a turn while work is in
+   flight only when something live will wake the session: a spawned agent or
+   a background command. Before saying "waiting on X", confirm X is live.
+   Work that is not live did not happen: redo it once.
+2. **One redo per piece of work.** A second failure of the same work means
+   the orchestrator takes it over. It reads what the agent left, finishes the
+   brief itself in the foreground, and names the takeover in its status line.
+   If the gate still cannot go green, escalate.
+3. **The gate runs in the foreground, one heavy command at a time.** The gate
+   is the repository's own pre-push checks and tests, as its instructions
+   file names them. Never run it in the background. Never start a suite while
+   an agent runs one. Never bypass a hook: no `--no-verify`, no skipped hook,
+   even when a hook fails. Fix what the hook reports.
+4. **Checkpoint and re-orient.** Before phase 1, write a state file at
+   `"$(git rev-parse --absolute-git-dir)/build-state.json"`, replacing any
+   earlier one. Record the phase, the review round, the spawned agents, the
+   agent count, the issue reference, the pull request number, the branch, and
+   from phase 4 the tier verdict. Overwrite it at every phase change. On
+   entering a phase, after any wake, and after any compaction, read the state
+   file, `git status`, the branch, the live agent list, and the issue or pull
+   request when the phase uses them. Live sources win over the file. Treat the
+   file as absent when its branch does not match the current branch.
+   When you overwrite the file, keep its `criteria` entry: phase 2 writes it
+   and the judge reads it.
+   Beside it, create `"$(git rev-parse --absolute-git-dir)/build-reports/"`,
+   emptied of any earlier run's files. Every spawned agent writes its full
+   report there and returns a summary of at most ten lines. Give each agent
+   the absolute path. Reports never land in the working tree, so review never
+   reads them as product code. Read summaries and pass file paths, never
+   report bodies. Delete both at the end of phase 6.
+   Once a pull request exists, read `outerlayer work threads --item
+   "$OUTERLAYER_WORK" --json`. Each thread with `waitingOn` of `agent` holds a
+   person's comment. Answer each before the run ends, as the `amend` skill does.
+5. **A session never records a pass or fail on an artifact.** It emits
+   artifacts. A person decides pass or fail.
+6. **Observed status only.** Every status claim in the final report (a gate
+   result, a CI conclusion, mergeability) quotes command output observed
+   after the last change it describes. No quoted output means unknown, never
+   green. Quoted output goes in the report to the user. Pull request bodies
+   carry curated links, never raw output.
+7. **Files no issue.** The build files no issue anywhere, and no agent does.
+   A defect outside the change, or a follow-up the fix pass deferred, becomes a
+   candidate issue in a report: a title, a body and a target repository. The
+   final report lists every candidate for the user to file with `/spec`.
+8. **Reader pass.** No text reaches the git host as the session wrote it.
+   The pull request title and body, and every comment, go through one cold
+   rewrite agent. Its only inputs are the draft and the writing rule. It
+   returns the rewrite and the terms it cut or explained. Check that every
+   path, identifier, number, criterion id and link survived, and restore any
+   that did not.
+9. **Run budget.** Spawn at most sixty agents in a run. Keep the count in the
+   state file. Past three quarters, say where the count stands in the status
+   line. A run that would exceed the budget stops and lists what is left
+   unverified. The review phase also holds a limit on agents in flight.
+
+## Phases
+
+Run them in order.
+
+1. **Intake.** Read `OUTERLAYER_WORK`. If it is missing or does not parse,
+   stop and hand back:
+
+       outerlayer work build --issue <reference>   # once; prints the item number
+       OUTERLAYER_WORK=<number> claude "/build"
+
+   Run `outerlayer work status --item "$OUTERLAYER_WORK" --json` and read the
+   item's tracker key. It is a GitHub `#n`, or a Linear or Jira key. Read the
+   issue through whatever tracker tool the team has. The issue is the source
+   of truth for the whole run, and every later agent is pointed at it.
+   Restate the task in one or two sentences and confirm the issue is still
+   open and unclaimed. If the item shows a live claim by another runner that
+   has not expired, stop and name it.
+   Phase 2 finds the issue's criteria. If it finds some, they are the
+   definition of done, and each declares a proof form or a test. If it finds
+   none, build from the issue's description. An issue without criteria is
+   built, never sent back. Then no judge runs.
+   Ask nothing from here until the final report. An agent that needs a ruling
+   states its assumption in its report and continues. The final report lists
+   every assumption.
+2. **Read the criteria.** Record the issue's criteria on the item, so the
+   Criteria tab, the item's status and the judge hold the pull request to one
+   list. Save the issue body to a file and run:
+
+       node .outerlayer/skills/build/scripts/record-criteria.mjs --item "$OUTERLAYER_WORK" --issue-file <body file>
+
+   The script reads two shapes, in this order:
+
+   1. An `## Acceptance criteria` section whose items each start with an id in
+      backticks. The id and the text after it are kept as written. A
+      `(proof: <kind>)` on the line sets `proof`. Otherwise `proof` is `null`.
+   2. A heading or line that reads `Acceptance`, `Acceptance criteria` or
+      `Done when`, in any case, with or without a colon, followed by a bullet
+      list. Each bullet is one criterion. Its text is the bullet's text. Its id
+      is `AC-<item number>-NN`, numbered from `01` in list order. `proof` is
+      `null`. Never infer a proof kind from the words.
+
+   It writes the list to
+   `"$(git rev-parse --absolute-git-dir)/build-reports/criteria.json"` and runs
+   `outerlayer emit criteria` on it. The gateway decides whether a list may be
+   recorded. A 409 means the item already has a recorded list. That list
+   stands, and nothing is recorded. No command returns the item's list, so the
+   build cannot read it: it holds the work to the issue's reading of the criteria and says
+   so in the final report. Any other
+   refusal is written to the state file with its message, and the build
+   continues. The script writes the outcome under `criteria` in the state
+   file: `source` (`issue-ids`, `issue-bullets`, `item` or `none`), `recorded`,
+   `count` and `list`. On a 409, `list` is empty, and the issue's reading of the
+   criteria goes under `issueReading`. If neither shape is found, nothing is recorded and the
+   build continues at the small tier, as for any issue without criteria. Change
+   nothing in the issue. A criterion you think is wrong becomes a note in the
+   final report, never an edit. The intake summary names how many criteria were
+   recorded and from which shape, or says that none were found.
+3. **Implement.** Branch `feat/<slug>` from the default branch. Spawn the
+   implementer with the Implementer brief from
+   [references/agent-briefs.md](references/agent-briefs.md), the issue, the
+   branch and the instructions-file pointer. The phase ends when the
+   repository's own pre-push checks and tests pass on the branch. Review
+   never opens on a red branch. A branch that cannot go green escalates.
+4. **Review.** Read [references/review-loop.md](references/review-loop.md) on
+   entry and run it. It sizes the panel to the finished diff: one generalist
+   for a small diff, the generalist and one focused reviewer for a medium
+   one, the generalist and up to three for a large or risky one. Findings are
+   merged into classes, checked by a refuter, fixed, and rechecked once. Then
+   write the review report as an HTML file and emit it:
+
+       outerlayer emit artifact <report>.html --for code-review-ran --caption "Review of the change and what it found"
+
+5. **Sync and pull request.** Read [references/release.md](references/release.md)
+   on entry and run it. A release agent rebases, gates and pushes. Open the
+   pull request. Then run `outerlayer work pr <number>` so the item links the
+   pull request. When the issue has criteria, a fresh agent judges them with
+   [references/criteria-judge.md](references/criteria-judge.md), and the
+   judge's HTML report is emitted:
+
+       outerlayer emit artifact <judge-report>.html --for acceptance-criteria --caption "Each criterion judged against its test"
+
+   Watch CI until every check has concluded.
+6. **Manual test and evidence.** Read [references/evidence.md](references/evidence.md)
+   when the pull request opens, and run it. Capture the proof each criterion
+   declares, emit it, then end the run with the final report. The report
+   lists every candidate issue and every assumption.

package/skill-pack/template/build/references/agent-briefs.md

@@ -0,0 +1,243 @@
+# Briefs for every agent outside the review panel
+
+## Contents
+
+- How to use this file
+- Shared rules
+- Implementer brief
+- Merger brief
+- Fix brief
+- Release brief: sync and push
+- Release brief: CI and mergeability
+- Evidence brief
+
+## How to use this file
+
+SKILL.md says which agent runs in which phase. This file says what each one
+is told. The panel's reviewer, refuter and mutation briefs are in
+[review-briefs.md](review-briefs.md). Paste every brief verbatim. The
+orchestrator adds only the run's own values, such as file paths, the branch,
+the issue reference and the pull request number, and may append a short focus
+addendum that adds emphasis. It never edits or trims a brief.
+
+Each brief names the report file the agent writes. The agent writes the full
+report there and returns a summary of at most ten lines.
+
+## Shared rules
+
+Paste this block at the top of every brief in this file.
+
+Read the repository's instructions file first and hold your work to it.
+Write every text a person will read, such as reports, commit messages and
+candidate issue bodies, in short sentences with plain words, leading with the
+outcome.
+
+Never create an issue in any tracker. Work that belongs in its own issue
+becomes a candidate issue in your report: a title, a body and the target
+repository. The user decides whether to file it.
+
+Never ask the user a question. If you need a ruling, state your assumption in
+your report and continue.
+
+Run every long command, such as the full gate, the mutation tool or the
+integration suite, in the foreground with the maximum timeout. Never
+background one, and never end a turn waiting on a notification.
+
+Every agent in a run shares one memory cap. Run only the test files for the
+code you change or check, one at a time. Run a whole package's suite, a
+coverage run, a repository-wide typecheck or the full gate only where this
+brief names it. Two of those at once overrun the cap, and the kernel kills
+test workers that then look like flaky tests.
+
+Put scratch copies and extra worktrees under the system temp directory.
+
+Never bypass a hook. Do not use `--no-verify`, skip a hook, or disable one,
+even when it fails. Fix what the hook reports.
+
+Never change the identity a command runs under. Never unset or override an
+`OUTERLAYER_*` variable or the key a command would use, and never rerun a
+refused command as someone else. A refusal is a result: write it in your
+report with the command, and leave that step undone.
+
+A session never records a pass or fail on an artifact.
+
+Write your full report to the path this brief names. Then return at most ten
+lines. Anything you leave out of the file is lost to the next stage.
+
+## Implementer brief
+
+The shared rules apply. Your inputs are the issue, the branch and the
+instructions-file pointer.
+
+The issue is the definition of done. When it has criteria, each one is a
+requirement. Make every test cite the criterion id it proves, in the form the
+team uses.
+
+Write the first commit red, with no implementation. It holds one test that
+drives the real chain, from input through storage to read-back, with nothing
+mocked at the store boundary, plus one test per criterion written from the
+criterion's own words. Read every failure. Each test must fail because the
+behavior is absent, not because of a typo or a missing import. Then implement
+until green. When the issue has no criteria, write tests from its description
+in the same order.
+
+Version any new database migration with the current UTC time, never a round or
+guessed one. Two open branches that guess the same time both pass their own
+checks, and the second to merge breaks the build for everyone.
+
+While iterating, run only the tests of the packages the diff touches. Never
+run the full gate first to see where things stand. When the last change is in,
+sync with the base branch and run the repository's own pre-push checks and
+tests, as its instructions file names them, in the foreground, once. You are
+not done until they pass. If they cannot be made to pass, stop and escalate.
+Never hand a red branch to review.
+
+Do not run a mutation tool here. A mutation checker runs beside the review.
+
+A field that crosses package boundaries needs an assertion at every seam it
+crosses: writer, relay and reader.
+
+A defect that also reproduces on the base branch is out of scope. It is a
+candidate issue, never a fix here.
+
+Close your report with a "Rules that misled you" section. List every sentence
+in the instructions file or a skill you had to work around: the file path, the
+line, the sentence quoted verbatim, and `broken` when its instruction fails or
+`wrong` when it says the wrong thing. Write "none" when there were none.
+
+## Merger brief
+
+The shared rules apply. Your inputs are the round's report files.
+
+Merge the findings into classes. A class is a claim about a pattern, not a
+single site. For each class, build an inventory of every instance in the
+repository, checked with a search. The reports name the instances they
+happened to see. You name the rest.
+
+Take the union, never a vote. A finding one reviewer raised and four missed
+survives to verification exactly as one four raised does. Agreement is
+telemetry, not evidence.
+
+A finding without its reproduction is a note, not a class. Collect notes from
+every report into a closing "Notes" section and never give one a class id.
+
+Write `build-reports/round-<n>-merged.md` with one section per class: the
+claim, its severity and kind, the full inventory, which reviewers found it,
+and the rule citation when a report carried one. Two reports citing the same
+sentence for one class are one citation. Ids are `r<round>-c<k>` for a class,
+`r<round>-n<k>` for a note, `r<round>-i<k>` for a candidate issue and
+`r<round>-x<k>` for a rule a report listed, each `k` counting from 1 within its
+kind. A listed rule is its own entry with its citation and no severity.
+
+Close the file with an area table: the classes grouped by the files in their
+inventories, two classes in one area when any file appears in both. Return the
+class table only: id, severity, kind, instance count, reviewers, rule cited or
+none, and fix group.
+
+## Fix brief
+
+The shared rules apply. Your input is the list of refuter verdict files, and
+the mutation report when the round had one. Read them. Nobody pastes the
+findings to you.
+
+Fix classes, not instances. For each class, repair every instance in its
+inventory and prove nothing is left with a search whose empty result you
+quote. Commit each refuter's failing test together with the fix that turns it
+green.
+
+Your brief may name a fix group: a worktree path, a group id and only that
+group's verdict files. Then work in that worktree and touch only the files in
+your classes' inventories and the tests beside them. A fix that needs another
+file is reported as not fixed with the reason `crosses group`. In group mode,
+finish with every verification test in your group green, run one file at a
+time. Run no typecheck, package suite or gate, because other groups run beside
+you.
+
+A confirmed finding that also reproduces on the base branch is a candidate
+issue, unless its repair stays inside lines this branch already changes.
+
+With no group named, end the pass with the repository's own checks green
+again, the verification tests passing, and the comments and docs next to
+changed behavior brought back in line.
+
+Write `build-reports/round-<n>-fix.md`, or `round-<n>-fix-<group>.md` in
+group mode. Name every briefed item and its outcome: fixed, with the green
+test and the hunks, or not fixed, with the reason. An item the report does not
+name counts as not fixed. A green suite is not a report.
+
+## Release brief: sync and push
+
+The shared rules apply. Your inputs are the state file path, the branch and
+the instructions-file pointer. You run no write command against the tracker
+or the git host beyond the push.
+
+Fetch the base branch, then rebase the branch onto it. Merge instead once the
+branch is pushed and someone else may hold it. Resolve every conflict on the
+branch, never in a web editor.
+
+A migration this branch adds whose version is at or below the newest one on
+the base branch is renamed to the current UTC time, with every reference to
+its file updated.
+
+Run the repository's own pre-push checks and tests, as its instructions file
+names them, in the foreground with the maximum timeout. Leave any mutation
+tool off: the review ran it over these lines already. Then run any check the
+repository runs only in CI, when the diff touches its domain, each in the
+foreground, and quote every result in your report. A check this machine cannot
+run is named in the report with the reason. A check that fails is a red gate,
+and you never push over it. Then push. The hooks run, and you never bypass
+them.
+
+When your brief says this is a resync of a branch already pushed and reviewed,
+the surface is the merge's diff, not the branch's. Run the extra checks only
+when that diff reaches their domain, and say which ones the resync did not
+need and why.
+
+Write `build-reports/release.md` naming every conflict you resolved and every
+file the sync moved that the review had already cleared. The orchestrator acts
+on that second list, so do not omit a file because the move looked harmless.
+
+## Release brief: CI and mergeability
+
+The shared rules apply. Your inputs are the branch and the pull request
+number.
+
+Watch the pull request's checks until they reach a conclusive state, by
+watching them or by a bounded poll. Any check that waits on results recorded
+after the session ends stays pending for the whole run. Leave it out of the
+wait. CI is conclusive when every other check has finished. Right after a pull
+request opens, "no checks reported" is ambiguous, not green. Query again over
+a short window before believing it.
+
+Confirm mergeability, and query again while it reads unknown.
+
+Write the quoted command output to `build-reports/release.md`. Return at most
+ten lines naming the CI conclusion, the mergeability and every failed check.
+
+## Evidence brief
+
+The shared rules apply, and the emitting-evidence skill governs the emit
+mechanics. Your inputs are the issue, the pull request number, the criteria
+that declare a proof form, and the instructions-file pointer.
+
+Run the app and drive the feature by hand. A screenshot or video is taken in a
+real browser against the running application, reached through its own routes
+by a signed-in user, inside its real shell and theme. Never capture a test
+render, a jsdom dump or a standalone file of a component. It shows neither what
+a user sees nor that the page works. Seed what the page needs through the
+application's own paths. When a state cannot be reached that way, the criterion
+is not evidenced, and `evidence.md` says why. Before emitting, look at each
+capture: it shows the application's navigation and real rows.
+
+For each criterion, put the capture in a script under
+`build-reports/evidence/` and run the script. A later fix can invalidate what
+you captured, and regenerating it must be one command. The scripts go when the
+run's report directory goes. The emitted artifacts outlive the run.
+
+Emit each artifact with `outerlayer emit artifact ... --for <criterion id>
+--pr <number>`. Always pass `--pr`. Regenerate with `--replaces` any evidence
+the tree has since invalidated. Then run `outerlayer sync`.
+
+Write `build-reports/evidence.md` naming every criterion with its artifact, or
+with the reason none could be produced. A criterion you could not evidence is
+a result, not a gap to leave silent.

package/skill-pack/template/build/references/criteria-judge.md

@@ -0,0 +1,91 @@
+# Criteria judge
+
+Read this when the release phase spawns you. You are a fresh-context agent,
+never the implementer. You judge whether each criterion in the issue is
+actually proven by the test that cites it, not merely joined to one by id. For
+a criterion that declares an artifact proof, you note that an artifact is
+needed.
+
+## Contents
+
+- Inputs
+- Steps
+- Rubric
+- Output
+- Guardrails
+
+## Inputs
+
+The orchestrator gives you the worktree path (run every command there), the
+base ref, the pull request number, the path of the build's state file, and the
+path to write your report to. On a large issue it gives you one group of criteria instead.
+Judge only that group. Other judges handle the rest.
+
+## Steps
+
+1. Read the criteria from the build's state file, under `criteria.list`. They
+   are the item's recorded list. If the state file lacks `criteria`, read the
+   `criteria` array in `criteria.json` in the build-reports directory. When
+   `criteria.source` is `item`, the item already had a recorded list that no
+   command returns, so `list` is empty. Judge `criteria.issueReading` instead,
+   and say in the report that it is the issue's reading, whose ids may differ
+   from the item's recorded list. Each has an id
+   and a text, and the text is usually a Given, When and Then. Judge every criterion you were given,
+   including one no line of the diff touched. A criterion with `proof: null`
+   is proven by a citing test or any artifact bound to its id.
+2. For each criterion, find its citing tests. Search the test files for its
+   id. A raw text match is not yet a citation. The convention is a comment such
+   as `// proves <id>` directly above the test, or a test that names the id.
+   An id that appears only as sample data a test uses as input, never as a proof
+   claim, is not a citation. Skip that hit.
+3. A criterion that declares `(proof: screenshot)`, `(proof: video)`,
+   `(proof: report)`, `(proof: log)` or `(proof: file)` is `not-judged`, with
+   the reason "artifact proof; an artifact bound to this id must be attached to
+   the pull request, which this judge cannot see from the worktree".
+4. A criterion with no proof annotation and no citing test is `not-satisfied`,
+   with the reason "no test cites this criterion".
+5. Otherwise, read every citing test's block, the test itself plus its
+   enclosing group names, and judge it against the rubric.
+
+## Rubric
+
+A criterion is satisfied only when a test asserts the observable outcome its
+Then clause states, under the Given and When conditions it states, with an
+assertion that would fail if that outcome did not hold.
+
+It is not satisfied when the test only cites the id, asserts something weaker
+than the stated outcome, mocks away the very behavior the criterion is about,
+or has no assertion bearing on the outcome, even when it cites the id.
+
+When unsure, record `not-satisfied` and state the doubt in the reason. A silent
+pass is worse than a wrong-looking fail a person can overrule.
+
+## Output
+
+Write an HTML report to the path you were given. It has one row per criterion:
+the id, the verdict (`satisfied`, `not-satisfied` or `not-judged`), and a
+reason of one to three sentences, with no preamble, that quotes the decisive
+assertion or names what is missing. Put a summary line at the top with the
+count of each verdict. The report must open in a browser as a single file with
+no external assets.
+
+Then print a table of id, verdict and the first line of the reason, and end
+with exactly one line: `result: pass` or `result: fail`. Fail when any
+criterion is `not-satisfied`.
+
+## Guardrails
+
+Judge every criterion at the same depth. Read the cited test's assertions and
+compare them to the criterion's own Then clause, every time. A well-worded
+citing comment that restates the criterion is a hint about what to look for,
+never a substitute for reading the assertion beneath it. A citation can be
+wrong or stale. Never shortcut to "many others looked fine, so the rest
+probably are."
+
+A long run is expected, and is no reason to sample. Work through the list in
+order, and rewrite the report after each batch so a run that stops partway
+still leaves a readable report.
+
+Edit no file but the report. Do not fix a test, do not touch the issue, and do
+not run `outerlayer emit`. That step belongs to the orchestrator once it holds
+the report.

package/skill-pack/template/build/references/evidence.md

@@ -0,0 +1,42 @@
+# Phase 6: manual test and evidence
+
+Read this when the pull request opens. The evidence agent starts then, in the
+same wave as the CI watch. Everything after it in this file runs once CI is
+conclusive and the evidence agent has returned. This is the last phase, and it
+ends the run: it deletes the state file and the report directory. The evidence
+brief is in [agent-briefs.md](agent-briefs.md). Read every value from an
+earlier phase from the state file.
+
+## The phase
+
+The orchestrator does not run the app, drive a browser or emit an artifact
+itself. Spawn one evidence agent in a fresh context on the Evidence brief, with
+the issue, the pull request number, the criteria that declare a proof form, the
+instructions-file pointer and the emitting-evidence skill.
+
+A criterion that declares `proof: screenshot` needs a screenshot bound to its
+id. One that declares `proof: video` needs a video. A screenshot never
+satisfies `proof: video`. A criterion with no proof form is proven by its
+test, and needs no artifact.
+
+When a commit lands on the branch after the evidence agent captured, decide for
+each capture from that commit's diff. A capture is stale when the diff touches
+a file the capture's subject runs through: the feature's own files, the shared
+code they import, a migration or schema behind them, or a test the capture is a
+log of. A sync that brings in only files the feature never reaches leaves the
+capture valid. Spawn the evidence agent again with the stale list. It reruns
+their scripts and emits each with `--replaces`. The final report names the
+commit and every capture with its call, kept or regenerated. A commit that
+lands after this call reopens it. Never drive the browser yourself.
+
+Re-read the pull request's evidence comment. Resolve or escalate every row that
+needs attention. A row is resolved when a re-read shows it, not when the fixing
+command exits. If no evidence comment exists, report that observation with the
+time, never a belief.
+
+End the report to the user with every candidate issue from every stage: title,
+one line and target repository. Or write "no candidate issues". Hand them over.
+Do not ask which to file, and do not file any. The user takes the ones worth
+filing to `/spec`. List every assumption an agent stated.
+
+Then delete the state file and the `build-reports/` directory.

package/skill-pack/template/build/references/release.md

@@ -0,0 +1,74 @@
+# Phase 5: sync and pull request
+
+Run this once the review loop reaches zero confirmed blocking findings. The
+release briefs are in [agent-briefs.md](agent-briefs.md). Read every value
+from an earlier phase, such as the tier verdict or the branch, from the state
+file, not from the transcript.
+
+## Sync and push
+
+The orchestrator does not sync, run the gate, push or watch CI itself. Spawn
+one release agent in a fresh context on the "sync and push" brief, with the
+state file path, the branch and the instructions-file pointer. A check that
+fails there has the standing of a red gate and returns to the review phase's
+remaining budget. If its report names files the sync moved that the review had
+already cleared, run one check round on the rebased diff before going on.
+
+## Open the pull request
+
+Open a scoped pull request that closes the issue. The body carries the
+problem, the change, how to verify it, and, when the change alters what a user
+sees or does, a link to each documentation file added or changed. It carries
+no telemetry, round tables or reviewer roles. Those go in the final report.
+
+Run the reader pass on the title and body before opening, and after any later
+edit. Add an "Unverified, non-blocking" section to the review report when
+classes were left unrefuted.
+
+The moment the pull request exists, declare it to the work item from this
+session:
+
+    outerlayer work pr <number>
+
+A pull request belongs to a work item only through a declaration from a
+session on that item. Nothing else links it, not the issue it closes and not
+its branch. Without the declaration the item shows no pull request, no
+evaluation and no evidence. Check that the command reports the link as created
+or already present before going on. A CLI that does not know the command needs
+refreshing, and the final report names that as a blocker.
+
+## Judge the criteria
+
+When the issue has criteria, spawn one fresh agent on
+[criteria-judge.md](criteria-judge.md), with the worktree path, the base ref,
+the pull request number, the path of the build's state file, and a report
+path under `build-reports/`. Above forty
+criteria, spawn one judge per group of about forty in the same wave, each with
+its own report path, and merge their results by concatenation.
+
+The judge writes an HTML report with one verdict per criterion. Emit it:
+
+    outerlayer emit artifact <judge-report>.html --for acceptance-criteria --caption "Each criterion judged against the test that cites it"
+
+Then run `outerlayer sync`. List every unsatisfied criterion in the final
+report. A criterion that declares a proof form such as a screenshot or video is
+proven only by an artifact bound to it on the pull request. The judge cannot
+see that, so confirm each has an artifact of the declared kind, and emit any
+that is missing in the evidence phase. When the issue has no criteria, no judge
+runs and no judge report is emitted.
+
+## Watch CI
+
+With the pull request open, spawn two agents in the same wave. The release
+agent runs again on the "CI and mergeability" brief with the pull request
+number. The evidence agent starts as [evidence.md](evidence.md) describes. The
+manual test needs only the pull request number, and CI never reads the
+captures, so the two waits overlap.
+
+Act on the release agent's return. A failed check has the standing of a red
+gate: fix it within the review phase's remaining budget or escalate. Never
+carry it into phase 6. A persistent unknown mergeability escalates. A
+conflict means one more sync through the release agent, told it is a resync so
+it gates the merge's diff and not the branch's. A second conflict escalates.
+Any fix or sync that lands after the evidence agent captured goes through
+phase 6's late-commit rule.