@orkestrel/scaffold 0.0.107 → 0.0.109

package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts

@@ -0,0 +1,389 @@
+// Check a Vitest JSON report against named red and green cases. Run from the checkout root:
+//   node .agents/skills/orkestrel-parallel/scripts/cases.ts --report FILE.json [--passed NAME ...] [--failed NAME ...]
+// The report is Vitest's `--reporter=json` output. A name matches every case whose full name (its
+// `describe` titles and its own title, joined by spaces) or whose own title equals it exactly; a name
+// that opens with `--` cannot be given. Each `--passed NAME` requires every case it matches to have
+// passed and each `--failed NAME` requires every one to have failed; a name that matches no case is
+// missing. A failed case that no name matches is refused, so a run that fails more than the request
+// expected reads as a difference. A test file that failed with no failed case (it did not collect,
+// or a hook threw) is an unnamed failure named by its file, and a report whose `success` is false
+// while no case and no file failed is a difference too. Name no case to require a report with no
+// failure. Both flags repeat and a name may not be given to both. The script prints one summary
+// line, one line per difference, and `ok` or `differences=N`. The script refuses a flag it does not
+// read, the `--flag=value` form included, and names an unknown flag before a flag given with no
+// value. Exit 0 when the report matches the names, 3 when it does not, 2 when the report cannot be
+// read as a Vitest report, 64 on usage.
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { relative } from 'node:path'
+
+/** Lists the flags that take a value. */
+export const VALUE_FLAGS: readonly string[] = ['--report', '--passed', '--failed']
+
+/** Lists every flag the script reads, value flags and switches alike. */
+export const FLAGS: readonly string[] = VALUE_FLAGS
+
+/** Holds the usage line printed when a call names no report. */
+export const USAGE =
+	'usage: cases.ts --report FILE.json [--passed NAME ...] [--failed NAME ...]; --passed and --failed repeat'
+
+/** Describes one test case a report holds. */
+export interface Case {
+	readonly file: string
+	readonly fullName: string
+	readonly title: string
+	readonly status: string
+}
+
+/**
+ * Names the value flags a caller gave with no value, at any occurrence.
+ *
+ * @param argv - The arguments after the script path.
+ * @param names - The flags that take a value.
+ * @returns Each named flag that appears last or is followed by another flag, in argument order.
+ */
+export function readMissingFlags(
+	argv: readonly string[],
+	names: readonly string[],
+): readonly string[] {
+	return names.filter((name) =>
+		argv.some((argument, index) => argument === name && isMissingValue(argv, index)),
+	)
+}
+
+/**
+ * Checks whether the argument after a flag is absent or is another flag.
+ *
+ * @param argv - The arguments after the script path.
+ * @param index - The position of the flag.
+ * @returns True when no value follows the flag; false otherwise.
+ */
+export function isMissingValue(argv: readonly string[], index: number): boolean {
+	const value = argv[index + 1]
+	return value === undefined || value.startsWith('--')
+}
+
+/**
+ * Names the flags a caller gave that the script does not read.
+ *
+ * @remarks
+ * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
+ * scan.
+ *
+ * @param argv - The arguments after the script path.
+ * @param flags - Every flag the script reads, value flags and switches alike.
+ * @returns Each argument that opens with `--` and is not a read flag, in argument order.
+ */
+export function readUnknownFlags(
+	argv: readonly string[],
+	flags: readonly string[],
+): readonly string[] {
+	const end = argv.indexOf('--')
+	return (end === -1 ? argv : argv.slice(0, end)).filter(
+		(argument) => argument.startsWith('--') && !flags.includes(argument),
+	)
+}
+
+/**
+ * Reads every value that follows a repeatable flag.
+ *
+ * @param argv - The arguments after the script path.
+ * @param name - The flag, such as `--passed`.
+ * @returns The values in order, empty when the flag never appears.
+ */
+export function readOptions(argv: readonly string[], name: string): readonly string[] {
+	return argv.flatMap((argument, index) => {
+		const value = argv[index + 1]
+		return argument === name && value !== undefined && !value.startsWith('--') ? [value] : []
+	})
+}
+
+/**
+ * Reads the arguments that are neither a flag nor the value of a value flag.
+ *
+ * @param argv - The arguments after the script path.
+ * @param valueFlags - The flags that take a value.
+ * @returns The positional arguments in order.
+ */
+export function readPositionals(
+	argv: readonly string[],
+	valueFlags: readonly string[],
+): readonly string[] {
+	return argv.filter(
+		(argument, index) => !argument.startsWith('--') && !valueFlags.includes(argv[index - 1] ?? ''),
+	)
+}
+
+/**
+ * Checks whether a value is a non-null, non-array object.
+ *
+ * @param value - The value to inspect.
+ * @returns True if the value is an object other than null or an array; false otherwise.
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Quotes an untrusted text for a diagnostic, JSON-encoded and cut to a bounded length.
+ *
+ * @param text - The text to quote.
+ * @returns The JSON string literal of the text, ending in an ellipsis inside the quotes when cut.
+ */
+export function quote(text: string): string {
+	return JSON.stringify(text.length > 120 ? `${text.slice(0, 120)}…` : text)
+}
+
+/**
+ * Reads one assertion result of a report as a case.
+ *
+ * @param file - The test file the result belongs to.
+ * @param result - The parsed JSON value of one assertion result.
+ * @returns The case as a one-member list, or an empty list when the result lacks a title or status.
+ */
+export function readCase(file: string, result: unknown): readonly Case[] {
+	if (!isRecord(result)) return []
+	const { title, status, fullName, ancestorTitles } = result
+	if (typeof title !== 'string' || typeof status !== 'string') return []
+	const ancestors = Array.isArray(ancestorTitles)
+		? ancestorTitles.filter((member) => typeof member === 'string')
+		: []
+	return [
+		{
+			file,
+			title,
+			status,
+			fullName: typeof fullName === 'string' ? fullName : [...ancestors, title].join(' '),
+		},
+	]
+}
+
+/**
+ * Reads the cases of a Vitest JSON report.
+ *
+ * @param report - The parsed JSON value of the report.
+ * @returns Every case in file order, or undefined when the value is not a Vitest report: an object
+ * whose `testResults` is an array.
+ */
+export function readCases(report: unknown): readonly Case[] | undefined {
+	if (!isRecord(report) || !Array.isArray(report.testResults)) return undefined
+	return report.testResults.flatMap((suite): readonly Case[] => {
+		if (!isRecord(suite) || !Array.isArray(suite.assertionResults)) return []
+		const file = typeof suite.name === 'string' ? suite.name : ''
+		return suite.assertionResults.flatMap((result) => readCase(file, result))
+	})
+}
+
+/**
+ * Reads the test files of a report that failed with no failed case.
+ *
+ * @param report - The parsed JSON value of the report.
+ * @returns The `name` of each `testResults` entry whose `status` is `failed` and whose assertion
+ * results hold no failed case, in file order; an empty text stands for an entry with no name.
+ */
+export function readFailedFiles(report: unknown): readonly string[] {
+	if (!isRecord(report) || !Array.isArray(report.testResults)) return []
+	return report.testResults.flatMap((suite): readonly string[] => {
+		if (!isRecord(suite) || suite.status !== 'failed') return []
+		const results = Array.isArray(suite.assertionResults) ? suite.assertionResults : []
+		if (results.some((result) => isRecord(result) && result.status === 'failed')) return []
+		return [typeof suite.name === 'string' ? suite.name : '']
+	})
+}
+
+/**
+ * Checks whether a report states that the run did not succeed.
+ *
+ * @param report - The parsed JSON value of the report.
+ * @returns True when the report is an object whose `success` is `false`; false otherwise.
+ */
+export function isUnsuccessful(report: unknown): boolean {
+	return isRecord(report) && report.success === false
+}
+
+/**
+ * Checks whether a name matches a case.
+ *
+ * @param entry - The case.
+ * @param name - The name from `--passed` or `--failed`.
+ * @returns True when the name equals the case's full name or its own title; false otherwise.
+ */
+export function matchesCase(entry: Case, name: string): boolean {
+	return entry.fullName === name || entry.title === name
+}
+
+/**
+ * Judges the cases of a report against the names a caller gave.
+ *
+ * @param cases - The report's cases.
+ * @param passed - The names that must have passed.
+ * @param failed - The names that must have failed.
+ * @param base - The directory the file names in each difference are written relative to.
+ * @returns Each difference in order: missing names, wrong statuses, then failed cases no name
+ * matches; empty when the report matches.
+ */
+export function judgeCases(
+	cases: readonly Case[],
+	passed: readonly string[],
+	failed: readonly string[],
+	base: string,
+): readonly string[] {
+	const expectations = [
+		...passed.map((name) => ({ name, status: 'passed' })),
+		...failed.map((name) => ({ name, status: 'failed' })),
+	]
+	const named = expectations.flatMap((expectation) => {
+		const matches = cases.filter((entry) => matchesCase(entry, expectation.name))
+		if (matches.length === 0) return [`missing: ${quote(expectation.name)} matches no case`]
+		return matches
+			.filter((entry) => entry.status !== expectation.status)
+			.map(
+				(entry) =>
+					`status: ${quote(entry.fullName)} is ${entry.status}, expected ${expectation.status}${describeFile(base, entry.file)}`,
+			)
+	})
+	const unnamed = cases
+		.filter(
+			(entry) =>
+				entry.status === 'failed' &&
+				!expectations.some((expectation) => matchesCase(entry, expectation.name)),
+		)
+		.map((entry) => `unnamed failure: ${quote(entry.fullName)}${describeFile(base, entry.file)}`)
+	return [...named, ...unnamed]
+}
+
+/**
+ * Judges the failures a report holds outside its cases.
+ *
+ * @param cases - The report's cases.
+ * @param failedFiles - The test files that failed with no failed case, from {@link readFailedFiles}.
+ * @param unsuccessful - Whether the report states that the run did not succeed.
+ * @param base - The directory the file names in each difference are written relative to.
+ * @returns One unnamed failure per failed file; or, when no file and no case failed yet the report
+ * is not successful, one unnamed failure for the report; empty otherwise.
+ */
+export function judgeFailures(
+	cases: readonly Case[],
+	failedFiles: readonly string[],
+	unsuccessful: boolean,
+	base: string,
+): readonly string[] {
+	if (failedFiles.length > 0) {
+		return failedFiles.map(
+			(file) =>
+				`unnamed failure: ${file === '' ? 'a test file' : quote(relativeFile(base, file))} failed with no failed case`,
+		)
+	}
+	return unsuccessful && cases.every((entry) => entry.status !== 'failed')
+		? ['unnamed failure: the report is not successful, yet no case and no file in it failed']
+		: []
+}
+
+/**
+ * Writes a test file path relative to a directory.
+ *
+ * @param base - The directory the path is written relative to.
+ * @param file - The test file path from the report.
+ * @returns The relative path with forward slashes.
+ */
+export function relativeFile(base: string, file: string): string {
+	return relative(base, file).split('\\').join('/')
+}
+
+/**
+ * Describes the file a case belongs to, written relative to a directory.
+ *
+ * @param base - The directory the path is written relative to.
+ * @param file - The test file path from the report.
+ * @returns ` in <path>` with forward slashes, or an empty text when the report names no file.
+ */
+export function describeFile(base: string, file: string): string {
+	return file === '' ? '' : ` in ${relativeFile(base, file)}`
+}
+
+/**
+ * Counts the cases that carry a status.
+ *
+ * @param cases - The report's cases.
+ * @param status - The status, such as `passed`.
+ * @returns How many cases have exactly that status.
+ */
+export function countStatus(cases: readonly Case[], status: string): number {
+	return cases.filter((entry) => entry.status === status).length
+}
+
+/**
+ * Reads a report file as JSON.
+ *
+ * @param path - The report file.
+ * @returns The parsed value, or undefined when the file is not readable JSON.
+ */
+export function readReport(path: string): unknown {
+	try {
+		return JSON.parse(readFileSync(path, 'utf8'))
+	} catch {
+		return undefined
+	}
+}
+
+/**
+ * Runs the script on its arguments.
+ *
+ * @param argv - The arguments after the script path.
+ * @returns The exit code: 0 when the report matches the names, 3 when it does not, 2 when the report
+ * cannot be read as a Vitest report, 64 on usage.
+ */
+export function main(argv: readonly string[]): number {
+	const unknown = readUnknownFlags(argv, FLAGS)
+	if (unknown.length > 0) {
+		console.error(`cases: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`)
+		return 64
+	}
+	const missing = readMissingFlags(argv, VALUE_FLAGS)
+	if (missing.length > 0) {
+		console.error(`cases: ${missing.join(', ')} given with no value`)
+		return 64
+	}
+	const reports = readOptions(argv, '--report')
+	const path = reports[0]
+	const passed = readOptions(argv, '--passed')
+	const failed = readOptions(argv, '--failed')
+	if (path === undefined || readPositionals(argv, VALUE_FLAGS).length > 0) {
+		console.error(USAGE)
+		return 64
+	}
+	const both = passed.filter((name) => failed.includes(name))
+	if (both.length > 0) {
+		console.error(
+			`cases: ${both.map(quote).join(', ')} given to both --passed and --failed; ${USAGE}`,
+		)
+		return 64
+	}
+	if (!existsSync(path) || !statSync(path).isFile()) {
+		console.error(`cases: ${quote(path)} is not a readable file`)
+		return 2
+	}
+	const report = readReport(path)
+	const cases = readCases(report)
+	if (cases === undefined) {
+		console.error(
+			`cases: ${quote(path)} is not a Vitest JSON report; it needs a "testResults" array (run vitest with --reporter=json)`,
+		)
+		return 2
+	}
+	const differences = [
+		...judgeCases(cases, passed, failed, process.cwd()),
+		...judgeFailures(cases, readFailedFiles(report), isUnsuccessful(report), process.cwd()),
+	]
+	const green = countStatus(cases, 'passed')
+	const red = countStatus(cases, 'failed')
+	console.log(
+		`cases total=${String(cases.length)} passed=${String(green)} failed=${String(red)} other=${String(cases.length - green - red)}`,
+	)
+	for (const difference of differences) console.log(difference)
+	console.log(differences.length === 0 ? 'ok' : `differences=${String(differences.length)}`)
+	return differences.length === 0 ? 0 : 3
+}
+
+if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === import.meta.filename) {
+	process.exitCode = main(process.argv.slice(2))
+}

package/dist/host/agents/skills/orkestrel-polish/SKILL.md

@@ -24,8 +24,8 @@ supposed to produce it. Source-reading review passes a component that renders no
   accessibility snapshot, and an interaction log.
 - Source is corroboration for a mechanism, never the proof that the surface shows it.
 - A claim the portfolio cannot show is unproven, not passed. Say so.
-- The same law governs an externally driven surface: a compatibility claim is proven by
-  driving it with a representative real client, not by its own tests.
+- Prove an externally driven surface's compatibility claim per the `orkestrel-harden` skill's
+  Production hardening → Use real implementations.
 
 ## Select the scope
 
@@ -36,29 +36,25 @@ Choose the smallest scope that satisfies the request:
   re-verdict on the repaired items → independent gates.
 
 A narrow verdict request does not authorize fixes. A polish request authorizes fixing every
-confirmed finding in scope and rebuilding the harness gaps the verdicts expose. A second round
-over the same surface needs an instruction from the user.
+confirmed finding in scope and rebuilding the harness gaps the verdicts expose.
 
 ## Execute the round
 
 1. **Build the portfolio.** Produce the full evidence set with the harness reference, then
-   eyeball every artifact yourself before spending a verdict round on it. An unexamined
-   portfolio buys harness bugs at verdict prices.
+   eyeball every artifact yourself before spending a verdict round on it.
 2. **Seed candidates.** Turn your own mid-integration observations into numbered
-   confirm-or-refute candidates inside the verdict brief. Observations that stay in your
-   head are neither evidence nor findings.
+   confirm-or-refute candidates inside the verdict brief.
 3. **Take independent verdicts** on the SAME portfolio, in the shape
-   § "Return the fixed verdict shape" fixes. The
-   lanes are subjective design fit; objective state truth; and mechanical inventory of
-   copy, classes, icons, and accessibility attributes. This is the surface variant of the
-   review in `.agents/orchestration.md` § Size gate, so its rules bind: each lane is a fresh
-   subagent with a clean context, blind to the others until reconciliation, run once, and no
-   lane is dropped because an engine is dark. A narrow verdict request runs the selected lane once
-   and stops.
+   § "Return the fixed verdict shape" fixes. Judgment runs as the two lanes
+   `.agents/orchestration.md` § Parallelism names: subjective design fit and objective state
+   truth. The mechanical inventory of copy, classes, icons, and accessibility attributes runs as a
+   `checker` lane. This is the surface variant of the review in `.agents/orchestration.md`
+   § Size gate, so its rules bind: each judgment lane is a fresh subagent with a clean context,
+   blind to the other until reconciliation, run once, and no lane is dropped because an engine is
+   dark. A narrow verdict request runs the selected lane once and stops.
 4. **Reconcile.** Confirmed findings get carriers; refuted findings close on the record with
    the evidence that refuted them; conflicts get a dated ruling. Then walk the reconciled
-   list once and name the fix-brief item carrying each finding — a finding with no carrier
-   is a dropped finding, and it will cost the next round.
+   list once and name the fix-brief item carrying each finding.
 5. **Dispatch serialized fix units,** objective lane first because it changes the ground
    truth the subjective lane reads. Each unit records the failing proof before the
    repair — the exact command and its red count — and the same command's green count
@@ -87,7 +83,7 @@ over the same surface needs an instruction from the user.
 
 ## Return the fixed verdict shape
 
-Free-form verdicts cost one reconciliation pass each. Every verdict returns:
+Every verdict returns:
 
 - one line per item, in the brief's numbering:
   - `RENDERED-PROVEN(<capture>)` — the artifact shows it;
@@ -101,8 +97,8 @@ Triage it against the capture reference before it becomes a finding.
 
 ## Accept the result
 
-Do not accept a source-only verdict, a self-audited fix unit, a round without a terminal
-line, or a green claim from the engine that wrote the code. Completion requires:
+Accept per `.agents/orchestration.md` § Acceptance. Refuse a source-only verdict, a self-audited
+fix unit, and a round without a terminal line. Completion requires:
 
 - every confirmed finding fixed or explicitly ruled out of scope on the record;
 - a final portfolio whose captures show the accepted state;

package/dist/host/agents/skills/orkestrel-polish/references/capture-harness.md

@@ -17,9 +17,7 @@ journey-generated and part spawned.
 Apply this section to a spawned harness only.
 
 - Write the harness as one self-contained script that spawns its own children, waits for readiness,
-  does the capture, and kills them before returning.
-- Never leave a child running across calls or expect one to survive its parent. A process started
-  inside one tool call dies with that call's process group.
+  does the capture, and kills them before returning. Spawn, capture, and tear down in one call.
 - Give every child a pinned working directory. A process that resolves assets, configuration, or
   fixtures relative to the current directory dies silently when launched from elsewhere.
 - Pipe child standard error somewhere readable and print it on failure.
@@ -43,33 +41,26 @@ and `orkestrel-journey` fixes how it enters and what it may reach past.
 
 ## Capture the full portfolio
 
-Produce every artifact in the following table each round, for every scenario in scope. The Source
-column names what produces the artifact in the journey run; a spawned harness produces each one
-itself.
-
-| Artifact               | Source in the journey run            | What the artifact must show                                                           |
-| ---------------------- | ------------------------------------ | ------------------------------------------------------------------------------------- |
-| Viewport captures      | `place` across the declared variants | Every breakpoint the surface declares, never one convenient size                      |
-| Theme captures         | `place` across the declared variants | Every theme the surface ships, at every declared viewport                             |
-| Accessibility snapshot | `describeTree` and `describeFocus`   | The rendered roles, names, and states, and the focus order the walk took              |
-| Interaction log        | The journal's `steps`                | Each interaction, its trigger, and the result observed after it                       |
-| Console and error log  | The journal's `output`               | Everything the page emitted, including an uncaught error                              |
-| Statechart outcome     | The harness after a play-all run     | The terminal status, the passed, failed, and total tallies, and each row's own result |
-
-- Require the statechart outcome of every surface that declares the statechart family, and omit the
-  row only where the surface declares none.
-- Read the journey run's per-variant written artifact for the accessibility snapshot and the logs,
-  and cite the statechart harness by its deep link where a lane must watch the widget move rather
-  than read a still of it. `orkestrel-journey` fixes what each holds and what each is named
-  for.
+Produce each of the following every round, for every scenario in scope:
+
+- Viewport captures at every breakpoint the surface declares, and theme captures for every theme it ships at every declared viewport. In the journey run, `place` across the declared variants produces them.
+- The rendered artifact per variant, composed as the `orkestrel-journey` skill's Routing a question → The rendered artifact fixes: the accessibility snapshot, the focus order, the interaction log, and the console and error log.
+- The statechart outcome of every surface that declares the statechart family: the terminal status, the passed, failed, and total tallies, and each row's own result. The harness produces it after a play-all run; cite its deep link where a lane must watch the widget move rather than read a still of it.
+
+A spawned harness produces each artifact itself.
+
 - Shoot the whole surface before selecting or focusing anything inside it. A capture taken after a
   selection reports a duplicate or highlighted artifact that does not exist.
 - Start a keyboard walk from a neutral state, never from an already-focused control, or the log will
   report a broken order no person meets.
 - Name a spawned harness's artifacts so a verdict cites one exactly: scenario, viewport, theme,
   step. The journey run's filename law already does this.
-- Keep the artifacts of each round beside its verdicts. A round judged against the previous round's
-  captures is not a round.
+- Keep the artifacts of each round beside its verdicts.
+- For a journey-generated portfolio, record the capture manifest snapshot the round judges beside
+  its verdicts. Require every judged frame to be current, with its recorded source digests equal
+  to the tree's; recapture every stale judged frame before dispatch. Apply this rule to sittings
+  and checkpoints alike. Admit
+  frames assembled from several runs only when every judged frame is current.
 
 ## Preflight before spending a round
 
@@ -84,8 +75,7 @@ Confirm each of the following:
   to the total;
 - nothing in the console log indicates the harness, rather than the surface, failed.
 
-Repair a portfolio that fails preflight before dispatching it. Never spend a verdict round
-discovering a harness defect.
+Repair a portfolio that fails preflight before dispatching it.
 
 ## Triage missing evidence to the harness first
 

package/dist/host/agents/skills/orkestrel-publish/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: orkestrel-publish
-description: Run an Orkestrel release from layer order to registry confirmation. Use when the user asks to publish a package, to run a fleet-wide release wave, or to recover a release that stalled at the npm approval, and follow it for the per-repository visit, the bump ruling, the layer preparation, the login approval, and the five-minute upload window.
+description: Run an Orkestrel release from layer order to registry confirmation, or adopt a published scaffold release in one consumer. Use when the user asks to publish a package, to run a fleet-wide release wave, to recover a release that stalled at the npm approval, or to adopt a published scaffold release in one repository, and follow it for the per-repository visit, the bump ruling, the layer preparation, the login approval, the upload approval, and the adoption.
 ---
 
 # Publish an Orkestrel release
@@ -14,9 +14,10 @@ description: Run an Orkestrel release from layer order to registry confirmation.
    here.
 2. The reference the moment needs: [wave.md](references/wave.md) before visiting a repository,
    ruling on a bump, or preparing a layer; [window.md](references/window.md) before running
-   `npm login` or any upload.
+   `npm login` or any upload; [adopt.md](references/adopt.md) before one consumer adopts a
+   published scaffold release outside a wave.
 3. The live evidence: the registry's packument for every package in the round, each target's
-   manifest, and the catalog table the contract names as the layer order.
+   manifest, and the catalog table `references/release.md` names as the layer order.
 
 ## Scripts
 
@@ -26,35 +27,20 @@ description: Run an Orkestrel release from layer order to registry confirmation.
 | `scripts/pins.ts`    | `--version PRIOR [--range PRIOR_RANGE ...] [--paths src,tests] [--json]`, run from the package root: lists every line under the paths carrying the prior version literal or a prior range literal, once per line, sweeping a one-comparator range such as `^8.3.0` for its bare version in any form. Exit 0 with no hits, 3 with hits, 64 on usage (no literal, or a flag with no value).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `scripts/swap.ts`    | One mode per run, from any directory: `--pin --consumer DIR --source DIR [--source DIR ...] [--override NAME ...] [--no-build] [--dry-run] [--json]` refuses a source whose packed manifest names a local dependency spec in any dependency field (a `file:` or `link:` prefix, a path start of `.`, `~/`, `/`, `\`, or a drive letter, or a protocol-free archive name ending in `.tgz`, `.tar.gz`, or `.tar` that is not a `user/repo` shorthand), builds and packs each source into `<consumer>/tmp/tarballs/` under a name carrying its SHA-256, records each replaced range in the ledger `pins.json` there, the record of which build the consumer runs, writes each tarball's absolute `file:` spec and each `--override` (repeatable, like `--source`) where oxfmt sorts it, installs, and proves that every pinned source, an override-only one included, is installed with the source's bytes; `--restore --consumer DIR [--package NAME ...] [--json]` puts back each recorded range and override, keeps an `overrides` block that existed before the pin, installs, proves the restored copy, and lists the re-pin arguments, and refuses with 64, before it writes anything, a ledger whose package or override keys are not package names or whose removal would leave `node_modules`; `--status --consumer DIR [--json]` writes nothing and reports drift between the ledger, the manifest, the tarballs, the installed bytes, and the source commits, a manifest spec holding its tarball only when it names the ledger archive's location. `--pin` and `--restore` write a receipt under `tmp/units/`. Exit 0 on success, 1 when a command or a proof failed, 3 when `--status` reports drift, 64 on usage. |
 | `scripts/wave.ts`    | `--visit [--target DIR] [--offline] [--regenerate] [--from STEP] [--to STEP] [--prior VERSION] [--dry-run] [--json] [--out FILE]` runs one repository's visit in the order [wave.md](references/wave.md) § Visit a repository fixes (pin, commit, overwrite, verify, install, pins, format, record, gates, compare), stops at the first failing step, journals each executed step's full output under the target's `tmp/units/wave/` when the work tree ignores `tmp/` and names the journal in its row, and prints each step's exit (a failed step names the `code: message` refusal or the `note` a JSON verb writes on stdout, else the last stderr lines), the bump ruling (the rebuilt dist against the published tarball, and the final runtime dependency set against the published manifest), and a row for `.orkestrel/release.md`; `--prior` names the version a pre-ruled bump replaced so the self-pin sweep finds it; `--plan` prints the packages by layer from the catalog table. An install that fails `ERESOLVE` names the rerun command, and `--regenerate` replaces the lockfile and `node_modules` from the manifest under the refusals and proof [wave.md](references/wave.md) § Regenerate a lock the install cannot move states; `record` commits the overwrite's writes as `Overwrite with scaffold VERSION`. Exit 0 when every step passed, 1 when one failed, 2 when a reading failed, 64 on usage, including `--regenerate` with `--plan`.                                                                                                                                                                                                                                                        |
-| `scripts/window.ts`  | `--whoami [--wait SECONDS]` reads or polls `npm whoami`; `--login` prints the operator's login command and polls `whoami` until it answers; `--publish DIR... --otp CODE` refuses a batch whose nearest `.git` entry is a file, including ancestor entries, with exit 3 before contacting npm; it names a linked worktree's primary clone or identifies a submodule, then uploads back to back with `npm publish --ignore-scripts --otp`, journals each upload under `tmp/units/`, stops at the first refusal naming where to resume, and confirms each accepted version against the registry; `--confirm NAME@VERSION...` re-reads the registry until it serves the version. Exit 0 on success, 3 when not.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `scripts/window.ts`  | `--whoami [--wait SECONDS]` reads or polls `npm whoami`; `--login` prints the operator's login command and polls `whoami` until it answers; `--publish DIR... --otp CODE` refuses a batch whose nearest `.git` entry is a file, including ancestor entries, with exit 3 before contacting npm; it names a linked worktree's primary clone or identifies a submodule, then uploads back to back with `npm publish --ignore-scripts --otp`, journals each upload under `tmp/units/`, stops at the first refusal naming where to resume, and confirms each accepted version against the registry; `--confirm NAME@VERSION...` re-reads the registry until it serves the version. Exit 0 on success, 3 when not, 64 on usage.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 
-The user's current instruction wins. `references/release.md` owns the credential
-and authorization law; nothing here weakens it.
-
-## The boundary with the contract
-
-`references/release.md` binds every release, and this skill does not
-repeat it. Read that section for the credential and approval law, the long-running-command
-binding, the serialization of uploads, the tarball swap that serves a consumer whose dependency
-has not published, what a bump obliges downstream, and where the layer order comes from.
-
-This skill carries what an operator needs while a release is running: the per-repository visit,
-the bump ruling, the preparation order, the login and approval mechanics, and the window.
-
-Where the skill and the contract disagree, the contract wins. Report the drift instead of
-following the skill.
+The user's current instruction wins. `references/release.md` binds every release: the credential and authorization law, the upload serialization, the tarball swap, what a bump obliges downstream, and the layer order. Nothing here weakens it. Where this skill disagrees with it, report the drift instead of following the skill.
 
 ## Run the release
 
 1. **Name the round.** List the packages the release covers, and group them into layers with
-   `node .agents/skills/orkestrel-publish/scripts/wave.ts --plan`, which reads the contract's
-   layer order from the catalog table.
+   `node .agents/skills/orkestrel-publish/scripts/wave.ts --plan`, which reads the layer order
+   from the catalog table.
 2. **Take the registry evidence.** Read what the registry serves for every package in the round.
    Derive each pin from that reading, never from a local manifest.
 3. **Visit each repository.** Run `node .agents/skills/orkestrel-publish/scripts/wave.ts --visit --target <repository>`,
    which runs the visit in [wave.md](references/wave.md) in its stated order and stops at the first
-   failing step; repair that step by hand and re-run from it with `--from`; for an `ERESOLVE`, follow [wave.md](references/wave.md) § Regenerate a lock the install cannot move. Run visits in parallel
-   slices of disjoint repositories, each slice serial inside itself.
+   failing step; repair that step by hand and re-run from it with `--from`; for an `ERESOLVE`, follow [wave.md](references/wave.md) § Regenerate a lock the install cannot move.
 4. **Rule on each package's bump.** Take the visit's comparison and range reading; repeat `compare.ts` only after the artifact changes or an unanswered result. Apply the triggers in [wave.md](references/wave.md) § Rule on
    the bump; `references/release.md` § What a bump obliges owns the blast radius.
 5. **Prepare the whole layer before authenticating**, in the order [wave.md](references/wave.md)
@@ -69,8 +55,8 @@ following the skill.
 8. **Close the layer from the registry, then prepare the next**, per [wave.md](references/wave.md)
    § Prepare a layer.
 
-Run that sequence for every layer, from the registry reading to the registry close. Refresh the
-registry evidence between layers rather than carrying the previous round's reading forward.
+Run that sequence for every layer, from the registry reading to the registry close;
+[wave.md](references/wave.md) § Refresh the registry between layers owns the refresh.
 
 ## Accept the release
 
@@ -81,7 +67,7 @@ Completion requires:
 - every obligation `references/release.md` § What a bump obliges places on a published package's dependents has closed as
   that section requires;
 - every tarball swap is restored per `references/release.md` § Fix a dependency before it publishes, and no target
-  repository is left holding an uncommitted bump or an unpushed commit;
+  repository is left holding an uncommitted bump or an unpushed commit the user has not held;
 - every gate that proved a package ran outside the window and against the artifact that shipped;
 - every gate red at a package's baseline for a cause `ROADMAP.md` already carries is recorded as a
   standing reading beside the package's row with its carrier, and the release report names it. A

package/dist/host/agents/skills/orkestrel-publish/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: 'Publish Orkestrel Release'
-  short_description: 'Run a release in layer order through the npm approval window'
-  default_prompt: 'Use $orkestrel-publish to run the release - layer order, per-repository visit, bump ruling, layer preparation, login approval, upload window, and registry confirmation.'
+  short_description: 'Run a release in layer order through the npm approval, or adopt a scaffold release in one consumer'
+  default_prompt: 'Use $orkestrel-publish to run the release - layer order, per-repository visit, bump ruling, layer preparation, login approval, upload approval, and registry confirmation - or to adopt a published scaffold release in one consumer.'