@poetic-ai/poetic 1.42.0

package/templates/guard-kit/GUARD_SETUP.md.template

@@ -0,0 +1,255 @@
+# Poetic Guard setup playbook (kit version {{KIT_VERSION}})
+
+## What this is
+
+This file is the PATH; `poetic guard verify` is the GROUND TRUTH. Follow these
+steps, in order, until `poetic guard verify` reports `configured` (all local and
+GitHub criteria pass) or `proven-gated` (a live rejection was also witnessed).
+Re-run `poetic guard verify` after every step and let its scorecard — not this
+document — tell you what is still missing.
+
+This file is generated by Poetic. It is overwritten on every
+`poetic init --guardrails` install/upgrade/reinstall. It is NOT hash-tracked, so
+you may annotate it freely without tripping a tamper check, but your notes are
+lost on the next upgrade — keep durable notes elsewhere.
+
+## The criteria (C1..C7)
+
+`poetic guard verify` evaluates seven criteria, in order. Order is load-bearing:
+later criteria depend on earlier ones (C5/C6 need the check identity from C4 and
+the remote default branch from C2; C7 needs the identity from C4).
+
+| ID | Meaning (one line) |
+|----|--------------------|
+| C1 | Kit installed and untampered (`.poetic/guard/` present, hashes match the lock). |
+| C2 | Gate present on the remote default branch (`check.mjs` committed on `main`). |
+| C3 | Local gate actually gates (self-test: the committed `check.mjs` rejects a planted violation). |
+| C4 | A single gate-check identity is derivable from your workflows (one job, correct triggers, no `continue-on-error`). |
+| C5 | That check is green on the CURRENT default-branch head sha (not just "ever green"). |
+| C6 | Branch protection (or a ruleset) REQUIRES that check context, ideally with up-to-date-branch strictness. |
+| C7 | Witnessed live rejection: a canary PR was actually blocked by the check (the proof). |
+
+### Verdict ladder
+
+- `not-gated` — a criterion in C1..C6 hard-FAILED, or a canary was NOT rejected
+  (C7 fail). `poetic guard verify` exits 1.
+- `partially-gated` — no hard failure, but at least one C1..C6 criterion is a
+  `gap` (could not be verified: missing `gh`, no network, opaque ruleset
+  semantics, or skipped via a flag). Exits 3.
+- `configured` — C1..C6 all pass. C7 may be a gap. This is the normal "the gate
+  is wired and required" target. Exits 0.
+- `proven-gated` — C1..C6 all pass AND C7 passes (a canary was witnessed being
+  rejected). The strongest verdict. Exits 0.
+
+A criterion that cannot be verified is a `gap`, never a `pass` — the scorecard
+fails closed. `configured` and `proven-gated` are unreachable while any C1..C6
+criterion is a gap (for example, an uninterpretable ruleset forces C6 to a gap).
+
+## Ordered steps
+
+Do these in order. Skipping ahead — especially requiring the check (C6) before
+it has ever reported green (C5) — deadlocks every PR.
+
+### Step 1 — Install the kit (C1)
+
+```
+poetic init --guardrails
+```
+
+This renders `.poetic/guard/` (`check.mjs`, `config.json`, `checks.lock`,
+`baselines/`, and this file). Confirm C1:
+
+```
+poetic guard verify
+```
+
+C1 should read `OK: C1 Kit installed and untampered`. If it reports `absent`,
+run the install again; if `tampered`/`partial`, run
+`poetic init --guardrails --reinstall-guard`.
+
+### Step 2 — Commit the gate on a branch
+
+Create a normal working branch and commit the whole guard directory:
+
+```
+git checkout -b add-poetic-guard
+git add .poetic/guard
+git commit -m "Add Poetic guard kit"
+```
+
+The gate only works once `check.mjs` is COMMITTED — the CI trusted-base pattern
+reads it from the base branch's tree. A repo-wide `.poetic/` gitignore silently
+swallows it; make sure `.poetic/guard/check.mjs` is tracked.
+
+### Step 3 — Add the reference workflow (C4)
+
+Print the reference GitHub Actions workflow and save it:
+
+```
+poetic guard print-ci > .github/workflows/poetic-guard.yml
+```
+
+(You can also copy `poetic-guard.yml.template` from the kit and substitute the
+kit version yourself.) Adapt ONLY the CUSTOMIZE-FREELY regions marked in the
+file (runner label, timeout, optional path-filter additions). Do NOT change the
+MUST-NOT-CHANGE regions: `permissions: contents: read`, the trusted-base
+extraction, the `test -s` non-empty guard, `fetch-depth: 0`, both triggers
+(`pull_request_target` and `merge_group`), checkout of the base branch (do
+not set checkout `ref:` to the PR head), and the literal job
+`name: Poetic Guard` (that name is the required status-check context).
+Commit it alongside the gate.
+
+### Step 4 — Land the gate + workflow on the default branch (C2, C5)
+
+Open a PR from your branch and merge it into the default branch through your
+normal flow. This satisfies C2 (gate present on the default branch) and lets the
+workflow run once on the new default-branch head.
+
+### Step 5 — Confirm one green run on the default-branch head (C5)
+
+After the merge, wait for the "Poetic Guard" check to complete on the
+default-branch head, then:
+
+```
+poetic guard verify
+```
+
+C5 passes only when the check is green on the CURRENT head sha (not merely "once
+green"). If C5 is a gap saying the check "has never reported on the current
+default-branch head", the run has not landed yet — wait and re-run. DO NOT
+require the check until C5 passes (Step 6 warns why).
+
+For a PR head that remains "Expected — Waiting for status", diagnose the exact
+SHA without changing the C1..C7 verdict:
+
+```
+poetic guard verify --head-sha <40-character-head-sha>
+```
+
+The diagnostic distinguishes absent, queued, running, completed, and stale-head
+state. If an open PR still has no event or app-bound check after 15 minutes,
+close and reopen that PR to retrigger the native `pull_request_target`
+workflow on the same SHA. Do not publish a replacement check manually; the
+GitHub Actions-owned workflow remains the only attestation producer.
+
+### Step 6 — Require the check in branch protection (C6)
+
+ONLY after C5 is green. Requiring a check that has never reported deadlocks every
+PR ("Expected — Waiting for status" forever). Require the exact context string
+`Poetic Guard` with up-to-date-branch strictness.
+
+UI path: Repository Settings -> Branches (or Rules -> Rulesets) -> the default
+branch rule -> "Require status checks to pass before merging" -> add
+`Poetic Guard` -> also enable "Require branches to be up to date before merging".
+
+Exact `gh` command (classic branch protection; replace `OWNER/REPO` and
+`main`):
+
+```
+gh api -X PUT repos/OWNER/REPO/branches/main/protection \
+  -H "Accept: application/vnd.github+json" \
+  -F 'required_status_checks[strict]=true' \
+  -F 'required_status_checks[contexts][]=Poetic Guard' \
+  -F 'enforce_admins=true' \
+  -F 'required_pull_request_reviews=' \
+  -F 'restrictions='
+```
+
+Strictness matters: without "up to date before merging" a PR can merge green
+against a stale base and break the gate on the new head (the stale-green-merge
+race). Re-run `poetic guard verify`; C6 should pass and the verdict should reach
+`configured`.
+
+### Step 7 — Optional live proof canary (C7)
+
+This upgrades `configured` to `proven-gated` by WITNESSING a real rejection.
+
+1. Branch: `git checkout -b poetic-guard-canary/<date>` (the
+   `poetic-guard-canary/` prefix lets `poetic guard verify` auto-discover it).
+2. Add a file whose path matches an artifact deny glob (see
+   `defaultDenyPaths` / `extraDenyPaths`) — for example a committed
+   `dist/` build output. NEVER use a secret-shaped string: push protection would
+   reject the push and page your security team, and the point is to test the
+   gate, not the platform.
+3. Open it as a DRAFT PR. Expect the "Poetic Guard" check to FAIL within
+   minutes. If it PASSES, your gate is broken — return to Step 3 and check the
+   workflow's trusted-base extraction and triggers.
+4. Close the PR UNMERGED (never merge a canary).
+5. Prove it:
+
+   ```
+   poetic guard verify --canary-pr <n>
+   ```
+
+   With C1..C6 already passing, C7 now passes and the verdict is `proven-gated`.
+
+## Exit-code contracts
+
+The gate (`check.mjs`, run in CI):
+
+- `0` — clean.
+- `1` — a HARD finding (secret in an added line, a denied artifact path, or a
+  baseline inflation). Blocks the merge.
+- `2` — ONLY guard-machinery changed under `.poetic/guard/` and no hard finding.
+  Softer than 1 (a shrink-only baseline change is exempt and stays 0), but the
+  reference workflow still blocks on it: it means "a human should review the
+  gate change." Legitimate kit-upgrade PRs are the expected exit-2 case. A hard
+  finding always dominates, so exit 1 wins when both are present.
+
+`poetic guard verify` (the scorecard):
+
+- `0` — `configured` or `proven-gated`.
+- `3` — `partially-gated` (at least one unverifiable gap, no hard failure).
+- `1` — `not-gated` (a criterion failed, or a canary was not rejected).
+
+## Troubleshooting
+
+| Scorecard message (paraphrased) | Next action |
+|---------------------------------|-------------|
+| C1 state is `absent` | Run `poetic init --guardrails`. |
+| C1 state is `tampered`/`partial` | Run `poetic init --guardrails --reinstall-guard`; `config.json` is preserved. |
+| C2 gate not on the default branch | Merge the branch from Step 2 to the default branch (Step 4). |
+| C3 self-test could not run / skipped via `--no-selftest` | Run in a full checkout with Node >= 24; drop `--no-selftest`. |
+| C4 "no GitHub Actions workflows found" | Add the workflow from Step 3 (`poetic guard print-ci`). |
+| C4 flags `continue-on-error` / missing trigger / dead extraction | Fix the workflow's MUST-NOT-CHANGE regions; do not soften the gate. |
+| C5 "has never reported on the current default-branch head" | Let the check run once on the default-branch head (Step 5); do not require it yet. |
+| C5 "not green ... latest conclusion: failure" | Investigate the failing run; the gate found a real problem or the workflow is misconfigured. |
+| C6 "does not require 'Poetic Guard'" | Require the context in branch protection / a ruleset (Step 6). |
+| C6 "strict ... enforcement is OFF" | Enable "Require branches to be up to date before merging" / `strict_required_status_checks_policy=true`. |
+| C6 "semantics could not be fully interpreted" | Inspect the ruleset with the `gh api` command shown; a merge-queue-only ruleset with no visible required checks reads as a gap. |
+| C7 "no canary proof recorded" | Run the Step 7 canary (an artifact-path violation, never a secret), or pass `--canary-pr <n>`. |
+| C7 "was merged — the gate did not block it" | The gate did not reject the canary: it is broken. Return to Step 3. |
+
+## Optional patterns
+
+### Two-context split for automerge teams
+
+If you want routine PRs to automerge but still block on gate-machinery changes,
+split the single check into two contexts: one required check that runs the gate
+and treats only hard findings (exit 1) as failing, and a second required check
+(or a `CODEOWNERS`-gated review) for guard-directory changes (exit 2). Require
+both; automation may merge when the hard-finding context is green while
+exit-2 PRs still wait for a human. Keep the trusted-base extraction in both.
+
+### Baseline seeding (dormant today)
+
+The gate ships a baseline anti-inflation engine and an `--update-baseline` flag,
+but it is DORMANT: no count-producing scanners exist yet, so `baselines/` stays
+empty and `--update-baseline` only creates the directory and prints a notice. Do
+not seed baselines by hand — the flag becomes active only when count scanners
+ship in a later kit phase.
+
+## Non-GitHub CI
+
+The trusted-base pattern is portable. On another CI platform, replicate the
+reference workflow's shell step: fail closed (`set -euo pipefail`), fetch the
+base branch, `git show base:.poetic/guard/check.mjs > "$PRIVATE_TMP/guard-check.mjs"`
+(use a private per-run temp path, never a predictable shared `/tmp` filename),
+`test -s` it, then run it with `POETIC_GUARD_DIR="$PWD/.poetic/guard"`. Enforce
+the equivalent of a required, up-to-date status check in your platform's
+merge-protection settings.
+
+Criteria C5, C6, and C7 use the GitHub API (via `gh`) and will report `gap` off
+GitHub, so `configured`/`proven-gated` are unreachable there — that is expected,
+not a failure. Rely on the local criteria (C1..C4) plus your platform's own
+equivalents of the green-run, required-check, and rejection-proof gates.