@jualopezmo/codeforge 0.4.0

package/install.ps1

@@ -0,0 +1,317 @@
+#!/usr/bin/env pwsh
+#
+# codeforge installer (Windows / PowerShell) — copy the workflow discipline into a target
+# project. Mirror of install.sh.
+#
+#   pwsh ./install.ps1 [target-dir] [-Upgrade] [-WithHooks] [-GitInit] [-NoIsolate]
+#
+# With no target-dir, installs into the current working directory.
+#
+# THIN INSTALL: the target receives only what the agent needs at RUNTIME. All framework
+# machinery (the neutral source in ./src/, the generators sync.sh/ps1, the generation
+# inputs in configs/, and the seed templates) stays in the codeforge repo — never copied
+# into the target. To customize or upgrade, edit the codeforge source and re-run this
+# installer against the target (-Upgrade, or a bare re-run from inside the project).
+#
+# This installer copies the runtime subset into the target, then runs `sync.ps1 -Out <target>`
+# to GENERATE each engine's config + skills straight into the target. No symlinks. The
+# generated engine artifacts are COMMITTED with the target so a fresh clone works with no
+# codeforge dependency at runtime.
+#
+# LANDS IN THE TARGET (runtime only): CLAUDE.md, AGENTS.md, opencode.json, .claude/,
+#   .agents/, .codex/ (generated), shared/rules/*.md + shared/state.template.md + shared/scripts/* (managed),
+#   docs/ scaffolding + CHANGELOG, PROJECT.md + CONTINUITY.md (project-owned, seeded).
+# STAYS IN codeforge (never copied): src/skills (neutral), configs/, sync.sh, sync.ps1,
+#   *.template.md, docs/extending.md.
+#
+param(
+  [Parameter(Mandatory = $false)][string]$Target,
+  [switch]$Upgrade,
+  [switch]$WithHooks,
+  [switch]$GitInit,
+  [switch]$NoIsolate
+)
+$ErrorActionPreference = 'Stop'
+
+$Src = Split-Path -Parent $MyInvocation.MyCommand.Path
+$Payload = Join-Path $Src 'src'
+$forgeVersion = "unknown"
+$versionFile = Join-Path $Src 'VERSION'
+if (Test-Path -LiteralPath $versionFile -PathType Leaf) {
+  $v = (Get-Content -LiteralPath $versionFile -TotalCount 1)
+  if ($v) { $forgeVersion = $v.Trim() }
+}
+$Mode = if ($Upgrade) { 'upgrade' } else { 'install' }
+if (-not $Target) { $Target = (Get-Location).Path }
+
+if (-not (Test-Path -PathType Container $Target)) { Write-Error "target dir not found: $Target"; exit 2 }
+$Target = (Resolve-Path $Target).Path
+# Did a prior forge install own .claude/settings.local.json? (read before the manifest is rewritten)
+$priorLocalManaged = $false
+$mf = Join-Path $Target '.forge-manifest'
+if ((Test-Path -LiteralPath $mf -PathType Leaf) -and (Select-String -LiteralPath $mf -Pattern '^localsettings:managed$' -Quiet)) {
+  $priorLocalManaged = $true
+}
+if (-not ((Test-Path (Join-Path $Payload 'CLAUDE.md')) -and (Test-Path (Join-Path $Payload 'skills')))) {
+  Write-Error "payload not found — run this from the codeforge repo"; exit 2
+}
+if ($Target -eq $Src) { Write-Error "refusing to install into codeforge itself"; exit 2 }
+if ($Target -eq $Payload) { Write-Error "refusing to install into the codeforge payload dir (src/)"; exit 2 }
+
+Write-Host "codeforge $forgeVersion -> installing into: $Target  (mode: $Mode)"
+
+# --- version drift advisory (informational only, never blocks) ---
+$priorVersion = ""
+$fvFile = Join-Path $Target '.forge-version'
+if (Test-Path -LiteralPath $fvFile -PathType Leaf) {
+  $pv = (Get-Content -LiteralPath $fvFile -TotalCount 1)
+  if ($pv) { $priorVersion = $pv.Trim() }
+}
+if ($priorVersion -and $priorVersion -ne $forgeVersion -and $forgeVersion -ne 'unknown' -and $priorVersion -ne 'unknown') {
+  try { $isUpgrade = ([version]$priorVersion -lt [version]$forgeVersion) }
+  catch { $isUpgrade = ($priorVersion -lt $forgeVersion) }
+  if ($isUpgrade) {
+    Write-Host "  ~ upgrading this target: codeforge $priorVersion -> $forgeVersion"
+  } else {
+    Write-Host "  ! this target was installed by a NEWER codeforge ($priorVersion) than you're running ($forgeVersion)."
+    Write-Host "    You may be downgrading it; teammates pinned to $priorVersion could see drift. (advisory only)"
+  }
+}
+
+function Has-ForgeMarker([string]$file) {
+  return (Test-Path $file) -and (Select-String -Quiet -SimpleMatch 'Workflow discipline for Claude Code' $file)
+}
+
+# --- self-healing: drop machinery this version no longer installs into the target ---
+# (thin model — migrates a target from an older, bloated install.) Gated on a prior forge
+# install (.forge-manifest present) so a FIRST install never touches an unrelated project's
+# own configs/ or skills/ dirs.
+if (Test-Path (Join-Path $Target '.forge-manifest')) {
+  # Detect a genuinely OLD (pre-thin) forge install by its machinery; only then migrate
+  # configs/skills, so a routine re-install never relocates an app's own top-level dirs.
+  $oldInstall = $false
+  foreach ($f in 'sync.sh', 'sync.ps1', 'state.template.md', 'PROJECT.template.md', 'CONTINUITY.template.md', 'docs/extending.md') {
+    if (Test-Path (Join-Path $Target $f)) { $oldInstall = $true }
+  }
+  foreach ($f in 'sync.sh', 'sync.ps1', 'state.template.md', 'PROJECT.template.md', 'CONTINUITY.template.md', 'docs/extending.md') {
+    $p = Join-Path $Target $f
+    if (Test-Path $p) { Remove-Item -Force $p; Write-Host "  - removed obsolete framework file: $f" }
+  }
+  # configs/ and neutral skills/ may hold pre-forge user edits — back up rather than delete.
+  $tConfigs = Join-Path $Target 'configs'
+  if ($oldInstall -and (Test-Path -PathType Container $tConfigs)) {
+    $bak = Join-Path $Target 'configs.pre-forge.bak'
+    if (Test-Path $bak) { Remove-Item -Recurse -Force $bak }
+    Move-Item $tConfigs $bak
+    Write-Host "  ! configs/ is obsolete (engine configs are generated now) -> configs.pre-forge.bak; per-project Claude tweaks go in .claude/settings.local.json"
+  }
+  $tSkills = Join-Path $Target 'skills'
+  if ($oldInstall -and (Test-Path -PathType Container $tSkills)) {
+    $bak = Join-Path $Target 'skills.pre-forge.bak'
+    if (Test-Path $bak) { Remove-Item -Recurse -Force $bak }
+    Move-Item $tSkills $bak
+    Write-Host "  ! neutral skills/ is obsolete (skills are generated now) -> skills.pre-forge.bak; add custom skills to the codeforge repo"
+  }
+}
+
+# --- MANAGED: CLAUDE.md (back up a pre-existing, non-forge one) ---
+$tClaude = Join-Path $Target 'CLAUDE.md'
+if ((Test-Path $tClaude) -and -not (Has-ForgeMarker $tClaude)) {
+  Copy-Item $tClaude "$tClaude.pre-forge.bak" -Force
+  Write-Host "  ! backed up existing CLAUDE.md -> CLAUDE.md.pre-forge.bak (move project-specifics into PROJECT.md)"
+}
+Copy-Item (Join-Path $Payload 'CLAUDE.md') $tClaude -Force
+
+# --- MANAGED: framework shared/rules/ (per-entry overwrite by name) ---
+New-Item -ItemType Directory -Force -Path (Join-Path $Target 'shared/rules') | Out-Null
+$newRules = @(Get-ChildItem -File (Join-Path $Payload 'shared/rules') -Filter *.md).Name
+
+# Prune framework rules removed upstream (see install.sh for rationale). Project-owned rules
+# aren't in the manifest, so they're untouched. No manifest yet = skip prune.
+$manifest = Join-Path $Target '.forge-manifest'
+if (Test-Path $manifest) {
+  foreach ($line in Get-Content $manifest) {
+    if ($line -like 'rule:*') {
+      $n = $line.Substring(5)
+      # Treat the committed manifest as untrusted: a prune target must be a bare *.md filename,
+      # never a path/traversal, so a tampered entry can't delete outside shared/rules/.
+      if ($n -match '[\\/]' -or $n -match '\.\.' -or $n -eq '' -or $n -notmatch '\.md$') {
+        [Console]::Error.WriteLine("  ! ignoring unsafe manifest rule entry: $n")
+      } elseif ($newRules -notcontains $n) {
+        Remove-Item -Force (Join-Path $Target "shared/rules/$n") -ErrorAction SilentlyContinue
+        Write-Host "  - pruned framework rule removed upstream: $n"
+      }
+    }
+  }
+}
+
+foreach ($f in Get-ChildItem -File (Join-Path $Payload 'shared/rules') -Filter *.md) {
+  Copy-Item $f.FullName (Join-Path $Target "shared/rules/$($f.Name)") -Force
+}
+
+# Record the framework-owned manifest for the next upgrade's prune (rules only).
+Set-Content -Path $manifest -Value (@($newRules | ForEach-Object { "rule:$_" }))
+
+# Stamp the version that produced this install, for drift detection on the next run.
+Set-Content -Path (Join-Path $Target '.forge-version') -Value $forgeVersion
+
+# --- MANAGED: workflow state template (in shared/) ---
+Copy-Item (Join-Path $Payload 'shared/state.template.md') (Join-Path $Target 'shared/state.template.md') -Force
+
+# --- MANAGED: framework shared/scripts/ (agent-invoked Tier-B helpers, e.g. check-gates) ---
+$scriptsSrc = Join-Path $Payload 'shared/scripts'
+if (Test-Path -LiteralPath $scriptsSrc -PathType Container) {
+  New-Item -ItemType Directory -Force -Path (Join-Path $Target 'shared/scripts') | Out-Null
+  foreach ($f in Get-ChildItem -File $scriptsSrc) {
+    Copy-Item $f.FullName (Join-Path $Target "shared/scripts/$($f.Name)") -Force
+  }
+}
+
+# --- MANAGED: docs/ scaffolding ---
+New-Item -ItemType Directory -Force -Path (Join-Path $Target 'docs') | Out-Null
+foreach ($d in 'prds', 'plans', 'research', 'solutions', 'adr', 'e2e/reports', 'e2e/use-cases') {
+  $dd = Join-Path $Target "docs/$d"
+  New-Item -ItemType Directory -Force -Path $dd | Out-Null
+  $gk = Join-Path $dd '.gitkeep'
+  if (-not (Test-Path $gk)) { New-Item -ItemType File -Path $gk | Out-Null }
+}
+
+# --- PROJECT-OWNED: PROJECT.md / CONTINUITY.md / docs/CHANGELOG.md (create only if missing) ---
+$tProject = Join-Path $Target 'PROJECT.md'
+if (-not (Test-Path $tProject)) {
+  Copy-Item (Join-Path $Payload 'PROJECT.template.md') $tProject
+  Write-Host "  + created PROJECT.md (fill in persona/info/variables/special rules)"
+}
+$tCont = Join-Path $Target 'CONTINUITY.md'
+if (-not (Test-Path $tCont)) { Copy-Item (Join-Path $Payload 'CONTINUITY.template.md') $tCont }
+$tChangelog = Join-Path $Target 'docs/CHANGELOG.md'
+if (-not (Test-Path $tChangelog)) { Copy-Item (Join-Path $Payload 'docs/CHANGELOG.md') $tChangelog }
+
+# --- back up any pre-existing, NON-forge per-engine skills dir before sync overwrites it ---
+foreach ($eng in '.claude', '.agents') {
+  $sd = Join-Path $Target "$eng/skills"
+  if ((Test-Path $sd) -and -not (Test-Path (Join-Path $sd '.forge-generated'))) {
+    Move-Item $sd "$sd.pre-forge.bak"
+    Write-Host "  ! backed up existing $eng/skills -> $eng/skills.pre-forge.bak (add custom skills to the codeforge repo)"
+  }
+}
+# back up a real, non-forge AGENTS.md before sync overwrites it
+$tAgents = Join-Path $Target 'AGENTS.md'
+if ((Test-Path $tAgents) -and -not (Has-ForgeMarker $tAgents)) {
+  Copy-Item $tAgents "$tAgents.pre-forge.bak" -Force
+  Write-Host "  ! backed up existing AGENTS.md -> AGENTS.md.pre-forge.bak"
+}
+
+# --- GENERATE engine dirs + AGENTS.md + opencode.json via sync (reads the codeforge source,
+#     writes straight into the target) ---
+& (Join-Path $Src 'src/sync.ps1') -Out $Target | Out-Null
+
+# --- Claude Code .claude/settings.local.json: auto-isolation + opt-in gate hook ---
+# Auto-isolation (default; -NoIsolate to keep inheritance) adds claudeMdExcludes so Claude Code
+# doesn't blend ancestor CLAUDE.md/.claude/rules into this project (Codex/OpenCode already scope
+# to the project root). -WithHooks adds the Tier-C PreToolUse gate. Both land in the one
+# gitignored file; codeforge only (re)writes it when absent or a prior install owned it.
+$excludes = @()
+if (-not $NoIsolate) {
+  $d = Split-Path -Parent $Target
+  $homeDir = [System.IO.Path]::GetFullPath($HOME)
+  while ($d -and $d -ne (Split-Path -Parent $d)) {
+    if (Test-Path -LiteralPath (Join-Path $d 'CLAUDE.md') -PathType Leaf)       { $excludes += (Join-Path $d 'CLAUDE.md') }
+    if (Test-Path -LiteralPath (Join-Path $d 'CLAUDE.local.md') -PathType Leaf) { $excludes += (Join-Path $d 'CLAUDE.local.md') }
+    if ((Test-Path -LiteralPath (Join-Path $d '.claude/rules') -PathType Container) -and ($d -ne $homeDir)) { $excludes += (Join-Path $d '.claude/rules/**') }
+    $d = Split-Path -Parent $d
+  }
+}
+
+$sl = Join-Path $Target '.claude/settings.local.json'
+if ($excludes.Count -gt 0 -or $WithHooks) {
+  if ((Test-Path -LiteralPath $sl -PathType Leaf) -and (-not $priorLocalManaged)) {
+    Write-Host "  ! .claude/settings.local.json exists and isn't codeforge-managed — not touching it."
+    Write-Host "    (skipped auto-isolation / gate hook; remove that file and re-run, or edit it by hand.)"
+  } else {
+    $settings = [ordered]@{}
+    if ($excludes.Count -gt 0) { $settings['claudeMdExcludes'] = $excludes }
+    if ($WithHooks) {
+      $settings['hooks'] = [ordered]@{
+        PreToolUse = @(
+          [ordered]@{
+            matcher = 'Bash'
+            hooks   = @([ordered]@{ type = 'command'; command = 'pwsh -NoProfile -File "$env:CLAUDE_PROJECT_DIR/shared/scripts/claude-gate-hook.ps1"' })
+          }
+        )
+      }
+    }
+    $settings | ConvertTo-Json -Depth 10 | Set-Content -Path $sl
+    if (-not (Select-String -LiteralPath $mf -Pattern '^localsettings:managed$' -Quiet)) { Add-Content -Path $mf -Value 'localsettings:managed' }
+    if ($excludes.Count -gt 0) { Write-Host "  + auto-isolated Claude Code from $($excludes.Count) ancestor instruction path(s) -> .claude/settings.local.json (-NoIsolate to keep inheritance)" }
+    if ($WithHooks)            { Write-Host "  + Claude gate hook -> .claude/settings.local.json (opt-in, hard-blocks ship on incomplete gates)" }
+  }
+} elseif ($priorLocalManaged -and (Test-Path -LiteralPath $sl -PathType Leaf)) {
+  Remove-Item -LiteralPath $sl -Force
+  Write-Host "  - removed codeforge-managed .claude/settings.local.json (nothing to configure now)"
+}
+
+# --- .gitignore (merge, don't clobber): ONLY local state (generated files are committed) ---
+$gi = Join-Path $Target '.gitignore'
+if (-not (Test-Path $gi)) { New-Item -ItemType File -Path $gi | Out-Null }
+$marker = '# codeforge (local state — do not commit)'
+if (-not (Select-String -Quiet -SimpleMatch $marker $gi)) {
+  $block = @"
+
+# codeforge (local state — do not commit)
+.DS_Store
+.workflow/
+.claude/settings.local.json
+"@
+  Add-Content -Path $gi -Value $block
+}
+
+# --- warn if the generated config lacks the forge push/PR gate ---
+function Warn-Gate([string]$rel, [string]$needle, [string]$hint) {
+  $f = Join-Path $Target $rel
+  if ((Test-Path $f) -and -not (Select-String -Quiet -SimpleMatch $needle $f)) {
+    Write-Host "  ! $rel has no forge push/PR gate ($hint) — add it to the codeforge source, then re-run."
+  }
+}
+Warn-Gate '.claude/settings.json' 'git push'       'ask-tier on git push / gh pr create'
+Warn-Gate '.codex/config.toml'    'approval_policy' 'approval_policy'
+Warn-Gate 'opencode.json'         'git push'       'permission.bash git push* / gh pr create*'
+
+# --- post-install validation: generated skill copies + AGENTS.md must exist ---
+$ok = $true
+foreach ($p in '.claude/skills', '.agents/skills') {
+  if (-not (Test-Path (Join-Path $Target "$p/new-feature/SKILL.md"))) {
+    Write-Host "  ! discovery FAILED: $p was not generated"; $ok = $false
+  }
+}
+foreach ($f in 'AGENTS.md', '.claude/settings.json', '.codex/config.toml', 'opencode.json', 'shared/state.template.md') {
+  if (-not (Test-Path (Join-Path $Target $f))) { Write-Host "  ! FAILED: $f was not generated"; $ok = $false }
+}
+if (-not $ok) {
+  Write-Host "  x install INCOMPLETE — issues above; NOT marking as installed"; exit 1
+}
+Write-Host "  + validation: skills (.claude + .agents), AGENTS.md, and engine configs generated"
+
+# --- git: the workflow (branches/commits) and ship gates operate on git ---
+& git -C $Target rev-parse --is-inside-work-tree *> $null
+if ($LASTEXITCODE -eq 0) {
+  # already a git repo — the workflow uses it
+} elseif ($GitInit) {
+  & git -C $Target init -q
+  & git -C $Target add -A
+  & git -C $Target commit -q -m "chore: adopt codeforge" 2>$null
+  if ($LASTEXITCODE -eq 0) {
+    Write-Host "  + initialized a git repo + baseline commit (chore: adopt codeforge)"
+  } else {
+    Write-Host "  + initialized a git repo (baseline commit skipped — set git user.name/email, then commit)"
+  }
+} else {
+  Write-Host "  ! not a git repo — codeforge's workflow (branches, commits) and the ship gates assume git."
+  Write-Host "    Run 'git init' here, or re-run the installer with -GitInit."
+}
+
+Write-Host "codeforge installed."
+Write-Host "  next: (1) fill PROJECT.md   (2) in Codex, trust the project when prompted"
+Write-Host "        (3) open the project in any of Claude Code / Codex / OpenCode"
+Write-Host "  to customize or upgrade: edit the codeforge source, then re-run this installer"
+Write-Host "  against the project (-Upgrade, or a bare re-run from inside it)."

package/install.sh

@@ -0,0 +1,326 @@
+#!/usr/bin/env bash
+#
+# codeforge installer — copy the workflow discipline into a target project.
+#
+#   ./install.sh [target-dir] [--upgrade] [--with-hooks] [--git-init] [--no-isolate]
+#
+# With no target-dir, installs into the current working directory. So the common flow is:
+#   cd my-project && /path/to/codeforge/install.sh
+#
+# THIN INSTALL: the target receives only what the agent needs at RUNTIME. All framework
+# machinery (the neutral source in ./src/, the generators sync.sh/ps1, the generation
+# inputs in configs/, and the seed templates) stays in the codeforge repo — never copied
+# into the target. To customize or upgrade, edit the codeforge source and re-run this
+# installer against the target (`--upgrade`, or a bare re-run from inside the project).
+#
+# The shippable payload is the NEUTRAL source in ./src/ (CLAUDE.md, skills/, shared/,
+# configs/, docs/, *.template.md). This installer copies the runtime subset into the
+# target, then runs `sync.sh --out <target>` to GENERATE each engine's config + skills
+# (.claude/ + .agents/skills + .codex/config.toml + AGENTS.md + opencode.json) straight
+# into the target. No symlinks (Windows-safe). The generated engine artifacts are COMMITTED
+# with the target project so a fresh clone works immediately — no codeforge dependency at
+# runtime; re-run the installer after editing the source to regenerate.
+#
+# LANDS IN THE TARGET (runtime only):
+#   CLAUDE.md, AGENTS.md, opencode.json, .claude/, .agents/, .codex/ (generated),
+#   shared/rules/*.md + shared/state.template.md + shared/scripts/* (managed), docs/ scaffolding + CHANGELOG,
+#   PROJECT.md + CONTINUITY.md (project-owned, seeded if missing).
+# STAYS IN codeforge (never copied): src/skills (neutral), configs/, sync.sh, sync.ps1,
+#   *.template.md, docs/extending.md.
+#
+# MANAGED (framework baseline — OVERWRITTEN on install/upgrade): CLAUDE.md, the framework's
+#   OWN entries in shared/rules/, shared/state.template.md. Your own rules dropped into
+#   shared/rules/ survive upgrades (selective, per-entry by name).
+# PROJECT-OWNED (created only if missing — NEVER clobbered): PROJECT.md, CONTINUITY.md,
+#   docs/CHANGELOG.md. Per-project Claude overrides go in .claude/settings.local.json.
+#
+set -euo pipefail
+
+SRC="$(cd "$(dirname "$0")" && pwd)"
+PAYLOAD="$SRC/src"
+FORGE_VERSION="unknown"
+[ -f "$SRC/VERSION" ] && FORGE_VERSION="$(head -n1 "$SRC/VERSION" | tr -d '[:space:]')"
+[ -n "$FORGE_VERSION" ] || FORGE_VERSION="unknown"
+MODE="install"
+WITH_HOOKS=0
+GIT_INIT=0
+ISOLATE=1   # auto-isolate Claude Code from ancestor CLAUDE.md by default (--no-isolate to keep inheritance)
+TARGET=""
+usage="usage: $0 [target-dir] [--upgrade] [--with-hooks] [--git-init] [--no-isolate]"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --upgrade)     MODE="upgrade" ;;
+    --with-hooks)  WITH_HOOKS=1 ;;
+    --git-init)    GIT_INIT=1 ;;
+    --no-isolate)  ISOLATE=0 ;;
+    -*)            echo "$usage  (unknown arg: $1)" >&2; exit 2 ;;
+    *)             if [ -z "$TARGET" ]; then TARGET="$1"; else echo "$usage  (unexpected arg: $1)" >&2; exit 2; fi ;;
+  esac
+  shift
+done
+TARGET="${TARGET:-$PWD}"
+
+[ -d "$TARGET" ] || { echo "error: target dir not found: $TARGET" >&2; exit 2; }
+TARGET="$(cd "$TARGET" && pwd)"
+# Did a prior forge install own .claude/settings.local.json? (read before the manifest is
+# rewritten below, so the settings writer knows whether it may safely regenerate the file.)
+PRIOR_LOCAL_MANAGED=0
+grep -q '^localsettings:managed$' "$TARGET/.forge-manifest" 2>/dev/null && PRIOR_LOCAL_MANAGED=1
+{ [ -f "$PAYLOAD/CLAUDE.md" ] && [ -d "$PAYLOAD/skills" ]; } || { echo "error: payload not found — run this from the codeforge repo" >&2; exit 2; }
+[ "$TARGET" != "$SRC" ]     || { echo "error: refusing to install into codeforge itself" >&2; exit 2; }
+[ "$TARGET" != "$PAYLOAD" ] || { echo "error: refusing to install into the codeforge payload dir (src/)" >&2; exit 2; }
+
+echo "codeforge $FORGE_VERSION → installing into: $TARGET  (mode: $MODE)"
+
+# --- version drift advisory (informational only, never blocks) ---
+# Compare the version that last stamped this target against the one we're installing.
+PRIOR_VERSION=""
+[ -f "$TARGET/.forge-version" ] && PRIOR_VERSION="$(head -n1 "$TARGET/.forge-version" | tr -d '[:space:]')"
+if [ -n "$PRIOR_VERSION" ] && [ "$PRIOR_VERSION" != "$FORGE_VERSION" ] \
+   && [ "$FORGE_VERSION" != "unknown" ] && [ "$PRIOR_VERSION" != "unknown" ]; then
+  lower="$(printf '%s\n%s\n' "$PRIOR_VERSION" "$FORGE_VERSION" | sort -V | head -n1)"
+  if [ "$lower" = "$PRIOR_VERSION" ]; then
+    echo "  ~ upgrading this target: codeforge $PRIOR_VERSION -> $FORGE_VERSION"
+  else
+    echo "  ! this target was installed by a NEWER codeforge ($PRIOR_VERSION) than you're running ($FORGE_VERSION)."
+    echo "    You may be downgrading it; teammates pinned to $PRIOR_VERSION could see drift. (advisory only)"
+  fi
+fi
+
+# --- self-healing: drop machinery this version no longer installs into the target ---
+# (thin model — machinery lives in the codeforge repo; the target gets runtime only.) This
+# migrates a target from an older, bloated install. Gated on a prior forge install
+# (.forge-manifest present) so a FIRST install never touches an unrelated project's own
+# configs/ or skills/ dirs.
+if [ -f "$TARGET/.forge-manifest" ]; then
+  # Detect a genuinely OLD (pre-thin) forge install: it left this machinery at the target root.
+  # A modern thin install — or an unrelated app that happens to keep its own top-level configs/
+  # or skills/ — does NOT. Gate the configs/skills migration on this signal so a routine
+  # re-install never relocates a project's own configs/ or skills/ just because a manifest exists.
+  old_install=0
+  for f in sync.sh sync.ps1 state.template.md PROJECT.template.md CONTINUITY.template.md docs/extending.md; do
+    [ -e "$TARGET/$f" ] && old_install=1
+  done
+  # Framework-owned machinery, no user content — removed outright.
+  for f in sync.sh sync.ps1 state.template.md PROJECT.template.md CONTINUITY.template.md docs/extending.md; do
+    [ -e "$TARGET/$f" ] && { rm -f "$TARGET/$f"; echo "  - removed obsolete framework file: $f"; }
+  done
+  # Only migrate configs/ and the neutral skills/ when this was actually an old bloated install
+  # (back them up rather than delete, so nothing is lost).
+  if [ "$old_install" = 1 ] && [ -d "$TARGET/configs" ]; then
+    rm -rf "$TARGET/configs.pre-forge.bak"; mv "$TARGET/configs" "$TARGET/configs.pre-forge.bak"
+    echo "  ! configs/ is obsolete (engine configs are generated now) -> configs.pre-forge.bak; per-project Claude tweaks go in .claude/settings.local.json"
+  fi
+  if [ "$old_install" = 1 ] && [ -d "$TARGET/skills" ]; then
+    rm -rf "$TARGET/skills.pre-forge.bak"; mv "$TARGET/skills" "$TARGET/skills.pre-forge.bak"
+    echo "  ! neutral skills/ is obsolete (skills are generated now) -> skills.pre-forge.bak; add custom skills to the codeforge repo"
+  fi
+fi
+
+# --- MANAGED: CLAUDE.md (back up a pre-existing, non-forge one on first install) ---
+if [ -f "$TARGET/CLAUDE.md" ] && ! grep -q "Workflow discipline for Claude Code" "$TARGET/CLAUDE.md" 2>/dev/null; then
+  cp "$TARGET/CLAUDE.md" "$TARGET/CLAUDE.md.pre-forge.bak"
+  echo "  ! backed up existing CLAUDE.md -> CLAUDE.md.pre-forge.bak (move project-specifics into PROJECT.md)"
+fi
+cp "$PAYLOAD/CLAUDE.md" "$TARGET/CLAUDE.md"
+
+# --- MANAGED: framework shared/rules/ (per-entry overwrite by name) ---
+# Refresh only the framework's own rule entries; anything else in shared/rules/ (your
+# project's own rules) is left untouched, so it survives --upgrade.
+mkdir -p "$TARGET/shared/rules"
+new_rules="$(cd "$PAYLOAD/shared/rules" && ls *.md 2>/dev/null)"
+
+# Prune framework rules removed upstream: anything in the last-install manifest that is no
+# longer in the current payload is a framework rule deleted upstream — remove it. Project-owned
+# rules are never in the manifest, so they are untouched. (No manifest yet = skip prune.)
+manifest="$TARGET/.forge-manifest"
+if [ -f "$manifest" ]; then
+  while IFS= read -r line; do
+    case "$line" in
+      rule:*)
+        n="${line#rule:}"
+        # The manifest is committed (and with --git-init, git-added), so treat it as untrusted:
+        # a prune target must be a bare *.md filename — never a path or traversal — so a tampered
+        # entry can't delete outside shared/rules/.
+        case "$n" in
+          */*|*..*|"") echo "  ! ignoring unsafe manifest rule entry: $n" >&2 ;;
+          *.md) printf '%s\n' "$new_rules" | grep -qxF "$n" || { rm -f "$TARGET/shared/rules/$n"; echo "  - pruned framework rule removed upstream: $n"; } ;;
+          *) echo "  ! ignoring non-.md manifest rule entry: $n" >&2 ;;
+        esac ;;
+    esac
+  done < "$manifest"
+fi
+
+for f in "$PAYLOAD"/shared/rules/*.md; do
+  cp "$f" "$TARGET/shared/rules/$(basename "$f")"
+done
+
+# Record the framework-owned manifest for the next upgrade's prune (rules only; skills are
+# fully generated by sync, so there is nothing skill-level to selectively prune).
+{ printf '%s\n' "$new_rules" | sed 's/^/rule:/'; } > "$manifest"
+
+# Stamp the version that produced this install, for drift detection on the next run.
+printf '%s\n' "$FORGE_VERSION" > "$TARGET/.forge-version"
+
+# --- MANAGED: workflow state template (lives in shared/, copied to .workflow/state.md at
+#     workflow start by the skills) ---
+cp "$PAYLOAD/shared/state.template.md" "$TARGET/shared/state.template.md"
+
+# --- MANAGED: framework shared/scripts/ (agent-invoked Tier-B helpers, e.g. check-gates) ---
+if [ -d "$PAYLOAD/shared/scripts" ]; then
+  mkdir -p "$TARGET/shared/scripts"
+  for f in "$PAYLOAD"/shared/scripts/*; do
+    [ -e "$f" ] || continue
+    cp "$f" "$TARGET/shared/scripts/$(basename "$f")"
+  done
+  chmod +x "$TARGET"/shared/scripts/*.sh 2>/dev/null || true
+fi
+
+# --- MANAGED: docs/ scaffolding ---
+mkdir -p "$TARGET/docs"
+for d in prds plans research solutions adr e2e/reports e2e/use-cases; do
+  mkdir -p "$TARGET/docs/$d"
+  [ -e "$TARGET/docs/$d/.gitkeep" ] || touch "$TARGET/docs/$d/.gitkeep"
+done
+
+# --- PROJECT-OWNED: PROJECT.md / CONTINUITY.md / docs/CHANGELOG.md (create only if missing) ---
+[ -f "$TARGET/PROJECT.md" ]    || { cp "$PAYLOAD/PROJECT.template.md" "$TARGET/PROJECT.md"; echo "  + created PROJECT.md (fill in persona/info/variables/special rules)"; }
+[ -f "$TARGET/CONTINUITY.md" ] || cp "$PAYLOAD/CONTINUITY.template.md" "$TARGET/CONTINUITY.md"
+[ -f "$TARGET/docs/CHANGELOG.md" ] || cp "$PAYLOAD/docs/CHANGELOG.md" "$TARGET/docs/CHANGELOG.md"
+
+# --- back up any pre-existing, NON-forge per-engine skills dir before sync overwrites it ---
+# (forge-generated dirs carry a .forge-generated marker; a dir without it is the user's own,
+#  so we never wipe a user's skills — even one coincidentally named new-feature.)
+for eng in .claude .agents; do
+  sd="$TARGET/$eng/skills"
+  if [ -e "$sd" ] && [ ! -e "$sd/.forge-generated" ]; then
+    mv "$sd" "$sd.pre-forge.bak"
+    echo "  ! backed up existing $eng/skills -> $eng/skills.pre-forge.bak (add custom skills to the codeforge repo)"
+  fi
+done
+# back up a real, non-forge AGENTS.md before sync overwrites it
+if [ -f "$TARGET/AGENTS.md" ] && ! grep -q "Workflow discipline for Claude Code" "$TARGET/AGENTS.md" 2>/dev/null; then
+  cp "$TARGET/AGENTS.md" "$TARGET/AGENTS.md.pre-forge.bak"
+  echo "  ! backed up existing AGENTS.md -> AGENTS.md.pre-forge.bak"
+fi
+
+# --- GENERATE engine dirs + AGENTS.md + opencode.json via sync (reads the codeforge source,
+#     writes straight into the target — no source or sync script copied there) ---
+bash "$PAYLOAD/sync.sh" --out "$TARGET" >/dev/null
+
+# --- Claude Code .claude/settings.local.json: auto-isolation + opt-in gate hook ---
+# Both features land in this one gitignored, per-developer, machine-specific file. Auto-isolation
+# (default; --no-isolate to keep inheritance) adds `claudeMdExcludes` so Claude Code does NOT
+# blend ancestor CLAUDE.md / .claude/rules into this project — Codex and OpenCode already scope
+# to the project root, Claude Code walks to the filesystem root. --with-hooks adds the Tier-C
+# PreToolUse gate. codeforge only (re)writes this file when it is absent or a prior forge install
+# owned it (tracked as `localsettings:managed` in .forge-manifest); a file it doesn't own is left
+# alone. The hook's $CLAUDE_PROJECT_DIR is resolved by Claude Code at runtime, not now.
+excludes=""
+if [ "$ISOLATE" = "1" ]; then
+  d="$(dirname "$TARGET")"
+  while [ -n "$d" ] && [ "$d" != "/" ]; do
+    [ -f "$d/CLAUDE.md" ]       && excludes="$excludes$d/CLAUDE.md
+"
+    [ -f "$d/CLAUDE.local.md" ] && excludes="$excludes$d/CLAUDE.local.md
+"
+    { [ -d "$d/.claude/rules" ] && [ "$d" != "$HOME" ]; } && excludes="$excludes$d/.claude/rules/**
+"
+    nd="$(dirname "$d")"; [ "$nd" = "$d" ] && break; d="$nd"
+  done
+fi
+n_excl=$(printf '%s' "$excludes" | grep -c . || true)
+
+sl="$TARGET/.claude/settings.local.json"
+if [ "$n_excl" -gt 0 ] || [ "$WITH_HOOKS" = "1" ]; then
+  if [ -f "$sl" ] && [ "$PRIOR_LOCAL_MANAGED" != "1" ]; then
+    echo "  ! .claude/settings.local.json exists and isn't codeforge-managed — not touching it."
+    echo "    (skipped auto-isolation / gate hook; remove that file and re-run, or edit it by hand.)"
+  else
+    excl_json=""
+    while IFS= read -r p; do
+      [ -n "$p" ] || continue
+      if [ -z "$excl_json" ]; then excl_json="$(printf '\n    "%s"' "$p")"
+      else excl_json="$excl_json$(printf ',\n    "%s"' "$p")"; fi
+    done <<EOF
+$excludes
+EOF
+    hook_block='  "hooks": {
+    "PreToolUse": [
+      { "matcher": "Bash", "hooks": [ { "type": "command", "command": "sh \"$CLAUDE_PROJECT_DIR/shared/scripts/claude-gate-hook.sh\"" } ] }
+    ]
+  }'
+    {
+      printf '{'
+      [ "$n_excl" -gt 0 ] && printf '\n  "claudeMdExcludes": [%s\n  ]' "$excl_json"
+      { [ "$n_excl" -gt 0 ] && [ "$WITH_HOOKS" = "1" ]; } && printf ','
+      [ "$WITH_HOOKS" = "1" ] && printf '\n%s' "$hook_block"
+      printf '\n}\n'
+    } > "$sl"
+    grep -q '^localsettings:managed$' "$manifest" 2>/dev/null || printf 'localsettings:managed\n' >> "$manifest"
+    [ "$n_excl" -gt 0 ]      && echo "  + auto-isolated Claude Code from $n_excl ancestor instruction path(s) -> .claude/settings.local.json (--no-isolate to keep inheritance)"
+    [ "$WITH_HOOKS" = "1" ]  && echo "  + Claude gate hook -> .claude/settings.local.json (opt-in, hard-blocks ship on incomplete gates)"
+  fi
+elif [ "$PRIOR_LOCAL_MANAGED" = "1" ] && [ -f "$sl" ]; then
+  rm -f "$sl"
+  echo "  - removed codeforge-managed .claude/settings.local.json (nothing to configure now)"
+fi
+
+# --- .gitignore (merge, don't clobber): ONLY local state ---
+# The generated engine artifacts (.claude/, .agents/, .codex/, AGENTS.md, opencode.json)
+# are COMMITTED with the project so a fresh clone works immediately — no post-clone step,
+# no dependency on codeforge. Only genuinely local/transient state is ignored here.
+touch "$TARGET/.gitignore"
+if ! grep -qx '# codeforge (local state — do not commit)' "$TARGET/.gitignore"; then
+  {
+    printf '\n# codeforge (local state — do not commit)\n'
+    printf '.DS_Store\n.workflow/\n.claude/settings.local.json\n'
+  } >> "$TARGET/.gitignore"
+fi
+
+# --- warn if the generated config lacks the forge push/PR gate (points at the codeforge
+#     source baseline that produced it) ---
+warn_gate() {  # $1 = generated file in target, $2 = grep needle, $3 = hint
+  if [ -f "$TARGET/$1" ] && ! grep -q "$2" "$TARGET/$1" 2>/dev/null; then
+    echo "  ! $1 has no forge push/PR gate ($3) — add it to the codeforge source, then re-run."
+  fi
+}
+warn_gate ".claude/settings.json" "git push"       "ask-tier on git push / gh pr create"
+warn_gate ".codex/config.toml"    "approval_policy" "approval_policy"
+warn_gate "opencode.json"         "git push"       "permission.bash git push* / gh pr create*"
+
+# --- post-install validation: generated skills + AGENTS.md + engine configs must exist ---
+ok=1
+for p in .claude/skills .agents/skills; do
+  [ -e "$TARGET/$p/new-feature/SKILL.md" ] || { echo "  ! discovery FAILED: $p was not generated"; ok=0; }
+done
+for f in AGENTS.md .claude/settings.json .codex/config.toml opencode.json shared/state.template.md; do
+  [ -f "$TARGET/$f" ] || { echo "  ! FAILED: $f was not generated"; ok=0; }
+done
+if [ "$ok" != 1 ]; then
+  echo "  ✗ install INCOMPLETE — issues above; NOT marking as installed" >&2
+  exit 1
+fi
+echo "  ✓ validation: skills (.claude + .agents), AGENTS.md, and engine configs generated"
+
+# --- git: the workflow (branches/commits) and ship gates operate on git ---
+if git -C "$TARGET" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  :  # already a git repo — the workflow uses it
+elif [ "$GIT_INIT" = "1" ]; then
+  git -C "$TARGET" init -q
+  git -C "$TARGET" add -A
+  if git -C "$TARGET" commit -q -m "chore: adopt codeforge" 2>/dev/null; then
+    echo "  + initialized a git repo + baseline commit (chore: adopt codeforge)"
+  else
+    echo "  + initialized a git repo (baseline commit skipped — set git user.name/email, then commit)"
+  fi
+else
+  echo "  ! not a git repo — codeforge's workflow (branches, commits) and the ship gates assume git."
+  echo "    Run 'git init' here, or re-run the installer with --git-init."
+fi
+
+echo "codeforge installed."
+echo "  next: (1) fill PROJECT.md   (2) in Codex, trust the project when prompted"
+echo "        (3) open the project in any of Claude Code / Codex / OpenCode"
+echo "  to customize or upgrade: edit the codeforge source, then re-run this installer"
+echo "  against the project (--upgrade, or a bare re-run from inside it)."