session-orchestrator 4.0.1 → 4.2.0

package/skills/bootstrap/SKILL.md

@@ -42,8 +42,9 @@ Store `INVOCATION_MODE = transitive | direct`.
 
 **Before dispatching to any tier template**, read `skills/bootstrap/public-fallback.md` and execute Step 1 (PATH_TYPE detection). Store the result as `PATH_TYPE = private | public`. This detection is silent — no user interaction.
 
-- `private`: `plan-baseline-path` is present in Session Config AND the path exists on disk. Baseline templates will be used for CLAUDE.md generation and archetype file sourcing.
-- `public`: `plan-baseline-path` is absent, empty, or points to a non-existent path. Plugin-bundled templates from `templates/` will be used.
+- `private`: the existing host-local config resolution found a baseline directory and its reduced contract validated. Use `private-contract.md` for selection, templates, commands, CI and rules.
+- `public`: the resolved baseline is absent, empty, or points to a missing directory. Use plugin-bundled templates.
+- Existing but invalid configured baseline: abort before dispatch; report the reader's sanitized error reason.
 
 Pass `PATH_TYPE` into Phase 1 and all subsequent phases. All tier templates (`fast-template.md`, `standard-template.md`, `deep-template.md`) must consult `public-fallback.md` for CLAUDE.md generation and archetype file sourcing when `PATH_TYPE = public`.
 
@@ -59,7 +60,7 @@ Inputs to the heuristic:
 
 Output from Phase 1:
 - `RECOMMENDED_TIER` = `fast` | `standard` | `deep`
-- `RECOMMENDED_ARCHETYPE` = `static-html` | `node-minimal` | `nextjs-minimal` | `python-uv` | `null`
+- `RECOMMENDED_ARCHETYPE` = validated private contract ID, public ID, or `null`
 - `HEURISTIC_REASON` = one-sentence explanation of why this tier was chosen (shown to user)
 - `PATH_TYPE` = `private` (plan-baseline-path configured and path exists) | `public` (no baseline)
 
@@ -120,7 +121,16 @@ AskUserQuestion({
 })
 ```
 
-Store as `CONFIRMED_ARCHETYPE`. The tier/stack block contributes **1–2** questions; a first-run full bootstrap adds **6 more** from the owner interview (Phase 3.5, five questions) and dispatcher-autonomy capture (Phase 3.5.1, one question) — **7–9 total**.
+Store as `CONFIRMED_ARCHETYPE`.
+
+For `PATH_TYPE = private` and Standard/Deep, execute `private-contract.md`'s
+Select section now. Reuse a valid detected or explicit ID; when evidence is
+insufficient, select from the returned catalog before scaffolding. Tier flags
+skip tier confirmation, not required private archetype selection. Never pass a
+null private ID into the public default. On upgrades, validate the lock's ID
+against the currently configured contract before generating any files.
+
+The tier/stack block contributes **1–2** questions; a first-run full bootstrap adds **6 more** from the owner interview (Phase 3.5, five questions) and dispatcher-autonomy capture (Phase 3.5.1, one question) — **7–9 total**.
 
 ## Upgrade Flow (`--upgrade <tier>`)
 
@@ -139,7 +149,12 @@ Entered when `$ARGUMENTS` contains `--upgrade <tier>`. No scaffolding questions
    `Error: Cannot downgrade from <CURRENT_TIER> to <TARGET_TIER>. Upgrade path is one-directional (fast → standard → deep).`
    Exit non-zero.
 
-4. **Compute delta.** Determine which files the target tier adds over the current tier:
+4. **Resolve source and compute delta.** Run Phase 0.5's read-only source
+   detection before dispatching any template. For a private contract, validate
+   the lock's archetype with `--archetype`; if the Fast lock has no archetype,
+   select from the returned catalog using `private-contract.md`. Use its staged,
+   additive scaffold and CI expectations; do not apply the public file matrix.
+   For the public path, determine which files the target tier adds:
    - `fast → standard`: all Standard-tier files (`package.json`/`pyproject.toml`, `tsconfig.json`, `eslint.config.mjs`, `.prettierrc`, `.editorconfig`, `tests/`, `src/`)
    - `standard → deep`: all Deep-tier files (CI pipeline, `CODEOWNERS`, `CHANGELOG.md`, issue templates, MR/PR template, branch protection)
    - `fast → deep`: union of both deltas (apply Standard first, then Deep)
@@ -148,7 +163,7 @@ Entered when `$ARGUMENTS` contains `--upgrade <tier>`. No scaffolding questions
 
 6. **Apply delta files.** Execute only the relevant template steps for the missing files. Read the appropriate template (`standard-template.md` and/or `deep-template.md`) and execute ONLY the steps that produce the delta files. Do NOT re-run already-completed steps.
 
-7. **Update bootstrap.lock atomically.** Overwrite `.orchestrator/bootstrap.lock` with `tier: <TARGET_TIER>`. Preserve `archetype`, `timestamp` (update to now), and `source` from the existing lock. Write `plugin-version` from `$PLUGIN_ROOT/package.json` (current plugin version at upgrade time).
+7. **Update bootstrap.lock atomically.** Overwrite `.orchestrator/bootstrap.lock` with `tier: <TARGET_TIER>`. Preserve a validated existing `archetype`; when upgrading a null Fast archetype, record the newly confirmed ID and scaffold source. Update `timestamp` to now. Preserve the prior `source` otherwise. Write `plugin-version` from `$PLUGIN_ROOT/package.json` (current plugin version at upgrade time).
 
 8. **Commit.** Stage only the delta files that were just written and commit:
    ```bash
@@ -185,7 +200,11 @@ Entered when `$ARGUMENTS` contains `--retroactive`. Writes the lock file and, pe
 
    Store as `INFERRED_TIER`.
 
-4. **Infer archetype.** Best-effort detection from existing files:
+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`
@@ -296,7 +315,8 @@ Entered when `$ARGUMENTS` contains `--refresh-lock`. No scaffolding questions ar
 
 ## Sync-Rules Flow (`--sync-rules`)
 
-Entered when `$ARGUMENTS` contains `--sync-rules`. This is a standalone flow — it short-circuits the tier/archetype/scaffolding flow. No `bootstrap.lock` read, no template dispatched, no initial commit.
+Entered when `$ARGUMENTS` contains `--sync-rules`. This standalone flow skips tier
+selection, scaffolding and initial commit. Rule selection may read the lock ID.
 
 **Purpose:** Vendor canonical rules from the plugin's `rules/` library (`rules/always-on/*.md`, and in the future `rules/opt-in-stack/*.md` and `rules/opt-in-domain/*.md`) into the consumer repo's `.claude/rules/`. Plugin-sourced files (identified by a `<!-- source: session-orchestrator plugin … -->` header) are overwritten on re-run; files without that header are preserved as local overrides. See `rules/_index.md` for the canonical manifest and `scripts/lib/rules-sync.mjs` for the implementation.
 
@@ -304,13 +324,34 @@ Entered when `$ARGUMENTS` contains `--sync-rules`. This is a standalone flow —
 
 1. **Resolve plugin root.** The plugin's `rules/_index.md` lives next to `SKILL.md`'s plugin directory. Use the plugin root inferred by the harness (`PLUGIN_ROOT`).
 
-2. **Invoke `scripts/lib/rules-sync.mjs`.** Run the CLI entrypoint from the consumer repo:
+2. **Invoke the bootstrap rule action.** It reloads a configured private contract
+   and supplies required plugin basenames to `scripts/lib/rules-sync.mjs`.
+   With no baseline, the writer's public/default behavior is unchanged. Map an
+   explicit `--archetype ID` to `CONFIRMED_ARCHETYPE`, `--dry-run` to
+   `DRY_RUN=true`, and optional category selections to comma-separated
+   `RULES_CATEGORIES`; otherwise leave those variables unset. Run from the repo:
 
    ```bash
-   node "$PLUGIN_ROOT/scripts/lib/rules-sync.mjs" --repo-root "$(pwd)"
+   export PLUGIN_ROOT CONFIRMED_ARCHETYPE DRY_RUN RULES_CATEGORIES
+   node --input-type=module <<'NODE'
+   import { pathToFileURL } from 'node:url';
+   const { syncBootstrapRules } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`));
+   const categories = (process.env.RULES_CATEGORIES || '').split(',').map(value => value.trim()).filter(Boolean);
+   const result = await syncBootstrapRules({ repoRoot: process.cwd(), archetype: process.env.CONFIRMED_ARCHETYPE || undefined,
+     dryRun: process.env.DRY_RUN === 'true', categories: categories.length ? categories : null });
+   process.stdout.write(`${JSON.stringify(result)}\n`);
+   if (result.status === 'error') process.exitCode = 2;
+   NODE
    ```
 
-   The script reads `rules/_index.md` from the plugin, iterates `always-on/` sources, and writes each file into `.claude/rules/` under the target repo. Stdout is a JSON object with `written[]`, `skipped[]`, `preserved[]`, and `errors[]`. Exit 1 on any error, 0 otherwise.
+   The canonical writer reads all selected categories in `rules/_index.md` and
+   writes into `.claude/rules/`. Required private targets remain subject to its
+   provenance and pre-write checks. Explicit ID takes precedence over lock ID,
+   then repository markers. Invalid private contracts abort before writes.
+   A valid Fast lock with `archetype: null` and no matching markers retains
+   ordinary plugin rule delivery after contract validation.
+   Stdout includes `status`, `created[]`, `written[]`, `skipped[]`, `preserved[]`,
+   and `errors[]`. Any error exits non-zero.
 
    Add `--dry-run` to preview without writing.
 
@@ -351,7 +392,7 @@ Pass the following context into the template execution:
 Follow the template's instructions precisely. The template is responsible for creating all files and the initial git commit.
 
 **Platform note for CLAUDE.md generation:**
-When `PATH_TYPE = public`, read `skills/bootstrap/public-fallback.md` for the full platform-specific CLAUDE.md generation logic (claude init path for Claude Code; `_minimal` template synthesis for Codex/Cursor). When `PATH_TYPE = private`, use the baseline scripts at `$BASELINE_PATH`.
+When `PATH_TYPE = public`, read `skills/bootstrap/public-fallback.md` for the full platform-specific CLAUDE.md generation logic (claude init path for Claude Code; `_minimal` template synthesis for Codex/Cursor). When `PATH_TYPE = private`, use the validated, staged flow in `private-contract.md`.
 
 ## Phase 3.4: Vault-Registration Prompt (#190)
 
@@ -438,7 +479,14 @@ if (!isDispatcherAutonomyBlockPresent(content)) {
 
 > Closes session-orchestrator issue #110.
 
-After the tier template completes scaffolding (Phase 3), the Standard and Deep templates run an optional rules-fetch step that pulls canonical `.claude/rules/*.md` (and optionally `.claude/agents/*.md`) directly from the baseline GitLab project. The step is opt-in and only fires when:
+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

package/skills/bootstrap/_shared-template.md

@@ -24,21 +24,39 @@ Idempotency is handled by the writer itself:
 Shell:
 ```bash
 mkdir -p "$REPO_ROOT/.claude"
-node "$PLUGIN_ROOT/scripts/lib/rules-sync.mjs" --repo-root "$REPO_ROOT"
-cp "$PLUGIN_ROOT/templates/_shared/loop.md" "$REPO_ROOT/.claude/loop.md"
+export PLUGIN_ROOT REPO_ROOT CONFIRMED_ARCHETYPE
+RULES_RESULT=$(node --input-type=module <<'NODE'
+import { pathToFileURL } from 'node:url';
+const { syncBootstrapRules } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`));
+const result = await syncBootstrapRules({ repoRoot: process.env.REPO_ROOT, archetype: process.env.CONFIRMED_ARCHETYPE || undefined });
+process.stdout.write(`${JSON.stringify(result)}\n`);
+if (result.status === 'error') process.exitCode = 2;
+NODE
+) || exit 2
+printf '%s\n' "$RULES_RESULT"
+while IFS= read -r _file; do BOOTSTRAP_FILES+=("$_file"); done \
+  < <(printf '%s\n' "$RULES_RESULT" | jq -r '.created[]')
+if [[ ! -e "$REPO_ROOT/.claude/loop.md" && ! -L "$REPO_ROOT/.claude/loop.md" ]]; then
+  cp "$PLUGIN_ROOT/templates/_shared/loop.md" "$REPO_ROOT/.claude/loop.md"
+  BOOTSTRAP_FILES+=(.claude/loop.md)
+fi
 ```
 
 The command prints a JSON report (`written` / `skipped` / `preserved` / `errors` / `warnings` / `sanitizer`) and exits non-zero on any error. Surface `errors[]` to the operator; a non-empty `preserved[]` is normal and means a repo-private rule was left alone.
 
 Also surface `sanitizer[]` (issue #1098) — `{file, line, kind, text}` records for citations that read fine inside the plugin repo and dangle once vendored (`repo-local-path`, `unresolvable-see-also`). The CLI additionally prints each one to stderr as `rules-sync: sanitizer <kind> <file>:<line> — <text>`. **Report it to the operator; do not act on it automatically** — the sanitizer never rewrites content and never changes the exit code, because silently stripping a citation would change a rule's meaning at vendoring time. A human decides whether the citation is a leak.
 
-Archetype-scoped entries in `rules/_index.md` resolve from `.orchestrator/bootstrap.lock`, which does not exist yet at this step — they report `archetype-unknown` and are skipped. The always-on rules (including `parallel-sessions.md`) are universal and vendor regardless. Re-run `/bootstrap --sync-rules` after the lock is written to pick up the archetype-scoped ones.
+The wrapper re-reads a configured private contract and passes its required plugin
+basenames into the canonical writer. The full set must resolve uniquely before
+any rule is written; source/provenance validation and local preservation still
+apply. On the public path, normal archetype filtering is unchanged. The selected
+ID is explicit during bootstrap; later `/bootstrap --sync-rules` can use the lock.
 
 Why: PSA-003 destructive-command safeguards require every consumer repo to carry the parallel-sessions rule. See issue #155. The `loop.md` vendor gives bare `/loop` a repo-aware maintenance prompt (issue #633 Hebel 3).
 
-Why one writer (issue #1060): a literal `cp` from a second source directory bypasses the pre-write validator AND lands a file carrying no provenance header. On the next `--sync-rules` a headerless file is classified as a repo-private override and preserved forever — so the plugin can never update it again, and whichever rival copy is smaller silently wins. `rules/` is the only source with a manifest, archetype scoping, a basename-collision guard and a pre-write validator, so it is the only sanctioned writer to `.claude/rules/`.
+Why one writer (issue #1060): a literal `cp` from a second source directory bypasses the pre-write validator AND lands a file carrying no provenance header. On the next `--sync-rules` a headerless file is classified as a repo-private override and preserved forever — so the plugin can never update it again, and whichever rival copy is smaller silently wins. For every basename declared in `rules/_index.md`, `rules-sync.mjs` is the sole writer: it owns the manifest, archetype scoping, basename-collision guard and pre-write validation. S99 may deliver baseline-only rules after excluding all plugin-owned basenames.
 
-Note: This step runs before the baseline-fetch step (S99/D99), and S99 must NOT overwrite a rule that `rules/` owns. The baseline's copy carries no provenance header, so letting it win would permanently mark the target as a repo-private override — the exact failure described above. `.claude/rules/parallel-sessions.md` has therefore been removed from the S99 manifest. Any other basename present in BOTH `rules/_index.md` and the S99 manifest has the same defect and needs the same treatment.
+Note: This step runs before S99/D99. Both the private local rule projection and the optional public fetch filter every basename in `rules/_index.md`, including currently nonmatching scoped entries. `parallel-sessions.md` and any future plugin-owned rule therefore remain under the same single writer.
 
 ---
 
@@ -48,7 +66,13 @@ Copy the opinionated agent templates into the consumer repo:
 
 ```bash
 mkdir -p "$REPO_ROOT/.claude/agents"
-cp "$PLUGIN_ROOT/skills/bootstrap/templates/agents/"*.md "$REPO_ROOT/.claude/agents/"
+for _source in "$PLUGIN_ROOT/skills/bootstrap/templates/agents/"*.md; do
+  _target=".claude/agents/$(basename "$_source")"
+  if [[ ! -e "$REPO_ROOT/$_target" && ! -L "$REPO_ROOT/$_target" ]]; then
+    cp "$_source" "$REPO_ROOT/$_target"
+    BOOTSTRAP_FILES+=("$_target")
+  fi
+done
 ```
 
 This scaffolds 3 opinionated agents (`project-discovery`, `project-code-review`, `project-quality-gate`) following CLAUDE.md Agent Authoring Rules. Consumer repos should edit descriptions/bodies to match project specifics — but keep the frontmatter structure intact (validated by `agent-frontmatter-invalid` probe).
@@ -103,7 +127,13 @@ vault:
 
 ## #baseline-fetch — Step S99: (Optional) Fetch Canonical Rules + Agents from Baseline
 
-This step is OPT-IN and only executes when ALL of the following are true:
+For `PATH_TYPE = private` and a confirmed archetype, this step applies only the
+validated local contract rule targets from `private-contract.md`. It is offline,
+rechecks conditional dependencies after scaffolding, preserves existing files,
+and fails closed on an invalid configured contract.
+
+For `PATH_TYPE = public`, the existing remote fetch remains OPT-IN and only
+executes when ALL of the following are true:
 - `baseline-ref` is present in Session Config (e.g., `baseline-ref: main`)
 - `GITLAB_TOKEN` env var is set
 - The session-orchestrator plugin includes `scripts/lib/fetch-baseline.mjs`
@@ -116,6 +146,23 @@ Without this step, rules arrive in the repo via Clank's weekly baseline sync MRs
 **Implementation:**
 
 ```bash
+if [[ "${PATH_TYPE:-public}" = "private" ]]; then
+  export PLUGIN_ROOT REPO_ROOT CONFIRMED_ARCHETYPE
+  BASELINE_RULES_RESULT=$(node --input-type=module <<'NODE'
+import { pathToFileURL } from 'node:url';
+const { applyBaselineRules } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`));
+const result = await applyBaselineRules({
+  repoRoot: process.env.REPO_ROOT,
+  archetype: process.env.CONFIRMED_ARCHETYPE,
+});
+process.stdout.write(`${JSON.stringify(result)}\n`);
+if (result.status === 'error') process.exitCode = 2;
+NODE
+) || exit 2
+  printf '%s\n' "$BASELINE_RULES_RESULT"
+  while IFS= read -r _file; do BOOTSTRAP_FILES+=("$_file"); done \
+    < <(printf '%s\n' "$BASELINE_RULES_RESULT" | jq -r '.created[]')
+else
 BASELINE_REF=$(echo "$CONFIG" | jq -r '."baseline-ref" // empty')
 BASELINE_PROJECT_ID=$(echo "$CONFIG" | jq -r '."baseline-project-id" // "52"')
 
@@ -145,6 +192,19 @@ if [[ -n "$BASELINE_REF" && -n "${GITLAB_TOKEN:-}" && -n "${GITLAB_HOST:-}" && -
 .claude/rules/ai-agent.md
 .claude/rules/claude-code-usage.md
 MANIFEST
+  # Every plugin-owned basename is excluded, including currently unmatched scoped
+  # rules. rules-sync is their sole writer; ownership does not depend on scope.
+  export PLUGIN_ROOT RULES_MANIFEST
+  node --input-type=module <<'NODE'
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+const { pluginRuleTargets } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`));
+const owned = new Set(pluginRuleTargets(process.env.PLUGIN_ROOT));
+const files = readFileSync(process.env.RULES_MANIFEST, 'utf8').split('\n')
+  .filter(file => file && !owned.has(path.posix.basename(file)));
+writeFileSync(process.env.RULES_MANIFEST, files.join('\n') + '\n');
+NODE
 
   echo "Fetching canonical rules from baseline (project $BASELINE_PROJECT_ID, ref $BASELINE_REF)…"
   # The .mjs CLI is single-file: it prints ONE file body to stdout, exit 0 on success
@@ -153,10 +213,13 @@ MANIFEST
   SUCCESS_LOG=$(mktemp)
   while IFS= read -r rule_path; do
     [[ -z "$rule_path" ]] && continue
+    _RULE_CREATED=false
+    [[ -e "$REPO_ROOT/$rule_path" || -L "$REPO_ROOT/$rule_path" ]] || _RULE_CREATED=true
     mkdir -p "$REPO_ROOT/$(dirname "$rule_path")"
     if node "$PLUGIN_ROOT/scripts/lib/fetch-baseline.mjs" \
          "$BASELINE_PROJECT_ID" "$rule_path" "$BASELINE_REF" > "$REPO_ROOT/$rule_path"; then
       printf '%s\n' "$rule_path" >> "$SUCCESS_LOG"
+      if [[ "$_RULE_CREATED" = true ]]; then BOOTSTRAP_FILES+=("$rule_path"); fi
     else
       # A 404 (or any error) for one rule must not abort the batch — drop the empty
       # target the redirect created and continue with the next manifest line.
@@ -167,6 +230,8 @@ MANIFEST
   if [[ -s "$SUCCESS_LOG" ]]; then
     FETCHED_JSON=$(jq -R . < "$SUCCESS_LOG" | jq -s .)
     LOCK_FILE="$REPO_ROOT/.claude/.baseline-fetch.lock"
+    _FETCH_LOCK_CREATED=false
+    [[ -e "$LOCK_FILE" || -L "$LOCK_FILE" ]] || _FETCH_LOCK_CREATED=true
     mkdir -p "$REPO_ROOT/.claude"
     FETCHED_JSON="$FETCHED_JSON" BASELINE_PROJECT_ID="$BASELINE_PROJECT_ID" \
       BASELINE_REF="$BASELINE_REF" LOCK_FILE="$LOCK_FILE" \
@@ -183,6 +248,7 @@ MANIFEST
       writeFileSync(process.env.LOCK_FILE, JSON.stringify(lock, null, 2) + '\n');
     "
     echo "Wrote .claude/.baseline-fetch.lock ($(wc -l < "$SUCCESS_LOG" | tr -d ' ') files)"
+    if [[ "$_FETCH_LOCK_CREATED" = true ]]; then BOOTSTRAP_FILES+=(.claude/.baseline-fetch.lock); fi
   else
     echo "WARNING: baseline fetch produced no files; rules will arrive via Clank sync MRs (legacy path)" >&2
   fi
@@ -191,23 +257,39 @@ MANIFEST
 else
   echo "Skipping baseline fetch: baseline-ref / GITLAB_TOKEN / GITLAB_HOST not configured (legacy Clank-sync path)"
 fi
+fi
 ```
 
-**Failure handling:** If the fetch fails, this step DOES NOT abort bootstrap. The repo still has its scaffold; rules will arrive via the legacy Clank weekly sync MR. The user is informed via stderr.
+**Failure handling:** A private contract/apply error aborts bootstrap. For the public optional remote path, if the fetch fails, this step DOES NOT abort bootstrap. The repo still has its scaffold; rules will arrive via the legacy Clank weekly sync MR. The user is informed via stderr.
 
-**Idempotency:** Re-running bootstrap on an existing repo will overwrite `.claude/rules/*.md` files. Local edits to baseline rules in a repo will be lost on re-fetch — this is intentional (rules are canonical). Repo-specific extensions belong in `.claude/rules/local/*.md` (not fetched).
+**Idempotency:** Private local rules preserve existing files and report them for review. On the public optional remote path, re-running bootstrap on an existing repo will overwrite `.claude/rules/*.md` files. Local edits to baseline rules in a repo will be lost on re-fetch — this is intentional (rules are canonical). Repo-specific extensions belong in `.claude/rules/local/*.md` (not fetched).
 
 ---
 
 ## #quality-gate-policy — Step 6.5: Quality-Gate Policy File (#183)
 
-Write the canonical quality-gate commands to `.orchestrator/policy/quality-gates.json`. Bootstrap detects the package manager and writes sensible defaults; users may hand-edit afterwards.
+Write canonical commands to `.orchestrator/policy/quality-gates.json`. A private
+contract supplies exact test/typecheck/lint IDs, with `false` and an unavailable
+reason for absent IDs. Public bootstrap retains package-manager defaults.
 
 **Idempotency:** Skip this step if `.orchestrator/policy/quality-gates.json` already exists. Do not overwrite user edits.
 
 ```bash
 POLICY_FILE="$REPO_ROOT/.orchestrator/policy/quality-gates.json"
-if [[ ! -f "$POLICY_FILE" ]]; then
+if [[ "${PATH_TYPE:-public}" = private ]]; then
+  export PLUGIN_ROOT REPO_ROOT CONFIRMED_ARCHETYPE
+  POLICY_RESULT=$(node --input-type=module <<'NODE'
+import { pathToFileURL } from 'node:url';
+const { writeBaselineQualityPolicy } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`));
+const result = await writeBaselineQualityPolicy({ repoRoot: process.env.REPO_ROOT, archetype: process.env.CONFIRMED_ARCHETYPE });
+process.stdout.write(`${JSON.stringify(result)}\n`);
+if (result.status === 'error') process.exitCode = 2;
+NODE
+) || exit 2
+  printf '%s\n' "$POLICY_RESULT"
+  while IFS= read -r _file; do BOOTSTRAP_FILES+=("$_file"); done \
+    < <(printf '%s\n' "$POLICY_RESULT" | jq -r '.created[]')
+elif [[ ! -e "$POLICY_FILE" && ! -L "$POLICY_FILE" ]]; then
   mkdir -p "$REPO_ROOT/.orchestrator/policy"
   # Detect package manager via scripts/lib/package-manager.mjs (falls back to npm defaults)
   PM_JSON="$(node --input-type=module -e "
@@ -226,6 +308,7 @@ if [[ ! -f "$POLICY_FILE" ]]; then
     "rationale": "Canonical quality-gate commands. Generated by bootstrap. Edit to change test/typecheck/lint invocations across skills. Schema: .orchestrator/policy/quality-gates.schema.json",
     "commands": $cmds
   }' > "$POLICY_FILE"
+  BOOTSTRAP_FILES+=(.orchestrator/policy/quality-gates.json)
   echo "Wrote $POLICY_FILE"
 fi
 ```
@@ -234,16 +317,18 @@ fi
 
 ## #state-md-scaffold — Step 6.6: STATE.md Scaffold (#184)
 
-Scaffold a placeholder `.claude/STATE.md` using the template at `skills/bootstrap/STATE.md.template`. The placeholder records `status: idle` — sessions overwrite it at Pre-Wave 1b.
+Scaffold a placeholder `.claude/STATE.md`. <!-- path-check: example -->
+Use the template at `skills/bootstrap/STATE.md.template`; the placeholder records `status: idle` — sessions overwrite it at Pre-Wave 1b.
 
-**Idempotency:** Skip if `.claude/STATE.md` already exists.
+**Idempotency:** Skip if `.claude/STATE.md` already exists. <!-- path-check: example -->
 
 ```bash
 STATE_FILE="$REPO_ROOT/.claude/STATE.md"
-if [[ ! -f "$STATE_FILE" ]]; then
+if [[ ! -e "$STATE_FILE" && ! -L "$STATE_FILE" ]]; then
   mkdir -p "$REPO_ROOT/.claude"
   ISO_NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
   sed "s|<ISO>|$ISO_NOW|g" "$PLUGIN_ROOT/skills/bootstrap/STATE.md.template" > "$STATE_FILE"
+  BOOTSTRAP_FILES+=(.claude/STATE.md)
   echo "Wrote $STATE_FILE"
 fi
 ```

package/skills/bootstrap/deep-template.md

@@ -5,6 +5,9 @@
 
 Deep tier is a strict superset of Standard tier. Execute all Standard-tier steps first, then the Deep-specific steps below.
 
+Keep the inherited `BOOTSTRAP_FILES` array. Append each new governance file by
+its relative filename when created; do not append existing files or directories.
+
 ## Step 1–8: Execute Standard Tier
 
 Read and execute `skills/bootstrap/standard-template.md` Steps 1–8 in full. Do not skip any step.
@@ -30,7 +33,13 @@ If `VCS` is empty or `none`, skip CI pipeline, issue templates, MR/PR template,
 
 ## Step D1: CI Pipeline
 
-Create the CI pipeline file. Mutually exclusive — create exactly one based on `VCS`.
+When `PATH_TYPE = private`, keep the selected baseline's rendered CI and
+`ci.profile` from `private-contract.md`. Respect `ci.required: false`; do not
+create a generic Node pipeline for an exempt archetype. A required CI missing
+from staging already aborts. Resolve VCS mismatch explicitly before changing
+canonical CI. Skip the public D1 examples below and continue at D2.
+
+For `PATH_TYPE = public`, create exactly one pipeline based on `VCS`.
 
 ### If `VCS = gitlab`: `.gitlab-ci.yml`
 
@@ -208,7 +217,7 @@ Replace `<YYYY-MM-DD>` with today's date in ISO 8601 format (e.g., `2026-04-16`)
 mkdir -p "$REPO_ROOT/.gitlab/issue_templates"
 ```
 
-Write `.gitlab/issue_templates/Bug.md`:
+In the consuming repository, create `.gitlab/issue_templates/Bug.md`: <!-- path-check: example -->
 
 ```markdown
 ## Summary
@@ -239,7 +248,7 @@ Write `.gitlab/issue_templates/Bug.md`:
 <!-- Screenshots, logs, related issues -->
 ```
 
-Write `.gitlab/issue_templates/Feature.md`:
+In the consuming repository, create `.gitlab/issue_templates/Feature.md`: <!-- path-check: example -->
 
 ```markdown
 ## Summary
@@ -334,7 +343,7 @@ labels: enhancement
 mkdir -p "$REPO_ROOT/.gitlab/merge_request_templates"
 ```
 
-Write `.gitlab/merge_request_templates/Default.md`:
+In the consuming repository, create `.gitlab/merge_request_templates/Default.md`: <!-- path-check: example -->
 
 ```markdown
 ## Summary
@@ -492,12 +501,11 @@ If the call fails, log the structured message above and continue. Raw API respon
 
 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 D99. D99 (via inherited 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
@@ -511,11 +519,13 @@ Deep tier creates both learnings and sessions metrics plus a schema-linking READ
 
 ```bash
 mkdir -p "$REPO_ROOT/.orchestrator/metrics"
-[[ -f "$REPO_ROOT/.orchestrator/metrics/learnings.jsonl" ]] || \
-  : > "$REPO_ROOT/.orchestrator/metrics/learnings.jsonl"
-[[ -f "$REPO_ROOT/.orchestrator/metrics/sessions.jsonl" ]] || \
-  : > "$REPO_ROOT/.orchestrator/metrics/sessions.jsonl"
-
+for _file in learnings.jsonl sessions.jsonl; do
+  if [[ ! -e "$REPO_ROOT/.orchestrator/metrics/$_file" && ! -L "$REPO_ROOT/.orchestrator/metrics/$_file" ]]; then
+    : > "$REPO_ROOT/.orchestrator/metrics/$_file"
+    BOOTSTRAP_FILES+=(".orchestrator/metrics/$_file")
+  fi
+done
+if [[ ! -e "$REPO_ROOT/.orchestrator/metrics/README.md" && ! -L "$REPO_ROOT/.orchestrator/metrics/README.md" ]]; then
 cat > "$REPO_ROOT/.orchestrator/metrics/README.md" <<'README'
 # Metrics
 
@@ -530,6 +540,8 @@ Schema: https://github.com/Kanevry/session-orchestrator
 **Do NOT gitignore** — these files are project artifacts intended to persist
 across sessions and contributors.
 README
+  BOOTSTRAP_FILES+=(.orchestrator/metrics/README.md)
+fi
 ```
 
 **Idempotent.** Existing files are preserved.
@@ -547,8 +559,10 @@ Standard-template Step S99 already executed as part of "Step 1–8: Execute Stan
 No additional fetch action is needed here.
 
 If S99 ran successfully, `.claude/rules/*.md` and `.claude/.baseline-fetch.lock` are already written
-to `$REPO_ROOT`. These files are included in the Deep commit at Step D8 via the `.claude/` entry
-in `BOOTSTRAP_FILES`. If S99 was skipped, rules arrive via the legacy Clank weekly sync MR path.
+to `$REPO_ROOT`. Their individual newly created paths remain in `BOOTSTRAP_FILES`
+for the Deep commit at Step D8. If the private contract applies, S99 already
+delivered its local filtered rule union. If public S99 was skipped, rules arrive
+via the legacy Clank weekly sync MR path.
 
 ---
 
@@ -580,6 +594,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
@@ -592,6 +608,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.
@@ -604,16 +621,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/ CHANGELOG.md CODEOWNERS
-  .gitlab/ .github/ .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 (deep)"
 ```

package/skills/bootstrap/fast-template.md

@@ -14,6 +14,10 @@
 
 Intentionally absent: `package.json`, frameworks, tests, CI config. The feature that follows brings its own stack.
 
+Maintain the inherited `BOOTSTRAP_FILES` array and append every newly created
+relative file at creation. Preserve existing owner files and never reset this
+array when Fast is inherited by Standard or Deep.
+
 ## Step 1: Ensure Git Repo is Initialized
 
 ```bash
@@ -38,7 +42,12 @@ After `public-fallback.md` completes CLAUDE.md generation, continue to Step 2b t
 
 **If `PATH_TYPE = private`:**
 
-Use the baseline scripts at `$BASELINE_PATH` as directed by the baseline's own documentation. Proceed with baseline-driven CLAUDE.md generation, then continue to Step 2b.
+For Standard/Deep inheritance, `private-contract.md` already rendered the
+instruction file and stack into the repo. Preserve those files and continue
+to Step 2b; use its quality-gate command mapping for missing Session Config
+fields. Preserve the rendered README and `.gitignore` in subsequent Fast steps.
+For a standalone Fast tier, no archetype is selected: use `public-fallback.md`'s
+minimal Fast instruction-file generation and report `source: plugin-template`.
 
 **Step 2b: Verify Session Config block.** After writing or updating CLAUDE.md, check for the sentinel string `## Session Config`:
 
@@ -107,7 +116,8 @@ elif ls *.ts *.js package.json 2>/dev/null | head -1 | grep -q .; then STACK="no
 else STACK="generic"; fi
 ```
 
-Write `.gitignore` with the appropriate content:
+If absent, write `.gitignore` with the appropriate content and append `.gitignore`
+to `BOOTSTRAP_FILES`. Preserve an existing file.
 
 **Generic (no stack detected):**
 ```gitignore
@@ -166,6 +176,10 @@ Note: `.orchestrator/` is NOT gitignored — `bootstrap.lock` must be committed.
 
 Vendor the canonical always-on rules from the plugin's `rules/` library into `$REPO_ROOT/.claude/rules/`. `rules/` is the single source of truth for every distributable rule — never `cp` a rule file from anywhere else.
 
+`syncBootstrapRules` calls the canonical `scripts/lib/rules-sync.mjs` writer.
+Standalone Fast uses ordinary plugin rules without private archetype selection;
+inherited Fast passes the confirmed contract ID and records all created paths.
+
 Idempotency is handled by the writer itself:
 - Missing → create
 - Exists, plugin-owned (first line is the `<!-- source: session-orchestrator plugin ... -->` header) and byte-identical → skip silently
@@ -175,11 +189,28 @@ Idempotency is handled by the writer itself:
 Shell:
 ```bash
 mkdir -p "$REPO_ROOT/.claude"
-node "$PLUGIN_ROOT/scripts/lib/rules-sync.mjs" --repo-root "$REPO_ROOT"
-cp "$PLUGIN_ROOT/templates/_shared/loop.md" "$REPO_ROOT/.claude/loop.md"
+export PLUGIN_ROOT REPO_ROOT CONFIRMED_ARCHETYPE
+RULES_RESULT=$(node --input-type=module <<'NODE'
+import { pathToFileURL } from 'node:url';
+const { syncBootstrapRules } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`));
+const result = await syncBootstrapRules({ repoRoot: process.env.REPO_ROOT,
+  archetype: process.env.CONFIRMED_ARCHETYPE || undefined, minimal: !process.env.CONFIRMED_ARCHETYPE });
+process.stdout.write(`${JSON.stringify(result)}\n`);
+if (result.status === 'error') process.exitCode = 2;
+NODE
+) || exit 2
+printf '%s\n' "$RULES_RESULT"
+while IFS= read -r _file; do BOOTSTRAP_FILES+=("$_file"); done \
+  < <(printf '%s\n' "$RULES_RESULT" | jq -r '.created[]')
+if [[ ! -e "$REPO_ROOT/.claude/loop.md" && ! -L "$REPO_ROOT/.claude/loop.md" ]]; then
+  cp "$PLUGIN_ROOT/templates/_shared/loop.md" "$REPO_ROOT/.claude/loop.md"
+  BOOTSTRAP_FILES+=(.claude/loop.md)
+fi
 ```
 
-The command prints a JSON report (`written` / `skipped` / `preserved` / `errors` / `warnings` / `sanitizer`) and exits non-zero on any error. At fast tier `.orchestrator/bootstrap.lock` does not exist yet (Step 5 writes it), so archetype-scoped entries report `archetype-unknown` and are skipped — the always-on rules vendor regardless.
+The command prints a JSON report and exits non-zero on any error. At standalone
+Fast tier the lock and selected ID are absent, so scoped rules are skipped.
+Inherited Fast delivers private required targets through the same writer.
 
 Surface `errors[]` and `sanitizer[]` to the operator. `sanitizer[]` (issue #1098) carries `{file, line, kind, text}` records for citations that read fine inside the plugin repo and dangle once vendored (`repo-local-path`, `unresolvable-see-also`); the CLI also prints each to stderr as `rules-sync: sanitizer <kind> <file>:<line> — <text>`. **Report it, do not act on it automatically** — it never rewrites content and never changes the exit code, so a human decides whether the citation is a leak.
 
@@ -189,6 +220,9 @@ Why one writer (issue #1060): a literal `cp` from a second source directory bypa
 
 ## Step 4: Generate README.md
 
+If absent, write the stub below and append `README.md` to `BOOTSTRAP_FILES`.
+Preserve an existing README.
+
 ```markdown
 # <REPO_NAME>
 
@@ -207,6 +241,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
@@ -219,6 +255,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`:
@@ -231,10 +268,9 @@ Stage all created files and commit:
 
 ```bash
 cd "$REPO_ROOT"
-BOOTSTRAP_FILES=(CLAUDE.md AGENTS.md .gitignore README.md .orchestrator/bootstrap.lock .claude/rules/parallel-sessions.md)
 # 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 (fast)"
 ```