@clossys/launcher 0.1.5 → 0.3.1

package/README.md

@@ -8,6 +8,46 @@ The hub inventories where Foundry packages are installed and coordinates
 engagement. It is not a product application and does not receive a dump of
 the catalogue.
 
+## Layout: the `clossys/` folder
+
+Every apply writes to one visible `clossys/` folder in the target repository —
+never a hidden dot-folder for anything a person might want to see. A generated
+`README.md` at the root of `clossys/` is an index of which `clossys/<role>/` folders are active and what
+each holds; it is rewritten on every run, never hand-edited. `clossys/.state/`
+holds machine files only — the hub marker, the inventory, and the skills
+manifest (below) — visible so it is easy to find, but still not a place to
+edit by hand. Other roles' folders (`clossys/strategist/`, `clossys/writer/`,
+and so on) are written by their own packages, not by launcher.
+
+A hub created before this layout existed kept its marker and inventory under
+a hidden `.clossys/`. Resume detects that automatically and migrates both
+files to `clossys/.state/`, removing the old directory, and reports the move
+in the health report. If somehow both a `.clossys/` and a `clossys/.state/`
+hub state exist at once, launcher refuses rather than guessing which one is
+current — remove one and resume again.
+
+## Conversation contract
+
+Every composed skill carries one shared conversation contract: lead with a
+plain-language status, always state a recommendation, ask exactly one
+question with the recommended option labelled first, and say what happens
+next. Launcher packs this contract at build time and injects it into each
+composed skill in place of that skill's own "how we work together" and "one
+question at a time" sections, at the same position — so an installed or
+catalogue skill's own wording never has to drift from it.
+
+## Skills manifest and freshness
+
+Every apply writes a skills manifest recording each composed skill's source
+(`installed` or `catalogue`), version, and a content digest. The health
+report states how many composed skills are out of date against the live
+`@clossys/launcher` version (catalogue-sourced skills are only ever as fresh
+as the launcher release that packed them) and how many were retired this
+run. Retirement means: a skill this directory's own manifest previously
+listed is no longer composed (its source disappeared), so launcher removes
+its composed output and host discovery links — and only that. It never
+touches a skill it did not itself write.
+
 ## Health report and staleness
 
 After create, resume, or appoint — and on every resume — the command prints
@@ -16,11 +56,17 @@ a read-only health report. It scans all four dependency buckets
 `peerDependencies`) for the Advisor pin and for extra `@clossys/*` names.
 When the live registry version is known, each pin is graded against it: a
 pin older than live is a `stale pin` finding and marks the report
-**degraded**. Exit stays 0 on resume (the report is advisory); adopt prints
-the same report and an unparseable pin-versus-live comparison is noted as
-indeterminate rather than stale. `checkInventoryEntries()` additionally
-validates hub inventory ids read-only, marking ids whose repository no
-longer resolves (skipped with a note when `gh` is unavailable).
+**degraded**. The report is also degraded when Advisor is missing, dual-pinned,
+or present in any bucket other than `devDependencies`, and when apply skipped
+one or more inventoried roster targets (missing sibling clone, origin mismatch,
+and similar — the same `skill roster skipped` lines in the report). Per-package
+skill sources missing from the catalogue are noted but do not by themselves mark
+degraded. Exit stays 0 on resume
+(the report is advisory); adopt prints the same report and an unparseable
+pin-versus-live comparison is noted as indeterminate rather than stale.
+`checkInventoryEntries()` additionally validates hub inventory ids read-only,
+marking ids whose repository no longer resolves (skipped with a note when
+`gh` is unavailable).
 
 
 ## Install
@@ -31,13 +77,25 @@ The get-started command is the package name:
 npx @clossys/launcher
 ```
 
+`npx` caches the resolved version, so a plain `npx @clossys/launcher` can
+keep running an old one. Because a catalogue-sourced skill is only ever as
+fresh as the launcher release that packed it (see "Skills manifest and
+freshness" above), run:
+
+```bash
+npx @clossys/launcher@latest
+```
+
+when the health report says a skill is out of date, or whenever you want to
+be sure you are on the current release.
+
 Public npm reads are credentialless. Packages publish to
 `https://registry.npmjs.org`. Do not add a token or private registry
 mapping for `@clossys`. Pin an exact version once you depend on the library
 API:
 
 ```bash
-npm install --save-dev --save-exact @clossys/launcher@0.1.5
+npm install --save-dev --save-exact @clossys/launcher@0.2.0
 ```
 
 ## Talking to the team
@@ -54,11 +112,20 @@ Voices are how you talk in a coding agent; they are not engagement engines. The
 `@clossys-advisor` in chat is its hiring and compatibility voice. Use
 `@clossys-advisor` and `@clossys-<package>` in the hub or in any inventoried
 product repository. Each voice can talk even when that npm package is not pinned
-in that repo. Launcher health notes missing catalogue sources but apply continues.
+in that repo. When composing into a checkout, the launcher reads each skill body
+from that checkout's installed `@clossys/<package>/skill/SKILL.md` when present,
+then from the packed catalogue or a sibling monorepo source. Launcher health
+notes missing catalogue sources but apply continues.
 
 Run `npx @clossys/launcher` again from the hub for a health report and to
-refresh composed voices on sibling inventoried clones. It does not
-`gh repo clone` missing inventory entries—that is not how you talk to the team.
+refresh composed voices on sibling inventoried clones. By default it does
+not `gh repo clone` missing inventory entries -- that is not how you talk to
+the team. `launcher --clone-missing` is the one explicit, approved
+exception (#1179): on resume only, it clones every inventoried repository
+not yet sitting beside the hub, using `cloneMissingInventoryRepositories()`,
+and only those -- an id skipped for any other reason (wrong account, the
+Foundry supplier tree, a mismatched git origin) is left exactly as skipped,
+never attempted.
 
 ## How to run it
 
@@ -72,9 +139,9 @@ silent fallback.
 
 | Current directory | What happens |
 | --- | --- |
-| Empty | Creates `{owner}/workspace` from the in-package skeleton, or clones that hub if it already exists. |
-| Already a hub (generated marker; packed template `skeleton/.clossys/workspace.json`) | Resumes. No new repository. `--inventory` here is refused with a pointer to the appointed hub's own `.clossys/inventory.json`. |
-| Any other GitHub repository you control | Appoints it as the account hub. Keeps the existing name and files. Refuses when the working tree has uncommitted changes (`git status --porcelain` non-empty) — the refusal names the offending remote host when the origin is not on github.com. Refuses when `CLOSSYS_OWNER` names a different account than the repository's github.com origin owner. Writes the hub marker. Leaves an existing `@clossys/advisor` pin in whichever bucket it already occupies; pins live Advisor in `devDependencies` only when missing. Refuses if the generated hub inventory is missing or empty (packed template `skeleton/.clossys/inventory.json`; that generated path does not ship) unless `--inventory <path>` supplies a populated document — or, when the on-disk inventory is already populated and `--inventory` is also supplied, merges the two by repository id (on-disk order first, new ids appended, first occurrence of an id wins). Does not rewrite the lockfile or dump the catalogue. Prints a read-only health report. |
+| Empty | Creates `{owner}/workspace` from the in-package skeleton (package name `@owner/workspace`), or clones that hub if it already exists. |
+| Already a hub (generated marker; packed template `skeleton/clossys/.state/workspace.json`) | Resumes. No new repository. `--inventory` here is refused with a pointer to the appointed hub's own `clossys/.state/inventory.json`. A legacy `.clossys/` hub state is migrated automatically; see "Layout" above. |
+| Any other GitHub repository you control | Appoints it as the account hub. Keeps existing product files. Refuses when the working tree has uncommitted changes (`git status --porcelain` non-empty) — the refusal names the offending remote host when the origin is not on github.com. Refuses when `CLOSSYS_OWNER` names a different account than the repository's github.com origin owner. Writes the hub marker. Pins live `@clossys/advisor` in `devDependencies`, relocating and upgrading any pin left in another bucket. A dedicated `{owner}/workspace` checkout is named `@owner/workspace`; a product repository keeps its package name. Always reads the public Advisor version (needed to pin live and to grade resume health). Refuses if the generated hub inventory is missing or empty (packed template `skeleton/clossys/.state/inventory.json`; that generated path does not ship) unless `--inventory <path>` supplies a populated document — or, when the on-disk inventory is already populated and `--inventory` is also supplied, merges the two by repository id (on-disk order first, new ids appended, first occurrence of an id wins). Does not rewrite the lockfile or dump the catalogue. Prints a read-only health report. |
 
 It does not have to be a brand-new exclusive repository, and it does not
 have to already match a Foundry layout. Informal "workspace-looking" trees
@@ -85,17 +152,23 @@ not install packages.
 
 Do not run this inside the Foundry supplier tree.
 
-Open the resulting folder in your coding agent. Advisor stays read-only
-until you approve a next action. The same command resumes later.
+Open the resulting folder in your coding agent. Talk in ordinary
+sentences. Advisor stays read-only until you approve a next action. A
+yes in chat is permission for that one step only; it is not a lasting
+grant and it does not write git unless a file is saved later. The same
+command resumes later.
 
 ## CLI
 
 ```bash
 launcher
 launcher --inventory path/to/inventory.json
+launcher --clone-missing
 launcher --help
 launcher-check --help
 launcher-check --input observation.json
+launcher-doctor
+launcher-apply-plan --plan plan.json --brief brief.json --repo ./product-checkout
 ```
 
 Exit codes preserve the ternary:
@@ -113,21 +186,137 @@ Exit codes preserve the ternary:
 | Export | Description |
 | --- | --- |
 | `planWorkspace()` | Decides create, resume, or adopt from a cwd observation. Optional `{ inventoryPath }` is the only way to appoint without a populated on-disk inventory. |
-| `applyWorkspacePlan()` | Copies the in-package skeleton or hub marker through a host port and returns a `WorkspaceApplyResult` with health. Composes the same skill voices on the hub and on inventoried sibling checkouts beside it; refreshes stale hub guidance on every path, including resume. Optional `{ skillCatalogueRoot, launcherPackageRoot }` selects where skill bodies are read. |
-| `observeWorkspace()` | Reads `gh`, git remotes, cwd, inventory classification, and the public Advisor version. |
+| `applyWorkspacePlan()` | Copies the in-package skeleton or hub marker through a host port and returns a `WorkspaceApplyResult` with health. Composes the same skill voices (with the shared conversation contract injected) on the hub and on inventoried sibling checkouts beside it; refreshes stale hub guidance and the generated `clossys/` README on every path, including resume; migrates a legacy `.clossys/` hub state automatically. Optional `{ skillCatalogueRoot, launcherPackageRoot, contractPath, liveLauncherVersion }` selects where skill and contract bodies are read and grades skill-manifest staleness. |
+| `observeWorkspace()` | Reads `gh`, git remotes, cwd, inventory classification, hub-state migration status, and the public Advisor version. |
 | `readInventoryRepositories()` | Reads repository ids from a `schemaVersion: 1` inventory document. |
-| `launcherPackageRootFromModule()` | Resolves this package's root from `import.meta.url` so apply can find the packed skill catalogue. |
+| `readLiveLauncherVersion()` | Reads the public `@clossys/launcher` registry version, used only to grade catalogue-sourced skill staleness. |
+| `launcherPackageRootFromModule()` | Resolves this package's root from `import.meta.url` so apply can find the packed skill catalogue and contract. |
 | `parseGitHubRemote()` | Parses a github.com remote and rejects any other host. |
-| `isHubDocument()` | Type guard for the generated hub marker (packed template: `skeleton/.clossys/workspace.json`). |
+| `isHubDocument()` | Type guard for the generated hub marker (packed template: `skeleton/clossys/.state/workspace.json`). |
 | `inspectInventory()` | Classifies inventory JSON as missing, empty, or populated. |
-| `reportHubHealth()` | Read-only pin and inventory report. Does not install or uninstall. |
+| `reportHubHealth()` | Read-only pin, inventory, migration, and skills-manifest report. Does not install or uninstall. |
 | `formatHubHealth()` | Human lines plus a `health:` JSON line for the same report. |
 | `hasAdvisorPin()` | True when a manifest already pins Advisor in any dependency bucket. |
 | `checkInventoryEntries()` | Read-only inventory id validation through `gh repo view` (batched; skips with a note when `gh` is unavailable). |
 | `DEFAULT_REPOSITORY_NAME` | Default new-hub repository name (`workspace`). Used only when creating, never when appointing. |
+| `CLOSSYS_DIR_REL` | Relative path of the one visible per-repository Clossys folder (`clossys`). |
+| `STATE_DIR_REL` | Relative path of the machine-state folder (`clossys/.state`). |
 | `WORKSPACE_MARKER_REL` | Relative path of the hub marker. |
 | `WORKSPACE_INVENTORY_REL` | Relative path of the hub inventory. |
-| `CommandResult` / `CwdObservation` / `DependencyBucket` / `HubDocument` / `HubHealthReport` / `InventoryObservation` / `InventoryValidationEntry` / `InventoryValidationReport` / `PinFinding` / `PinGrade` / `ApplyWorkspaceOptions` / `WorkspaceApplyResult` / `WorkspaceDecision` / `WorkspaceHost` / `WorkspaceObservation` / `WorkspacePlan` / `WorkspaceRefusal` / `WorkspaceState` | Typed host, observation, plan, health, and outcome contracts. |
+| `CLOSSYS_README_REL` | Relative path of the generated index README at the root of `clossys/`. |
+| `LEGACY_STATE_DIR_REL` / `LEGACY_WORKSPACE_MARKER_REL` / `LEGACY_WORKSPACE_INVENTORY_REL` | Pre-#1171 `.clossys/` paths, kept only so resume can detect and migrate them. |
+| `CommandResult` / `CwdObservation` / `DependencyBucket` / `HubDocument` / `HubHealthReport` / `HubMigrationState` / `InventoryObservation` / `InventoryValidationEntry` / `InventoryValidationReport` / `PinFinding` / `PinGrade` / `SkillManifestDocument` / `SkillManifestEntry` / `SkillsManifestSummary` / `ApplyWorkspaceOptions` / `WorkspaceApplyResult` / `WorkspaceDecision` / `WorkspaceHost` / `WorkspaceObservation` / `WorkspacePlan` / `WorkspaceRefusal` / `WorkspaceState` | Typed host, observation, plan, health, and outcome contracts. |
+| `cloneMissingInventoryRepositories()` | Explicit, approved action (#1179): clones every inventoried repository `resolveSisterCloneTargets` skipped for "not beside the hub", and only those. Returns a `CloneMissingOutcome[]`. |
+| `runDoctorChecks()` | Read-only prerequisite checks in fix-in-this-order sequence: git, `gh`, signed in, Node.js, npm, then the advisory coding-agent step. Returns a `DoctorReport`. |
+| `renderDoctorReport()` | Renders a `DoctorReport` one step at a time, the way `launcher-doctor` prints it. |
+| `checkCloudSessionBootstrap()` | Read-only: the three product-repository-layout.json cloud-session-bootstrap checks against a directory. Returns a `CloudBootstrapReport`. |
+| `reportInventoryDrift()` | Compares a declared external inventory against the launcher-written one; reports external-only, launcher-only, and agreeing repository ids. Returns an `InventoryDriftReport`. |
+| `detectLinkedHosts()` | Read-only: which of `claude-code`, `cursor`, `codex` can currently discover skills in a directory. |
+| `serializeHostRecord()` / `parseHostRecord()` | Round-trip `clossys/.state/hosts.json` (`HOSTS_REL`). |
+| `parsePreferences()` | Reads `clossys/preferences.json`'s budget stance; defaults to `"balanced"` on absence or malformed input. |
+| `readHostModelProfile()` | Reads a packed `model-profiles/<host>.json`; returns `undefined`, never throws, on a missing or malformed file. |
+| `resolveModelForTier()` | Resolves a tier and budget preference to one model name for a host, reporting `belowFloor` rather than silently substituting a weaker tier's model. |
+| `validateAdvisorPlan()` / `validateEngagementBrief()` | Shape validation against the #1175 "Plan file contract" for `clossys/advisor/plan.json` and `clossys/brief.json`. |
+| `isPlanApproved()` | True only when a plan's most recent decision (by timestamp) has `chosen === "approved"`. |
+| `applyEngagementBrief()` | Writes `clossys/brief.json` into a repository directory once both the plan and the brief validate; refuses and writes nothing otherwise. |
+| `CloneMissingOutcome` / `DoctorCheckHost` / `DoctorReport` / `DoctorStepId` / `DoctorStepResult` / `CloudBootstrapCheck` / `CloudBootstrapReport` / `ExternalInventoryDeclaration` / `InventoryDriftReport` / `DiscoveredHost` / `HostRecord` / `BudgetPreference` / `HostModelProfile` / `HostTierMapping` / `ModelResolution` / `PreferencesDocument` / `ReasoningTier` / `SupportedHost` / `AdvisorPlan` / `ApplyBriefResult` / `BlockerKind` / `EngagementBrief` / `EngagementBriefRole` / `PlanBlocker` / `PlanDecision` / `ValidationResult` | Typed contracts for the sections above. |
+
+## Doctor
+
+`launcher-doctor` (installed alongside `@clossys/launcher`) is read-only and
+never writes anything (#1220). It checks the prerequisites a client needs
+before the hub even exists -- git, the GitHub command-line tool, whether
+you are signed in, Node.js, and npm -- and reports the first thing that is
+missing, in plain language, with the one next action to take. Run it again
+after fixing that one thing; it always reports the next thing, never a dump
+of everything at once. A missing coding agent is reported but never blocks
+the verdict: `runDoctorChecks()` marks it advisory, since Launcher cannot
+detect every host and it is a one-time choice, not a step to fix in
+sequence. `renderDoctorReport()` renders the report the way the CLI prints
+it.
+
+## Product repositories
+
+`docs/contracts/product-repository-layout.json` (this repository's own contract; it does not ship in the published package) extends the account hub's
+`clossys/` layout to a product repository: `apps/*`, workspace wiring so
+`@clossys/*` packages install as exact pinned versions, `AGENTS.md` /
+`CLAUDE.md` pointers, and the CI Starter proof (#1215). A cloud agent
+session (browser plus GitHub, no local setup) can pick up a product
+repository too -- `checkCloudSessionBootstrap()` verifies exactly what that
+session needs: a resolvable `package.json` plus `package-lock.json` pair,
+an `AGENTS.md` that mentions `clossys/`, and a hub marker at the same
+relative path as the packed template `skeleton/clossys/.state/workspace.json`.
+It never runs `npm ci` itself and never mutates anything; it only reports
+which of the three is missing.
+
+## Inventory: adopting an existing source
+
+When an account already keeps a repository inventory in its own control
+plane, launcher reads it as the source of truth instead of writing a
+second, diverging one (#1216). Declare it by hand-editing the hub marker (the packed template
+`skeleton/clossys/.state/workspace.json`; the generated path does not
+ship) to add an `externalInventory: { path, shape }` field (a `"foundry"`
+or `"custom"` shape). Every `launcher` run
+(create, resume, or appoint) then calls `reportInventoryDrift()`
+automatically and prints the result in hub health output when the marker
+declares one: three sets, all three even when one is empty -- ids only in
+the external source, ids only in launcher's own inventory, and ids both
+agree on. A `"custom"` shape is reported indeterminate rather than guessed
+at -- launcher has no mapping for a non-foundry inventory shape yet. It
+never merges the two silently; writing the reconciled set is left as a
+separate, explicit apply step for a follow-up.
+
+## Hosts
+
+Every `launcher` run (create, resume, or appoint) records which
+coding-agent hosts a directory could already discover skills through,
+*before* that run composes skills and stamps every host's discovery path
+(#1180): `claude-code` and `cursor` are detected by their own discovery
+symlink (`.claude/skills`, `.cursor/skills`); `codex` is detected by the
+presence of `.agents/skills` itself, since Codex reads repository skills
+from that path directly and needs no separate discovery link (verified
+against developers.openai.com/codex/skills, 2026-09-22). The snapshot is
+written to `clossys/.state/hosts.json` (`HOSTS_REL`, via
+`serializeHostRecord()` / `parseHostRecord()`) for the hub and for every
+sibling clone launcher composes skills into -- so a consumer such as
+Advisor's next-action phrasing can name the client's actual tool instead
+of guessing.
+
+## Model guidance
+
+Packages declare what a step demands -- a reasoning tier (`light` /
+`standard` / `deep`) -- never a model name (#1219). Launcher ships the
+tier-to-model mapping per host in `model-profiles/<host>.json`, dated and
+re-verified against that host's real current models;
+`readHostModelProfile()` reads one. `parsePreferences()` reads
+`clossys/preferences.json`'s budget stance (`cost-conscious` / `balanced` /
+`max-quality`, defaulting to `balanced` when absent or malformed) --
+Advisor asks the question and writes the file; this package only resolves
+against it. `resolveModelForTier()` combines a profile, a tier, and a
+preference into one `ModelResolution`, and reports `belowFloor` rather than
+silently substituting a weaker model when a caller-supplied hard floor
+tier cannot be met.
+
+## Applying an approved plan
+
+`launcher-apply-plan --plan <plan.json> --brief <brief.json> --repo <dir>`
+writes `clossys/brief.json` into a staffed repository once the plan is
+approved (#1178). `validateAdvisorPlan()` and `validateEngagementBrief()`
+check both files against the exact shapes recorded on issue #1175's "Plan
+file contract"; `isPlanApproved()` reads a plan's most recent decision (by
+timestamp, not array position) and requires it to be `"approved"` --
+absence of any decision is never treated as approval.
+`applyEngagementBrief()` refuses, and writes nothing, unless both checks
+pass, then writes the brief byte-identically -- it never re-authors its
+prose. This package does not compute a brief's content (that is
+`@clossys/advisor`'s `EngagementBrief`, landing in #1193) and does not
+decide whether a plan should be approved (that is Advisor's job); it only
+validates the two landed shapes and writes the one file. Multi-repository
+orchestration -- branch creation, exact package installs, adding Starter's
+caller workflow, and opening one pull request per repository -- is
+deferred: the landed contract does not yet specify how a plan's approved
+roles map to inventory repository ids or to install/remove/relocate work
+items.
 
 ## Why this is not Advisor, Starter, Builder, installer, creator, or a connector
 
@@ -170,3 +359,7 @@ repository.
 ## Licence
 
 MIT.
+
+## Changelog
+
+Release notes for every version are in the [changelog](https://github.com/clossys/foundry/blob/main/docs/changelogs/launcher.md), kept in the public repository rather than in the installed package.

package/contracts/conversation-contract.md

@@ -0,0 +1,41 @@
+# Conversation contract
+
+One conversation contract for every Foundry role (#1182). Every `packages/*/skill/SKILL.md`
+carried a byte-identical `## How we work together` / `## One question at a time`
+pair with no gate enforcing it; this file is the single source those sections
+now come from. `@clossys/launcher` packs this file at build time and, when it
+composes a skill, replaces that skill's own `## How we work together` and
+`## One question at a time` sections (if present) with the block below, at
+the same position. Packages keep their own role content; only this shared
+block is owned here. A later, separate migration removes the duplicated
+block from each package's own `skill/SKILL.md` on its next natural version
+bump — no package edit is needed for the contract to take effect, because
+composition already replaces it.
+
+Everything from the heading below to the end of this file is the injected
+block, verbatim.
+
+## How we work together
+
+Before anything else, a role reads `clossys/brief.json` to learn why it is
+staffed here and what its goals are. If the brief is absent, or does not
+staff this role, it says so in plain language and routes the client to
+`@clossys-advisor`, rather than improvising a mandate.
+
+Every reply has four parts:
+
+1. **Where we are** — one or two plain sentences: the `summary` of this role's status probe, set against the brief's goals. The status probe is the one source for this part; never derive it from `STATUS.md` or any other file. If the role has no status probe, or it cannot measure yet, say so plainly.
+2. **My recommendation** — what we would do, with a one-line reason. Always stated.
+3. **Your call** — one question with 2-4 options, the recommended option listed first and labelled, "something else" as the only free-text path. Use the host's multiple-choice control when one exists; otherwise numbered picks.
+4. **What happens next** — what happens if the client takes the recommendation.
+
+Rules:
+
+- Ask only what only the client can know: business facts, audience, taste, authority, risk appetite.
+- Decide craft yourself and state it (for example, "I'm using a four-step type scale; say if you want otherwise").
+- Never ask for ids, slugs, paths, versions, commands, or tool choices.
+- Translate machine states into plain language; no exit codes or check names in the default reply.
+- One decision per turn; no forms.
+- Push back once, plainly, when a choice goes against the recommendation. Refuse, with the reason, when a choice breaks a hard rule.
+- Read-only until approval, one approved step at a time; chat agreement by itself is never authorization.
+- Invoked with the `loop` keyword, run exactly one iteration of the five stages defined in `@clossys/controller`'s shipped `contracts/role-loop-archetypes.json` -- `sense`, `judge`, `act`, `verify`, `learn` -- and stop at the approval gate inside `judge`; a bare mention without `loop` never starts one.

package/dist/apply-plan-cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { createNodeHost } from "./host.js";
+export declare const APPLY_PLAN_USAGE = "Usage: launcher-apply-plan --plan <plan.json> --brief <brief.json> --repo <directory>\n\nWrites clossys/brief.json into <directory> from the given brief, once the\ngiven plan's most recent decision is \"approved\". Refuses, and writes\nnothing, otherwise.\n\nDeterministic mechanics only: this does not decide whether a plan should be\napproved (that is Advisor's job) and does not compute the brief's content\n(that is @clossys/advisor's EngagementBrief, #1193) -- it validates the\nexact shapes recorded on issue #1175 and writes the one file.\n\nExit codes: 0 = applied, 1 = refused (not approved, or a shape does not\nvalidate), 2 = a given file could not be read as JSON.";
+export declare class ApplyPlanInputError extends Error {
+}
+export declare function main(argv: readonly string[], host: ReturnType<typeof createNodeHost>): number;
+//# sourceMappingURL=apply-plan-cli.d.ts.map

package/dist/apply-plan-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-plan-cli.d.ts","sourceRoot":"","sources":["../src/apply-plan-cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3C,eAAO,MAAM,gBAAgB,yqBAY0B,CAAC;AAExD,qBAAa,mBAAoB,SAAQ,KAAK;CAAG;AAgCjD,wBAAgB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,GAAG,MAAM,CAgC7F"}

package/dist/apply-plan-cli.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { isDirectInvocation } from "./cli.js";
+import { createNodeHost } from "./host.js";
+import { applyEngagementBrief, validateAdvisorPlan, validateEngagementBrief } from "./apply-plan.js";
+export const APPLY_PLAN_USAGE = `Usage: launcher-apply-plan --plan <plan.json> --brief <brief.json> --repo <directory>
+
+Writes clossys/brief.json into <directory> from the given brief, once the
+given plan's most recent decision is "approved". Refuses, and writes
+nothing, otherwise.
+
+Deterministic mechanics only: this does not decide whether a plan should be
+approved (that is Advisor's job) and does not compute the brief's content
+(that is @clossys/advisor's EngagementBrief, #1193) -- it validates the
+exact shapes recorded on issue #1175 and writes the one file.
+
+Exit codes: 0 = applied, 1 = refused (not approved, or a shape does not
+validate), 2 = a given file could not be read as JSON.`;
+export class ApplyPlanInputError extends Error {
+}
+function parseArgs(argv) {
+    if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h"))
+        return { help: true };
+    const flags = new Map();
+    for (let index = 0; index < argv.length; index += 2) {
+        const name = argv[index];
+        const value = argv[index + 1];
+        if ((name !== "--plan" && name !== "--brief" && name !== "--repo") || value === undefined) {
+            throw new ApplyPlanInputError("usage: launcher-apply-plan --plan <path> --brief <path> --repo <directory>");
+        }
+        flags.set(name, value);
+    }
+    const planPath = flags.get("--plan");
+    const briefPath = flags.get("--brief");
+    const repoDirectory = flags.get("--repo");
+    if (planPath === undefined || briefPath === undefined || repoDirectory === undefined) {
+        throw new ApplyPlanInputError("--plan, --brief, and --repo are all required");
+    }
+    return { help: false, planPath, briefPath, repoDirectory };
+}
+function readJson(readText, path, label) {
+    const raw = readText(path);
+    if (raw === null)
+        throw new ApplyPlanInputError(`${label} could not be read: ${path}`);
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new ApplyPlanInputError(`${label} is not valid JSON: ${path}`);
+    }
+}
+export function main(argv, host) {
+    const parsed = parseArgs(argv);
+    if (parsed.help) {
+        console.log(APPLY_PLAN_USAGE);
+        return 0;
+    }
+    let planRaw;
+    let briefRaw;
+    try {
+        planRaw = readJson(host.readText, parsed.planPath, "--plan");
+        briefRaw = readJson(host.readText, parsed.briefPath, "--brief");
+    }
+    catch (cause) {
+        console.error(`launcher-apply-plan: ${cause instanceof Error ? cause.message : String(cause)}`);
+        return 2;
+    }
+    const planValidation = validateAdvisorPlan(planRaw);
+    if (!planValidation.valid) {
+        console.error(`launcher-apply-plan: --plan does not validate: ${planValidation.reason}`);
+        return 1;
+    }
+    const briefValidation = validateEngagementBrief(briefRaw);
+    if (!briefValidation.valid) {
+        console.error(`launcher-apply-plan: --brief does not validate: ${briefValidation.reason}`);
+        return 1;
+    }
+    const result = applyEngagementBrief(host, parsed.repoDirectory, planRaw, briefRaw, "clossys/brief.json");
+    if (result.state === "refused") {
+        console.error(`launcher-apply-plan: refused -- ${result.reason}`);
+        return 1;
+    }
+    console.log(`wrote ${result.path}`);
+    return 0;
+}
+function run() {
+    try {
+        process.exitCode = main(process.argv.slice(2), createNodeHost());
+    }
+    catch (cause) {
+        console.error(`launcher-apply-plan: ${cause instanceof Error ? cause.message : String(cause)}`);
+        process.exitCode = 2;
+    }
+}
+if (isDirectInvocation(import.meta.url, process.argv[1]))
+    run();
+//# sourceMappingURL=apply-plan-cli.js.map

package/dist/apply-plan-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-plan-cli.js","sourceRoot":"","sources":["../src/apply-plan-cli.ts"],"names":[],"mappings":"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"}

package/dist/apply-plan.d.ts

@@ -0,0 +1,79 @@
+import type { WorkspaceHost } from "./types.js";
+export interface EngagementBriefRole {
+    readonly role: string;
+    readonly why: string;
+    readonly goal: {
+        readonly metric: string;
+        readonly direction: "increase" | "decrease";
+    };
+    readonly inputsFrom: readonly string[];
+    readonly outputsTo: readonly string[];
+}
+export interface EngagementBrief {
+    readonly schemaVersion: 1;
+    readonly problem: string;
+    readonly roles: readonly EngagementBriefRole[];
+    readonly sequence: readonly string[];
+    readonly deliverables: readonly string[];
+}
+export type BlockerKind = "missing-input" | "missing-authority" | "failing-evidence" | "unavailable-environment" | "contradiction";
+export interface PlanBlocker {
+    readonly kind: BlockerKind;
+    readonly description: string;
+    readonly owner: string;
+    readonly dueDate?: string;
+}
+export interface PlanDecision {
+    readonly at: string;
+    readonly recommended: string;
+    readonly chosen: string;
+    readonly by: string;
+}
+export interface AdvisorPlan {
+    readonly schemaVersion: 1;
+    readonly asOf: string;
+    readonly mandate: {
+        readonly problem: string;
+        readonly primaryProblemId: string;
+        readonly roles: readonly string[];
+    };
+    readonly whereWeAre: readonly string[];
+    readonly recommendedNext: {
+        readonly action: string;
+        readonly owner: string;
+        readonly due: string;
+    } | null;
+    readonly decisions: readonly PlanDecision[];
+    readonly blockers: readonly PlanBlocker[];
+}
+export type ValidationResult = {
+    readonly valid: true;
+} | {
+    readonly valid: false;
+    readonly reason: string;
+};
+/** Validates an EngagementBrief's shape exactly against the #1175 contract. Never mutates, never re-derives content. */
+export declare function validateEngagementBrief(value: unknown): ValidationResult;
+/** Validates an AdvisorPlan's shape exactly against the #1175 contract. */
+export declare function validateAdvisorPlan(value: unknown): ValidationResult;
+/**
+ * The plan is approved when its most recent decision (by `at`) records
+ * chosen === "approved". No decisions, or a most-recent decision that
+ * isn't "approved", is not approved -- this never assumes approval from
+ * absence.
+ */
+export declare function isPlanApproved(plan: AdvisorPlan): boolean;
+export type ApplyBriefResult = {
+    readonly state: "applied";
+    readonly path: string;
+} | {
+    readonly state: "refused";
+    readonly reason: string;
+};
+/**
+ * Writes clossys/brief.json into `repositoryDirectory`, byte-identically
+ * from the validated brief -- never re-authors its prose. Refuses (does
+ * not write) unless both the plan is approved and the brief validates.
+ */
+export declare function applyEngagementBrief(host: WorkspaceHost, repositoryDirectory: string, plan: AdvisorPlan, brief: EngagementBrief, briefRelPath: string): ApplyBriefResult;
+//# sourceMappingURL=apply-plan.d.ts.map

package/dist/apply-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-plan.d.ts","sourceRoot":"","sources":["../src/apply-plan.ts"],"names":[],"mappings":"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"}