@pareto4/pp-core 1.10.0 → 1.11.0

package/pp-core/workflows/init.md

@@ -7,7 +7,23 @@ Implements decisions: D-02 (no Obsidian/board scaffolding), D-03 (no discovery s
 scaffolding here — /pp-discovery self-generates them), D-04 (ASK handoff with smart
 default), D-06 (generic remote wiring: prompt URL → git remote add → confirmed push,
 zero provider API), D-07 (minimal identity only — no CLAUDE.md client-context block),
-D-13 (gate on .platform-bindings.json via the Phase 7 reader).
+D-13 (gate on .platform-bindings.json via the Phase 7 reader — Step 2 now composes and
+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
+**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.
 
 Inert of all Pareto/GitLab behavior when no .platform-bindings.json is present.
 </purpose>
@@ -119,61 +135,51 @@ Step 0). Continue honoring it for every `AskUserQuestion` call in this and later
 
 ---
 
-## 2. Minimal identity capture (D-07)
+## 2. Identity, provider and binding — run `pp-tools init` (D-05, D-07, INIT-01, INIT-02, INIT-03)
 
-Capture ONLY the five identity fields below. Persist them as a stub in
-`.planning/config.json` under a top-level `"project"` key, merged with any existing
-config. These fields are used by the gated GitLab provisioning path (Plan 02) for
-`group/repo-slug` and `visibility`; they do NOT produce a `CLAUDE.md` client-context
-block — that is Phase 9 (CTX-01..03) territory. Do NOT write a coding-standards,
-architecture, or DoD block here; executor and Phase 9 must not double-capture these.
-
-Ask the user with `AskUserQuestion` (or plain-text prompts in TEXT_MODE):
-
-```text
-1. Project name (human-readable, e.g. "Acme Dashboard")
-2. Project slug (kebab-case, e.g. "acme-dashboard")
-3. Client name (company / team, e.g. "Acme Corp") — type "internal" if none
-4. Client slug (kebab-case, e.g. "acme") — type "internal" if none
-5. One-line description (what this project does)
-```
-
-Also ask — used only by the gated GitLab path (D-13, Plan 02):
+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:
 
 ```text
-6. Provider (gitlab / github / other / none)
-7. Visibility (private / public / internal)
-```
-
-Write these to `.planning/config.json`:
-
-```json
-{
-  "project": {
-    "name": "<value>",
-    "slug": "<value>",
-    "client_name": "<value>",
-    "client_slug": "<value>",
-    "description": "<value>",
-    "provider": "<value>",
-    "visibility": "<value>"
-  }
-}
+pp-tools init
 ```
 
-`mkdir -p .planning` before writing if the directory does not exist.
-
-**Scope boundary:** this step writes identity 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 self-generates its own session files (D-03).
+**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.
+
+**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.
+
+**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
+self-generates its own session files (D-03).
 
 ---
 
 ## 3. Remote wiring — provider-agnostic (non-Pareto / no bindings)
 
-**Gate (D-06, D-13):** this step is the active path when
-`pp_run query platform-bindings --pick present 2>/dev/null` does NOT equal `"true"`.
-When bindings ARE present, see the gated GitLab provisioning section below instead.
+**Gate (D-06, D-13) — bindings presence ONLY, never the provider answer.** Step 3 always
+runs exactly one of its two sub-paths on every `/pp-init` invocation; it is never skipped
+outright. Take THIS generic sub-path when
+`pp_run query platform-bindings --pick present 2>/dev/null` does NOT equal `"true"`. 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.
 
 On the generic path:
 
@@ -213,17 +219,80 @@ 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 provisioning (Pareto projects — bindings present)
+### Gated GitLab/Azure 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
+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
+reconciliation; coordinates sourced one-per-value, no phantom `gitlab.*` binding reads),
+D-13 (bindings gate; `resolveProvider` is the sole authority for which path runs).
+Covers INIT-02, INIT-03, and the cross-cutting SAFE-01 invariant.
+
+#### G-1. Config reads — one source per value (D-12)
+
+Per-project values (repo slug, visibility, description) come from the `project.*` block
+Step 2 already writes to `.planning/config.json`; the org-wide group root comes from the
+org profile's init-only seed section, read through the composer's own offline probe; the
+host comes from the composed binding. **No `gitlab` namespace exists in the schema**
+(`additionalProperties: false` at the top level, no such block) or will be declared —
+declaring one would put the same value in both the binding and `.planning/config.json`, a
+fresh instance of the two-sources-of-truth class this repo has already paid for twice.
+One source per value:
+
+```bash
+GROUP=$(pp_run query compose-bindings --offline --pick seed.provisioningGroup 2>/dev/null)
+SLUG=$(pp_run query config-get project.slug --raw 2>/dev/null)
+VIS_RAW=$(pp_run query config-get project.visibility --raw 2>/dev/null)
+HOST=$(pp_run query platform-bindings --pick platform.host 2>/dev/null)
+# D-10: hard-default to private when field is absent or empty
+VIS="${VIS_RAW:-private}"
+DESC=$(pp_run query config-get project.description --raw 2>/dev/null || echo "")
+```
+
+`HOST` still defaults to `gitlab.com` in remote URLs below when empty (the existing
+`${HOST:-gitlab.com}` fallback below, unchanged). `DESC` now carries `--raw`: without it
+`config-get` returns a JSON-quoted string, so the create step's `--description "$DESC"`
+would pass the surrounding quotes through into the created project's description.
+
+**Empty-group guard (closes T-34-41).** A bare or half-empty group/slug pair is the
+personal-namespace landmine named in the security invariants below: creating with an
+empty group lands under the user's personal namespace, not the client group. When
+`GROUP` or `SLUG` is empty, print a clear line naming which one is missing and where it
+comes from, skip G-2 through G-5 entirely, and fall through to Step 3's generic remote
+wiring:
+
+```bash
+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."
+fi
+```
 
-This path runs **instead of** the generic remote-wiring path above when
-`pp_run query platform-bindings --pick present 2>/dev/null` equals `"true"`. Implements
-D-05 (per-action confirmation), D-09 (existence probe → adopt-if-exists), D-10 (private
-by default), D-11 (auth verify-only), D-12 (adopt-if-exists reconciliation), D-13
-(bindings gate). Covers INIT-02 and the cross-cutting SAFE-01 invariant.
+**Provider gate (D-11, D-13).** Read the one authority for which provisioning path runs —
+`--offline` so this never touches the network:
+
+```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."
+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`)
+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.
 
 **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.
+  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`.
@@ -233,25 +302,6 @@ by default), D-11 (auth verify-only), D-12 (adopt-if-exists reconciliation), D-1
 - 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-1. Config reads from the bindings reader (Pattern C, D-09, D-13)
-
-All values come from the Phase 7 bindings reader. **Never hardcoded.**
-
-```bash
-GROUP=$(pp_run query platform-bindings --pick gitlab.group 2>/dev/null)
-SLUG=$(pp_run query platform-bindings --pick gitlab.repo_slug 2>/dev/null)
-VIS_RAW=$(pp_run query platform-bindings --pick gitlab.visibility 2>/dev/null)
-HOST=$(pp_run query platform-bindings --pick gitlab.host 2>/dev/null)
-# D-10: hard-default to private when field is absent or empty
-VIS="${VIS_RAW:-private}"
-DESC=$(pp_run query config-get project.description 2>/dev/null || echo "")
-```
-
-The `gitlab.*` namespace is provisional — the bindings reader is lenient on unknown fields
-(it only hard-validates `schemaVersion`, `platform.repo`, and `platform.tag`). Treat any
-absent `gitlab.*` field gracefully: fall back to safe defaults, never fail hard on a
-missing key. `HOST` defaults to `gitlab.com` in remote URLs when empty.
-
 #### G-2. Auth verify-only (D-11)
 
 `/pp-init` **never establishes auth and never reads or writes the user's token.**
@@ -518,13 +568,24 @@ chosen command or stop cleanly.
 
 ## 5. Commit
 
-Commit the `.planning/config.json` identity stub created in Step 2:
+Commit the `.planning/config.json` identity stub created in Step 2. When the Step 2 session
+composed and wrote a binding (the `compose_confirm` approval), commit `.platform-bindings.json`
+in this same commit rather than a second one (D-09): being committed is what makes the
+binding outrank the profile on every later run, and leaving it untracked would leave the
+precedence story half-built while still tripping every presence gate. The file may
+legitimately not exist — the session declines or composes nothing on the inert path
+(INIT-02) — so branch explicitly rather than word-splitting an unquoted variable into
+`--files`:
 
 ```bash
-pp_run query commit "docs: initialize project" --files .planning/config.json
+if [ -f .platform-bindings.json ]; then
+  pp_run query commit "docs: initialize project" --files .planning/config.json .platform-bindings.json
+else
+  pp_run query commit "docs: initialize project" --files .planning/config.json
+fi
 ```
 
-If `.planning/config.json` is the only new file, stage only that file. If other planning
-artifacts were created (e.g. `.planning/` directory structure), include them.
+If other planning artifacts were created (e.g. `.planning/` directory structure), include
+them too.
 
 </process>

package/scripts/gen-platform-bindings-schema.cjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Generates schemas/platform-bindings.schema.json's three GENERATED values
+ * from src/platform-bindings.cts's exported constants (via the COMPILED
+ * pp-core/bin/lib/platform-bindings.cjs). Commit the result; CI re-runs the
+ * script's --check arm and fails on drift.
+ *
+ * This script owns EXACTLY three values in the schema — the JSON pointers
+ * `properties.platform.properties.repo.pattern`,
+ * `properties.client.properties.vaultRepo.pattern`, and (34-02)
+ * `properties.schemaVersion.default`. Every other field in
+ * schemas/platform-bindings.schema.json is hand-authored and must be edited
+ * by hand. `--write` additionally normalizes the whole file's JSON
+ * formatting (two-space indent, single trailing newline).
+ *
+ * BUILD ORDER: this script requires the COMPILED
+ * pp-core/bin/lib/platform-bindings.cjs, so it must run AFTER `build:lib` in
+ * the `build` npm script chain — running it before the TypeScript build
+ * would throw a missing-module error.
+ *
+ * Usage:
+ *   node scripts/gen-platform-bindings-schema.cjs              # print to stdout
+ *   node scripts/gen-platform-bindings-schema.cjs --write      # write the schema
+ *   node scripts/gen-platform-bindings-schema.cjs --check      # exit 1 if committed schema is stale
+ *   node scripts/gen-platform-bindings-schema.cjs --schema <path>  # override the target file
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const DEFAULT_SCHEMA_PATH = path.join(ROOT, 'schemas', 'platform-bindings.schema.json');
+
+const PLATFORM_REPO_POINTER = 'properties.platform.properties.repo.pattern';
+const VAULT_REPO_POINTER = 'properties.client.properties.vaultRepo.pattern';
+// 34-02: carries CONTRACT_SCHEMA_VERSION into the schema as `default`, never
+// `const`/`enum` — JSON Schema treats `default` as annotation-only, so this
+// documents the current contract without constraining validation. Using
+// `const`/`enum` here would reject every existing `1.0.0` binding and break
+// Phase 32 D-08.
+const CONTRACT_VERSION_POINTER = 'properties.schemaVersion.default';
+
+/**
+ * Two-space-indented JSON with a single trailing newline — the format the
+ * committed schema file already uses.
+ */
+function serialize(obj) {
+  return JSON.stringify(obj, null, 2) + '\n';
+}
+
+/**
+ * Build the regenerated schema object: read and parse `schemaPath`, then
+ * assign the two owned pattern values from the compiled library. Throws an
+ * ExitError if either exported pattern source is missing or empty — a
+ * silently-empty pattern written into the schema would accept everything.
+ */
+function buildSchema(schemaPath) {
+  const lib = require(path.join(ROOT, 'pp-core', 'bin', 'lib', 'platform-bindings.cjs'));
+  const { PLATFORM_REPO_PATTERN_SOURCE, VAULT_REPO_PATTERN_SOURCE, CONTRACT_SCHEMA_VERSION } = lib;
+
+  if (typeof PLATFORM_REPO_PATTERN_SOURCE !== 'string' || PLATFORM_REPO_PATTERN_SOURCE.length === 0) {
+    throw new ExitError(
+      1,
+      'pp-core/bin/lib/platform-bindings.cjs does not export a non-empty PLATFORM_REPO_PATTERN_SOURCE — ' +
+        'run `npm run build:lib` first.',
+    );
+  }
+  if (typeof VAULT_REPO_PATTERN_SOURCE !== 'string' || VAULT_REPO_PATTERN_SOURCE.length === 0) {
+    throw new ExitError(
+      1,
+      'pp-core/bin/lib/platform-bindings.cjs does not export a non-empty VAULT_REPO_PATTERN_SOURCE — ' +
+        'run `npm run build:lib` first.',
+    );
+  }
+  if (typeof CONTRACT_SCHEMA_VERSION !== 'string' || !/^\d+\.\d+\.\d+$/.test(CONTRACT_SCHEMA_VERSION)) {
+    throw new ExitError(
+      1,
+      'pp-core/bin/lib/platform-bindings.cjs does not export a semver-triplet CONTRACT_SCHEMA_VERSION — ' +
+        'run `npm run build:lib` first.',
+    );
+  }
+
+  const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+  schema.properties.platform.properties.repo.pattern = PLATFORM_REPO_PATTERN_SOURCE;
+  schema.properties.client.properties.vaultRepo.pattern = VAULT_REPO_PATTERN_SOURCE;
+  schema.properties.schemaVersion.default = CONTRACT_SCHEMA_VERSION;
+  return schema;
+}
+
+function parseSchemaPathArg(argv) {
+  const idx = argv.indexOf('--schema');
+  if (idx === -1) return DEFAULT_SCHEMA_PATH;
+  const value = argv[idx + 1];
+  if (!value) {
+    throw new ExitError(1, '--schema requires a path argument');
+  }
+  return path.resolve(value);
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const schemaPath = parseSchemaPathArg(argv);
+
+  if (argv.includes('--check')) {
+    const committed = fs.readFileSync(schemaPath, 'utf8');
+    const live = serialize(buildSchema(schemaPath));
+    if (committed !== live) {
+      const committedObj = JSON.parse(committed);
+      const liveObj = JSON.parse(live);
+      process.stderr.write(
+        schemaPath + ' is stale. The generator owns exactly three values:\n' +
+        '  ' + PLATFORM_REPO_POINTER + '\n' +
+        '  ' + VAULT_REPO_POINTER + '\n' +
+        '  ' + CONTRACT_VERSION_POINTER + '\n\n' +
+        '  ' + PLATFORM_REPO_POINTER + '\n' +
+        '    committed: ' + JSON.stringify(committedObj.properties.platform.properties.repo.pattern) + '\n' +
+        '    live:      ' + JSON.stringify(liveObj.properties.platform.properties.repo.pattern) + '\n' +
+        '  ' + VAULT_REPO_POINTER + '\n' +
+        '    committed: ' + JSON.stringify(committedObj.properties.client.properties.vaultRepo.pattern) + '\n' +
+        '    live:      ' + JSON.stringify(liveObj.properties.client.properties.vaultRepo.pattern) + '\n' +
+        '  ' + CONTRACT_VERSION_POINTER + '\n' +
+        '    committed: ' + JSON.stringify(committedObj.properties.schemaVersion.default) + '\n' +
+        '    live:      ' + JSON.stringify(liveObj.properties.schemaVersion.default) + '\n\n' +
+        'Run:\n' +
+        '  node scripts/gen-platform-bindings-schema.cjs --write' +
+        (schemaPath === DEFAULT_SCHEMA_PATH ? '' : ' --schema ' + schemaPath) +
+        '\n',
+      );
+      throw new ExitError(1);
+    }
+    process.stdout.write(schemaPath + ' is up to date.\n');
+    return;
+  }
+
+  if (argv.includes('--write')) {
+    fs.writeFileSync(schemaPath, serialize(buildSchema(schemaPath)));
+    process.stdout.write('Wrote ' + schemaPath + '\n');
+    return;
+  }
+
+  process.stdout.write(serialize(buildSchema(schemaPath)));
+}
+
+runMain(main);