session-orchestrator 3.16.0

package/skills/bootstrap/fast-template.md

@@ -0,0 +1,251 @@
+# Bootstrap Fast Template
+
+> Scaffold instructions for the Fast tier.
+> Called from `skills/bootstrap/SKILL.md` Phase 3 when `CONFIRMED_TIER = fast`.
+
+## What Fast Tier Creates
+
+| File | Purpose |
+|------|---------|
+| `CLAUDE.md` (or `AGENTS.md` on Codex) | Project instruction file with `## Session Config` |
+| `.gitignore` | Platform-appropriate minimal ignore rules |
+| `README.md` | One-line stub with project name and description |
+| `.orchestrator/bootstrap.lock` | Gate marker — committed to git |
+
+Intentionally absent: `package.json`, frameworks, tests, CI config. The feature that follows brings its own stack.
+
+## Step 1: Ensure Git Repo is Initialized
+
+```bash
+cd "$REPO_ROOT"
+if [[ ! -d ".git" ]]; then
+  git init
+  echo "Git repo initialized."
+fi
+```
+
+## Step 2: Generate CLAUDE.md (or AGENTS.md)
+
+**If `PATH_TYPE = public`:**
+
+Defer entirely to `skills/bootstrap/public-fallback.md` — "Public Path — Fast Tier" section. That file is the single source of truth for Public-path CLAUDE.md generation (claude init path for Claude Code; `_minimal` template synthesis for Codex/Cursor; Session Config injection). Do not duplicate its logic here.
+
+**`claude init` overwrite guard:** `public-fallback.md` Fast Tier runs `claude init` only when
+`CLAUDE.md` does not already exist (`[[ ! -f "$REPO_ROOT/CLAUDE.md" ]]`). This prevents
+overwriting project-specific customisations on re-runs (issue #108).
+
+After `public-fallback.md` completes CLAUDE.md generation, continue to Step 2b to verify the Session Config block.
+
+**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.
+
+**Step 2b: Verify Session Config block.** After writing or updating CLAUDE.md, check for the sentinel string `## Session Config`:
+
+```bash
+if grep -q "^## Session Config" CLAUDE.md; then
+  echo "Session Config block confirmed."
+else
+  # Sentinel absent — claude init did NOT populate the file (or wrote minimal content).
+  # Fall back to plugin-template generation: append canonical Harte-Regeln block
+  # BEFORE the Session Config block (pattern: the templates/_shared/... cp steps
+  # in Step 3a below).
+  if ! grep -q "^## Harte Regeln" CLAUDE.md 2>/dev/null; then
+    cat "$PLUGIN_ROOT/templates/_shared/harte-regeln.md" >> CLAUDE.md
+  fi
+  # Fall back to plugin-template generation: append canonical Session Config block
+  # (issue #182: 7 mandatory fields enforced by scripts/lib/config-schema.mjs).
+  cat >> CLAUDE.md <<'EOF'
+
+## Session Config
+
+project-name: <PROJECT_NAME>
+vcs: <VCS>
+persistence: true
+enforcement: warn   # strict | warn | off
+waves: 5
+agents-per-wave: 6
+test-command: <detect per package-manager>
+typecheck-command: <detect>
+lint-command: <detect>
+recent-commits: 20
+stale-branch-days: 7
+skill-evolution:
+  autonomy: off            # off | advisory | autonomous-gated — opt-in self-evolution (default off)
+EOF
+fi
+```
+
+If `## Session Config` is present, confirm the 7 mandatory fields (per issue #182, enforced by `scripts/lib/config-schema.mjs`) plus `project-name` and `vcs` are present. Mandatory: `test-command`, `typecheck-command`, `lint-command`, `agents-per-wave`, `waves`, `persistence`, `enforcement`. If any are missing, append them.
+
+**Config file selection by platform:**
+- Claude Code → `CLAUDE.md`
+- Codex CLI → `AGENTS.md`
+- Cursor IDE → `CLAUDE.md`
+
+**Step 2c: CLAUDE.md budget lint.** After Step 2b confirms/repairs the Session Config block, run the raw-file-property lint against the freshly written instruction file:
+
+```bash
+node "$PLUGIN_ROOT/scripts/lib/claude-md-budget-lint.mjs" --repo-root "$REPO_ROOT" --require-provenance --mode warn --json
+```
+
+`--mode warn` is deliberate at Anlage-time — the lint informs, the operator decides; it never blocks the scaffold. Interpret the JSON `violations[]`:
+- `max-lines` — the instruction file is already over the lean-root ceiling (150 lines default). Recommend trimming to pointers per the lean-root convention (delegate detail to `README.md` / `.orchestrator/steering/` / `.claude/rules/*.md` — see this plugin's own `CLAUDE.md` for a worked example of the pointer pattern — note it predates the lint and currently exceeds the 150-line ceiling itself).
+- `max-line-chars` — a single line exceeds the char ceiling (400 default); surface the line number for a quick manual wrap.
+- `provenance-header` — line 1 lacks a `<!-- source: ...` attribution. On the `claude init` path (Public Fast Tier, Claude Code) this is a WARN only, never a hard failure — `claude init` output is not plugin-authored and has no reason to carry the plugin's provenance convention.
+
+Report any violations to the user as part of the bootstrap summary; do not block or retry on them.
+
+## Step 3: Generate .gitignore
+
+Detect the platform from existing files in the repo root (best-effort, repo may be empty):
+
+```bash
+# Detection order — first match wins
+if ls *.py pyproject.toml setup.py 2>/dev/null | head -1 | grep -q .; then STACK="python"
+elif ls *.ts *.js package.json 2>/dev/null | head -1 | grep -q .; then STACK="node"
+else STACK="generic"; fi
+```
+
+Write `.gitignore` with the appropriate content:
+
+**Generic (no stack detected):**
+```gitignore
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Logs
+*.log
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Session Orchestrator state (platform-specific, not committed)
+.claude/
+.codex/
+.cursor/
+```
+
+**Node/TypeScript (append to generic):**
+```gitignore
+# Node
+node_modules/
+dist/
+build/
+.next/
+coverage/
+*.tsbuildinfo
+```
+
+**Python (append to generic):**
+```gitignore
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+```
+
+Note: `.orchestrator/` is NOT gitignored — `bootstrap.lock` must be committed. Only the platform state dirs (`.claude/`, `.codex/`, `.cursor/`) are excluded.
+
+## Step 3a: Install Parallel-Sessions Rule
+
+Write the vendored rule from `$PLUGIN_ROOT/templates/_shared/rules/parallel-sessions.md` to `$REPO_ROOT/.claude/rules/parallel-sessions.md`.
+
+Idempotency:
+- Missing → create
+- Exists and byte-identical → skip silently
+- Exists and differs → overwrite (vendored is canonical)
+
+Shell:
+```bash
+mkdir -p "$REPO_ROOT/.claude/rules"
+cp "$PLUGIN_ROOT/templates/_shared/rules/parallel-sessions.md" "$REPO_ROOT/.claude/rules/parallel-sessions.md"
+cp "$PLUGIN_ROOT/templates/_shared/loop.md" "$REPO_ROOT/.claude/loop.md"
+```
+
+Why: PSA-003 destructive-command safeguards require every consumer repo to carry the rule. See issue #155. The `loop.md` vendor gives bare `/loop` a repo-aware maintenance prompt (issue #633 Hebel 3).
+
+## Step 4: Generate README.md
+
+```markdown
+# <REPO_NAME>
+
+<One-sentence description — same as used in CLAUDE.md.>
+```
+
+Keep it minimal. One heading, one sentence. The feature that follows will expand it.
+
+## Step 5: Create .orchestrator Directory and bootstrap.lock
+
+```bash
+mkdir -p "$REPO_ROOT/.orchestrator"
+```
+
+Write `.orchestrator/bootstrap.lock` **atomically** (mktemp + mv prevents a corrupt lock if the
+process is interrupted mid-write):
+
+```bash
+_LOCK_TMP=$(mktemp "$REPO_ROOT/.orchestrator/bootstrap.lock.XXXXXX")
+cat > "$_LOCK_TMP" << LOCK
+# .orchestrator/bootstrap.lock
+version: 1
+tier: fast
+archetype: null
+timestamp: <current ISO 8601 UTC — e.g., 2026-04-16T09:30:00Z>
+source: <claude-init | plugin-template>
+plugin-version: <session-orchestrator plugin version — read from $PLUGIN_ROOT/package.json .version field>
+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"
+```
+
+Set `source`:
+- `claude-init` if CLAUDE.md contained `## Session Config` before Step 2b's sentinel check (i.e., `claude init` populated it)
+- `plugin-template` if the sentinel was absent and the fallback path wrote the block
+
+## Step 6: Initial Git Commit
+
+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"
+done
+git commit -m "chore: bootstrap (fast)"
+```
+
+The commit message is fixed — do not vary it. It is the artifact that documents bootstrap provenance in `git log`.
+
+## Step 7: Report Created Files
+
+After the commit succeeds, output a concise summary:
+
+```
+Bootstrap (fast) complete. Created:
+  CLAUDE.md (or AGENTS.md)              — Session Config with project-name, vcs
+  .gitignore                            — <stack>-appropriate minimal rules
+  README.md                             — one-line stub
+  .claude/rules/parallel-sessions.md   — vendored PSA rule (issue #155)
+  .orchestrator/bootstrap.lock          — version: 1, tier: fast
+Committed: "chore: bootstrap (fast)"
+```
+
+Then return control to `SKILL.md` Phase 5.

package/skills/bootstrap/intensity-heuristic.md

@@ -0,0 +1,80 @@
+# Bootstrap Intensity Heuristic
+
+> Tier + archetype recommendation logic for the bootstrap skill.
+> Called from `skills/bootstrap/SKILL.md` Phase 1.
+
+## Outputs
+
+After executing this algorithm, report:
+
+- `RECOMMENDED_TIER`: `fast` | `standard` | `deep`
+- `RECOMMENDED_ARCHETYPE`: `static-html` | `node-minimal` | `nextjs-minimal` | `python-uv` | `null`
+- `HEURISTIC_REASON`: one sentence explaining the recommendation (shown to user)
+- `ARCHETYPE_CONFIDENCE`: `high` | `low` (used to decide whether to ask the optional second question)
+
+## Step 1: Primary Tier Signal (from user prompt)
+
+Scan the user's first prompt for these keyword groups. Match is case-insensitive; German and English terms are equivalent.
+
+| Keywords | Tier |
+|----------|------|
+| demo, prototype, prototyp, spike, playground, spielwiese, test, versuch, probier, ausprobier, mini, schnell, quick, klein, small, simple, einfach, poc, proof-of-concept, draft, skizze, scratch | `fast` |
+| mvp, minimum-viable, produkt, product, saas, app, application, service, platform, plattform, tool, fullstack, webapp, api, backend, frontend | `standard` |
+| kunden, customer, production, produktiv, team, enterprise, skalierbar, scalable, compliance, soc2, gdpr, dsgvo, multi-tenant, long-term, langfristig, langlebig | `deep` |
+
+**Match priority:** If multiple groups match, use the highest-intensity tier that matched. If no group matches → default to `standard`.
+
+## Step 2: Secondary Signals (adjust recommendation)
+
+Apply these modifiers after Step 1. Each modifier can shift the recommendation up or down one level.
+
+| Signal | Adjustment |
+|--------|-----------|
+| Repo name starts with `demo-`, `playground-`, `scratch-`, `poc-`, `test-`, `spike-` | Force `fast`, regardless of prompt |
+| Repo name starts with `demo-`, `playground-` AND prompt contains production signals | Hold at `fast` (name wins) |
+| Prompt mentions specific integrations: Stripe, Auth0, Supabase, Postgres, Redis, Firebase, Clerk, Prisma | Minimum `standard` (shift up if currently `fast`) |
+| Prompt mentions CI, pipeline, monitoring, observability, Sentry, Datadog, alerting | Shift up one level (fast→standard, standard→deep) |
+| Prompt mentions CODEOWNERS, branch protection, multiple contributors, team review | Shift to `deep` |
+| `plan-baseline-path` is configured and user names a specific baseline archetype | Minimum `standard` |
+| Existing repo has `package.json`, `pyproject.toml`, or `Cargo.toml` already committed | Minimum `standard` (repo is already structured) |
+| Existing repo has a CI file (`.github/workflows/`, `.gitlab-ci.yml`) | Minimum `deep` |
+
+## Step 3: Resolve Final Tier
+
+After applying all modifiers, clamp the result to `fast` | `standard` | `deep`.
+
+Set `HEURISTIC_REASON` to one sentence that references the signals that drove the recommendation:
+
+Examples:
+- *"Basierend auf 'animiertes Glücksrad' (Signal: Demo/Spike) empfehle ich Fast."*
+- *"Basierend auf 'SaaS mit Stripe-Integration' (Signal: Produkt + externe Integration) empfehle ich Standard."*
+- *"Basierend auf 'Kundenprojekt mit Compliance-Anforderungen' (Signal: Production/Team) empfehle ich Deep."*
+
+## Step 4: Archetype Selection
+
+**Fast tier:** Always `RECOMMENDED_ARCHETYPE = null`, `ARCHETYPE_CONFIDENCE = high`. No stack needed — skip to output.
+
+**Private path (baseline configured):** Always `RECOMMENDED_ARCHETYPE = null` at this stage. The baseline's own archetype selector is used during Standard/Deep scaffolding. Set `ARCHETYPE_CONFIDENCE = high`.
+
+**Public path + Standard or Deep:** Scan the prompt for these signals:
+
+| Prompt signals | Archetype | Confidence |
+|----------------|-----------|------------|
+| html, canvas, svg, animation, animier, static, statisch, landing, landingpage, visualization, visualisierung, glücksrad, wheel, chart, graph (no backend mention) | `static-html` | high |
+| next.js, nextjs, react, saas fullstack, webapp, web app, app with frontend | `nextjs-minimal` | high |
+| cli, command-line, script, utility, library, bibliothek, tool, npm package, node (no frontend) | `node-minimal` | high |
+| python, py, data, daten, ml, machine learning, api (python context), django, fastapi, flask, pandas, numpy | `python-uv` | high |
+| Ambiguous — prompt mentions multiple stacks, no clear frontend/backend split, or is too vague (e.g., "Ich brauche ein Projekt", "neues Repo", "etwas bauen") | `node-minimal` (safe default) | `low` |
+
+When `ARCHETYPE_CONFIDENCE = low`, the bootstrap skill will ask a second `AskUserQuestion` to confirm the archetype. `node-minimal` is the pre-selected default for that question.
+
+## Step 5: Output
+
+Return all four values to `SKILL.md` Phase 1:
+
+```
+RECOMMENDED_TIER: fast | standard | deep
+RECOMMENDED_ARCHETYPE: static-html | node-minimal | nextjs-minimal | python-uv | null
+HEURISTIC_REASON: <one sentence>
+ARCHETYPE_CONFIDENCE: high | low
+```

package/skills/bootstrap/public-fallback.md

@@ -0,0 +1,342 @@
+# Bootstrap Public Fallback
+
+> Support file for `skills/bootstrap/SKILL.md`.
+> Defines the Private vs. Public path decision and the Public path scaffold logic for all tiers.
+
+## Step 1: Detect PATH_TYPE (Silent — No User Interaction)
+
+Read `plan-baseline-path` from Session Config in `CLAUDE.md` (or `AGENTS.md` on Codex):
+
+```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}"
+```
+
+Decision logic (evaluated in order — first match wins):
+
+| 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.
+
+---
+
+## 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.
+
+---
+
+## Public Path
+
+When `PATH_TYPE = public`, no `projects-baseline` is available. Use the plugin-bundled templates and platform-appropriate CLAUDE.md generation described below.
+
+### Detect Platform
+
+Read the current platform using the patterns from `skills/_shared/platform-tools.md`:
+
+```bash
+if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" ]]; then
+  PLATFORM="claude"
+elif [[ -n "${CODEX_PLUGIN_ROOT:-}" ]]; then
+  PLATFORM="codex"
+elif [[ -n "${CURSOR_RULES_DIR:-}" ]]; then
+  PLATFORM="cursor"
+else
+  # Fallback: inspect running process name or default to claude
+  PLATFORM="claude"
+fi
+```
+
+---
+
+### Public Path — Fast Tier
+
+#### If `PLATFORM = claude`
+
+Run `claude init` to generate `CLAUDE.md`, **but only if `CLAUDE.md` does not already exist**.
+Skipping when the file is present prevents `claude init` from overwriting project-specific
+customisations on bootstrap re-runs or Upgrade Flow passes (issue #108):
+
+```bash
+cd "$REPO_ROOT"
+if [[ ! -f "$REPO_ROOT/CLAUDE.md" ]]; then
+  claude init 2>/dev/null
+fi
+CLAUDE_INIT_STATUS=$?
+```
+
+If `claude init` exits 0 and produces a non-empty `CLAUDE.md`, it is the base. Proceed to inject the Harte Regeln block, then the Session Config block.
+
+**Inject `## Harte Regeln` section** — append the canonical hard-rules content BEFORE the Session Config block, if the section is absent:
+
+```bash
+if ! grep -q "^## Harte Regeln" "$REPO_ROOT/CLAUDE.md" 2>/dev/null; then
+  cat "$PLUGIN_ROOT/templates/_shared/harte-regeln.md" >> "$REPO_ROOT/CLAUDE.md"
+fi
+```
+
+**Inject `## Session Config` section** — append after the last line of the generated CLAUDE.md if the section is absent:
+
+```markdown
+## Session Config
+
+project-name: <REPO_NAME>
+vcs: <detect: "gitlab" | "github" | "none" — see VCS detection below>
+persistence: true
+enforcement: warn   # strict | warn | off
+waves: 5
+agents-per-wave: 6
+test-command: <detect per package-manager — e.g., "npm test">
+typecheck-command: <detect — e.g., "npm run typecheck">
+lint-command: <detect — e.g., "npm run lint">
+recent-commits: 20
+stale-branch-days: 7
+```
+
+Note: `plan-baseline-path` is intentionally omitted on the Public path. The 7 mandatory fields enforced by the Session Config validator (`scripts/lib/config-schema.mjs`, issue #182) are: `test-command`, `typecheck-command`, `lint-command`, `agents-per-wave`, `waves`, `persistence`, `enforcement`.
+
+If `claude init` fails (non-zero exit or empty output), fall through to the Codex/Cursor path below.
+
+#### If `PLATFORM = codex` or `PLATFORM = cursor`
+
+Use the minimal template to synthesize `CLAUDE.md` (for Claude Code/Cursor) or `AGENTS.md` (for Codex):
+
+1. Read `templates/_minimal/CLAUDE.md.tmpl` from the plugin root.
+2. Substitute the following placeholders using repo context:
+
+   | Placeholder | Source |
+   |-------------|--------|
+   | `{{PROJECT_TITLE}}` | `$REPO_NAME` (from `basename $(git rev-parse --show-toplevel)`) |
+   | `{{PROJECT_DESCRIPTION}}` | One-sentence description derived from the user's first prompt — be concrete, not generic |
+   | `{{STACK_LANGUAGE}}` | Detected from `ls` output: `*.py` / `pyproject.toml` → Python, `*.ts` / `*.js` / `package.json` → TypeScript, else "TBD" |
+   | `{{STACK_PACKAGE_MANAGER}}` | `pnpm` for Node, `uv` for Python, else "TBD" |
+   | `{{STACK_TEST_RUNNER}}` | `vitest` for Node, `pytest` for Python, else "TBD" |
+   | `{{STACK_LINTER}}` | `eslint` for Node, `ruff` for Python, else "TBD" |
+   | `{{CMD_DEV}}` | Infer from stack: `pnpm dev` / `uv run python src/main.py` / "TBD" |
+   | `{{CMD_TEST}}` | `pnpm test` / `uv run pytest` / "TBD" |
+   | `{{CMD_BUILD}}` | `pnpm build` / "N/A" / "TBD" |
+   | `{{CMD_LINT}}` | `pnpm lint` / `uv run ruff check .` / "TBD" |
+   | `{{CONVENTIONS}}` | Pull 3–5 lines from `git log -n 5 --oneline` if available, else "Follow existing project conventions." |
+   | `{{HARD_RULES_TABLE}}` | Verbatim content of `templates/_shared/harte-regeln.md` (rules list, minus the provenance comment line) |
+   | `{{VCS}}` | See VCS detection below |
+   | `{{PROJECT_NAME}}` | `$REPO_NAME` |
+   | `{{PLAN_BASELINE_PATH}}` | Omit this entire line (remove the `plan-baseline-path: ...` line from output) |
+   | `{{TEST_COMMAND}}` | Same as `{{CMD_TEST}}` |
+   | `{{TYPECHECK_COMMAND}}` | `pnpm build` for TS, `false` otherwise |
+   | `{{LINT_COMMAND}}` | Same as `{{CMD_LINT}}` |
+
+3. Write the substituted output to:
+   - `CLAUDE.md` for Claude Code and Cursor
+   - `AGENTS.md` for Codex CLI
+
+**VCS detection:**
+
+```bash
+REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")
+if echo "$REMOTE_URL" | grep -q "gitlab"; then VCS="gitlab"
+elif echo "$REMOTE_URL" | grep -q "github"; then VCS="github"
+else VCS="none"; fi
+```
+
+Also substitute README and gitignore from `_minimal` templates:
+
+- Copy `templates/_minimal/README.md.tmpl` → `README.md`, substituting:
+  - `{{PROJECT_TITLE}}` → `$REPO_NAME`
+  - `{{PROJECT_DESCRIPTION}}` → one-sentence description from user prompt
+  - `{{USAGE_INSTRUCTIONS}}` → "TBD — add usage instructions here."
+  - `{{DEVELOPMENT_INSTRUCTIONS}}` → "TBD — add development instructions here."
+  - `{{LICENSE}}` → "MIT" (default) — user may change
+- Copy `templates/_minimal/gitignore.tmpl` → `.gitignore` as-is (no placeholders to substitute)
+
+---
+
+### Public Path — Standard Tier
+
+1. **Resolve archetype** from `CONFIRMED_ARCHETYPE` (set by `intensity-heuristic.md` or user selection in Phase 2 of SKILL.md):
+
+   | Archetype | Template Directory |
+   |-----------|-------------------|
+   | `static-html` | `templates/static-html/` |
+   | `node-minimal` | `templates/node-minimal/` |
+   | `nextjs-minimal` | `templates/nextjs-minimal/` |
+   | `python-uv` | `templates/python-uv/` |
+
+   If `CONFIRMED_ARCHETYPE` is `null` or unset, default to `node-minimal`.
+
+2. **Copy all files** from the template directory to `$REPO_ROOT`:
+
+   Use `cp -rP` (no-dereference) so that symlinks inside the template directory are copied **as
+   symlinks** rather than followed. This prevents a maliciously crafted or accidentally
+   misconfigured template from writing files outside `$REPO_ROOT` via absolute-target symlinks
+   (issue #108 — CWE-22 symlink traversal):
+
+   ```bash
+   PLUGIN_ROOT="$(dirname "$(dirname "$(dirname "$0")")")"  # resolve plugin root
+   TMPL_DIR="$PLUGIN_ROOT/templates/$CONFIRMED_ARCHETYPE"
+   # -P: copy symlinks as symlinks (no-dereference) — prevents symlink-traversal outside $REPO_ROOT
+   cp -rP "$TMPL_DIR/." "$REPO_ROOT/"
+   ```
+
+   Preserve directory structure. Do not overwrite files that already exist (from Fast tier steps) unless explicitly noted.
+
+3. **Substitute placeholders** in all copied files. For each file under `$REPO_ROOT` that was just copied, apply substitutions for every placeholder used across archetype templates:
+
+   | Placeholder | Source / Default |
+   |-------------|-----------------|
+   | `{{PROJECT_NAME}}` | `$REPO_NAME` (slugified: lowercase, hyphens for spaces) |
+   | `{{PROJECT_TITLE}}` | `$REPO_NAME` (title-cased: first letter of each word capitalised) |
+   | `{{PROJECT_DESCRIPTION}}` | One-sentence description from user prompt |
+   | `{{DESCRIPTION}}` | Same as `{{PROJECT_DESCRIPTION}}` (alias used in some templates) |
+   | `{{VCS}}` | `gitlab` / `github` / `none` (from VCS detection above) |
+   | `{{LICENSE}}` | `MIT` (default — user may change after bootstrap) |
+   | `{{USAGE_INSTRUCTIONS}}` | `TBD — add usage instructions here.` |
+   | `{{DEVELOPMENT_INSTRUCTIONS}}` | `TBD — add development instructions here.` |
+   | `{{STACK_LANGUAGE}}` | `Python` for python-uv, `TypeScript` for node/nextjs, `HTML/CSS/JS` for static-html |
+   | `{{STACK_PACKAGE_MANAGER}}` | `uv` for python-uv, `pnpm` for node/nextjs, `none` for static-html |
+   | `{{STACK_TEST_RUNNER}}` | `pytest` for python-uv, `vitest` for node/nextjs, `none` for static-html |
+   | `{{STACK_LINTER}}` | `ruff` for python-uv, `eslint` for node/nextjs, `none` for static-html |
+   | `{{CMD_DEV}}` | `uv run python src/main.py` for python-uv, `pnpm dev` for nextjs, `pnpm build` for node-minimal, `open index.html` for static-html |
+   | `{{CMD_TEST}}` | `uv run pytest` for python-uv, `pnpm test` for node/nextjs, `(none)` for static-html |
+   | `{{CMD_BUILD}}` | `(N/A)` for python-uv, `pnpm build` for node/nextjs, `(none)` for static-html |
+   | `{{CMD_LINT}}` | `uv run ruff check .` for python-uv, `pnpm lint` for node/nextjs, `(none)` for static-html |
+   | `{{CONVENTIONS}}` | Pull 3–5 lines from `git log -n 5 --oneline` if available, else `Follow existing project conventions.` |
+   | `{{TEST_COMMAND}}` | Same value as `{{CMD_TEST}}` |
+   | `{{TYPECHECK_COMMAND}}` | `pnpm build` for TS archetypes (node/nextjs), `false` for python-uv and static-html |
+   | `{{LINT_COMMAND}}` | Same value as `{{CMD_LINT}}` |
+   | `{{PLAN_BASELINE_PATH}}` | Remove the line entirely (Public path — no baseline) |
+
+   Derive `PROJECT_TITLE` from `REPO_NAME` by title-casing (replace hyphens/underscores with spaces, capitalise each word):
+
+   ```bash
+   PROJECT_SLUG=$(echo "$REPO_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+   PROJECT_TITLE=$(echo "$REPO_NAME" | tr '-_' ' ' | awk '{for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) tolower(substr($i,2)); print}')
+   ```
+
+   Set archetype-specific values before substitution:
+
+   ```bash
+   case "$CONFIRMED_ARCHETYPE" in
+     python-uv)
+       STACK_LANGUAGE="Python"; STACK_PKG="uv"; STACK_TEST="pytest"; STACK_LINT="ruff"
+       CMD_DEV="uv run python src/main.py"; CMD_TEST="uv run pytest"
+       CMD_BUILD="N/A"; CMD_LINT="uv run ruff check ."
+       TYPECHECK_CMD="false"
+       ;;
+     nextjs-minimal)
+       STACK_LANGUAGE="TypeScript"; STACK_PKG="pnpm"; STACK_TEST="vitest"; STACK_LINT="eslint"
+       CMD_DEV="pnpm dev"; CMD_TEST="pnpm test"
+       CMD_BUILD="pnpm build"; CMD_LINT="pnpm lint"
+       TYPECHECK_CMD="pnpm build"
+       ;;
+     node-minimal)
+       STACK_LANGUAGE="TypeScript"; STACK_PKG="pnpm"; STACK_TEST="vitest"; STACK_LINT="eslint"
+       CMD_DEV="pnpm build"; CMD_TEST="pnpm test"
+       CMD_BUILD="pnpm build"; CMD_LINT="pnpm lint"
+       TYPECHECK_CMD="pnpm build"
+       ;;
+     static-html)
+       STACK_LANGUAGE="HTML/CSS/JS"; STACK_PKG="none"; STACK_TEST="none"; STACK_LINT="none"
+       CMD_DEV="open index.html"; CMD_TEST=""; CMD_BUILD=""; CMD_LINT=""
+       TYPECHECK_CMD="false"
+       ;;
+   esac
+
+   CONVENTIONS=$(git -C "$REPO_ROOT" log -n 5 --oneline 2>/dev/null | head -5 || echo "Follow existing project conventions.")
+   ```
+
+   Apply all substitutions:
+
+   ```bash
+   find "$REPO_ROOT" -type f \
+     ! -path "*/.git/*" \
+     ! -path "*/.orchestrator/*" \
+     ! -name "*.lock" | while IFS= read -r file; do
+     python3 - "$file" \
+       "$PROJECT_SLUG" "$PROJECT_TITLE" "$PROJECT_DESCRIPTION" "$VCS" \
+       "$STACK_LANGUAGE" "$STACK_PKG" "$STACK_TEST" "$STACK_LINT" \
+       "$CMD_DEV" "$CMD_TEST" "$CMD_BUILD" "$CMD_LINT" \
+       "$CONVENTIONS" "$TYPECHECK_CMD" <<'PYEOF'
+import sys
+
+(path, project_slug, project_title, description, vcs,
+ stack_lang, stack_pkg, stack_test, stack_lint,
+ cmd_dev, cmd_test, cmd_build, cmd_lint,
+ conventions, typecheck_cmd) = sys.argv[1:16]
+
+with open(path, 'r', encoding='utf-8', errors='replace') as fh:
+    content = fh.read()
+
+content = content.replace('{{PROJECT_NAME}}', project_slug)
+content = content.replace('{{PROJECT_TITLE}}', project_title)
+content = content.replace('{{PROJECT_DESCRIPTION}}', description)
+content = content.replace('{{DESCRIPTION}}', description)
+content = content.replace('{{VCS}}', vcs)
+content = content.replace('{{LICENSE}}', 'MIT')
+content = content.replace('{{USAGE_INSTRUCTIONS}}', 'TBD — add usage instructions here.')
+content = content.replace('{{DEVELOPMENT_INSTRUCTIONS}}', 'TBD — add development instructions here.')
+content = content.replace('{{STACK_LANGUAGE}}', stack_lang)
+content = content.replace('{{STACK_PACKAGE_MANAGER}}', stack_pkg)
+content = content.replace('{{STACK_TEST_RUNNER}}', stack_test)
+content = content.replace('{{STACK_LINTER}}', stack_lint)
+content = content.replace('{{CMD_DEV}}', cmd_dev)
+content = content.replace('{{CMD_TEST}}', cmd_test)
+content = content.replace('{{CMD_BUILD}}', cmd_build)
+content = content.replace('{{CMD_LINT}}', cmd_lint)
+content = content.replace('{{CONVENTIONS}}', conventions)
+content = content.replace('{{TEST_COMMAND}}', cmd_test)
+content = content.replace('{{TYPECHECK_COMMAND}}', typecheck_cmd)
+content = content.replace('{{LINT_COMMAND}}', cmd_lint)
+# Remove lines containing the plan-baseline-path placeholder
+content = '\n'.join(
+    line for line in content.splitlines()
+    if '{{PLAN_BASELINE_PATH}}' not in line
+)
+# Preserve trailing newline if original had one
+if not content.endswith('\n'):
+    content += '\n'
+with open(path, 'w', encoding='utf-8') as fh:
+    fh.write(content)
+PYEOF
+   done
+   ```
+
+4. **python-uv only: rename source directory**
+
+   If `CONFIRMED_ARCHETYPE = python-uv`, the template contains `src/__PROJECT_NAME__/`. Rename it to `src/<project_slug>/`:
+
+   ```bash
+   if [[ "$CONFIRMED_ARCHETYPE" == "python-uv" ]] && [[ -d "$REPO_ROOT/src/__PROJECT_NAME__" ]]; then
+     mv "$REPO_ROOT/src/__PROJECT_NAME__" "$REPO_ROOT/src/$PROJECT_SLUG"
+   fi
+   ```
+
+5. **Tier-specific extensions:** After copying and substituting, continue with `standard-template.md` Standard-specific steps (S1–S6 for the matched archetype). Those steps write additional tooling files (`.editorconfig`, expanded README, etc.) and tier-gate correctly — they already know the archetype from `CONFIRMED_ARCHETYPE`.
+
+---
+
+### Public Path — Deep Tier
+
+Follow all Standard tier steps above (including archetype template copy + substitution + python-uv rename), then continue with `deep-template.md` Deep-specific steps (D1–D6 for VCS-conditional CI, CODEOWNERS, CHANGELOG, issue templates, MR/PR template, branch protection).
+
+The deep-template steps already reference `VCS` and `CONFIRMED_ARCHETYPE` — they integrate correctly without modification.
+
+---
+
+## Source Value for bootstrap.lock
+
+After the Public path scaffold completes, set `source` for the lock file:
+
+| Condition | `source` value |
+|-----------|---------------|
+| `claude init` ran successfully (Claude Code Fast path) | `claude-init` |
+| Plugin template copied (any other case) | `plugin-template` |
+
+This value is passed back to SKILL.md Phase 4 for writing `.orchestrator/bootstrap.lock`.