@pareto4/pp-core 1.12.1 → 1.17.1

package/pp-core/workflows/init.md

@@ -16,14 +16,11 @@ only when it resolves to `gitlab`; under any other provider (`azure` today) it i
 **skipped, not failed**, and the run falls through to this same generic remote-wiring
 path so the user still leaves with a wired remote (Phase 34 INIT-03).
 
-Step 2 is a single instruction to run `pp-tools init` in a real terminal, not a prose
-questionnaire and not a relay this document drives (Phase 34-09 gap closure). Four prior
-UAT walks — plain prose, hardened prose, a tested CLI arm, and a session state machine the
-agent was still handed one step at a time — all failed at the identical point: the agent's
-own model of which steps exist overrode this document and it substituted its own
-`AskUserQuestion` wizard for the question set (`34-VALIDATION.md`). The interaction now
-lives entirely inside `pp-tools init` itself — a human types answers directly into the
-process that acts on them — so this document has nothing left to compress, reorder or drop.
+Step 2 relays the `init-contract` session: the engine returns one step at a time and the
+agent shows each prompt verbatim and passes the reply back, adding no questions of its own
+(earlier relays failed exactly there, `34-VALIDATION.md`). With the embedded org profile the
+session asks only the project name, the description and the compose confirmation.
+`pp-tools init` in a terminal is the same session for a user who prefers it.
 
 Inert of all Pareto/GitLab behavior when no .platform-bindings.json is present.
 </purpose>
@@ -67,23 +64,9 @@ _PP_SHIM_NAME="pp-tools.cjs"; _pp_root() { ( for _v in $(env | sed -n 's/^\(GIT_
 # Gate on presence via reader — absent file → {present:false} exit 0 (inert, step skipped, no jq)
 if [ "$(pp_run query platform-bindings --pick present 2>/dev/null)" = "true" ]; then
   PINNED=$(pp_run query platform-bindings --pick platform.tag)
-  REPO=$(pp_run query platform-bindings --pick platform.repo)
-  HOST_FROM_BINDINGS=$(pp_run query platform-bindings --pick platform.host 2>/dev/null)
-  PLATFORM_HOST="${HOST_FROM_BINDINGS:-${HOST:-gitlab.com}}"
-  PLATFORM_REPO_URL="https://${PLATFORM_HOST}/${REPO}.git"
-  # Resolve latest STABLE tag from remote — never hard-block if offline (empty LATEST → skip drift check)
-  # Keep --refs to strip ^{} annotated-tag rows; --sort=-v:refname sorts server-side
-  # Stable filter fixes prerelease mis-ordering: git ranks v1.4.0-rc.1 after v1.4.0 (wrong by semver)
-  # semver-compare.cjs is the single blessed source for comparison — do NOT reimplement
-  REMOTE_TAGS=$(git ls-remote --tags --refs --sort=-v:refname "$PLATFORM_REPO_URL" 'v*' 2>/dev/null | sed 's#.*/##')
-  # IN-03: pass the lib dir via env (PP_LIB_DIR) rather than interpolating ${PP_TOOLS%/*}
-  # into the JS program text — keeps the path out of the evaluated source.
-  LATEST=$(printf '%s\n' "$REMOTE_TAGS" | PP_LIB_DIR="${PP_TOOLS%/*}/lib" node -e "
-const sc = require(process.env.PP_LIB_DIR + '/semver-compare.cjs');
-const lines = require('fs').readFileSync(0, 'utf-8').split('\n').map(s=>s.trim()).filter(Boolean);
-const stable = lines.filter(sc.isStableTripletSemver).sort(sc.compareSemverCore);
-process.stdout.write((stable[stable.length-1] || '') + '\n');
-" 2>/dev/null)
+  # The owner is compose-bindings resolveLatestPlatformTag — the same lookup pp-tools init and check ship.platform-drift use — so the URL is never composed in shell.
+  # Tagless, offline and unreachable all print as empty: latest=<unresolved> and the drift comparison is skipped (never hard-block).
+  LATEST=$(pp_run query platform-latest-tag --pick latest 2>/dev/null)
   echo "platform preflight: pinned=${PINNED:-<none>} latest=${LATEST:-<unresolved>}"
   if [ -n "$LATEST" ] && [ -n "$PINNED" ] && [ "$PINNED" != "$LATEST" ]; then
     echo "PP_PLATFORM_DRIFT=1"
@@ -100,8 +83,8 @@ tag. STOP before Step 1 and use `AskUserQuestion` to let the user choose:
 - **Proceed on the older pin** — continue knowingly; record the deferral in `PROJECT.md`
   so it is a conscious decision, not silent drift.
 
-If `LATEST` was unresolved (offline / no network), note it and proceed — never hard-block
-initiation on an unreachable remote. For non-Pareto repos the block is a no-op and this
+If `LATEST` was unresolved (no stable release tag, offline, or an unreachable remote), note it
+and proceed — never hard-block initiation on an unresolved tag. For non-Pareto repos the block is a no-op and this
 step is skipped entirely.
 
 ---
@@ -125,7 +108,8 @@ Apply the `#3491` guard (never nest `.git` inside an existing worktree):
 - If `has_git` is `true` and `in_nested_subdir` is `true`: **skip `git init`**; warn the
   user: "Initializing inside an existing worktree (`${git_worktree_root}`); planning files
   will track to the outer repo." Do not call `git init`. This case pairs with the
-  `--skipGitInit` flag used by the gated GitLab provisioning path in Plan 02.
+  skip-git-init flag the gated GitLab provisioning path's locked create recipe
+  carries (G-4).
 - If `has_git` is `true` and `in_nested_subdir` is `false`: **skip `git init`** (already
   at the worktree root).
 - If `has_git` is `false`: run `git init` to initialize a new repository.
@@ -135,50 +119,42 @@ Step 0). Continue honoring it for every `AskUserQuestion` call in this and later
 
 ---
 
-## 2. Identity, provider and binding — run `pp-tools init` (D-05, D-07, INIT-01, INIT-02, INIT-03)
+## 2. Identity, provider and binding — relay the `init-contract` session (D-05, D-07, INIT-01, INIT-02, INIT-03)
 
-Tell the user to run this in their own terminal, then **stop** and wait for them to confirm
-they are done before continuing to Step 3:
+`pp-tools init` is a loop over this same session, so relaying it here makes the same writes
+(`.planning/config.json`, `vault.provider`, `vault.enabled`, `.platform-bindings.json`). The
+engine owns which questions exist, their order and every write; you only relay. Repeat until
+the step is `done`:
 
-```text
-node "<dir>/bin/pp-tools.cjs" init
+```bash
+pp_run query init-contract --session-next
 ```
 
-`<dir>` is the directory on this run's `pp-core answered from:` line, so the terminal runs the
-install this session runs; a bare `pp-tools` resolves through `PATH` and can be another one.
-With no such line, give `pp-tools init`.
-
-**Do not ask the identity questions yourself. Do not describe the question set, the
-provider options, or the compose confirmation. Do not attempt to drive the `init-contract`
-session on the user's behalf — not even one step of it, even via `--session-next` /
-`--session-answer`.** Four dated UAT walks (`34-VALIDATION.md` § Manual-Only Verifications)
-found the IDENTICAL failure at exactly this boundary, across four escalating strategies —
-plain prose, hardened prose, a data-supplying CLI arm, and a session state machine the
-agent was still handed one step at a time. Every pure-bash step ran reliably every time;
-the one step whose job is to ask a structured question set was always overridden by the
-agent's own `AskUserQuestion` wizard instead. The only strategy left is to remove the
-interaction from this document entirely: `pp-tools init` prompts on a real terminal, reads
-the answers itself, and performs every write (`.planning/config.json`, `vault.provider`,
-`.platform-bindings.json`) — a human types answers directly into the process that acts on
-them, with nothing in between. It refuses to run when stdin is not a TTY.
+Act on the JSON it prints and on nothing else. Ask in plain chat text, never with
+`AskUserQuestion`: the answers are free text, and invented options or extra questions are the
+failure this step guards against.
+
+- **A question** (`step` is a question id): first list each new `autoAnswered` entry once as
+  `id = value (source)`, then ask `prompt` word for word. With `optionalAnswer: true` the user
+  may answer `none`. Pass the reply unchanged, in single quotes (a `'` written as `'\''`):
+  `pp_run query init-contract --session-answer '<step>=<reply>'`. On an error, show its
+  message and ask the same `prompt` again.
+- **`compose_confirm`**: show `info.provenance` as a field / value / source table, ask
+  `prompt`, and pass the reply the same way.
+- **`verify`**: show each violation's code and message and stop; the user fixes the cause, or
+  runs `pp_run query init-contract --session-reset` and Step 2 starts over.
+- **`done`**: continue to Step 2.6.
+
+A user who would rather type into the engine directly can run
+`node "<dir>/bin/pp-tools.cjs" init` in their own terminal instead, `<dir>` being the directory
+on this run's `pp-core answered from:` line (a bare `pp-tools` resolves through `PATH` and can
+be another install); wait for them to confirm before Step 2.6.
 
 **If this step is skipped, `/pp-init` has not completed** — no identity config, no
 `vault.provider`, and no binding are produced without it. `pp_run query init-contract
 --verify` reports exactly what is still missing if the operator wants to confirm before
 continuing.
 
-**Then arm and probe the client vault** (after `pp-tools init` finishes):
-
-```bash
-pp_run query init-contract --arm-vault
-pp_run vault probe
-```
-
-Show both outputs verbatim. `--arm-vault` sets `vault.enabled: true` only where the key is
-absent (an explicit `false` is kept); `ok:false` means no client vault is bound — re-run
-`pp-tools init`. The probe line says whether the client vault is reachable at its pinned ref;
-it prints nothing when the vault is disabled. Neither ever blocks this step.
-
 **Scope boundary:** this step writes identity, provider and the platform binding only. All
 coding-standards, architecture context, client-engagement CLAUDE.md blocks, and
 discovery-session scaffolding are out of scope here. Phase 9 owns those; /pp-discovery
@@ -186,6 +162,188 @@ self-generates its own session files (D-03).
 
 ---
 
+## 2.6. Reachability proof (D-07-01, D-07-05, INIT-01, INIT-02, INIT-03)
+
+Runs immediately after the Step 2 session is `done`, before any remote wiring. Three gate
+signals decide whether it does anything at all, in this order: `vault.enabled` is the
+literal `true` (OD-1 — `pp-tools init` writes it once a profile resolved and composition
+succeeded); an org profile resolves (D-07-01); then a platform binding is present ⇒ probe,
+absent ⇒ the loud failure below (D-07-02). A generic or non-vault project fails the first
+two signals, and this whole step then prints **nothing at all** — no probe, no cache, no
+record, no side effect of any kind (INIT-01).
+
+The probe's exit code is `0` on every path by contract (STRICT-02): the verdict lives in
+its booleans, never in `$?`, and its `error` prose is never echoed (D-07-07). The fetch
+runs only *after* a clean probe, so a project that cannot reach its vault never ends up
+with a half-populated cache (D-07-05).
+
+```bash
+# D-07-01 + OD-1 + INIT-01: three signals, all read through the resolvers every other path
+# uses. Anything but the literal "true" is a fail-inert default.
+PP_INIT_PROBE=""
+# 16-16 D-81: the gate answers for itself (isVaultGateActive). A string "true" and a
+# flat-only key read OFF there, in --verify (15-04 D-32) and here alike. It reads no
+# bindings, so the unbound arm below stays reachable.
+VAULT_ON=$(pp_run loop render-hooks plan:pre --active-cap vault 2>/dev/null || echo false)
+# --raw is load-bearing on the org-profile read: without it that arm prints prose.
+PROFILE_RESOLVED=$(pp_run query vault org-profile --raw --pick profile.resolved 2>/dev/null || echo false)
+if [ "$VAULT_ON" = "true" ] && [ "$PROFILE_RESOLVED" = "true" ]; then
+  PROFILE_NAME=$(pp_run query vault org-profile --raw --pick profile.name 2>/dev/null || echo "")
+  if [ "$(pp_run query platform-bindings --pick present 2>/dev/null)" != "true" ]; then
+    # D-07-02: bindings ABSENT on a profile-bound project is the loud failure, never a skip; a
+    # present but malformed file is named as such (D-47 b: the verb treats it as present).
+    PP_INIT_PROBE=unbound
+    PP_INIT_BINDINGS="is absent"; PP_INIT_WHY="no platform binding"; PP_INIT_SEEN="--verify cannot see an unbound stop without a record: it reports ok:true until .planning is writable and /pp-init is re-run"
+    [ -f .platform-bindings.json ] && { PP_INIT_BINDINGS="is present and will not parse"; PP_INIT_WHY="malformed platform binding"; PP_INIT_SEEN="--verify reports INIT_PROBE_NOT_RUN until a re-run records it"; }
+    printf '%s\n' "Reachability proof: NOT POSSIBLE — org profile \"${PROFILE_NAME}\" resolved, so a platform binding is expected, but .platform-bindings.json ${PP_INIT_BINDINGS}."
+    # WR-02: the remedy branches on a MEASUREMENT (D-07-07): `--reset` reaches the compose
+    # confirmation only when something is composable. Offline dry run, exit 0.
+    COMPOSABLE=$(pp_run query compose-bindings --offline --pick composable 2>/dev/null || echo false)
+    if [ "$COMPOSABLE" = "true" ]; then
+      printf '%s\n' "Nothing was probed. Run \"pp-tools init --reset\" to redo the question set and reach the compose confirmation, then re-run /pp-init."
+    else
+      printf '%s\n' "Nothing was probed, and \"pp-tools init --reset\" cannot help — the org profile seeds no binding to compose. Add platform.repo and client.vaultRepo / client.vaultRef to .platform-bindings.json by hand (or update the profile), then re-run /pp-init."
+    fi
+    # WR-02: nothing was probed, but the stop IS recorded, or --verify reports ok:true on a
+    # project that halted. R2-WR-04: a REFUSED write is a detail line (reachability-outcome.md
+    # c-unrecorded) stating the MEASURED consequence: owesAProof keys on the bindings file, so
+    # --verify sees the stop only when the file exists (the malformed case). Both arms' wording
+    # is re-measured by the Step 2.6 test file.
+    if ! pp_run query init-contract --record-probe "failed=${PP_INIT_WHY}; nothing could be probed" >/dev/null 2>&1; then
+      printf '%s\n' "  record   .planning/config.json  not written — this stop is unrecorded, and ${PP_INIT_SEEN}"
+    fi
+    echo "PP_INIT_PROBE=unbound"
+  else
+    # D-07-05: probe first. ONE --raw capture; every read below parses this text, because
+    # each --pick would re-run the whole probe. The exit code is 0 on every path.
+    PROBE=$(pp_run query vault probe --raw 2>/dev/null || echo '{"targets":[]}')
+    # R3-CR-02 + R3-WR-02: ONE evaluation of the target set, read by every arm
+    # below. FOUR hand-copied de-dup pipelines stood here and had already
+    # diverged; the one that mattered inverted the proof. 07-18 excluded the
+    # fallback tier AFTER the de-dup, and targets arrive in the fixed order
+    # client, shared, platform — so a platform sharing a coordinate with the
+    # fallback survived under the FALLBACK'S NAME, the exclusion deleted the
+    # only representative of a REQUIRED tier, and Step 2.6 printed and durably
+    # recorded a platform reachable line for a target measured unreachable. The
+    # exclusion now runs BEFORE the de-dup; the DISPLAY de-dup keeps the REQUIRED
+    # tier's identity when two tiers name one coordinate (a fallback identical to
+    # the client is still one remote, not two). OD-5 Option A unchanged: the
+    # fallback tier stays out of the verdict and out of the note's sick list and
+    # keeps its "(fallback tier, not required)" line when its coordinate is its
+    # own. The all-down flag counts EVERY distinct remote, fallback included, ON
+    # PURPOSE: it drives the offline candidate below, and a fallback that answered
+    # is evidence the network is up. CR-02: a REQUIRED target with no coordinate
+    # gets its own "missing" line — without it the D-07-02 case printed a card
+    # whose every line read healthy under a fail verdict; measured, not a
+    # diagnosis (D-07-07). EMITS: line 1 verdict, 2 all-down, 3 note, 4+ card; a
+    # card line can never carry a newline of its own (redactCloneTarget collapses
+    # the control class at the source, R2-WR-03), so the split below is safe.
+    PROBE_EVAL=$(printf '%s' "$PROBE" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const t=(JSON.parse(d).targets||[]).filter(x=>x&&x.configured===true);const key=x=>[x.repo,x.ref,x.host].join('|');const names=new Set(t.map(x=>x.name));const seen=new Set();const req=t.filter(x=>x.name!=='shared'&&!seen.has(key(x))&&seen.add(key(x)));const pick=new Map();for(const x of t){const k=key(x);const p=pick.get(k);if(!p||(p.name==='shared'&&x.name!=='shared'))pick.set(k,x);}const shown=t.filter(x=>pick.get(key(x))===x);const cfg={client:'client.vaultRepo',platform:'platform.repo'};const gone=Object.keys(cfg).filter(n=>!names.has(n));const ok=names.has('client')&&names.has('platform')&&req.length>0&&req.every(x=>x.reachable===true&&x.refFound===true);const sick=req.filter(x=>!(x.reachable===true&&x.refFound===true)).map(x=>String(x.name)+' '+String(x.repoSafe)+' @ '+String(x.ref)+' '+(x.reachable===true?'ref not found':'unreachable'));const all=gone.map(n=>n+' not configured').concat(sick);const lines=shown.map(x=>'  '+String(x.name).padEnd(9)+String(x.repoSafe)+' @ '+((x.name==='platform'&&x.ref==='HEAD')?'(unpinned)':String(x.ref))+'  '+(x.reachable===true?(x.refFound===true?'reachable, ref found':'ref not found'):'unreachable')+(x.name==='shared'?'  (fallback tier, not required)':'')).concat(gone.map(n=>'  '+n.padEnd(9)+'(not configured)  missing — '+cfg[n]+' is absent from .platform-bindings.json'));process.stdout.write([ok?'pass':'fail',String(shown.length>0&&shown.every(x=>x.reachable!==true)),'failed='+(all.length?all.join('; '):'probe payload unreadable')].concat(lines).join('\n'));}catch{process.stdout.write('fail\nfalse\nfailed=probe payload unreadable');}")
+    PROBE_VERDICT=$(printf '%s' "$PROBE_EVAL" | sed -n '1p')
+    PROBE_ALL_DOWN=$(printf '%s' "$PROBE_EVAL" | sed -n '2p')
+    PROBE_NOTE=$(printf '%s' "$PROBE_EVAL" | sed -n '3p')
+    PROBE_LINES=$(printf '%s' "$PROBE_EVAL" | sed -n '4,$p')
+    FAIL_KIND=""
+    FAIL_DETAIL=""
+    FAIL_NOTE=""
+    if [ "$PROBE_VERDICT" = "pass" ]; then
+      # D-07-05: the fetch is what produces INIT-02's count, warm cache and SUMMARY.md.
+      FETCH=$(pp_run query vault fetch --raw 2>/dev/null || echo '{}')
+      FETCH_TIER=$(printf '%s' "$FETCH" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(String(JSON.parse(d).tier||''));}catch{process.stdout.write('');}")
+      FETCH_SOURCE=$(printf '%s' "$FETCH" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(String(JSON.parse(d).source||''));}catch{process.stdout.write('');}")
+      FETCH_REPO=$(printf '%s' "$FETCH" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(String(JSON.parse(d).repoSafe||''));}catch{process.stdout.write('');}")
+      FETCH_REF=$(printf '%s' "$FETCH" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(String(JSON.parse(d).ref||''));}catch{process.stdout.write('');}")
+      FETCH_SHA=$(printf '%s' "$FETCH" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(String(JSON.parse(d).resolvedSha||'').slice(0,8));}catch{process.stdout.write('');}")
+      FETCH_COUNT=$(printf '%s' "$FETCH" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(String((JSON.parse(d).files||[]).length));}catch{process.stdout.write('0');}")
+      FETCH_SUMMARY=$(printf '%s' "$FETCH" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(String(JSON.parse(d).summaryWritten===true));}catch{process.stdout.write('false');}")
+      PLATFORM_REPO=$(printf '%s' "$PROBE" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const x=(JSON.parse(d).targets||[]).find(y=>y&&y.name==='platform');process.stdout.write(String((x&&x.repoSafe)||''));}catch{process.stdout.write('');}")
+      # Never the probe's internal HEAD placeholder — an unpinned platform says so.
+      PLATFORM_TAG=$(pp_run query platform-bindings --pick platform.tag 2>/dev/null)
+      if [ "$FETCH_TIER" = "client" ] && [ "$FETCH_SUMMARY" = "true" ] && { [ "$FETCH_SOURCE" = "fetched" ] || [ "$FETCH_SOURCE" = "cache" ]; }; then
+        # WR-03: the record write runs BEFORE the card and its exit status decides which
+        # card prints. A refused write used to be a warning under a PASSED card, and PASSED
+        # routes to "continue to Step 3" — so "unrecorded" was defined to continue. It is a
+        # failure of the step, kind FAIL_KIND=record. Markers unchanged: pass/unbound/fail.
+        if pp_run query init-contract --record-probe "passed=platform ${PLATFORM_REPO} @ ${PLATFORM_TAG:-(unpinned)}; vault ${FETCH_REPO} @ ${FETCH_REF} tier ${FETCH_TIER} ${FETCH_COUNT} files" >/dev/null 2>&1; then
+          PP_INIT_PROBE=pass
+          echo "Reachability proof: PASSED"
+          # OD-3 + CR-01: the DISPLAY-SAFE coordinate (repoSafe), ref, tier and booleans
+          # only. Credentials are stripped at the source, so a PAT in the binding reaches
+          # neither this card nor the record. Never url, never error.
+          printf '%s\n' "  platform  ${PLATFORM_REPO} @ ${PLATFORM_TAG:-(unpinned)}  reachable"
+          printf '%s\n' "  vault     ${FETCH_REPO} @ ${FETCH_REF}  reachable, ref found — tier ${FETCH_TIER}, sha ${FETCH_SHA}, ${FETCH_COUNT} files, SUMMARY.md written (${FETCH_SOURCE})"
+          printf '%s\n' "$PROBE_LINES" | grep '^  shared ' || true
+          echo "PP_INIT_PROBE=pass"
+        else
+          PP_INIT_PROBE=fail
+          FAIL_KIND=record
+          FAIL_NOTE=""
+          FAIL_DETAIL="$PROBE_LINES
+  record   .planning/config.json  not written — the proof is unrecorded; --verify reports it as never run"
+        fi
+      else
+        PP_INIT_PROBE=fail
+        FAIL_KIND=fetch
+        FAIL_DETAIL="  The probe answered, but the fetch did not land on the client vault: tier ${FETCH_TIER:-none}, source ${FETCH_SOURCE:-none}, SUMMARY.md written ${FETCH_SUMMARY:-false}."
+        FAIL_NOTE="failed=fetch tier ${FETCH_TIER:-none} source ${FETCH_SOURCE:-none} summaryWritten ${FETCH_SUMMARY:-false}"
+      fi
+    else
+      PP_INIT_PROBE=fail
+      FAIL_KIND=probe
+      FAIL_DETAIL="$PROBE_LINES"
+      # R3-WR-02: the recorded miss comes from the SAME evaluation the verdict and
+      # the card came from — recomputing it here is how the four copies drifted.
+      # CR-02: filtering the RENDERING was the original defect (an ABSENT target
+      # left the note a bare failed=, which recordProbeOutcome refused).
+      FAIL_NOTE="$PROBE_NOTE"
+    fi
+    # INIT-03 + D-07-07: ONE failure block for both fail arms — the header, the candidate
+    # heading and the escape sentence have a single home, so they cannot drift apart.
+    if [ "$PP_INIT_PROBE" = "fail" ]; then
+      echo "Reachability proof: FAILED — init is not complete."
+      printf '%s\n' "$FAIL_DETAIL"
+      echo "Things to check (candidates, not diagnoses):"
+      if [ "$FAIL_KIND" = "record" ]; then
+        echo "  - .planning/config.json or its directory is not writable (permissions, a read-only mount, a full disk)"
+        echo "  - re-run /pp-init once it is — the probe and fetch are cheap to repeat"
+      elif [ "$FAIL_KIND" = "fetch" ]; then
+        echo "  - the client vault ref exists at the remote but its content could not be cloned (sparse paths, permissions)"
+        echo "  - a fresh cache from an earlier run recorded a fallback tier — remove .planning/vault and re-run /pp-init"
+        echo "  - .planning/vault/SUMMARY.md could not be written (directory permissions)"
+      else
+        if [ "$PROBE_ALL_DOWN" = "true" ]; then
+          echo "  - no network / offline — every distinct remote was unreachable (record a deferral if you are offline; re-run /pp-init when back)"
+        fi
+        echo "  - SSH key not loaded in the agent (scp-style targets)"
+        echo "  - HTTPS credentials not configured for this host — git refused to prompt (GIT_TERMINAL_PROMPT=0)"
+        echo "  - az login / host CLI session expired"
+        echo "  - the ref does not exist at the remote (a 'ref not found' line above)"
+        echo "  - a typo in the org profile or in .platform-bindings.json"
+        echo "  - a global git url.<base>.insteadOf rewrite sending git to a different host than the one printed"
+      fi
+      echo "Next: fix and re-run /pp-init, or record an attributed deferral (see below)."
+      # Skipped when the failure IS the record write — it just failed (FAIL_KIND=record).
+      if [ "$FAIL_KIND" != "record" ]; then
+        pp_run query init-contract --record-probe "$FAIL_NOTE" >/dev/null 2>&1 || echo "warning: the probe outcome could not be recorded in .planning/config.json — --verify will report INIT_PROBE_NOT_RUN until a re-run records it"
+      fi
+      echo "PP_INIT_PROBE=fail"
+    fi
+  fi
+fi
+```
+
+**What the block printed decides what happens next.** Nothing at all ⇒ Step 2.6 was inert
+(generic project, vault off, or no org profile resolved): continue to Step 3 without
+comment, and do not mention the vault, the probe or this step to the user. On any other
+outcome — `PP_INIT_PROBE=pass`, `PP_INIT_PROBE=unbound` or `PP_INIT_PROBE=fail` — **Read
+`pp-core/workflows/init/steps/reachability-outcome.md` now and follow it.** That file owns
+the pass narration, the INIT-03 stop, the two-option `AskUserQuestion`, the
+`init-contract --defer-probe` escape and its three reason rules, and D-07-06 (being offline
+is not a reason to skip). Do not invent a fourth outcome, and do not re-run the probe
+hoping for a different answer.
+
+---
+
 ## 3. Remote wiring — provider-agnostic (non-Pareto / no bindings)
 
 **Gate (D-06, D-13) — bindings presence ONLY, never the provider answer.** Step 3 always
@@ -305,6 +463,12 @@ instead — do not fail, do not error, do not prompt for a missing CLI. "Skipped
 failed" is satisfied *and* the user still leaves with a wired remote, which a bare skip
 would not give them; pp-core makes zero provider-API calls it has no client for.
 
+When both conditions hold, **Read `pp-core/workflows/init/steps/gitlab-provisioning.md` and
+follow it.** That file owns G-2 (auth verify-only), G-3 (existence probe →
+adopt-if-exists), G-4 (per-action confirmation, then the locked `--private` create) and G-5
+(post-create reconciliation). Under any other provider do not read it at all — fall through
+to Step 3's generic remote wiring above.
+
 **Security invariants — landmine guards:**
 - Always use the group-qualified `$GROUP/$SLUG` path — never a bare slug (T-08-04, D-09).
   A bare slug creates under the user's personal namespace, not the client group. G-1's
@@ -318,126 +482,6 @@ would not give them; pp-core makes zero provider-API calls it has no client for.
 - Always reconcile create with a `glab repo view` probe — a non-zero create exit does
   NOT mean nothing happened (T-08-09, D-09).
 
-#### G-2. Auth verify-only (D-11)
-
-`/pp-init` **never establishes auth and never reads or writes the user's token.**
-Secrets stay in the environment or OS keyring. Only verify that a session exists:
-
-```bash
-glab auth status >/dev/null 2>&1 || {
-  echo "Not authenticated to GitLab. Run: glab auth login"
-  exit 1
-}
-```
-
-If this check fails, stop immediately. Do not proceed to probe or create.
-Never run `glab auth login` from within `/pp-init`.
-
-#### G-3. Existence probe → adopt-if-exists (D-09, D-12)
-
-Pre-check with a read-only probe before any create attempt. `glab repo create` is **not
-idempotent** — re-running it against an existing project errors but may still produce side
-effects (the GitLab project is created before the remote-add step that then fails). The
-probe avoids this landmine.
-
-This is one self-contained block: it sets `PROJECT_EXISTS` and, on the exists path,
-adopts (links the remote). It NEVER creates — create lives in its own G-4 block, gated
-on `PROJECT_EXISTS=false`, so the create invocation can never fall inside the exists
-branch.
-
-```bash
-if glab repo view "$GROUP/$SLUG" -F json >/dev/null 2>&1; then
-  # Project already exists — ADOPT: link remote only, skip create (D-12)
-  PROJECT_EXISTS=true
-  echo "GitLab project $GROUP/$SLUG already exists — adopting (linking remote, skipping create)."
-  # IN-01: match the remote scheme glab itself uses on the create path — honor the
-  # user's `glab config get git_protocol` (https default) instead of hardcoding SSH,
-  # so adopt and create produce a consistent origin URL.
-  GIT_PROTO=$(glab config get git_protocol 2>/dev/null || echo https)
-  if [ "$GIT_PROTO" = "ssh" ]; then
-    ADOPT_URL="git@${HOST:-gitlab.com}:$GROUP/$SLUG.git"
-  else
-    ADOPT_URL="https://${HOST:-gitlab.com}/$GROUP/$SLUG.git"
-  fi
-  git remote get-url origin >/dev/null 2>&1 || git remote add origin "$ADOPT_URL"
-  echo "Remote 'origin' → $ADOPT_URL"
-else
-  # Project not found — defer to G-4 for confirm-then-create
-  PROJECT_EXISTS=false
-  echo "GitLab project $GROUP/$SLUG not found — will confirm before create."
-fi
-```
-
-If the project exists (`PROJECT_EXISTS=true`), the remote is already linked above
-(skipping create entirely) — proceed straight to G-5 reconciliation. The adopt path does
-not show a create confirmation — it only links the remote, which is a local-only
-operation and can be undone with `git remote remove origin`.
-
-#### G-4. Per-action confirmation, then create (D-05, D-09, D-10, SAFE-01)
-
-**Only run this step when `PROJECT_EXISTS=false`** (the existence probe in G-3 found no
-project). If `PROJECT_EXISTS=true`, skip G-4 entirely — the project was already adopted —
-and go to G-5. When creating, **show the exact command and target before firing**. The
-user must confirm explicitly. Nothing is batched. (D-05)
-
-Present to the user (via `AskUserQuestion` or TEXT_MODE numbered list):
-
-```text
-About to create GitLab project:
-  Command:        glab repo create "$GROUP/$SLUG"
-  Group path:     $GROUP/$SLUG
-  Visibility:     private (enforced --private; never the glab default --internal)
-  Requested:      $VIS  (from bindings gitlab.visibility — see note below)
-  Default branch: main
-  Skip git init:  yes  (local repo already initialized — --skipGitInit)
-  Remote name:    origin
-
-Proceed? [y/N]
-```
-
-`$VIS` (from G-1) is surfaced in the confirmation so the binding's requested visibility is
-never silently ignored (WR-01). pp-core always **creates private** regardless; a
-non-private binding must be applied as a deliberate, separate post-create change.
-
-Only after the user confirms — and only with `PROJECT_EXISTS=false` — run the locked
-create recipe (D-09, D-10). This is a standalone block: it carries no `if`/`else`/`fi`, so
-it can only ever run as the deliberate, confirmed not-exists path:
-
-```bash
-glab repo create "$GROUP/$SLUG" \
-  --description "$DESC" \
-  --private \
-  --defaultBranch main \
-  --skipGitInit \
-  --remoteName origin
-```
-
-**Visibility hard-default (D-10):** the create invocation always carries `--private`.
-Never omit it and let `glab` silently apply `--internal`. `VIS` from bindings is read in
-G-1 and **surfaced in the G-4 confirmation** (WR-01) so a `public`/`internal` request is
-visible to the user — but pp-core still creates the project **private**. Applying a
-non-private visibility is a deliberate, separate post-create action (e.g. `glab repo edit
---visibility …`) the operator performs knowingly; `/pp-init` never auto-relaxes visibility.
-
-#### G-5. Post-create reconciliation (D-09)
-
-After the create (or after the adopt path), re-probe existence. A non-zero exit from
-`glab repo create` does **not** mean the project was not created — `glab` exits non-zero
-(code 3) when the GitLab project was created but the subsequent `git remote add` step
-then failed (e.g., because `origin` already existed). The `repo view` probe is the source
-of truth, not the exit code (research §1 "Remote-add caveat — VERIFIED"):
-
-```bash
-if glab repo view "$GROUP/$SLUG" -F json >/dev/null 2>&1; then
-  echo "Reconciled: GitLab project $GROUP/$SLUG confirmed."
-else
-  echo "WARN: glab repo view $GROUP/$SLUG returned non-zero — verify the project was created before continuing."
-fi
-```
-
-If reconciliation warns, do not auto-retry. Prompt the user to check GitLab directly
-before proceeding to Step 4 (handoff routing).
-
 ### Gated client-context capture (Pareto projects — bindings present)
 
 This step runs **only when** `pp_run query platform-bindings --pick present 2>/dev/null` equals
@@ -445,96 +489,12 @@ This step runs **only when** `pp_run query platform-bindings --pick present 2>/d
 success criterion #4). All capture is **offline-only** — no Obsidian, no MCP, no network (D-05 /
 T-09-05).
 
-```bash
-if [ "$(pp_run query platform-bindings --pick present 2>/dev/null)" = "true" ]; then
-  # ── D-05: edit-on-re-run — read existing block first ──────────────────────────
-  EXISTING=$(pp_run query generate-client-context --read 2>/dev/null || echo '{"present":false}')
-  EXISTING_PRESENT=$(echo "$EXISTING" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const o=JSON.parse(d);process.stdout.write(String(o.present||'false'));}catch{process.stdout.write('false');}")
-
-  if [ "$EXISTING_PRESENT" = "true" ]; then
-    echo ""
-    echo "Existing client-context block found. Press Enter to keep each value, or type to replace it."
-    EXISTING_CLIENT_NAME=$(echo "$EXISTING" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const o=JSON.parse(d);process.stdout.write(o.client_name||'');}catch{}" 2>/dev/null)
-    EXISTING_CLIENT_SLUG=$(echo "$EXISTING" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const o=JSON.parse(d);process.stdout.write(o.client_slug||'');}catch{}" 2>/dev/null)
-    EXISTING_CODING=$(echo "$EXISTING" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const o=JSON.parse(d);process.stdout.write(o.coding_standards||'');}catch{}" 2>/dev/null)
-    EXISTING_ARCH=$(echo "$EXISTING" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const o=JSON.parse(d);process.stdout.write(o.architecture_patterns||'');}catch{}" 2>/dev/null)
-    EXISTING_UI=$(echo "$EXISTING" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const o=JSON.parse(d);process.stdout.write(o.ui_brand_conventions||'');}catch{}" 2>/dev/null)
-    EXISTING_DOD=$(echo "$EXISTING" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const o=JSON.parse(d);process.stdout.write(o.definition_of_done||'');}catch{}" 2>/dev/null)
-  fi
-fi
-```
-
-**Field capture — one field at a time (D-01, D-02):** Prompt the user for each of the five fields
-sequentially. All five are required — **re-prompt on empty input until a non-empty value is given**
-(no skip, no catch-all). Multi-line values are accepted: instruct the user to type or paste, then
-enter a blank line (or a sentinel line such as `EOF`) to signal end-of-field. Do not call any
-network resource during capture.
-
-Capture these fields, in this order:
-
-1. **Client name** — the human-readable client or project name (e.g. "Acme Corp").
-   - On re-run: show the current value (`$EXISTING_CLIENT_NAME`) and let the user keep or replace.
-   - After capturing, derive a URL-safe slug via `pp_run query generate-slug` on the name; present
-     the suggested slug and let the user confirm or override. Store as `CLIENT_SLUG`.
-
-2. **Coding standards** — the conventions and rules the Build agent must follow (e.g. language,
-   style guide, patterns to use/avoid). Multi-line OK.
-   - On re-run: show `$EXISTING_CODING`.
-
-3. **Architecture patterns** — the structural patterns and constraints the Build agent must respect
-   (e.g. layering, module boundaries, framework idioms). Multi-line OK.
-   - On re-run: show `$EXISTING_ARCH`.
-
-4. **UI / brand conventions** — visual and component standards the Build agent must apply (e.g.
-   design system, color tokens, typography rules). Multi-line OK.
-   - On re-run: show `$EXISTING_UI`.
-
-5. **Definition of done** — the quality gates that must pass before any task is marked complete
-   (e.g. tests green, lint clean, accessibility checked). Multi-line OK.
-   - On re-run: show `$EXISTING_DOD`.
-
-**Write block** — after all five fields are captured, write them to a temp file and invoke the
-managed-block writer:
-
-```bash
-if [ "$(pp_run query platform-bindings --pick present 2>/dev/null)" = "true" ]; then
-  # Write collected values to a temp JSON file using node + JSON.stringify so that
-  # multi-line values, embedded quotes, backslashes, and $(...) sequences are encoded
-  # correctly (CR-02: an unquoted heredoc would produce invalid JSON for any multi-line
-  # field, breaking cmdGenerateClientContext with "Failed to parse JSON input").
-  TMP_CTX=$(mktemp /tmp/pp-client-ctx-XXXXXX.json)
-  CLIENT_NAME="$CLIENT_NAME" \
-  CLIENT_SLUG="$CLIENT_SLUG" \
-  CODING_STANDARDS="$CODING_STANDARDS" \
-  ARCHITECTURE_PATTERNS="$ARCHITECTURE_PATTERNS" \
-  UI_BRAND_CONVENTIONS="$UI_BRAND_CONVENTIONS" \
-  DEFINITION_OF_DONE="$DEFINITION_OF_DONE" \
-  node -e "
-const e = process.env;
-const fs = require('fs');
-fs.writeFileSync(process.argv[1], JSON.stringify({
-  client_name: e.CLIENT_NAME,
-  client_slug: e.CLIENT_SLUG,
-  coding_standards: e.CODING_STANDARDS,
-  architecture_patterns: e.ARCHITECTURE_PATTERNS,
-  ui_brand_conventions: e.UI_BRAND_CONVENTIONS,
-  definition_of_done: e.DEFINITION_OF_DONE
-}));
-" "$TMP_CTX"
-
-  # Invoke the Plan 09-01 writer — routes through updateSection, marker-bounded, idempotent
-  pp_run query generate-client-context --from-json "$TMP_CTX"
-  rm -f "$TMP_CTX"
-  echo "Client context written to CLAUDE.md (<!-- PP:client-context-start --> block)."
-fi
-```
-
-This writes a `## Client Context & Patterns` block bounded by
-`<!-- PP:client-context-start -->` … `<!-- PP:client-context-end -->` markers into the local
-CLAUDE.md (config-driven path, default `./.claude/CLAUDE.md`). The write is idempotent —
-re-running `/pp-init` replaces the bounded block, never duplicates it. All values stay local;
-no network or external service is involved.
-
+When — and only when — that gate answers `"true"`, **Read
+`pp-core/workflows/init/steps/client-context-capture.md` and follow it.** That file owns
+the re-run edit path (D-05), the five required fields with their re-prompt-on-empty and
+multi-line rules (D-01, D-02), and the marker-bounded `generate-client-context` write into
+the local CLAUDE.md. On a non-Pareto project do not read it at all — skip straight to
+Step 4, leaving no prompt fired and no block written.
 ---
 
 ## 4. Handoff routing (D-04)