@lannguyensi/harness 0.63.0 → 1.0.0

package/dist/policy-packs/builtin/post-merge-gate-runtime.d.ts

@@ -1,286 +0,0 @@
-export declare const PACK_NAME = "post-merge-gate";
-/**
- * Content prefix the producer writes and the blocker substring-matches.
- * The full recorded content is
- * `${MERGED_TAG_PREFIX}:${repo}:${branch}:${sha}[ pr:<n>] at:<iso>`; the
- * blocker only ever tests for the `${MERGED_TAG_PREFIX}:${repo}:${branch}:
- * ${sha}` prefix (an exact 40-hex-char sha), so the trailing `pr:` / `at:`
- * tokens are audit decoration, not part of the match key.
- */
-export declare const MERGED_TAG_PREFIX = "post-merge-gate:merged";
-/** The exact substring the blocker tests ledger entries for. */
-export declare function mergedTagMatchKey(repo: string, branch: string, sha: string): string;
-/** Build the full fact content the producer writes (match key + audit decoration). */
-export declare function buildMergedTagContent(args: {
-    repo: string;
-    branch: string;
-    sha: string;
-    pr: string | null;
-    whenIso: string;
-}): string;
-/**
- * Producer trigger: does this Bash command look like a `gh pr merge`
- * invocation? Same anchoring convention as `DEFAULT_PUSH_BASH_RE`
- * (solution-acceptance-runtime.ts): tolerates a leading `cd … &&`, inline
- * `VAR=val` assignments, and chaining. Known gap, same class as that
- * regex's own documented residual: a heredoc / `sh -c` / `eval`
- * indirection defeats this match before the producer ever runs — not
- * attempted to close here (the MCP merge path, `pull_requests_merge`, is
- * the other documented gap; see the pack's instructions.md).
- *
- * Task 76671e5a: bare `&` added to the boundary alternation (`&&` kept to
- * its left only to mirror `src/runtime/command-normalize.ts`'s alternation
- * order for readability — NOT because order is load-bearing here, unlike
- * that module). Same fix as `d834a065` applied to every policy trigger —
- * bash starts a new command after a single `&`, so `A=x&gh pr merge` used
- * to miss this trigger entirely and the producer silently never recorded
- * the merged-tip fact for that spelling. Broadening a TRIGGER only widens
- * when the producer fires (a strictly safer direction, mirrors the
- * deny-side reasoning below), unlike the escape allowlist further down.
- * Measured: swapping to `&|&&` produces a byte-identical match set for this
- * matcher (a `RegExp.test` existential check over every start offset, not a
- * segmenter — the reasoning that makes order matter in
- * `command-normalize.ts`'s `BOUNDARY_RE`/`AMP_BOUNDARY_RE` does not transfer
- * to a plain `.test()` matcher like this one).
- *
- * The RECORDER (`hook-post-merge-gate-record.ts`) does not test this regex
- * against the raw command alone: it tests it against four forms, raw first
- * and lazily, mirroring the gate's `policyMatchesEvent` arms (raw,
- * `normalizeCommand`, `normalizeCommandAmpAware`,
- * `normalizeCommandQuoteAware`). The regex itself stays anchored for the
- * raw form, so wrapper spellings (`nice gh pr merge 1`), a bare-`&` chain
- * before a wrapper and a quoted assignment value holding a boundary
- * character are matched via the normalised forms, not by this pattern.
- * Named residual: a command longer than MAX_NORMALIZE_LENGTH is not
- * normalised and is tested raw only.
- */
-export declare const GH_PR_MERGE_BASH_RE: RegExp;
-/**
- * Blocker deny-scope v1 (03-decisions.md): the curated mutation command
- * list. Deliberately NOT "every Bash command" — read-only git
- * (status/log/diff/branch) and unrelated shell stay unaffected. Same
- * anchoring convention as `GH_PR_MERGE_BASH_RE`.
- *
- * Task 76671e5a: bare `&` added to the boundary alternation, same reasoning
- * as `GH_PR_MERGE_BASH_RE` above — this is a DENY-scope matcher, so
- * broadening it is the STRICTER direction (more commands recognized as
- * curated mutations, none dropped). Verified disjoint from the escape
- * allowlist below on a single-command corpus (no verb overlap), so this
- * broadening cannot lock out the documented recovery path.
- */
-export declare const CURATED_MUTATION_BASH_RE: RegExp;
-/**
- * Escape allowlist, git verbs (03-decisions.md): the exact recovery path
- * the deny message recommends, plus read-only stash inspection. Since task
- * 19356be7 this list no longer short-circuits the blocker — the deny
- * match decides gate-eligibility, and every one of these verbs stays free
- * simply because it is not a curated mutation (verb disjointness, pinned).
- * The list remains the deny message's recovery vocabulary and a
- * diagnostics aid.
- *
- * Task 76671e5a, DELIBERATELY LEFT on the old (no bare-`&`) boundary
- * alphabet: this is an ALLOW-side matcher, so broadening it is the LOOSER
- * direction. Its remaining consumers (diagnostics, docs interpolation)
- * still must not silently widen what reads as "recovery". Pinned by a
- * regression test asserting this regex's source never gains the `&|`
- * boundary token.
- */
-export declare const ESCAPE_GIT_BASH_RE: RegExp;
-/**
- * Escape allowlist, harness verbs (03-decisions.md): names any invocation
- * of harness's own CLI (recovery commands like `harness session-start
- * branch-check`, diagnostics, a future self-check), regardless of
- * spelling — mirrors the `npx` / absolute-path / `./node_modules/.bin`
- * robustness the `deny-kill-switch-bash` regex in
- * `src/cli/init/templates.ts` already established for the same class of
- * bypass concern. Since task 19356be7 its only job is the deny message's
- * / diagnostics' vocabulary: a bare harness command stays free through
- * verb disjointness with the curated deny list, not through a
- * short-circuit.
- *
- * Task 76671e5a: DELIBERATELY LEFT narrow, same reasoning as
- * `ESCAPE_GIT_BASH_RE` immediately above — an allow-side matcher, so
- * broadening its boundary alphabet is the loosening direction.
- */
-export declare const ESCAPE_HARNESS_BASH_RE: RegExp;
-/**
- * True when `command` matches any escape pattern. Since task 19356be7
- * this is DIAGNOSTICS ONLY — the blocker's decision is
- * `isGateEligibleCommand` below; when escape and deny both match, deny
- * wins. (Under the original escape-first ordering this function was the
- * blocker's first, unconditional check, which let `harness preflight &&
- * git push origin master` — the documented normal workflow — skip the
- * gate entirely.)
- */
-export declare function isEscapeCommand(command: string): boolean;
-/** True when `command` matches the curated v1 deny-scope. */
-export declare function isCuratedMutationCommand(command: string): boolean;
-/**
- * The blocker's single classification entry point (task 19356be7): a
- * command is gate-eligible iff the curated mutation matcher fires.
- * Everything else — the whole recovery vocabulary, read-only git,
- * unrelated shell — is allowed by the hook BEFORE any manifest load or
- * ledger query, preserving the recovery-never-starved property the
- * escape-first ordering used to provide.
- *
- * A thin wrapper over `isCuratedMutationCommand` by DELIBERATE choice,
- * not by accident. An earlier iteration of this task pre-processed the
- * command here, stripping the bodies of quoted-delimiter heredocs fed to
- * a harness invocation, so that an `harness approve understanding <<'…'`
- * report body mentioning a mutation verb would not become gate-eligible.
- * Two review rounds found two successive families of UNDER-blocks in that
- * pre-processing (bodies consumed that bash really executes), both rooted
- * in the same cause: deciding where a heredoc body BEGINS requires
- * re-implementing bash's quote and word grammar on the permissive side of
- * a security boundary. Tasks `dbc6d303` and `5b1b24fb` had already been
- * halted for that same reason. It was therefore removed rather than
- * patched a third time; see
- * `.ai/runs/2026-08-02-post-merge-gate-escape-precedence/03-decisions.md`
- * D5/D6 for the measurement history, and task `5b1b24fb` for the real
- * fix, which belongs at the `bash_match` layer for every surface at once.
- *
- * Accepted consequence, OVER-block direction: a harness report heredoc
- * whose body carries a boundary-anchored mutation verb IS gate-eligible.
- * It only denies while the branch tip equals a recorded merged tip, and
- * `git switch <default>` — the gate's own recommended recovery — stays
- * free. Same residual class as the quoted-text false positives this
- * change already accepts. Do NOT reintroduce a strip here without a
- * design that does not re-derive bash's grammar.
- */
-export declare function isGateEligibleCommand(command: string): boolean;
-/**
- * Defensive `tool_output.exit_code` reader for the PostToolUse Bash
- * payload — Contract A. Returns `null` on ANY shape other than a plain
- * finite number — missing field, a differently-named variant, a string,
- * etc. — so the producer's "no fact on anything but a confirmed success"
- * rule (03-decisions.md) degrades to "no fact" rather than guessing.
- *
- * PAYLOAD REALITY (2026-07, follow-up to 03-decisions.md): live
- * verification against a real Claude Code 2.1.218 native install (a
- * `claude -p --settings` dump-hook capture, 19/19 fired events) found NO
- * `tool_output` field at all — the field is `tool_response`, shaped
- * `{ stdout, stderr, interrupted, isImage, noOutputExpected }` with no
- * exit-code equivalent (see `tests/fixtures/post-merge-gate/
- * real-posttooluse-payload-2.1.218.json`, a verbatim capture). The
- * `tool_output.stdout/stderr/exit_code` shape this function reads
- * evidently describes a DIFFERENT — newer, or differently-shimmed —
- * Claude Code contract than 2.1.218's, not a documentation error to
- * "fix" here: Contract A is left exactly as it was (any install that
- * DOES send `tool_output.exit_code` still works unchanged), and Contract
- * B below is the fallback that makes the producer fire on 2.1.218 at
- * all. See `resolveMergeConfirmation`.
- */
-export declare function extractExitCode(toolOutput: unknown): number | null;
-/** Best-effort PR number extraction from a `gh pr merge` command string. */
-export declare function extractPrNumber(command: string): string | null;
-/**
- * Contract B success-text matcher (2.1.218 payload-reality follow-up).
- * `gh pr merge`'s own past-tense confirmation sentence, verbatim across
- * all three merge methods.
- *
- * SOURCE (verified against the installed `gh` binary, v2.94.0,
- * `pkg/cmd/pr/merge/merge.go` lines 369-376): the success line is built
- * as `infof("%s %s pull request %s#%d (%s)", icon, action,
- * ghrepo.FullName(baseRepo), pr.Number, pr.Title)` — i.e. the repo
- * FULLNAME sits directly between "pull request" and the bare `#<n>`,
- * GLUED to the `#` with no space (`%s#%d`, not `%s #%d`):
- *
- *   ✓ Squashed and merged pull request owner/repo#65 (Some title)
- *   ✓ Rebased and merged pull request owner/repo#65 (Some title)
- *   ✓ Merged pull request owner/repo#65 (Some title)
- *
- * `infof` writes to `gh`'s STDERR (the informational-message channel,
- * distinct from `gh`'s own stdout, which is reserved for machine-
- * consumable output) — another reason this matcher tests the CONCATENATED
- * `stdout`+`stderr`, not stdout alone. `icon` is a bare `✓` (or `!` for
- * warnings) with no ANSI color codes when `gh` detects a non-TTY output
- * stream, which a hook-captured Bash hijacks it into.
- *
- * `[^\s#]*` between "pull request" and `#` accepts BOTH that real
- * `owner/repo#<n>` shape AND a bare `#<n>` (no fullname) — the latter is
- * not `gh`'s actual current wording but is accepted defensively as a
- * documentation-shape / future-`gh`-version tolerance, at zero matching-
- * surface cost (repo fullnames never contain whitespace or `#`, so the
- * character class cannot itself widen what counts as a match beyond
- * "some non-space run immediately before the PR number").
- *
- * Still deliberately narrow overall (conservative — false negatives are
- * the safe direction here, false positives are not):
- *   - exact past-tense phrase, not a bare "merged" substring — excludes
- *     `gh pr merge --auto`'s pending text (real wording, same source
- *     file: "Pull request owner/repo#65 will be automatically merged via
- *     squash when all requirements are met" — capitalized standalone
- *     "Pull request", no "Squashed/Rebased and merged" or standalone
- *     "Merged" immediately precedes it), and excludes the already-merged
- *     warning (real wording: "Pull request owner/repo#65 was already
- *     merged" — word order is reversed: "Pull request ... was already
- *     merged", not "Merged pull request ...").
- *   - case-sensitive, matching gh's own capitalization exactly (no `/i`)
- *     — narrower matching surface, same conservative direction.
- *   - `\b` word boundaries on both ends so a partial-word coincidence
- *     (e.g. a hypothetical "ReMerged") cannot match.
- *
- * KNOWN GAP (documented, not attempted to close here): this is coupled
- * to `gh`'s current wording. A future `gh` release that rephrases its
- * success sentence makes this matcher — and therefore the whole
- * Contract-B path — silently, fail-safely inert (no fact written, same
- * as any other unmatched shape; never a false "merged" record). See the
- * pack's instructions.md / docs/policy-packs/post-merge-gate.md "Known
- * gaps" for the operator-facing verification path.
- */
-export declare const GH_MERGE_SUCCESS_RE: RegExp;
-export type GhMergeSuccessMatch = {
-    matched: true;
-    pr: string | null;
-} | {
-    matched: false;
-};
-/**
- * Contract B confirmation: does `toolResponse` carry a real Claude Code
- * 2.1.218-shaped Bash result (`{ stdout, stderr, interrupted, ... }`)
- * whose `stdout`+`stderr` contain a `gh pr merge` success sentence?
- *
- * `interrupted` must be the LITERAL boolean `false` — missing, `true`,
- * or any other value all fail closed (no match), the same fail-safe
- * direction as Contract A's exit_code check. `stdout`/`stderr` default
- * to `""` when absent or non-string (never throws), and are joined with
- * a newline before matching so a phrase cannot accidentally form by
- * concatenating the tail of one stream with the head of the other.
- */
-export declare function matchGhMergeSuccessText(toolResponse: unknown): GhMergeSuccessMatch;
-export interface MergeConfirmation {
-    confirmed: boolean;
-    /** Which contract produced the verdict; "none" when `confirmed` is false. */
-    contract: "exit_code" | "gh_success_text" | "none";
-    /** Resolved PR number (command-first; text-fallback only for gh_success_text), or null. */
-    pr: string | null;
-    /** Human-readable reason, always populated (feeds the producer's stderr diagnostic). */
-    reason: string;
-}
-/**
- * Dual-contract merge confirmation (2.1.218 payload-reality follow-up).
- * Tries Contract A (`tool_output.exit_code`, unchanged) first; falls
- * back to Contract B (`tool_response` + a matching `gh` success
- * sentence) only when Contract A yields no verdict at all.
- *
- * BINDING ordering decision — Contract A wins whenever it resolves to
- * ANY definite verdict, success OR failure: a well-formed, non-zero
- * `exit_code` is Contract A's own explicit failure signal and short-
- * circuits WITHOUT consulting Contract B, so a coincidental gh success
- * phrase sitting in a sibling `tool_response` field (the hypothetical
- * "both present" shape) can never override an authoritative failure.
- * Contract B is consulted only when `exit_code` is entirely unresolvable
- * (`extractExitCode` returns `null` — missing field, wrong shape, or the
- * field genuinely absent as on 2.1.218).
- */
-export declare function resolveMergeConfirmation(toolOutput: unknown, toolResponse: unknown, command: string): MergeConfirmation;
-/**
- * Best-effort default-branch name for the deny message's `git switch
- * <default>` line. Offline, reusing the same `origin/HEAD` resolution
- * `harness record review --base` uses (now shared via
- * `runtime/git-context.ts`, see that module's header). Returns `null`
- * when `cwd` is not in a git work tree, or the repo has no resolvable
- * `origin/HEAD` (e.g. no remote) — the caller falls back to a generic
- * placeholder in that case; this is advisory text, never a gate input.
- */
-export declare function resolveDefaultBranchName(cwd: string): string | null;