session-orchestrator 4.1.0 → 5.0.0

package/skills/bootstrap/public-fallback.md

@@ -5,32 +5,38 @@
 
 ## Step 1: Detect PATH_TYPE (Silent — No User Interaction)
 
-Read `plan-baseline-path` from Session Config in `CLAUDE.md` (or `AGENTS.md` on Codex):
+Run the dependency-free local contract reader. It uses the existing configuration
+resolvers, with precedence `SO_BASELINE_PATH` → matching named baseline →
+`owner.yaml` `paths.baseline-path` → committed Session Config. Paths resolve
+host-locally and are never written into the contract result.
 
 ```bash
-BASELINE_PATH=$(grep -m1 "^plan-baseline-path:" "$REPO_ROOT/CLAUDE.md" 2>/dev/null | awk '{print $2}')
-# Expand leading ~ to $HOME so paths like ~/Projects/projects-baseline work correctly
-BASELINE_PATH="${BASELINE_PATH/#\~/$HOME}"
+BOOTSTRAP_CONTRACT=$(node "$PLUGIN_ROOT/scripts/baseline-archetypes.mjs" --repo "$REPO_ROOT") || exit 2
+PATH_TYPE=$(printf '%s' "$BOOTSTRAP_CONTRACT" | node --input-type=module -e '
+let input = ""; for await (const chunk of process.stdin) input += chunk;
+process.stdout.write(JSON.parse(input).status);
+')
+export BOOTSTRAP_CONTRACT PATH_TYPE
 ```
 
-Decision logic (evaluated in order — first match wins):
+| Reader outcome | Bootstrap behavior |
+|----------------|--------------------|
+| No configured baseline, empty value, or missing directory | `public`; use bundled templates |
+| Existing baseline with valid reduced schema v1 export | `private`; retain `archetypes` and `selected` |
+| Existing baseline with missing CLI, invalid export, unsafe source, or producer failure | Abort; report the sanitized error reason |
+| Valid private contract but no matching repository markers | `private`, `selected: null`; require selection for Standard/Deep |
 
-| Condition | PATH_TYPE |
-|-----------|-----------|
-| `plan-baseline-path` key is absent in Session Config | `public` |
-| `plan-baseline-path` key is present but value is empty | `public` |
-| Key is present, value is non-empty, AND `test -d "$BASELINE_PATH"` succeeds | `private` |
-| Key is present, value is non-empty, BUT path does not exist on disk | `public` |
-
-Set `PATH_TYPE = private | public`. Do not report this detection to the user — it is silent.
-
-> **Note on rules-fetch (Phase 3.5 of SKILL.md):** The optional rules-fetch step runs regardless of `PATH_TYPE`. Both private (with `plan-baseline-path` set) and public (without it) repos can opt into the fetch by setting `baseline-ref` in Session Config. The fetch is independent of how the initial scaffold was generated.
-
----
+Lookup is offline and read-only. A broken configured contract never silently
+switches to a public archetype. Missing directories retain the established
+public fallback. Never guess a baseline path or fetch one automatically.
 
 ## Private Path
 
-When `PATH_TYPE = private`, the baseline templates are used directly. No new logic is needed here — the existing tier-template flow (`fast-template.md`, `standard-template.md`, `deep-template.md`) already calls `$BASELINE_PATH` scripts for CLAUDE.md generation and archetype file sourcing. Continue with the calling template file's steps unchanged.
+Read and execute [`private-contract.md`](private-contract.md): use its selection,
+staged scaffold, command/CI expectations, and S99 rule projection. Keep
+`CONFIRMED_ARCHETYPE` as the validated contract ID throughout the tier flow.
+The optional remote rules fetch is only a public-path opt-in; a configured
+private baseline supplies selected rules locally.
 
 ---
 
@@ -38,6 +44,12 @@ When `PATH_TYPE = private`, the baseline templates are used directly. No new log
 
 When `PATH_TYPE = public`, no `projects-baseline` is available. Use the plugin-bundled templates and platform-appropriate CLAUDE.md generation described below.
 
+For each file newly created by these steps, append its relative filename to the
+existing `BOOTSTRAP_FILES` array. This includes instruction files, minimal
+README/gitignore files and each copied template file. Preserve the accumulated
+array through inherited tiers; never append a directory or an existing owner
+file just because it is present.
+
 ### Detect Platform
 
 Read the current platform using the patterns from `skills/_shared/platform-tools.md`:

package/skills/bootstrap/references/bootstrap-ecosystem-health-flow.md

@@ -0,0 +1,48 @@
+# Bootstrap — Ecosystem-Health Flow (`--ecosystem-health`)
+
+> Reference of the `bootstrap` skill, split out of `SKILL.md` (#1246). Body moved **byte-identical**; only this header is new.
+> **Sibling-file paths inside this body are relative to the parent directory, not to `references/`**: `SKILL.md` → `../SKILL.md`. They were deliberately NOT rewritten, so the moved bytes stay verifiable against the pre-split file.
+
+## Ecosystem-Health Flow (`--ecosystem-health`)
+
+Entered when `$ARGUMENTS` contains `--ecosystem-health`. This is a **standalone flow** — it does not scaffold repo structure and does not write `bootstrap.lock`. Dispatch immediately; do not proceed to Phase 1.
+
+**Purpose:** Populate the `health-endpoints`, `pipelines`, and `criticalIssueLabels` configuration consumed by `skills/ecosystem-health/SKILL.md`. Runs the interactive wizard in `scripts/lib/ecosystem-wizard.mjs`, which detects CI provider + package manager automatically and prompts the user for the remaining values.
+
+**Steps:**
+
+1. **Run the wizard.**
+
+   ```bash
+   node "$PLUGIN_ROOT/scripts/lib/ecosystem-wizard.mjs" --repo-root "$(pwd)"
+   ```
+
+   The wizard will:
+   - Detect CI provider (`.gitlab-ci.yml` → `gitlab`; `.github/workflows/` → `github`; else `none`)
+   - Detect package manager from lockfile
+   - Prompt for health endpoints (format: `Name|URL`, comma-separated)
+   - Prompt for CI pipeline identifiers (format: `id` or `id:label`, comma-separated)
+   - Prompt for critical issue labels (comma-separated strings)
+
+2. **Wizard writes two files** (or skips each if already present):
+   - `CLAUDE.md` (or `AGENTS.md`) — appends `ecosystem-health:` block inside `## Session Config`
+   - `.orchestrator/policy/ecosystem.json` — full policy file (schema: `.orchestrator/policy/ecosystem.schema.json`)
+
+3. **No auto-commit.** The wizard prints what it wrote. The user reviews with `git status && git diff` and commits manually.
+
+**Report:** The wizard prints a one-line summary per file:
+
+```
+Ecosystem-Health Wizard complete.
+Written: .orchestrator/policy/ecosystem.json, CLAUDE.md
+Skipped (already present): (none)
+
+Review changes with: git status && git diff
+```
+
+**Idempotency:** Safe to re-run. If both output files are already present with matching content, the wizard exits 0 with "Nothing to do." To update, remove the existing `ecosystem-health:` key from Session Config and delete `.orchestrator/policy/ecosystem.json`, then re-run.
+
+See `skills/ecosystem-health/wizard.md` for the full prompt spec and schema details.
+
+---
+

package/skills/bootstrap/references/bootstrap-refresh-lock-flow.md

@@ -0,0 +1,37 @@
+# Bootstrap — Refresh-Lock Flow (`--refresh-lock`)
+
+> Reference of the `bootstrap` skill, split out of `SKILL.md` (#1246). Body moved **byte-identical**; only this header is new.
+> **Sibling-file paths inside this body are relative to the parent directory, not to `references/`**: `SKILL.md` → `../SKILL.md`. They were deliberately NOT rewritten, so the moved bytes stay verifiable against the pre-split file.
+
+## Refresh-Lock Flow (`--refresh-lock`)
+
+Entered when `$ARGUMENTS` contains `--refresh-lock`. No scaffolding questions are asked, and — unlike the Retroactive Flow above — this is NOT a no-op once the lock already has valid `version`/`tier` fields: refreshing is the load-bearing action.
+
+**Purpose (#57):** Acknowledge the current plugin version and reset the freshness clock on an existing, already-valid `bootstrap.lock` without disturbing its original bootstrap provenance. This closes the gap left by the Retroactive Flow: once a lock already has `version` + `tier`, re-running `/bootstrap --retroactive` reports "bootstrap.lock already present ... Nothing to do." and changes nothing — exactly the no-op the bootstrap-lock-freshness probe (#186/#290) was recommending as its remediation. `--refresh-lock` is the actual remediation for a present-but-stale or version-drifted lock.
+
+**Steps:**
+
+1. **Precondition check.** Read `.orchestrator/bootstrap.lock`. If missing, or present but missing a non-empty `version` or `tier` field, abort with: `Error: No valid bootstrap.lock found. Run /bootstrap or /bootstrap --retroactive first.` Do not fabricate a lock — this flow only refreshes an existing one.
+
+2. **Resolve the current plugin version.** Read `plugin-version` from `$PLUGIN_ROOT/package.json` (same source Phase 4 uses).
+
+3. **Call the refresh writer.**
+
+   ```js
+   import { refreshBootstrapLock } from '$PLUGIN_ROOT/scripts/lib/bootstrap-lock-refresh.mjs';
+   const result = refreshBootstrapLock({
+     repoRoot: REPO_ROOT,
+     currentPluginVersion: PLUGIN_VERSION,
+   });
+   ```
+
+   `refreshBootstrapLock` writes (or replaces, if already present) exactly two lines — `refreshed-at: <ISO 8601 UTC>` and `refreshed-plugin-version: <current plugin version>` — via the same atomic tmp-file + rename pattern used by the Retroactive Flow's lock write: write to a sibling tmp file, then rename over the target so the lock is never observed half-written. **Every other line of the lock — `bootstrapped-at`, `timestamp`, `plugin-version`, `tier`, `archetype`, `source`, … — is left byte-identical.** This is the provenance-honesty guarantee: a refresh is an acknowledgement, not a re-bootstrap. On failure (`result.ok === false`), surface `result.message` and stop — do not retry with a fabricated lock.
+
+4. **No auto-commit.** Unlike the Retroactive Flow, `--refresh-lock` does not stage or commit. The refreshed lock is a small, reviewable diff (two changed/added lines); the user commits it alongside their own work at their own cadence.
+
+5. **Report.** Print: `Lock refreshed (refreshed-at: <now>, plugin-version: <current>). Original bootstrap provenance unchanged.`
+
+**Idempotency.** Running `/bootstrap --refresh-lock` twice in a row replaces the same two lines in place — it never duplicates them.
+
+---
+

package/skills/bootstrap/references/bootstrap-retroactive-flow.md

@@ -0,0 +1,108 @@
+# Bootstrap — Retroactive Flow (`--retroactive`)
+
+> Reference of the `bootstrap` skill, split out of `SKILL.md` (#1246). Body moved **byte-identical**; only this header is new.
+> **Sibling-file paths inside this body are relative to the parent directory, not to `references/`**: `SKILL.md` → `../SKILL.md`. They were deliberately NOT rewritten, so the moved bytes stay verifiable against the pre-split file.
+
+## Retroactive Flow (`--retroactive`)
+
+Entered when `$ARGUMENTS` contains `--retroactive`. Writes the lock file and, per #182, optionally patches missing mandatory Session Config fields with defaults.
+
+**Purpose:** Adopt an existing repo that already has `CLAUDE.md` + `## Session Config` but was bootstrapped manually (no `bootstrap.lock`). Writes the lock so the gate passes on all future invocations, and ensures the Session Config block satisfies the validated schema defined in `scripts/lib/config-schema.mjs`.
+
+**Steps:**
+
+1. **Verify preconditions.** Confirm `CLAUDE.md` (or `AGENTS.md`) exists and contains `## Session Config`. If not, abort: `Error: CLAUDE.md with Session Config required for retroactive bootstrap.`
+
+2. **Check lock not already present.** If `.orchestrator/bootstrap.lock` already exists and has valid `version` + `tier` fields, report: `bootstrap.lock already present (tier: <tier>). Nothing to do.` and exit 0 (idempotent).
+
+3. **Infer tier from file inventory.** Examine the repo root:
+
+   | Condition (evaluated in order) | Inferred Tier |
+   |---|---|
+   | CI file present (`.gitlab-ci.yml` OR `.github/workflows/`) AND `CHANGELOG.md` present | `deep` |
+   | Package manifest present (`package.json` OR `pyproject.toml`) | `standard` |
+   | Neither of the above | `fast` |
+
+   Store as `INFERRED_TIER`.
+
+4. **Infer archetype.** Run Phase 0.5's read-only source detection. For a private
+   contract, use its detected `selected.id`; retain `null` with an explicit
+   `insufficient-evidence` report if no markers match. An invalid configured
+   contract aborts. Do not scaffold or apply rules in this retroactive flow.
+   For the public path, use best-effort detection from existing files:
+   - `pyproject.toml` present → `python-uv`
+   - `package.json` with `next` in dependencies → `nextjs-minimal`
+   - `package.json` without `next` → `node-minimal`
+   - No manifest → `null`
+
+   Store as `INFERRED_ARCHETYPE`.
+
+5. **Write bootstrap.lock.** Create `.orchestrator/` if needed, then write:
+   ```yaml
+   # .orchestrator/bootstrap.lock
+   version: 1
+   tier: <INFERRED_TIER>
+   archetype: <INFERRED_ARCHETYPE or null>
+   timestamp: <current ISO 8601 UTC>
+   source: retroactive
+   plugin-version: <current plugin version from $PLUGIN_ROOT/package.json>
+   ```
+
+6. **Patch Session Config (#182).** Run the validator against the current `## Session Config` block; append any missing mandatory fields with defaults. The 7 mandatory fields (per `scripts/lib/config-schema.mjs`) are: `test-command`, `typecheck-command`, `lint-command`, `agents-per-wave`, `waves`, `persistence`, `enforcement`.
+
+   ```bash
+   CONFIG_OUT="$(node "$PLUGIN_ROOT/scripts/parse-config.mjs" 2>&1 >/dev/null)"
+   # parse-config.mjs emits validation warnings to stderr when enforcement=warn.
+   # Grep for 'must be' lines (issued by validate-config.mjs) to detect missing fields.
+   MISSING_FIELDS="$(echo "$CONFIG_OUT" | grep -oE '(test-command|typecheck-command|lint-command|agents-per-wave|waves|persistence|enforcement)' | sort -u || true)"
+   if [[ -n "$MISSING_FIELDS" ]]; then
+     # Detect package manager to pick sensible defaults for commands.
+     PM_DEFAULTS="$(node --input-type=module -e "
+       import {detectPackageManager, defaultQualityGateCommands} from '$PLUGIN_ROOT/scripts/lib/package-manager.mjs';
+       const pm = detectPackageManager(process.cwd());
+       const cmds = defaultQualityGateCommands(pm);
+       console.log('test-command: ' + cmds.test.command);
+       console.log('typecheck-command: ' + cmds.typecheck.command);
+       console.log('lint-command: ' + cmds.lint.command);
+     " 2>/dev/null)"
+
+     CONFIG_FILE="CLAUDE.md"
+     [[ -f "AGENTS.md" ]] && CONFIG_FILE="AGENTS.md"
+
+     # Append each missing field under the ## Session Config block.
+     for field in $MISSING_FIELDS; do
+       case "$field" in
+         test-command|typecheck-command|lint-command)
+           default_line="$(echo "$PM_DEFAULTS" | grep "^$field:")" ;;
+         agents-per-wave) default_line="agents-per-wave: 6" ;;
+         waves)           default_line="waves: 5" ;;
+         persistence)     default_line="persistence: true" ;;
+         enforcement)     default_line="enforcement: warn" ;;
+       esac
+       # Insert after `## Session Config` line if not already present.
+       grep -q "^$field:" "$CONFIG_FILE" \
+         || awk -v insert="$default_line" '/^## Session Config/ && !done { print; print ""; print insert; done=1; next } { print }' "$CONFIG_FILE" > "$CONFIG_FILE.tmp" \
+         && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
+     done
+     echo "Patched $CONFIG_FILE with defaults for: $MISSING_FIELDS"
+   fi
+   ```
+
+   This patch is best-effort: existing fields are never overwritten. If no fields are missing, this step is a no-op.
+
+7. **Commit.** Stage the lock file (and the patched config file, if it changed) and commit:
+   ```bash
+   mkdir -p .orchestrator
+   git add .orchestrator/bootstrap.lock
+   # Also stage CLAUDE.md/AGENTS.md if step 6 patched it.
+   git diff --name-only --cached CLAUDE.md AGENTS.md 2>/dev/null | head -1 >/dev/null || {
+     [[ -f CLAUDE.md ]] && git diff --quiet CLAUDE.md || git add CLAUDE.md
+     [[ -f AGENTS.md ]] && git diff --quiet AGENTS.md || git add AGENTS.md
+   }
+   git commit -m "chore: bootstrap lock (retroactive)"
+   ```
+
+8. **Report.** Print: `Retroactive bootstrap complete. Lock written (tier: <INFERRED_TIER>, source: retroactive).` Include a second line `Patched Session Config: <fields>` when step 6 applied any patches, otherwise `No config changes.`.
+
+---
+

package/skills/bootstrap/references/bootstrap-rules-fetch-bridge.md

@@ -0,0 +1,64 @@
+# Bootstrap — Phase 3.6: (Optional) Rules-Fetch Bridge
+
+> Reference of the `bootstrap` skill, split out of `SKILL.md` (#1246). Body moved **byte-identical**; only this header is new.
+> **Sibling-file paths inside this body are relative to the parent directory, not to `references/`**: `SKILL.md` → `../SKILL.md`, `private-contract.md` → `../private-contract.md`, `standard-template.md` → `../standard-template.md`, `deep-template.md` → `../deep-template.md`. They were deliberately NOT rewritten, so the moved bytes stay verifiable against the pre-split file.
+
+## Phase 3.6: (Optional) Rules-Fetch Bridge
+
+> Closes session-orchestrator issue #110.
+
+After scaffolding, the Standard and Deep templates execute S99. On the private
+path, it applies the selected contract's local rule union, rechecks conditional
+dependencies and preserves existing files. It excludes every plugin-owned
+basename and aborts on an invalid configured contract; see `private-contract.md`.
+
+On the public path, S99 retains the optional remote rules-fetch step. It pulls
+canonical `.claude/rules/*.md` directly from the configured baseline GitLab
+project, excluding all plugin-owned basenames. The remote step only fires when:
+
+- `baseline-ref` is present in Session Config
+- `GITLAB_TOKEN` env var is set
+- `scripts/lib/fetch-baseline.mjs` is present in the plugin
+- A GitLab host is resolvable from the `gitlab-host` Session Config key (or the `GITLAB_HOST` env var) — never a hardcoded default
+
+When triggered, the step:
+
+1. Loops over a default rule manifest, invoking `node scripts/lib/fetch-baseline.mjs <project_id> <file_path> <baseline-ref>` once per rule. The CLI prints one file body to stdout (exit 0 success; 1 auth, 2 not-found, 3 network) — bootstrap redirects stdout to the target path and skips failures so a single 404 cannot abort the batch.
+2. Fetches each rule listed in the default manifest from the configured `baseline-project-id` (default `52`) at the configured `baseline-ref`
+3. Writes `.claude/.baseline-fetch.lock` (via an inline `node --input-type=module -e`) recording what was fetched
+4. Populates `.claude/.baseline-cache/` for offline fallback on subsequent invocations
+
+When the fetch fails (network error, auth, missing file), bootstrap **does not abort**. Rules will arrive in the repo via Clank's weekly baseline sync MRs (the legacy path). A warning is printed.
+
+**Why opt-in:** Repos without `baseline-ref` continue to receive rules via the existing Clank sync flow. The fetch bridge is a faster on-demand alternative for newly-bootstrapped repos that want current rules immediately.
+
+**Local edits:** Re-running bootstrap with `baseline-ref` set will overwrite `.claude/rules/*.md` (rules are canonical). Repo-specific extensions belong in `.claude/rules/local/*.md` (not fetched, not overwritten).
+
+See `standard-template.md` (Step S99) and `deep-template.md` (Step D99) for the implementation, and `docs/session-config-reference.md` for the `baseline-ref` and `baseline-project-id` field definitions.
+
+### `.claude/.baseline-fetch.lock` Schema
+
+The lock file is committed to git and records what was fetched.
+
+```yaml
+# .claude/.baseline-fetch.lock
+version: 1
+project_id: 52
+baseline_ref: main
+fetched_at: 2026-04-17T13:42:00Z   # ISO 8601 UTC
+files:
+  - .claude/rules/development.md
+  - .claude/rules/security.md
+  - .claude/rules/...
+```
+
+| Field | Description |
+|---|---|
+| `version` | Lock file schema version. Currently `1`. |
+| `project_id` | GitLab project ID the files were fetched from. |
+| `baseline_ref` | The git ref (branch/tag/SHA) at fetch time. |
+| `fetched_at` | ISO 8601 UTC timestamp. |
+| `files` | List of fetched file paths (relative to repo root). |
+
+---
+

package/skills/bootstrap/standard-template.md

@@ -5,6 +5,20 @@
 
 Standard tier is a strict superset of Fast tier. Execute all Fast-tier steps first, then the Standard-specific steps below.
 
+Track actual newly created relative files in one `BOOTSTRAP_FILES` array across
+all inherited steps. Append each file when created; preserve the array across
+repeated steps. Never append an existing owner file or a directory.
+
+## Private Contract Preparation
+
+When `PATH_TYPE = private`, resolve `CONFIRMED_ARCHETYPE` with
+`private-contract.md` and execute its Scaffold section **before** the inherited
+Fast steps. Preserve its rendered metadata, manifests, source, README and CI.
+Add its reported created files to `BOOTSTRAP_FILES`. Skip the four public
+archetype sections below, then continue at Step 3a, S99 and the lock/quality-policy
+steps. Populate command expectations from the selected contract as described
+in `private-contract.md`.
+
 ## Step 1–7: Execute Fast Tier
 
 Read and execute `skills/bootstrap/fast-template.md` Steps 1–7 in full. Do not skip any step. The Fast commit (`chore: bootstrap (fast)`) is NOT made — Fast steps produce files only; the single commit happens at Standard Step 7 below.
@@ -21,9 +35,9 @@ Before executing the stack-specific steps, resolve the final archetype:
 ARCHETYPE = CONFIRMED_ARCHETYPE  # set by SKILL.md from intensity-heuristic or user selection
 ```
 
-Valid values: `static-html` | `node-minimal` | `nextjs-minimal` | `python-uv`
+For `PATH_TYPE = public`, valid values are `static-html` | `node-minimal` | `nextjs-minimal` | `python-uv`. Private IDs come only from the validated contract.
 
-If `ARCHETYPE` is `null` or unset at this point, default to `node-minimal`.
+On the public path only, if `ARCHETYPE` is `null` or unset, default to `node-minimal`. A private missing/invalid selection aborts before scaffolding; it never reaches the public sections.
 
 The sections below are conditional on `ARCHETYPE`. Execute only the section that matches.
 
@@ -592,12 +606,11 @@ indent_size = 2
 
 Canonical implementation in [`_shared-template.md#parallel-sessions-rule`](_shared-template.md).
 
-Run `node "$PLUGIN_ROOT/scripts/lib/rules-sync.mjs" --repo-root "$REPO_ROOT"` — it vendors every
-rule registered in `rules/_index.md` (idempotent: missing→create, identical→skip, differs→overwrite),
-and it is the only writer that applies the pre-write validator, the basename-collision guard and the
-copy-on-write branch that preserves repo-private rules. The shared partial also runs
-`cp "$PLUGIN_ROOT/templates/_shared/loop.md" "$REPO_ROOT/.claude/loop.md"` so bare `/loop` gets a
-repo-aware maintenance prompt. See shared partial for full shell command. Issues #155, #633, #1060.
+Execute the shared partial's `syncBootstrapRules` action. It supplies private
+required basenames to `scripts/lib/rules-sync.mjs`, preserving its manifest,
+pre-write validation and local-override checks. The partial appends actual newly
+created rule paths, and creates `.claude/loop.md` only when missing. See the
+shared partial for the executable shell command. Issues #155, #633, #1060.
 
 Note: Runs before S99. S99 no longer fetches `parallel-sessions.md` from the baseline — that entry
 was removed from the S99 manifest in #1060. The baseline copy carries no provenance header, so
@@ -611,8 +624,10 @@ Create the metrics directory and an empty learnings file so the `/evolve` skill
 
 ```bash
 mkdir -p "$REPO_ROOT/.orchestrator/metrics"
-[[ -f "$REPO_ROOT/.orchestrator/metrics/learnings.jsonl" ]] || \
+if [[ ! -e "$REPO_ROOT/.orchestrator/metrics/learnings.jsonl" && ! -L "$REPO_ROOT/.orchestrator/metrics/learnings.jsonl" ]]; then
   : > "$REPO_ROOT/.orchestrator/metrics/learnings.jsonl"
+  BOOTSTRAP_FILES+=(.orchestrator/metrics/learnings.jsonl)
+fi
 ```
 
 **Idempotent.** Re-running bootstrap does not overwrite an existing file.
@@ -624,11 +639,13 @@ mkdir -p "$REPO_ROOT/.orchestrator/metrics"
 
 Canonical implementation in [`_shared-template.md#baseline-fetch`](_shared-template.md).
 
-OPT-IN: only fires when `baseline-ref` is in Session Config, `GITLAB_TOKEN` is set, and
+PRIVATE: applies the selected local contract rule union without network access, preserving existing files and excluding every plugin-owned basename. An invalid contract aborts.
+
+PUBLIC OPT-IN: only fires when `baseline-ref` is in Session Config, `GITLAB_TOKEN` is set, and
 `scripts/lib/fetch-baseline.mjs` exists. Fetches `.claude/rules/*.md` from the baseline GitLab
 project (default project 52) and writes `.claude/.baseline-fetch.lock`. Does NOT abort on failure.
-The rule manifest includes `owner-persona.md` (alongside `parallel-sessions.md`, `development.md`,
-and the rest of the always-on rules). See shared partial for full implementation.
+The private rule manifest comes from the selected contract. Every plugin-owned
+basename is excluded from either delivery path. See the shared partial.
 
 ---
 
@@ -649,6 +666,8 @@ Write `.orchestrator/bootstrap.lock` **atomically** (mktemp + mv prevents a corr
 process is interrupted mid-write):
 
 ```bash
+_LOCK_CREATED=false
+[[ -e "$REPO_ROOT/.orchestrator/bootstrap.lock" || -L "$REPO_ROOT/.orchestrator/bootstrap.lock" ]] || _LOCK_CREATED=true
 _LOCK_TMP=$(mktemp "$REPO_ROOT/.orchestrator/bootstrap.lock.XXXXXX")
 cat > "$_LOCK_TMP" << LOCK
 # .orchestrator/bootstrap.lock
@@ -661,6 +680,7 @@ plugin-version: <session-orchestrator plugin version — read from $PLUGIN_ROOT/
 bootstrapped-at: <current ISO 8601 UTC — same value as timestamp; distinct field for age-validation probe>
 LOCK
 mv "$_LOCK_TMP" "$REPO_ROOT/.orchestrator/bootstrap.lock"
+if [[ "$_LOCK_CREATED" = true ]]; then BOOTSTRAP_FILES+=(.orchestrator/bootstrap.lock); fi
 ```
 
 Set `source` using the same logic as fast-template Step 5:
@@ -673,8 +693,8 @@ Set `source` using the same logic as fast-template Step 5:
 
 Canonical implementation in [`_shared-template.md#quality-gate-policy`](_shared-template.md).
 
-Write `.orchestrator/policy/quality-gates.json` with package-manager-detected defaults (idempotent:
-skip if file already exists). Uses `scripts/lib/package-manager.mjs`; falls back to npm defaults.
+Write `.orchestrator/policy/quality-gates.json` from exact private contract gates,
+or package-manager defaults on the public path. Skip existing owner policy.
 See shared partial for full shell command. Issue #183.
 
 <!-- @include _shared-template.md#state-md-scaffold -->
@@ -682,8 +702,9 @@ See shared partial for full shell command. Issue #183.
 
 Canonical implementation in [`_shared-template.md#state-md-scaffold`](_shared-template.md).
 
-Scaffold `.claude/STATE.md` from `skills/bootstrap/STATE.md.template` (idempotent: skip if
-already exists). On Codex CLI / Cursor IDE, substitute `.codex/` or `.cursor/` for `.claude/`.
+Scaffold `.claude/STATE.md` (idempotent: skip if it already exists). <!-- path-check: example -->
+Use `skills/bootstrap/STATE.md.template`.
+On Codex CLI / Cursor IDE, substitute `.codex/` or `.cursor/` for `.claude/`.
 See shared partial for full shell command. Issue #184.
 
 <!-- @include _shared-template.md#agents-scaffold -->
@@ -701,15 +722,9 @@ Stage all created files and commit:
 
 ```bash
 cd "$REPO_ROOT"
-BOOTSTRAP_FILES=(
-  CLAUDE.md AGENTS.md .gitignore README.md .orchestrator/bootstrap.lock
-  .orchestrator/policy/quality-gates.json
-  package.json pyproject.toml tsconfig.json eslint.config.mjs .prettierrc
-  .editorconfig src/ tests/ .claude/
-)
 # Add only the files bootstrap created — no sweeping -u/-A to avoid catching pre-existing files
-for _f in "${BOOTSTRAP_FILES[@]}"; do
-  [[ -e "$_f" ]] && git add -- "$_f"
+for _f in ${BOOTSTRAP_FILES[@]+"${BOOTSTRAP_FILES[@]}"}; do
+  [[ -f "$_f" && ! -L "$_f" ]] && git add -- "$_f"
 done
 git commit -m "chore: bootstrap (standard)"
 ```

package/skills/claude-md-drift-check/SKILL.md

@@ -41,7 +41,7 @@ PHASE 1 IMPLEMENTED (2026-04-19). Session-end opt-in quality gate. Upstream of `
 | 6 | `session-config-parity` | Top-level keys under `## Session Config` in `CLAUDE.md` / `AGENTS.md` | diff against `docs/session-config-template.md`; a missing MANDATORY (minimal-baseline) key is an error, a missing OPT-IN-baseline-only key is a warning |
 | 7 | `vault-dir-parity` | `vault-integration.vault-dir` in BOTH `CLAUDE.md` AND `AGENTS.md` | reuse `_parseVaultIntegration`; flag when the two files disagree. Short-circuits to PASS when the two are the SAME file by construction (symlink / same inode / byte-identical generated copy) |
 | 8 | `generated-rule-staleness` *(WARN only)* | `.claude/rules/*.md` with `auto-generated: true` frontmatter | extract `learning-key`; WARN when the key is absent from `.orchestrator/metrics/learnings.jsonl` or its learning's `expires_at` is in the past; skipped silently when no auto-generated rules exist |
-| 9 | `rule-scoping` | `.claude/rules/*.md` frontmatter + `## See Also` footers + `.claude/rules/<name>.md` citations in `CLAUDE.md`/`AGENTS.md` | five probes: `paths:` frontmatter (error), cited-but-missing rule citations (error), zero-match `globs:` patterns (warn), foreign PascalCase glob tokens (warn), unreadable rule files (warn — surfaced instead of silently skipped); skipped silently when `.claude/rules/` is absent |
+| 9 | `rule-scoping` | `.claude/rules/*.md` frontmatter + `## See Also` footers + `.claude/rules/<name>.md` citations in `CLAUDE.md`/`AGENTS.md` | six probes: `paths:` frontmatter (error), cited-but-missing rule citations (error), zero-match `globs:` patterns (warn), foreign PascalCase glob tokens (warn), unreadable rule files (warn — surfaced instead of silently skipped), declared fleet-intent globs (**note**, never warn); skipped silently when `.claude/rules/` is absent |
 | 10 | `docs-parity` | `docs/components.md` count-claims, Session Config key parity (`docs/session-config-template.md` vs `docs/session-config-reference.md`), `.claude/metrics/` stale-path references in `docs/*.md` / `docs/examples/*.md` | three sub-checks (a/b/c) — see below; skipped silently when `docs/components.md` is absent |
 
 Check 3 deliberately scopes to forward-looking sections. Mentions inside "Recently Closed", "Decisions", "Archive", etc. describe history and must not be flagged.
@@ -65,7 +65,9 @@ Check 7 (issue #600) is the **only** check that intentionally reads BOTH instruc
 
 The same predicate guards Check 9's probe 2a, which iterates `['CLAUDE.md', 'AGENTS.md']`: with an aliased `AGENTS.md` it scans `CLAUDE.md` only, because otherwise every dangling `.claude/rules/*.md` citation would be reported TWICE — one defect, two errors, and in `--mode strict` a doubled blocking surface against a file the operator is not allowed to edit.
 
-Check 9 (`rule-scoping`) validates `.claude/rules/*.md` frontmatter against the `scripts/lib/rule-loader.mjs` contract, catching the class of defect where a rule silently drifts out of the activation pipeline the loader actually implements. Four probes: **(1) paths-presence** — a top-level `paths:` frontmatter key is not a key `rule-loader.mjs` recognises (it only reads `globs:`), so a rule with `paths:` silently loads ALWAYS-ON regardless of intended file scope; flagged as an error. **(2) cited-but-missing** — `(a)` `.claude/rules/<name>.md` citations inside `CLAUDE.md`/`AGENTS.md` that don't resolve to a file on disk, and `(b)` bare `<name>.md` tokens in a rule's own `## See Also` footer that don't exist as sibling rule files (tokens carrying a path separator, e.g. `../../skills/_shared/state-ownership.md`, are cross-directory references and explicitly out of scope); both flagged as errors. **(3) zero-match-globs** — a `globs:` pattern matching zero files in `git ls-files` (falls back to a manual directory walk when git is unavailable); flagged as a WARNING, not an error, because library/exemplar repos legitimately carry dead stack rules (this repo alone carries ~37 by design — Swift/Next.js/Supabase rules with no matching files in a pure-Node-ESM codebase). **(4) foreign-glob** — a glob pattern containing a PascalCase product-like token (regex `[A-Z][a-z]+[A-Z]`, e.g. `WalkAITalkieTests`) — a likely copy-paste leftover from another project's rule scope; flagged as a WARNING. Glob matching reuses the same picomatch-with-inline-fallback resolution `scripts/lib/rule-loader.mjs` uses (`parseGlobsFrontmatter` is imported directly; the picomatch resolution itself is duplicated locally since `rule-loader.mjs` does not export a public matcher function). The check is skipped silently (no `checks_run` entry, no `checks_skipped` entry) when `.claude/rules/` is absent, or explicitly via `--skip-rule-scoping`.
+Check 9 (`rule-scoping`) validates `.claude/rules/*.md` frontmatter against the `scripts/lib/rule-loader.mjs` contract, catching the class of defect where a rule silently drifts out of the activation pipeline the loader actually implements. Six probes: **(1) paths-presence** — a top-level `paths:` frontmatter key is not a key `rule-loader.mjs` recognises (it only reads `globs:`), so a rule with `paths:` silently loads ALWAYS-ON regardless of intended file scope; flagged as an error. **(2) cited-but-missing** — `(a)` `.claude/rules/<name>.md` citations inside `CLAUDE.md`/`AGENTS.md` that don't resolve to a file on disk, and `(b)` bare `<name>.md` tokens in a rule's own `## See Also` footer that don't exist as sibling rule files (tokens carrying a path separator, e.g. `../../skills/_shared/state-ownership.md`, are cross-directory references and explicitly out of scope); both flagged as errors. **(3) zero-match-globs** — a `globs:` pattern matching zero files in `git ls-files` (falls back to a manual directory walk when git is unavailable); flagged as a WARNING, not an error, because library/exemplar repos legitimately carry dead stack rules. **(4) foreign-glob** — a glob pattern containing a PascalCase product-like token (regex `[A-Z][a-z]+[A-Z]`, e.g. `WalkAITalkieTests`) — a likely copy-paste leftover from another project's rule scope; flagged as a WARNING. **(5) unreadable-file** — a rule file that could not be read (permissions, a race with a concurrent delete); flagged as a WARNING rather than silently skipped, so a completeness audit does not drop files, and so an unreadable file cannot brick the gate under `mode: hard`. **(6) fleet-intent-glob** — a `globs:` pattern DECLARED as fleet intent goes to `notes[]` (see below), never to `warnings[]`, and the declaration also settles probe 4 for that same pattern: a pattern the rule author declared is by construction not a copy-paste leftover. Glob matching reuses the same picomatch-with-inline-fallback resolution `scripts/lib/rule-loader.mjs` uses (`parseGlobsFrontmatter` is imported directly; the picomatch resolution itself is duplicated locally since `rule-loader.mjs` does not export a public matcher function). The check is skipped silently (no `checks_run` entry, no `checks_skipped` entry) when `.claude/rules/` is absent, or explicitly via `--skip-rule-scoping`.
+
+**Fleet-intent declaration (Check 9, probe 6).** A rule may declare that a `globs:` pattern is aimed at CONSUMER repos rather than this one, via its own frontmatter key `fleet-intent-globs:`. Accepted forms are block style (`fleet-intent-globs:` plus indented `  - "<pattern>"` lines), flow style (`fleet-intent-globs: ["a", "b"]`) and a single inline value; surrounding quotes are stripped, blank and `#` comment lines are ignored. The key is inert for rule loading — `rule-loader.mjs`'s `parseGlobsFrontmatter` skips unknown top-level keys and their continuation lines. A declared pattern is reported in `notes[]` with its file, the pattern, whether it matches `≥1` or `0` tracked files here, and the declaration `source` (`frontmatter`). The grain is per pattern AND per rule file: declaring one glob amnesties neither a sibling glob in the same rule nor the same pattern in another rule. There is deliberately NO checker-side exemption list: a rule that does not declare the pattern itself is not exempt, so the declaration always sits with the rule it describes.
 
 Check 10 (`docs-parity`, issue #780) validates the public docs surface against live repository state via three sub-checks, all reported under the single `docs-parity` check id: **(a) count-claims** — `docs/components.md`'s own heading counts ("## Skills (N user-facing)", "## Commands (N)", "## Agents (N typed sub-agents)", "## Hook event types (N)") are compared against the SAME actual on-disk derivation the surface-count family (Check 5) uses (`countSkills`/the commands-dir listing/`countAgents`/`readHookCounts`) — NOT Check 5's `claimRe` regexes, which are tuned for CLAUDE.md/README prose phrasing and verifiably do not match `components.md`'s own heading convention; a dedicated set of regexes tailored to the doc's actual authored structure is used instead. **(b) config-block-parity** — top-level Session Config keys documented in `docs/session-config-template.md` (opt-in baseline, via the Check 6 'last'-occurrence extractor) are compared against `docs/session-config-reference.md`; a key is considered documented in the reference when it appears in a `yaml` fence (any indent), a `##`/`###`/`####` heading, or the first cell of a markdown table row (`` | `key-name` | ... ``) — the reference's dominant documentation shape is one table row per field, so a naive fence-only extraction under-counts what it actually documents. Missing keys surface as `docs-parity` errors attributed to `docs/session-config-reference.md`. **(c) metrics-path-liveness** — any `.claude/metrics/` path reference (stale; canonical is `.orchestrator/metrics/`) found in root `docs/*.md` or `docs/examples/*.md` surfaces as an error at its exact file/line. The whole check is skipped silently (no `checks_run` entry, no `checks_skipped` entry) when `docs/components.md` is absent, or explicitly via `--skip-docs-parity`.
 
@@ -124,10 +126,15 @@ Environment:
   "warnings": [
     { "check": "<name>", "file": "<relative path>", "line": N, "message": "<human>", "extracted": "<raw text>" }
   ],
+  "notes": [
+    { "check": "rule-scoping", "probe": "fleet-intent-glob", "file": "<relative path>", "line": N, "message": "<human>", "extracted": "<pattern>", "source": "frontmatter" }
+  ],
   "command_count": { "actual": N }
 }
 ```
 
+`notes[]` is the THIRD output category, alongside `errors[]` and `warnings[]`: a finding that is reported but asks for no action. It never affects `status` or the exit code, and it is always present (empty array when nothing was noted, including on the short-circuit "no scope files matched" path). Its only producer today is Check 9's fleet-intent-glob probe.
+
 The `resolved_path` / `resolved_kind` pair surfaces the alias resolution outcome (issue #33 AC2) so users on either platform can audit which instruction file the checker scanned. `kind: 'claude'` for `CLAUDE.md`, `kind: 'agents'` for `AGENTS.md`, `null` when neither was found.
 
 When `command-count` fires a drift error, the error object also carries `"command_count": { "actual": N, "claimed": M }` for easy programmatic diffing.