@pareto4/pp-core 1.17.1 → 1.19.0

package/pp-core/workflows/init/steps/github-provisioning.md

@@ -0,0 +1,145 @@
+# Gated GitHub provisioning — H-2..H-5 (D-05, D-09, D-10, D-11, D-12, D-13)
+
+Lazily Read by `pp-core/workflows/init.md` § "Gated GitLab/GitHub provisioning" — Step 3's
+other sub-path — and ONLY when BOTH of that section's gates hold: `.platform-bindings.json`
+is present AND `resolveProvider` answers `github`. Both gates, G-1's one-source-per-value
+config reads and the empty-group guard stay in `init.md`; this file is the GitHub create
+recipe those guards protect, the counterpart of `gitlab-provisioning.md` step for step.
+`$GROUP` (the GitHub organization), `$SLUG`, `$VIS`, `$DESC` and `$HOST` are the variables
+G-1 has already set. Every `gh` call names the host through `GH_HOST`, so a GitHub
+Enterprise host in the binding is honored and `github.com` is the default:
+
+```bash
+GH_HOSTNAME="${HOST:-github.com}"
+```
+
+#### H-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
+gh auth status --hostname "$GH_HOSTNAME" >/dev/null 2>&1 || {
+  echo "Not authenticated to GitHub ($GH_HOSTNAME). Run: gh auth login --hostname $GH_HOSTNAME"
+  exit 1
+}
+```
+
+If this check fails, stop immediately. Do not proceed to probe or create.
+Never run `gh auth login` from within `/pp-init`.
+
+#### H-3. Existence probe → adopt-if-exists (D-09, D-12)
+
+Pre-check with a read-only probe before any create attempt. The create command is **not
+idempotent** — re-running it against an existing repository fails, and a create whose
+remote-add step fails has still created the repository. 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 H-4 block, gated
+on `PROJECT_EXISTS=false`, so the create invocation can never fall inside the exists
+branch.
+
+```bash
+if GH_HOST="$GH_HOSTNAME" gh repo view "$GROUP/$SLUG" --json name >/dev/null 2>&1; then
+  # Repository already exists — ADOPT: link remote only, skip create (D-12)
+  PROJECT_EXISTS=true
+  echo "GitHub repository $GROUP/$SLUG already exists — adopting (linking remote, skipping create)."
+  # Match the remote scheme gh itself uses on the create path — honor the user's
+  # `gh config get git_protocol` (https default) instead of hardcoding SSH.
+  GIT_PROTO=$(gh config get git_protocol --host "$GH_HOSTNAME" 2>/dev/null || echo https)
+  if [ "$GIT_PROTO" = "ssh" ]; then
+    ADOPT_URL="git@$GH_HOSTNAME:$GROUP/$SLUG.git"
+  else
+    ADOPT_URL="https://$GH_HOSTNAME/$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
+  # Repository not found — defer to H-4 for confirm-then-create
+  PROJECT_EXISTS=false
+  echo "GitHub repository $GROUP/$SLUG not found — will confirm before create."
+fi
+```
+
+If the repository exists (`PROJECT_EXISTS=true`), the remote is already linked above
+(skipping create entirely) — proceed straight to H-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`.
+
+#### H-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 H-3 found no
+repository). If `PROJECT_EXISTS=true`, skip H-4 entirely — the repository was already
+adopted — and go to H-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 GitHub repository:
+  Command:        gh repo create "$GROUP/$SLUG"
+  Host:           $GH_HOSTNAME
+  Organization:   $GROUP
+  Repository:     $GROUP/$SLUG
+  Visibility:     private (enforced --private)
+  Requested:      $VIS  (from project.visibility — see note below)
+  Source:         this directory (--source .) — nothing is pushed
+  Remote name:    origin
+
+Proceed? [y/N]
+```
+
+`$VIS` (from G-1) is surfaced in the confirmation so the requested visibility is never
+silently ignored (WR-01). pp-core always **creates private** regardless; a non-private
+repository must be 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
+GH_HOST="$GH_HOSTNAME" gh repo create "$GROUP/$SLUG" \
+  --description "$DESC" \
+  --private \
+  --source . \
+  --remote origin
+```
+
+**Visibility hard-default (D-10):** the create invocation always carries `--private` and
+never `--public` or `--internal`. `VIS` is read in G-1 and **surfaced in the H-4
+confirmation** (WR-01) so a `public`/`internal` request is visible to the user — but
+pp-core still creates the repository **private**. Applying a non-private visibility is a
+deliberate, separate post-create action (e.g. `gh repo edit --visibility …`) the operator
+performs knowingly; `/pp-init` never auto-relaxes visibility. The create pushes nothing
+(no `--push`): the first push is Step 3's own confirmed push, and the repository's default
+branch is whatever that push sends.
+
+#### H-5. Post-create reconciliation (D-09)
+
+After the create (or after the adopt path), re-probe existence. A non-zero exit from
+`gh repo create` does **not** mean the repository was not created — the repository is
+created before `--remote origin` is added, so an `origin` that already exists fails the
+command after the create succeeded. The `repo view` probe is the source of truth, not the
+exit code:
+
+```bash
+if GH_HOST="$GH_HOSTNAME" gh repo view "$GROUP/$SLUG" --json name >/dev/null 2>&1; then
+  echo "Reconciled: GitHub repository $GROUP/$SLUG confirmed."
+else
+  echo "WARN: gh repo view $GROUP/$SLUG returned non-zero — verify the repository was created before continuing."
+fi
+```
+
+If reconciliation warns, do not auto-retry. Prompt the user to check GitHub directly
+before proceeding to Step 4 (handoff routing).
+
+**Security invariants — landmine guards:**
+- Always use the organization-qualified `$GROUP/$SLUG` — never a bare slug (T-08-04, D-09).
+  A bare slug creates under the user's personal account, not the client organization.
+  G-1's empty-group guard is what actually enforces this before any create attempt.
+- Always pass `--private` explicitly — never `--public` or `--internal` (T-08-05, D-10).
+- Always confirm immediately before each outward action — nothing batched (T-08-06, D-05).
+- Verify-only auth via `gh auth status` — never run `gh auth login`, never read or write
+  the user's token (T-08-08, D-11). Bindings hold only non-secret routing data.
+- Always reconcile create with a `gh repo view` probe — a non-zero create exit does NOT
+  mean nothing happened (T-08-09, D-09).

package/pp-core/workflows/init/steps/gitlab-provisioning.md

@@ -1,10 +1,11 @@
 # Gated GitLab provisioning — G-2..G-5 (D-05, D-09, D-10, D-11, D-12, D-13)
 
-Lazily Read by `pp-core/workflows/init.md` § "Gated GitLab/Azure provisioning" — Step 3's
+Lazily Read by `pp-core/workflows/init.md` § "Gated GitLab/GitHub provisioning" — Step 3's
 other sub-path — and ONLY when BOTH of that section's gates hold: `.platform-bindings.json`
 is present AND `resolveProvider` answers `gitlab`. Both gates, G-1's one-source-per-value
-config reads, the empty-group guard and the security-invariant list stay in `init.md`; this
-file is the create recipe those guards protect. Extracted from `init.md` (07-10) so the
+config reads and the empty-group guard stay in `init.md`; this file is the create recipe
+those guards protect, and ends with its security invariants (moved here from `init.md`
+beside `github-provisioning.md`'s own). Extracted from `init.md` (07-10) so the
 always-loaded workflow stays under its DEFAULT size cap — relocation, not deletion: this
 text is the authority for how `/pp-init` provisions a GitLab project, and `$GROUP`, `$SLUG`,
 `$VIS`, `$DESC` and `$HOST` are the variables G-1 has already set.
@@ -26,7 +27,7 @@ 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
+Pre-check with a read-only probe before any create attempt. The create command 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.
@@ -128,3 +129,16 @@ fi
 
 If reconciliation warns, do not auto-retry. Prompt the user to check GitLab directly
 before proceeding to Step 4 (handoff routing).
+
+**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
+  empty-group guard in `init.md` is what actually enforces this before any create attempt.
+- Always pass `--private` explicitly — never inherit `glab`'s default `--internal`
+  visibility (T-08-05, D-10). The `--internal` flag is what makes this dangerous; the
+  locked recipe must carry `--private` and must NOT emit `--internal`.
+- Always confirm immediately before each outward action — nothing batched (T-08-06, D-05).
+- Verify-only auth via `glab auth status` — never run `glab auth login`, never read
+  or write the user's token (T-08-08, D-11). Bindings hold only non-secret routing data.
+- Always reconcile create with a `glab repo view` probe — a non-zero create exit does
+  NOT mean nothing happened (T-08-09, D-09).

package/pp-core/workflows/init/steps/reachability-outcome.md

@@ -16,7 +16,9 @@ the probe, or this step to the user.
 named ref exists, and the client vault landed with a written `SUMMARY.md` (INIT-02).
 Continue to Step 3. A `shared` line on that card is information about the fallback
 tier (OD-5) — it is probed and shown, never required; an unreachable shared vault does
-not fail the proof and is not in the recorded note.
+not fail the proof and is not in the recorded note. A `platform` line reading
+`unreachable (not required)` is information too: the platform repo is not required, and
+the record states what was measured.
 
 **(c) `PP_INIT_PROBE=unbound` or `PP_INIT_PROBE=fail`** — **STOP. `/pp-init` is not
 complete (INIT-03).** Do not continue to Step 3, and do not re-run the probe hoping for a

package/pp-core/workflows/init.md

@@ -11,8 +11,8 @@ D-13 (gate on .platform-bindings.json via the Phase 7 reader — Step 2 now comp
 writes this file too, not only reads it, Phase 34 INIT-01).
 
 Provisioning is provider-aware (Phase 34 D-11/D-13): `resolveProvider` is the sole
-authority for which provisioning path runs. The gated GitLab `glab` recipe (G-2…G-5) runs
-only when it resolves to `gitlab`; under any other provider (`azure` today) it is
+authority for which provisioning path runs. The gated create recipe runs only when it
+resolves to `gitlab` (`glab`, G-2…G-5) or `github` (`gh`, H-2…H-5); under any other provider (`azure` today) it is
 **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).
 
@@ -31,13 +31,6 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 <process>
 
-## Shim hoist
-
-Resolve `pp_run` before any step — required for the platform-bindings preflight (D-13).
-
-```bash
-```
-
 ## Text mode (resolve before any prompt — WR-02)
 
 Resolve `TEXT_MODE` here, **before Step 0**, because the Step 0 drift prompt is the first
@@ -91,13 +84,13 @@ step is skipped entirely.
 
 ## 1. Worktree-aware git init
 
-Parse the init signals by running the query below. `init.execute-phase` is reused here
-deliberately (IN-02): it is the shared verb that emits the generic git-state signals
-(`has_git`, `in_nested_subdir`, `git_worktree_root`) this step needs — no phase work is
-triggered when called with an empty phase argument.
+Parse the init signals by running the query below. `init.ingest-docs` takes no argument
+and emits the git-state signals this step needs (`has_git`, `in_nested_subdir`,
+`git_worktree_root`) from the same #3491 reader `init.new-project` uses. Never use
+`init.execute-phase ""`: it refuses an empty phase, and the `{}` fallback would disable the guard.
 
 ```bash
-INIT=$(pp_run query init.execute-phase "" 2>/dev/null || echo '{}')
+INIT=$(pp_run query init.ingest-docs 2>/dev/null || echo '{}')
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -177,7 +170,12 @@ its booleans, never in `$?`, and its `error` prose is never echoed (D-07-07). Th
 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).
 
+The verdict is the client vault's. The platform repo is probed and shown, but a client
+project may have no access to it, so an unreachable platform repo reads `(not required)`
+and does not fail the proof.
+
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # 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=""
@@ -219,26 +217,25 @@ if [ "$VAULT_ON" = "true" ] && [ "$PROFILE_RESOLVED" = "true" ]; then
     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');}")
+    # diverged, so every arm reads this one line. Only the CLIENT vault decides
+    # the verdict: it is what the fetch below lands. The platform repo is shown
+    # and recorded but not required (a client project may have no access to
+    # it), so an unreachable platform line carries "(not required)", like the
+    # fallback tier (OD-5 Option A: shared is probed and shown, out of the
+    # verdict and out of the note's sick list). A binding with no platform.repo
+    # at all still fails as "not configured". The DISPLAY de-dup keeps a
+    # non-shared tier's identity when two tiers name one coordinate, so a
+    # platform colliding with the fallback is still shown as platform. The
+    # all-down flag counts EVERY distinct remote, fallback included, ON
+    # PURPOSE: it drives the offline candidate below, and a remote that
+    # answered is evidence the network is up. CR-02: a 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 healthy=x=>x.reachable===true&&x.refFound===true;const req=t.filter(x=>x.name==='client');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(healthy);const sick=req.filter(x=>!healthy(x)).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)':(x.name==='platform'&&!healthy(x)?'  (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')
@@ -257,6 +254,9 @@ if [ "$VAULT_ON" = "true" ] && [ "$PROFILE_RESOLVED" = "true" ]; then
       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('');}")
+      # The platform repo is not required (a client may have no access to it): its measured
+      # state goes on the card and into the record, it never decides the verdict.
+      PLATFORM_STATE=$(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(x&&x.reachable===true?(x.refFound===true?'reachable':'ref not found (not required)'):'unreachable (not required)');}catch{process.stdout.write('unreachable (not required)');}")
       # 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
@@ -264,13 +264,13 @@ if [ "$VAULT_ON" = "true" ] && [ "$PROFILE_RESOLVED" = "true" ]; then
         # 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
+        if pp_run query init-contract --record-probe "passed=platform ${PLATFORM_REPO} @ ${PLATFORM_TAG:-(unpinned)} ${PLATFORM_STATE}; 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' "  platform  ${PLATFORM_REPO} @ ${PLATFORM_TAG:-(unpinned)}  ${PLATFORM_STATE}"
           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"
@@ -353,7 +353,7 @@ outright. Take THIS generic sub-path when
 bindings ARE present, take the gated GitLab/Azure sub-path below instead — that section is
 still part of Step 3, not a separate optional step. **The provider answer never decides
 whether Step 3 runs** — inside the gated sub-path it only decides whether the
-GitLab-specific `glab` recipe fires or falls through to this same generic code below.
+`glab` or `gh` create recipe fires or falls through to this same generic code below.
 
 On the generic path:
 
@@ -393,14 +393,14 @@ gets its own per-action confirmation immediately before it fires — nothing bat
 step makes **ZERO `gh`/`glab`/provider-API calls**. The push target is the user-supplied
 URL only.
 
-### Gated GitLab/Azure provisioning (Step 3's other sub-path — bindings present)
+### Gated GitLab/GitHub provisioning (Step 3's other sub-path — bindings present)
 
 This is Step 3's other sub-path, not a separate step. It runs **instead of** the generic
 remote-wiring path above when
 `pp_run query platform-bindings --pick present 2>/dev/null` equals `"true"`. Within it,
-G-1 always runs first to source coordinates and apply the two guards below; the
-GitLab-specific create recipe (G-2…G-5) runs **only when the resolved provider is
-`gitlab`** — under any other provider (`azure` today) it is skipped, not failed, and the
+G-1 always runs first to source coordinates and apply the two guards below; a create
+recipe runs **only when the resolved provider is `gitlab` or `github`** — under any
+other provider (`azure` today) it is skipped, not failed, and the
 run falls through to Step 3's generic remote-wiring path above instead (D-11, D-13).
 Implements D-05 (per-action confirmation), D-09 (existence probe → adopt-if-exists), D-10
 (private by default), D-11 (auth verify-only; gated on provider), D-12 (adopt-if-exists
@@ -442,8 +442,9 @@ comes from, skip G-2 through G-5 entirely, and fall through to Step 3's generic
 wiring:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ -z "$GROUP" ] || [ -z "$SLUG" ]; then
-  echo "Skipping GitLab provisioning: $( [ -z "$GROUP" ] && echo "GROUP (org profile seed provisioning group)" || echo "SLUG (project.slug)" ) is empty — falling through to Step 3's generic remote wiring."
+  echo "Skipping repository provisioning: $( [ -z "$GROUP" ] && echo "GROUP (org profile seed provisioning group)" || echo "SLUG (project.slug)" ) is empty — falling through to Step 3's generic remote wiring."
 fi
 ```
 
@@ -452,35 +453,24 @@ fi
 
 ```bash
 PROVIDER=$(pp_run query compose-bindings --offline --pick provider 2>/dev/null)
-if [ "$PROVIDER" != "gitlab" ]; then
-  echo "Skipping GitLab-specific provisioning for provider \"$PROVIDER\" — falling through to Step 3's generic remote wiring instead."
+if [ "$PROVIDER" != "gitlab" ] && [ "$PROVIDER" != "github" ]; then
+  echo "Skipping repository provisioning for provider \"$PROVIDER\" — falling through to Step 3's generic remote wiring instead."
 fi
 ```
 
-Continue to G-2 only when the empty-group guard above did not skip **and** `PROVIDER`
-equals `gitlab`. Otherwise stop here and go to Step 3's generic remote wiring (`:283-312`)
+Continue only when the empty-group guard above did not skip **and** `PROVIDER`
+is `gitlab` or `github`. Otherwise stop here and go to Step 3's generic remote wiring (`:283-312`)
 instead — do not fail, do not error, do not prompt for a missing CLI. "Skipped, not
 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
-  empty-group guard above is what actually enforces this before any create attempt.
-- Always pass `--private` explicitly — never inherit `glab`'s default `--internal`
-  visibility (T-08-05, D-10). The `--internal` flag is what makes this dangerous; the
-  locked recipe must carry `--private` and must NOT emit `--internal`.
-- Always confirm immediately before each outward action — nothing batched (T-08-06, D-05).
-- Verify-only auth via `glab auth status` — never run `glab auth login`, never read
-  or write the user's token (T-08-08, D-11). Bindings hold only non-secret routing data.
-- Always reconcile create with a `glab repo view` probe — a non-zero create exit does
-  NOT mean nothing happened (T-08-09, D-09).
+When both conditions hold, **Read `pp-core/workflows/init/steps/gitlab-provisioning.md`
+(provider `gitlab`) or `pp-core/workflows/init/steps/github-provisioning.md` (provider
+`github`) and follow it.** Each owns, for its
+CLI, auth verify-only, the existence probe → adopt-if-exists, per-action confirmation then
+the locked `--private` create, post-create reconciliation, and its security invariants
+(landmine guards: group-qualified path, explicit `--private`, verify-only auth). Under any
+other provider read neither — fall through to Step 3's generic remote wiring above.
 
 ### Gated client-context capture (Pareto projects — bindings present)
 
@@ -555,9 +545,9 @@ legitimately not exist — the session declines or composes nothing on the inert
 
 ```bash
 if [ -f .platform-bindings.json ]; then
-  pp_run query commit "docs: initialize project" --files .planning/config.json .platform-bindings.json
+  pp_run query commit "docs(planning): initialize project" --files .planning/config.json .platform-bindings.json
 else
-  pp_run query commit "docs: initialize project" --files .planning/config.json
+  pp_run query commit "docs(planning): initialize project" --files .planning/config.json
 fi
 ```
 

package/pp-core/workflows/map-codebase.md

@@ -327,6 +327,7 @@ Continue to verify_output.
 Verify all documents created successfully:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls -la .planning/codebase/
 wc -l .planning/codebase/*.md
 ```
@@ -346,6 +347,7 @@ Continue to scan_for_secrets.
 Run secret pattern detection:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Check for common API key patterns in generated docs
 grep -E '(sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]+|sk_test_[a-zA-Z0-9]+|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9_-]+|AKIA[A-Z0-9]{16}|xox[baprs]-[a-zA-Z0-9-]+|-----BEGIN.*PRIVATE KEY|eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.)' .planning/codebase/*.md 2>/dev/null && SECRETS_FOUND=true || SECRETS_FOUND=false
 ```
@@ -379,7 +381,8 @@ Continue to commit_codebase_map.
 Commit the codebase map:
 
 ```bash
-pp_run query commit "docs: map existing codebase" --files .planning/codebase/*.md
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
+pp_run query commit "docs(planning): map existing codebase" --files .planning/codebase/*.md
 ```
 
 Continue to offer_next.
@@ -390,6 +393,7 @@ Present completion summary and next steps.
 
 **Get line counts:**
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 wc -l .planning/codebase/*.md
 ```
 

package/pp-core/workflows/milestone-summary.md

@@ -78,6 +78,7 @@ git tag -l "v${VERSION}" | head -1
 ```
 If the tag exists:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 git log v${VERSION} --oneline | wc -l
 git diff --stat $(git log --format=%H --reverse v${VERSION} | head -1)..v${VERSION}
 ```
@@ -190,7 +191,7 @@ mkdir -p .planning/reports
 
 Write the summary, then commit:
 ```bash
-pp_run query commit "docs(v${VERSION}): generate milestone summary for onboarding" --files \
+pp_run query commit "docs(planning): generate v${VERSION} milestone summary for onboarding" --files \
   ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md"
 ```
 

package/pp-core/workflows/mvp-phase.md

@@ -99,6 +99,7 @@ If any of the three answers is empty or whitespace-only, error and re-prompt tha
 **Validate via the centralized User Story validator.** The verb owns the canonical regex `/^As a .+, I want to .+, so that .+\.$/` and surfaces per-error guidance:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 USER_STORY_RESULT=$(pp_run query user-story.validate --story "$USER_STORY")
 if [ "$(echo "$USER_STORY_RESULT" | jq -r '.valid')" != "true" ]; then
   echo "$USER_STORY_RESULT" | jq -r '.errors[]' >&2

package/pp-core/workflows/new-milestone.md

@@ -55,6 +55,7 @@ If the flag is absent, keep the current behavior of continuing phase numbering f
 Check `.planning/seeds/` for seed files that match the milestone goals gathered in step 2.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls .planning/seeds/SEED-*.md 2>/dev/null
 ```
 
@@ -217,7 +218,7 @@ pp_run query phases.clear --confirm
 ```
 
 ```bash
-pp_run query commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
+pp_run query commit "docs(planning): start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
 ```
 
 ## 7. Load Context and Resolve Models
@@ -256,6 +257,7 @@ If `--reset-phase-numbers` is active:
 If `phase_dir_count > 0`, let the engine archive what the closed milestones name — never move phase directories by hand:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ARCHIVED=$(pp_run query phases.archive-closed ${GSD_WS})
 ```
 
@@ -368,7 +370,7 @@ Commit after writing.
 **Synthesizer output self-heal (#222) — verify SUMMARY.md materialized:** The synthesizer's canonical output is `.planning/research/SUMMARY.md` on disk; its brief structured return (`## SYNTHESIS COMPLETE` plus a few `###` confirmation lines) is NOT the file content. A known LLM false-refusal (issue #222) sometimes makes the agent return the full SUMMARY.md document inline — fabricating a write restriction (e.g. "the runtime is blocking file writes") — instead of writing the file. Prompt hardening alone does not fully eliminate it, so the orchestrator MUST absorb the failure deterministically before spawning `pp-roadmapper`:
 
 1. Verify `.planning/research/SUMMARY.md` exists AND is substantive — non-empty, and free of any leftover `<!-- gsd:write-continue -->` continuation sentinel (which marks a truncated/incomplete write). You may validate with `pp-tools verify-summary .planning/research/SUMMARY.md` — it exits 0 regardless, so check its JSON `passed` field (`"passed": false` means missing or invalid), not the process exit code. If it passes, continue normally.
-2. If it is MISSING or invalid AND the synthesizer's return message contains the FULL SUMMARY.md document — recognizable by the template's top-level markers `# Project Research Summary`, `## Key Findings`, `## Implications for Roadmap`, and `## Sources`, not merely the brief `## SYNTHESIS COMPLETE` confirmation — the false-refusal fired: write that returned document to `.planning/research/SUMMARY.md` with the Write tool, then commit ALL research artifacts the synthesizer owns (it commits on behalf of the four researchers) with `pp-tools query commit "docs: complete project research" --files .planning/research/` unless they are already committed. Log `⚠ #222 self-heal: synthesizer returned SUMMARY.md inline without writing it; orchestrator persisted the file.`
+2. If it is MISSING or invalid AND the synthesizer's return message contains the FULL SUMMARY.md document — recognizable by the template's top-level markers `# Project Research Summary`, `## Key Findings`, `## Implications for Roadmap`, and `## Sources`, not merely the brief `## SYNTHESIS COMPLETE` confirmation — the false-refusal fired: write that returned document to `.planning/research/SUMMARY.md` with the Write tool, then commit ALL research artifacts the synthesizer owns (it commits on behalf of the four researchers) with `pp_run query commit "docs(planning): complete project research" --files .planning/research/` unless they are already committed. Log `⚠ #222 self-heal: synthesizer returned SUMMARY.md inline without writing it; orchestrator persisted the file.`
 3. If it is MISSING or invalid AND the return is only a brief confirmation (no full SUMMARY document to recover), the synthesizer genuinely failed — surface the error and stop; do NOT spawn `pp-roadmapper` against a missing or incomplete SUMMARY.md.
 
 This guarantees `pp-roadmapper` (which lists SUMMARY.md as required reading) never runs against a missing or truncated SUMMARY.md.
@@ -456,7 +458,7 @@ If "adjust": Return to scoping.
 
 **Commit requirements:**
 ```bash
-pp_run query commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
+pp_run query commit "docs(planning): define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
 ```
 
 ## 10. Create Roadmap
@@ -542,7 +544,7 @@ Success criteria:
 
 **Commit roadmap** (after approval):
 ```bash
-pp_run query commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+pp_run query commit "docs(planning): create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
 ```
 
 ## 10.5. Link Pending Todos to Roadmap Phases
@@ -551,6 +553,7 @@ After roadmap approval, scan pending todos against the newly approved phases. Fo
 
 **Check for pending todos:**
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 PENDING_TODOS=$(ls .planning/todos/pending/*.md 2>/dev/null | head -50)
 ```
 
@@ -585,7 +588,8 @@ files: [existing]
 
 **If any todos were linked:**
 ```bash
-pp_run query commit "docs: tag [count] pending todos with resolves_phase after milestone v[X.Y] roadmap" --files .planning/todos/pending/*.md
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
+pp_run query commit "docs(planning): tag [count] pending todos with resolves_phase after milestone v[X.Y] roadmap" --files .planning/todos/pending/*.md
 ```
 
 Print a summary: