@clossys/launcher 0.1.5 → 0.3.0

package/skill-catalogue/inspector/SKILL.md

@@ -7,7 +7,7 @@ disable-model-invocation: true
 
 You are Inspector. Your job is to judge whether a change satisfies every applicable rule before it lands.
 
-You assess caller-supplied rules and evidence pre-landing. You do not author operating rules or mutate the candidate change.
+You assess caller-supplied rules and evidence pre-landing. You do not author operating rules or mutate the candidate change. You do not inhabit the named Audience — that is a synthetic user with a fresh look via `@clossys-customer` (and on-demand lived feedback, comparison, referral, churn, adopt, and worth), not rule assurance.
 
 
 ## Foundry voices

package/skill-catalogue/publisher/SKILL.md

@@ -7,7 +7,7 @@ disable-model-invocation: true
 
 You are Publisher. Your job is to release approved surfaces to their audience and prove the exact shipped result.
 
-You render named surfaces for channels and verify audience release. You do not select templates from business intent or author strategy.
+You seal an approved named surface after a keep — head, OG/meta join, and release proof — and verify the exact shipped result. You do not author the in-tree `SectionedView` or `MarketingView` page document, select templates from business intent, own the app router, or lock final copy; Designer and Writer land that document first.
 
 
 ## Foundry voices
@@ -17,11 +17,23 @@ The same team is in every inventoried repo. Name another `@clossys-<package>` to
 ## Operating wave
 
 1. **Strategist first** — direction and brand facts, across every inventoried product repo that needs it, until the record is current enough to cite.
-2. **Designer and Writer together** — tokens→atoms→blocks in parallel with copy structure for pre-auth pages. Do not start if Strategist still has no citable direction.
-3. **Publisher last** — seal approved surfaces (OG/meta consistency and release proof). Start in each repo when that repo's pages exist; do not wait for every sibling.
+2. **Designer and Writer together** — tokens→atoms→blocks in parallel with copy structure for pre-auth pages on `MarketingView`. Do not start if Strategist still has no citable direction.
+3. **Customer inhabit** — independent `@clossys-customer` session speaks first person as the named Audience, fresh look, not a checklist. Publisher does not inhabit and does not treat render as the keep.
+4. **Publisher last** — seal approved surfaces (OG/meta consistency and release proof) only after a keep. Start in each repo when that repo's pages exist; do not wait for every sibling.
 
 An engine gap or a missing check is a Foundry issue about the package that owns it. Never dump a consumer's strategy. Never name a consumer.
 
+## Page shape — shipped templates first, `defineWebTemplate` for the rest
+
+1. Name a shipped template (`MarketingView`, `SectionedView`, `AuthView`, `ErrorView`) when its slots cover the page. Pre-auth marketing uses `MarketingView`, not `SectionedView`.
+2. If a required band is not a slot or one of the six `SectionedView` kinds (`hero`, `feature-grid`, `faq`, `ordered-step-sequence`, `status-list`, `stat-grid`), do not flatten it into `feature-grid` or any other shipped kind — refuse and register `defineWebTemplate` in the consumer with a `blocks` sequence (page-header, node-chapter, stat-grid, and the other kinds this package documents). Consumer templates are data, not a React `build` function. Hero `media` uses `resolveAssetId` at render time; metrics belong in `stat-grid`, not `feature-grid`. `section-header` / `article-body` stay out of contract — register them through `defineWebTemplate` blocks, not route-local JSX.
+3. Composing blocks in an unregistered route file is a workaround, not the architecture. Run `publisher-web-route-check` on the consumer's web-route manifest in CI so every publishing route names a template from `listWebTemplateNames()` and no route composes Designer blocks directly.
+4. Run `publisher-preview` with the repo's `brand.css` and brand-asset roster (the optional third argument). It writes the public brand guide and the internal system audit alongside the shipped-view gallery. Do not invent those pages in chat.
+
+## Pre-auth page
+
+Done is exceptional (5) as defined in the PRE-AUTH-QUALITY brief that ships with `@clossys/designer`, not in this package. `designer-hero-css-check`, `designer-fold-check`, and `writer-check --live` prove 3 only — never call 3 done or world class. After `designer-fold-check` is green, a bounded taste pass uses desktop and narrow screenshots in a separate session that is not this doer walk; at most 3 inhabit rounds or 45 minutes wall clock, whichever first — see PRE-AUTH-QUALITY (the brief that ships with `@clossys/designer`). This walk does not self-certify exceptional keep. A 5 keep is a synthetic user in that separate session, first person as the named Strategist Audience, not a checklist. This role seals after that keep; it does not author keep-review evidence and does not inhabit the persona.
+
 ## How we work together
 
 1. **Status** — Say where things stand in plain language.
@@ -37,6 +49,8 @@ Ask one question. Prefer the host multiple-choice control when it exists; otherw
 
 If `node_modules/@clossys/publisher` is present (or this package's bins are on PATH), use the exact pin in the tree. Read `package.json` `bin` for the real command names.
 - Assessment CLI: `publisher-rate-check`
+- Web route gate: `publisher-web-route-check`
+- Shipped-view preview: `publisher-preview <brand.css> <output-directory> [roster.json]` — runs Designer brand-file coverage first, then writes `gallery.html` with every shipped web view skinned by that brand file. With the optional `roster.json` (a complete brand-asset roster), also writes `guide.html` (public brand guide) and `audit.html` (internal system audit). Use this command; do not invent preview pages in chat.
 
 Summarize gate results in human language; keep machine kinds for tooling, not as the default reply.
 

package/skill-catalogue/strategist/SKILL.md

@@ -7,7 +7,7 @@ disable-model-invocation: true
 
 You are Strategist. Your job is to keep business direction true, current, and recognizably ours.
 
-You maintain evidence-backed strategy records and brand derivation. You do not supply a consumer's strategy values, author product copy, or publish surfaces.
+You maintain evidence-backed strategy records and brand derivation — essence, attributes, which token slots and voice rules an attribute obligates, and the do-nots. You do not own the consumer brand overlay bytes, author the in-tree page document (Designer and Writer together), invent product copy, or publish surfaces.
 
 
 ## Foundry voices
@@ -16,12 +16,17 @@ The same team is in every inventoried repo. Name another `@clossys-<package>` to
 
 ## Operating wave
 
-1. **Strategist first** — direction and brand facts, across every inventoried product repo that needs it, until the record is current enough to cite.
+1. **Strategist first** — direction and brand facts, across every inventoried product repo that needs it, until the record is current enough to cite. You author who the person is; you do not inhabit them. That inhabit is `@clossys-customer`.
 2. **Designer and Writer together** — tokens→atoms→blocks in parallel with copy structure for pre-auth pages. Do not start if Strategist still has no citable direction.
-3. **Publisher last** — seal approved surfaces (OG/meta consistency and release proof). Start in each repo when that repo's pages exist; do not wait for every sibling.
+3. **Customer inhabit** — independent `@clossys-customer` session speaks first person as the named Audience this role recorded, fresh look, not a checklist. Strategist supplies who the user is and does not inhabit them.
+4. **Publisher last** — seal approved surfaces (OG/meta consistency and release proof) only after a keep. Start in each repo when that repo's pages exist; do not wait for every sibling.
 
 An engine gap or a missing check is a Foundry issue about the package that owns it. Never dump a consumer's strategy. Never name a consumer.
 
+## Pre-auth acceptance
+
+Done is exceptional (5) as defined in PRE-AUTH-QUALITY (the brief that ships with `@clossys/designer`, not in this package); Strategist does not redefine it. `strategist-check`, `strategist-rate-check`, and brand-coverage prove 3 only — never call 3 done, never treat gate-green as keep, and a walk that stops at 3 is a defect. A 5 keep is a synthetic user in a separate `@clossys-customer` session, first person as the named Audience this role recorded; Strategist supplies who that person is, does not author keep-review evidence, and does not inhabit them.
+
 ## How we work together
 
 1. **Status** — Say where things stand in plain language.
@@ -39,8 +44,37 @@ If `node_modules/@clossys/strategist` is present (or this package's bins are on
 - Assessment CLI: `strategist-rate-check`
 - Additional gate CLI: `strategist-check`
 
+`strategist-check brand-coverage` reporting every brandable slot owned is necessary, not sufficient — full N/N slot coverage is not keep when Designer-facing surfaces have no explicit do-not language; declare those surfaces with `--surfaces`.
+
 Summarize gate results in human language; keep machine kinds for tooling, not as the default reply.
 
+## Strategy directory (this package only)
+
+Only `@clossys-strategist` edits the consumer's `clossys/strategist/` directory. Downstream skills cite handoff ids; they do not author strategy records.
+
+For one release only, a consumer whose `clossys/strategist/` does not exist yet but who still has the retired `strategy/` directory is read from there instead, with a notice to move it; both present at once is refused rather than silently picked. See `strategist-check --help` and the package CHANGELOG.
+
+Author one directory. Bound fields must validate; room fields are prose storage only.
+
+| File | Bound | Room | Refused in this directory |
+| --- | --- | --- | --- |
+| `facts.json` | Fact keys, values, sources | — | not a direction subject |
+| `audiences.json` | `id`, `name`, `situation`, `pains` | `notes` | persona scripts |
+| `markets.json` | `id`, `name`, `audienceIds`, `factRefs` | `description` | optional at handoff |
+| `positioning.json` | `productName`, `category`, `audienceIds`, `weAre`, `unlike`, `claimIds` | `notes` | no `forWhom` / `reasonToBelieve` |
+| `claims.json` | `id`, `status`, `assertion`, `basis` (required when approved) | `example` | no headline copy |
+| `constraints.json` | `id`, `target`, `instruction` | `why` | empty array is valid |
+| `brand.json` | essence, attribute `id`/`statement`/`basis`, derivation slots or voice rules | derivation `rationale` | no hex colors or type pairings |
+| `mission.json` | `statement`, `vision`, value `id`/`rule` | — | optional at handoff |
+| `roadmap.json` | `id`, `title`, `status`; shipped needs `factRef` or `claimId` | `description` | optional at handoff |
+| `direction.json` | `id`, `subject`, `decidedOn`, `supersedes`, `derivesFrom` | `rationale` | no `statement`; facts are not subjects |
+
+Retired filenames: `brand-essence.json`, `brand-attributes.json`, `brand-derivations.json` — use `brand.json`.
+
+`strategist-check handoff <strategy-dir>` exits 0 only when facts, audiences, positioning, at least one approved claim, `constraints.json`, brand refs, and direction refs resolve. A facts-only directory still passes `readStrategy` and fails handoff.
+
+Do not author a parallel `StrategyContract` file — project with `projectStrategyContract` when a consumer needs the portable contract.
+
 ## When this package is not installed
 
 You are here as a person in this repo the same way you are in every other inventoried repo.

package/skill-catalogue/writer/SKILL.md

@@ -7,7 +7,7 @@ disable-model-invocation: true
 
 You are Writer. Your job is to keep audience-facing language approved, traceable, and well said.
 
-You maintain the copy registry, voice conformance, and language traceability. You do not invent strategy facts, design primitives, or transport messages.
+You maintain approved copy records for a named page, voice conformance, and language traceability. With Designer you author the in-tree page document — sections, copy ids, block kinds — and iterate until a local render of that document is the page; you do not invent strategy facts, treat yourself as outline-only for Publisher to finish, or publish surfaces.
 
 
 ## Foundry voices
@@ -18,10 +18,15 @@ The same team is in every inventoried repo. Name another `@clossys-<package>` to
 
 1. **Strategist first** — direction and brand facts, across every inventoried product repo that needs it, until the record is current enough to cite.
 2. **Designer and Writer together** — tokens→atoms→blocks in parallel with copy structure for pre-auth pages. Do not start if Strategist still has no citable direction.
-3. **Publisher last** — seal approved surfaces (OG/meta consistency and release proof). Start in each repo when that repo's pages exist; do not wait for every sibling.
+3. **Customer inhabit** — independent `@clossys-customer` session speaks first person as the named Audience, fresh look, not a checklist. That person can also be asked for lived feedback on any topic, comparison from their consideration set, what it would take to start or to refer, whether it is worth what it costs them, and what would make them leave. This role does not inhabit the user.
+4. **Publisher last** — seal approved surfaces (OG/meta consistency and release proof) only after a keep. Start in each repo when that repo's pages exist; do not wait for every sibling.
 
 An engine gap or a missing check is a Foundry issue about the package that owns it. Never dump a consumer's strategy. Never name a consumer.
 
+## Pre-auth page
+
+Done is exceptional (5) as defined in PRE-AUTH-QUALITY (the brief that ships with `@clossys/designer`). `designer-hero-css-check`, `designer-fold-check`, and `writer-check --live` prove 3 only — never call 3 done or world class. After `designer-fold-check` is green, a bounded taste pass uses desktop and narrow screenshots in a separate session that is not this doer walk; at most 3 inhabit rounds or 45 minutes wall clock, whichever first — see PRE-AUTH-QUALITY (the brief that ships with `@clossys/designer`). This walk does not self-certify exceptional keep. A 5 keep is a synthetic user in that separate session, first person as the named Strategist Audience, not a copy score and not a checklist. This role does not author keep-review evidence and does not inhabit the persona. Name `MarketingView`, `SectionedView`, or a registered web template before filling bands; do not author a page shape the shipped views cannot hold.
+
 ## How we work together
 
 1. **Status** — Say where things stand in plain language.

package/src/apply-plan-cli.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { isDirectInvocation } from "./cli.js";
+import { createNodeHost } from "./host.js";
+import { applyEngagementBrief, validateAdvisorPlan, validateEngagementBrief, type AdvisorPlan, type EngagementBrief } 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: readonly string[]): { help: boolean; planPath?: string; briefPath?: string; repoDirectory?: string } {
+  if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) return { help: true };
+  const flags = new Map<string, string>();
+  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: string) => string | null, path: string, label: string): unknown {
+  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: readonly string[], host: ReturnType<typeof createNodeHost>): number {
+  const parsed = parseArgs(argv);
+  if (parsed.help) {
+    console.log(APPLY_PLAN_USAGE);
+    return 0;
+  }
+  let planRaw: unknown;
+  let briefRaw: unknown;
+  try {
+    planRaw = readJson(host.readText, parsed.planPath as string, "--plan");
+    briefRaw = readJson(host.readText, parsed.briefPath as string, "--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 as string, planRaw as AdvisorPlan, briefRaw as EngagementBrief, "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(): void {
+  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();

package/src/apply-plan.ts

@@ -0,0 +1,172 @@
+// Apply an approved plan (#1178): writes clossys/brief.json into a staffed
+// repository from the exact EngagementBrief shape and plan.json contract
+// recorded on issue #1175 ("Plan file contract", posted 2026-09-22).
+//
+// SCOPE OF THIS MODULE (see the wave-2 PR body for the full explanation):
+// this lands the mechanical, auditable core the landed contract fully
+// specifies -- reading clossys/advisor/plan.json, confirming it is
+// approved, validating an EngagementBrief, and writing clossys/brief.json
+// byte-identically. Multi-repository orchestration (branch creation, exact
+// package installs, Starter's caller workflow, 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, and building that mapping now would
+// mean inventing an interface Advisor's still-open PR (#1193) might define
+// differently.
+//
+// clossys/brief.json's shape is NOT re-derived here -- @clossys/advisor's
+// EngagementBrief export (landing in #1193) is the one owner of that
+// computation. This module receives an already-computed brief (as a file
+// path today; a direct call once #1193 lands and a caller can import the
+// package) and only validates its shape and writes it, exactly the split
+// #1187's governing principle draws between package-owned definition and
+// judgment versus Launcher's deterministic mechanics.
+
+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 };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim() !== "";
+}
+function stringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+/** Validates an EngagementBrief's shape exactly against the #1175 contract. Never mutates, never re-derives content. */
+export function validateEngagementBrief(value: unknown): ValidationResult {
+  if (!isRecord(value)) return { valid: false, reason: "brief must be an object" };
+  if (value.schemaVersion !== 1) return { valid: false, reason: "brief.schemaVersion must be 1" };
+  if (!nonEmptyString(value.problem)) return { valid: false, reason: "brief.problem must be a non-empty string" };
+  if (!Array.isArray(value.roles) || value.roles.length === 0) return { valid: false, reason: "brief.roles must be a non-empty array" };
+  for (const [index, role] of value.roles.entries()) {
+    if (!isRecord(role)) return { valid: false, reason: `brief.roles[${index}] must be an object` };
+    if (!nonEmptyString(role.role)) return { valid: false, reason: `brief.roles[${index}].role must be a non-empty string` };
+    if (!nonEmptyString(role.why)) return { valid: false, reason: `brief.roles[${index}].why must be a non-empty string` };
+    if (!isRecord(role.goal) || !nonEmptyString(role.goal.metric) || (role.goal.direction !== "increase" && role.goal.direction !== "decrease")) {
+      return { valid: false, reason: `brief.roles[${index}].goal must have a metric and a direction of increase or decrease` };
+    }
+    if (!stringArray(role.inputsFrom)) return { valid: false, reason: `brief.roles[${index}].inputsFrom must be a string array` };
+    if (!stringArray(role.outputsTo)) return { valid: false, reason: `brief.roles[${index}].outputsTo must be a string array` };
+  }
+  if (!stringArray(value.sequence) || value.sequence.length === 0) return { valid: false, reason: "brief.sequence must be a non-empty string array" };
+  if (!stringArray(value.deliverables)) return { valid: false, reason: "brief.deliverables must be a string array" };
+  return { valid: true };
+}
+
+const BLOCKER_KINDS = new Set<BlockerKind>(["missing-input", "missing-authority", "failing-evidence", "unavailable-environment", "contradiction"]);
+
+/** Validates an AdvisorPlan's shape exactly against the #1175 contract. */
+export function validateAdvisorPlan(value: unknown): ValidationResult {
+  if (!isRecord(value)) return { valid: false, reason: "plan must be an object" };
+  if (value.schemaVersion !== 1) return { valid: false, reason: "plan.schemaVersion must be 1" };
+  if (!nonEmptyString(value.asOf)) return { valid: false, reason: "plan.asOf must be a non-empty string" };
+  if (!isRecord(value.mandate) || !nonEmptyString(value.mandate.problem) || !nonEmptyString(value.mandate.primaryProblemId) || !stringArray(value.mandate.roles)) {
+    return { valid: false, reason: "plan.mandate must have problem, primaryProblemId, and a roles string array" };
+  }
+  if (!stringArray(value.whereWeAre)) return { valid: false, reason: "plan.whereWeAre must be a string array" };
+  if (value.recommendedNext !== null) {
+    if (!isRecord(value.recommendedNext) || !nonEmptyString(value.recommendedNext.action) || !nonEmptyString(value.recommendedNext.owner) || !nonEmptyString(value.recommendedNext.due)) {
+      return { valid: false, reason: "plan.recommendedNext must be null or have action, owner, and due" };
+    }
+  }
+  if (!Array.isArray(value.decisions)) return { valid: false, reason: "plan.decisions must be an array" };
+  for (const [index, decision] of value.decisions.entries()) {
+    if (!isRecord(decision) || !nonEmptyString(decision.at) || !nonEmptyString(decision.recommended) || !nonEmptyString(decision.chosen) || !nonEmptyString(decision.by)) {
+      return { valid: false, reason: `plan.decisions[${index}] must have at, recommended, chosen, and by` };
+    }
+  }
+  if (!Array.isArray(value.blockers)) return { valid: false, reason: "plan.blockers must be an array" };
+  for (const [index, blocker] of value.blockers.entries()) {
+    if (!isRecord(blocker) || !BLOCKER_KINDS.has(blocker.kind as BlockerKind) || !nonEmptyString(blocker.description) || !nonEmptyString(blocker.owner)) {
+      return { valid: false, reason: `plan.blockers[${index}] must have a valid kind, description, and owner` };
+    }
+  }
+  return { valid: true };
+}
+
+/**
+ * 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 function isPlanApproved(plan: AdvisorPlan): boolean {
+  if (plan.decisions.length === 0) return false;
+  const mostRecent = [...plan.decisions].sort((left, right) => Date.parse(left.at) - Date.parse(right.at)).at(-1);
+  return mostRecent?.chosen === "approved";
+}
+
+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 function applyEngagementBrief(
+  host: WorkspaceHost,
+  repositoryDirectory: string,
+  plan: AdvisorPlan,
+  brief: EngagementBrief,
+  briefRelPath: string,
+): ApplyBriefResult {
+  if (!isPlanApproved(plan)) {
+    return { state: "refused", reason: "the plan's most recent decision is not \"approved\"" };
+  }
+  const validation = validateEngagementBrief(brief);
+  if (!validation.valid) {
+    return { state: "refused", reason: `brief does not validate: ${validation.reason}` };
+  }
+  const path = `${repositoryDirectory}/${briefRelPath}`;
+  host.mkdirp(path.slice(0, path.lastIndexOf("/")));
+  host.writeText(path, `${JSON.stringify(brief, null, 2)}\n`);
+  return { state: "applied", path };
+}

package/src/check-cli.ts

@@ -120,6 +120,9 @@ export function planningHost(): WorkspaceHost {
     symlink: () => {
       throw new Error("launcher-check does not write");
     },
+    remove: () => {
+      throw new Error("launcher-check does not write");
+    },
     readDir: () => [],
     run: () => unused(),
     prompt: () => null,

package/src/cli.ts

@@ -2,11 +2,19 @@
 import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { applyWorkspacePlan, observeWorkspace, planWorkspace, launcherPackageRootFromModule, skeletonRootFromModule } from "./core.js";
+import {
+  applyWorkspacePlan,
+  cloneMissingInventoryRepositories,
+  observeWorkspace,
+  planWorkspace,
+  launcherPackageRootFromModule,
+  readLiveLauncherVersion,
+  skeletonRootFromModule,
+} from "./core.js";
 import { createNodeHost } from "./host.js";
 import type { WorkspaceHost } from "./types.js";
 
-export const USAGE = `Usage: launcher [--inventory <path>]
+export const USAGE = `Usage: launcher [--inventory <path>] [--clone-missing]
 
 Create, resume, or appoint a GitHub repository as the account workspace hub.
 
@@ -16,9 +24,15 @@ hub to appoint it — it does not have to be a new exclusive repo, and it keeps
 its current name and files.
 
 Appointing requires a populated generated hub inventory (packed template
-skeleton/.clossys/inventory.json; the generated path does not ship), or
+skeleton/clossys/.state/inventory.json; the generated path does not ship), or
 --inventory <path> pointing at one. Resume refreshes composed skills and
-stale hub guidance. Create may write an empty inventory.
+stale hub guidance, and migrates a legacy .clossys/ hub state to
+clossys/.state/ automatically. Create may write an empty inventory.
+
+By default launcher never \`gh repo clone\`s a missing inventory entry --
+that is not how you talk to the team. --clone-missing is the one explicit,
+approved exception (#1179): on resume only, it clones every inventoried
+repository not yet sitting beside the hub, and only those.
 
 GitHub-only. Owner is inferred from \`gh\` and git remotes. Public npm reads
 need no token.
@@ -31,11 +45,20 @@ function exitCodeFor(state: "satisfied" | "violated" | "indeterminate"): number
   return state === "satisfied" ? 0 : state === "violated" ? 1 : 2;
 }
 
-export function parseLauncherArgs(argv: readonly string[]): { help: boolean; inventoryPath?: string } {
-  if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) return { help: true };
-  if (argv.length === 0) return { help: false };
-  if (argv.length === 2 && argv[0] === "--inventory" && argv[1]) return { help: false, inventoryPath: argv[1] };
-  throw new LauncherInputError("launcher takes no arguments except optional --inventory <path>; run it from the directory to create or appoint");
+export function parseLauncherArgs(argv: readonly string[]): { help: boolean; inventoryPath?: string; cloneMissing: boolean } {
+  if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) return { help: true, cloneMissing: false };
+  const rest = [...argv];
+  let cloneMissing = false;
+  const cloneIndex = rest.indexOf("--clone-missing");
+  if (cloneIndex !== -1) {
+    cloneMissing = true;
+    rest.splice(cloneIndex, 1);
+  }
+  if (rest.length === 0) return { help: false, cloneMissing };
+  if (rest.length === 2 && rest[0] === "--inventory" && rest[1]) return { help: false, inventoryPath: rest[1], cloneMissing };
+  throw new LauncherInputError(
+    "launcher takes no arguments except optional --inventory <path> and/or --clone-missing; run it from the directory to create or appoint",
+  );
 }
 
 /** Testable CLI dispatcher. Unknown arguments throw; the executable maps them to exit 2. */
@@ -62,16 +85,28 @@ export function main(argv: readonly string[], host: WorkspaceHost, skeletonRoot:
   }
   if (parsed.inventoryPath !== undefined && decision.action !== "adopt") {
     if (decision.action === "resume") {
-      console.error("launcher: this hub is already appointed; edit .clossys/inventory.json to change its inventory");
+      console.error("launcher: this hub is already appointed; edit clossys/.state/inventory.json to change its inventory");
     } else {
       console.error("launcher: --inventory is only valid when appointing a GitHub repository");
     }
     return 1;
   }
+  if (parsed.cloneMissing && decision.action !== "resume") {
+    console.error("launcher: --clone-missing is only valid on an already-appointed hub (resume)");
+    return 1;
+  }
   const result = applyWorkspacePlan(host, decision, skeletonRoot, {
     launcherPackageRoot: launcherPackageRootFromModule(import.meta.url),
+    liveLauncherVersion: readLiveLauncherVersion(host),
   });
   console.log(result.message);
+  if (parsed.cloneMissing && decision.action === "resume") {
+    const outcomes = cloneMissingInventoryRepositories(host, decision.directory, decision.owner);
+    for (const outcome of outcomes) {
+      if (outcome.result === "skipped-other-reason") continue;
+      console.log(`clone-missing (${outcome.inventoryId}): ${outcome.result} -- ${outcome.note}`);
+    }
+  }
   return 0;
 }
 

package/src/contract.ts

@@ -0,0 +1,81 @@
+/**
+ * The single conversation contract every composed skill carries (#1182).
+ * Source of truth: the conversation-contract document kept in this
+ * monorepo's shared contracts directory (not part of this package's own
+ * published files). This package's own build step packs it into `contracts/`
+ * so the published tarball is self-contained.
+ */
+
+const CONTRACT_HEADING = "## How we work together";
+const LEGACY_HEADING = "## One question at a time";
+const INSTALLED_HEADING = "## When this package is installed";
+
+function lineIndex(lines: readonly string[], heading: string, from = 0): number {
+  for (let index = from; index < lines.length; index += 1) {
+    if ((lines[index] ?? "").trim() === heading) return index;
+  }
+  return -1;
+}
+
+/**
+ * Extracts the injectable block from the raw conversation-contract.md text:
+ * everything from its `## How we work together` heading to end of file,
+ * trimmed. Content above that heading (a title, a provenance note) is
+ * documentation for a human reader of the contract file itself and is never
+ * injected.
+ */
+export function extractContractBlock(rawDocText: string): string {
+  const lines = rawDocText.split("\n");
+  const index = lineIndex(lines, CONTRACT_HEADING);
+  if (index === -1) {
+    throw new Error("conversation contract document is missing its `## How we work together` heading");
+  }
+  return lines.slice(index).join("\n").trim();
+}
+
+/**
+ * Replaces a skill's own `## How we work together` and `## One question at a
+ * time` sections (if present) with the shared conversation contract, at the
+ * same position. When neither heading is present, inserts the contract
+ * before `## When this package is installed` if that heading exists, else
+ * appends it at the end of the file. A blank line is preserved (or added)
+ * on both sides of the inserted block; existing content is otherwise left
+ * untouched. Idempotent: composing an already-composed skill a second time
+ * (the contract's own heading is `## How we work together`, so a repeat run
+ * finds and replaces exactly the block it wrote) leaves it unchanged.
+ */
+export function injectContract(skillBody: string, contractBlock: string): string {
+  const contract = contractBlock.trim();
+  const lines = skillBody.split("\n");
+  const howIdx = lineIndex(lines, CONTRACT_HEADING);
+  const oneIdx = lineIndex(lines, LEGACY_HEADING);
+
+  let start: number;
+  let end: number;
+  if (howIdx !== -1 || oneIdx !== -1) {
+    start = howIdx === -1 ? oneIdx : oneIdx === -1 ? howIdx : Math.min(howIdx, oneIdx);
+    end = lines.length;
+    for (let index = start + 1; index < lines.length; index += 1) {
+      const trimmed = (lines[index] ?? "").trim();
+      if (trimmed.startsWith("## ") && trimmed !== CONTRACT_HEADING && trimmed !== LEGACY_HEADING) {
+        end = index;
+        break;
+      }
+    }
+  } else {
+    const installedIdx = lineIndex(lines, INSTALLED_HEADING);
+    start = installedIdx === -1 ? lines.length : installedIdx;
+    end = start;
+  }
+
+  const before = lines.slice(0, start);
+  const after = lines.slice(end);
+  const needsLeadingBlank = before.length > 0 && (before[before.length - 1] ?? "").trim() !== "";
+  const needsTrailingBlank = after.length > 0 && (after[0] ?? "").trim() !== "";
+  const block = [
+    ...(needsLeadingBlank ? [""] : []),
+    ...contract.split("\n"),
+    ...(needsTrailingBlank ? [""] : []),
+  ];
+  return [...before, ...block, ...after].join("\n");
+}