@lannguyensi/harness 0.48.0 → 0.50.0

package/dist/runtime/workflow-policies.d.ts

@@ -0,0 +1,164 @@
+import type { Manifest, Policy, Workflow } from "../schema/index.js";
+/**
+ * Runtime enforcement for `workflows:` (99f47307, Slice 1).
+ *
+ * `manifest.workflows[]` describes a review-then-merge process (schema:
+ * `src/schema/workflows.ts`), but until now nothing read it at
+ * enforcement time: `src/runtime/intercept.ts` (the Risk Gate / policy
+ * engine `harness policy intercept` runs on every PreToolUse) only ever
+ * evaluates `manifest.policies[]`. A `workflows:` declaration alone was
+ * documentation, not a gate (`docs/for-agents.md`, pre-Slice-1 wording:
+ * "The schema cannot enforce that today").
+ *
+ * This module closes that gap for exactly ONE step pairing: a
+ * `review_subagent` step with `spawn: "required"` followed (at any
+ * later index in the same workflow) by a `merge` step. When BOTH
+ * `require-review-evidence` and `require-review-evidence-bash` are
+ * declared in `manifest.hooks[]`, `deriveWorkflowGatePolicies` returns
+ * the SAME policy pair `harness init --template full` would hand-author
+ * (`src/cli/init/templates.ts` `review-before-merge` /
+ * `review-before-merge-bash`), renamed per workflow so the provenance
+ * is visible in `harness list policies` / `harness explain`.
+ *
+ * Deliberately does NOT touch `src/runtime/intercept.ts`: the engine
+ * already knows how to evaluate a `Policy`, so the only thing missing
+ * was a `Policy` to hand it. `src/cli/loader.ts#loadManifest` calls
+ * `withDerivedPolicies` after parsing and appends the result to
+ * `manifest.policies` before any consumer (the CLI `policy intercept`
+ * entrypoint, `list`, `explain`, `explain-policy`) reads it.
+ *
+ * TWO VIEWS OF ONE MANIFEST (review round 3, 99f47307 Slice 1). Every
+ * reader of a parsed manifest sees exactly one of:
+ *
+ * - the HAND-AUTHORED view: `parseManifest(...)` as-is, only what the
+ *   operator wrote under `policies:`. Right for anything that writes a
+ *   manifest back to disk or serialises it for later comparison
+ *   (`harness export`, the `.last-apply` manifest snapshot, `add` /
+ *   `remove` / `adopt` / `pack reseed` file rewrites, the schema gate in
+ *   `io/validate-before-write.ts`), because a derived policy written out
+ *   as if hand-authored would be re-derived on top of itself next time.
+ *   `withoutDerivedPolicies` turns a derived view back into this one.
+ * - the DERIVED view: `withDerivedPolicies(parseManifest(...))`, hand-
+ *   authored policies plus the workflow gate pair. Right for enforcement
+ *   (`policy intercept`, hook entrypoints), validation (`validate`,
+ *   `doctor`, `add`'s asset gate), display (`list`, `explain[-policy]`,
+ *   `describe`, `dry-run`), and every COMPARISON where the other side is
+ *   also derived (`diff --since` ref side vs working side; the
+ *   `.last-apply` snapshot vs the current manifest in restart hints).
+ *   `loadManifest` hands out this view; the few readers that parse
+ *   without it (`validate`, `diff`'s ref side, `apply`'s snapshot
+ *   reader, `add`'s gate) call `withDerivedPolicies` themselves.
+ *
+ * Both helpers are idempotent and accept either view as input (they
+ * partition on `isDerivedPolicy`), so a reader can never "double derive"
+ * or strip a hand-authored policy by calling them on the wrong view.
+ * Review rounds 1 and 2 each found one reader on the wrong side of this
+ * line (`apply` vs `validate`; `diff --since`'s two sides); the table
+ * above plus tests/cli/manifest-view-parity.test.ts are the guard.
+ *
+ * Fail direction: when the two evidence hooks are NOT wired, this
+ * returns `[]` for every workflow rather than deriving an
+ * unenforceable policy (there would be no hook name to bind it to, and
+ * `manifest.policies[].hook` must reference a declared hook, see
+ * `ManifestSchema`'s superRefine in `src/schema/index.ts`). That silent
+ * non-enforcement case is exactly what `checkWorkflowGateWiring`
+ * (`src/cli/validate/checks.ts`) turns into a loud `validate` error, so
+ * "declared `spawn: required`, gate never wired" cannot pass silently.
+ */
+/** The two hooks templates.ts wires for the hand-authored merge gate. */
+export declare const REVIEW_EVIDENCE_HOOK_MCP = "require-review-evidence";
+export declare const REVIEW_EVIDENCE_HOOK_BASH = "require-review-evidence-bash";
+export declare const MERGE_MCP_MATCH = "mcp__agent-tasks__pull_requests_merge";
+export declare const MERGE_BASH_MATCH = "(^|\\n|;|\\||&|\\()\\s*(\\w+=\\S+\\s+)*gh pr merge\\b";
+/**
+ * True when `workflow.steps` contains a `review_subagent` step with
+ * `spawn: "required"` at an index earlier than some `merge` step
+ * (not necessarily adjacent; a `ci_gate` or another step may sit
+ * between them). A workflow with no `merge` step at all, or whose only
+ * `review_subagent` steps are `spawn: "optional"` / `"skip"`, returns
+ * `false`.
+ */
+export declare function workflowRequiresMergeGate(workflow: Workflow): boolean;
+/** True when both merge-gate evidence hooks are declared in `manifest.hooks[]`. */
+export declare function hasWiredMergeGateHooks(manifest: Manifest): boolean;
+/** True when `policy` is an object this module derived (see `withDerivedPolicies`). */
+export declare function isDerivedPolicy(policy: Policy): boolean;
+/**
+ * The hand-authored slice of `manifest.policies`: everything the operator
+ * wrote under `policies:`, none of the workflow-derived entries. Works on
+ * either view (see module doc); on a hand-authored view it is the
+ * identity.
+ */
+export declare function handAuthoredPolicies(manifest: Manifest): Policy[];
+/** One weaker hand-authored policy sharing a derived gate's trigger surface. */
+export interface WeakGatePolicyOverlap {
+    /** The workflow whose `spawn: "required"` step derives the gate. */
+    workflowName: string;
+    /** Name of the derived policy that is ALSO in force (`workflow:<name>:review-before-merge[-bash]`). */
+    derivedPolicyName: string;
+    /** Human-readable surface label for the message (`mcp__agent-tasks__pull_requests_merge` or `` `gh pr merge` (Bash) ``). */
+    surface: string;
+    /** The weaker hand-authored policy's name. */
+    handPolicyName: string;
+    /** Why it does not stand in for the derived gate (see `nonEquivalenceReason`). */
+    reason: string;
+}
+/**
+ * Derive the merge-gate `Policy` pair for every workflow that needs one
+ * and does not already have an equivalent policy (hand-authored, or
+ * derived from an earlier workflow in the same manifest) intercepting
+ * the same surface for the same evidence tag.
+ *
+ * Returns `[]` when `manifest.hooks[]` is missing either evidence hook
+ * (see module doc: that gap is a `validate` error, not silent
+ * derivation of an unenforceable policy) or when no workflow declares
+ * a `spawn: "required"` review step followed by a merge step.
+ */
+export declare function deriveWorkflowGatePolicies(manifest: Manifest): Policy[];
+/**
+ * Every hand-authored policy that shares an ACTUALLY DERIVED gate's
+ * trigger surface + ledger_tag but does not stand in for it: weaker
+ * (F1, review round 2) or extracting its variables differently (F4,
+ * review round 3). Both policies apply in that case, and the overlap is
+ * worth flagging: an operator reading `enforcement: warn` on a
+ * `two-reviewers-required`-shaped policy might reasonably believe THAT
+ * is the only gate on the surface. `src/cli/validate/checks.ts` turns
+ * each entry into a warning Diagnostic; `src/cli/doctor/index.ts`
+ * renders the same list in the Workflows section.
+ *
+ * Mirrors `deriveWorkflowGatePolicies` exactly (same walk, same `seen`
+ * set): a surface an equivalent hand-authored policy already covers
+ * derives nothing and therefore reports nothing, even when a second,
+ * weaker policy sits on it too. Returns `[]` when the evidence hooks are
+ * not wired or no workflow needs a gate.
+ */
+export declare function findWeakGatePolicyOverlaps(manifest: Manifest): WeakGatePolicyOverlap[];
+/**
+ * The ONE place `workflows[]` gets folded into `manifest.policies` (F2,
+ * review round 2). Before this, `src/cli/loader.ts#loadManifest` inlined
+ * the append, so every OTHER manifest consumer that parses the manifest
+ * a different way (`src/cli/validate/index.ts`'s `loadMergedRaw` +
+ * `parseManifest`, notably) saw a manifest with no derived policies at
+ * all, and `apply` and `validate` diverged. See the module doc for the
+ * full list of readers and which view each one takes.
+ *
+ * Idempotent and view-agnostic (review round 3): the derivation runs on
+ * `handAuthoredPolicies(manifest)` only and any derived entries already
+ * present are replaced, so calling this on an already-derived view yields
+ * the same policy names with no duplicates. Returns the input object
+ * unchanged when there is nothing to derive and nothing to replace.
+ *
+ * Registers each derived `Policy` object in the module-level
+ * `derivedPolicyRegistry` (F7) so `isDerivedPolicy` can later distinguish
+ * it from a hand-authored one (used by `harness export`'s filter and
+ * `list`/`doctor`'s "(derived from workflows[])" marker).
+ */
+export declare function withDerivedPolicies(manifest: Manifest): Manifest;
+/**
+ * The hand-authored view of a manifest that may carry derived policies:
+ * what `harness export` emits and what the `.last-apply` manifest
+ * snapshot stores, so nothing that gets written out or re-read later
+ * carries a derived policy as if the operator had declared it. Returns
+ * the input object unchanged when it carries no derived policy.
+ */
+export declare function withoutDerivedPolicies(manifest: Manifest): Manifest;

package/dist/runtime/workflow-policies.js

@@ -0,0 +1,439 @@
+/**
+ * Runtime enforcement for `workflows:` (99f47307, Slice 1).
+ *
+ * `manifest.workflows[]` describes a review-then-merge process (schema:
+ * `src/schema/workflows.ts`), but until now nothing read it at
+ * enforcement time: `src/runtime/intercept.ts` (the Risk Gate / policy
+ * engine `harness policy intercept` runs on every PreToolUse) only ever
+ * evaluates `manifest.policies[]`. A `workflows:` declaration alone was
+ * documentation, not a gate (`docs/for-agents.md`, pre-Slice-1 wording:
+ * "The schema cannot enforce that today").
+ *
+ * This module closes that gap for exactly ONE step pairing: a
+ * `review_subagent` step with `spawn: "required"` followed (at any
+ * later index in the same workflow) by a `merge` step. When BOTH
+ * `require-review-evidence` and `require-review-evidence-bash` are
+ * declared in `manifest.hooks[]`, `deriveWorkflowGatePolicies` returns
+ * the SAME policy pair `harness init --template full` would hand-author
+ * (`src/cli/init/templates.ts` `review-before-merge` /
+ * `review-before-merge-bash`), renamed per workflow so the provenance
+ * is visible in `harness list policies` / `harness explain`.
+ *
+ * Deliberately does NOT touch `src/runtime/intercept.ts`: the engine
+ * already knows how to evaluate a `Policy`, so the only thing missing
+ * was a `Policy` to hand it. `src/cli/loader.ts#loadManifest` calls
+ * `withDerivedPolicies` after parsing and appends the result to
+ * `manifest.policies` before any consumer (the CLI `policy intercept`
+ * entrypoint, `list`, `explain`, `explain-policy`) reads it.
+ *
+ * TWO VIEWS OF ONE MANIFEST (review round 3, 99f47307 Slice 1). Every
+ * reader of a parsed manifest sees exactly one of:
+ *
+ * - the HAND-AUTHORED view: `parseManifest(...)` as-is, only what the
+ *   operator wrote under `policies:`. Right for anything that writes a
+ *   manifest back to disk or serialises it for later comparison
+ *   (`harness export`, the `.last-apply` manifest snapshot, `add` /
+ *   `remove` / `adopt` / `pack reseed` file rewrites, the schema gate in
+ *   `io/validate-before-write.ts`), because a derived policy written out
+ *   as if hand-authored would be re-derived on top of itself next time.
+ *   `withoutDerivedPolicies` turns a derived view back into this one.
+ * - the DERIVED view: `withDerivedPolicies(parseManifest(...))`, hand-
+ *   authored policies plus the workflow gate pair. Right for enforcement
+ *   (`policy intercept`, hook entrypoints), validation (`validate`,
+ *   `doctor`, `add`'s asset gate), display (`list`, `explain[-policy]`,
+ *   `describe`, `dry-run`), and every COMPARISON where the other side is
+ *   also derived (`diff --since` ref side vs working side; the
+ *   `.last-apply` snapshot vs the current manifest in restart hints).
+ *   `loadManifest` hands out this view; the few readers that parse
+ *   without it (`validate`, `diff`'s ref side, `apply`'s snapshot
+ *   reader, `add`'s gate) call `withDerivedPolicies` themselves.
+ *
+ * Both helpers are idempotent and accept either view as input (they
+ * partition on `isDerivedPolicy`), so a reader can never "double derive"
+ * or strip a hand-authored policy by calling them on the wrong view.
+ * Review rounds 1 and 2 each found one reader on the wrong side of this
+ * line (`apply` vs `validate`; `diff --since`'s two sides); the table
+ * above plus tests/cli/manifest-view-parity.test.ts are the guard.
+ *
+ * Fail direction: when the two evidence hooks are NOT wired, this
+ * returns `[]` for every workflow rather than deriving an
+ * unenforceable policy (there would be no hook name to bind it to, and
+ * `manifest.policies[].hook` must reference a declared hook, see
+ * `ManifestSchema`'s superRefine in `src/schema/index.ts`). That silent
+ * non-enforcement case is exactly what `checkWorkflowGateWiring`
+ * (`src/cli/validate/checks.ts`) turns into a loud `validate` error, so
+ * "declared `spawn: required`, gate never wired" cannot pass silently.
+ */
+/** The two hooks templates.ts wires for the hand-authored merge gate. */
+export const REVIEW_EVIDENCE_HOOK_MCP = "require-review-evidence";
+export const REVIEW_EVIDENCE_HOOK_BASH = "require-review-evidence-bash";
+// Exported (review round 2, F5) so `src/cli/validate/checks.ts` can check a
+// declared hook's `match`/`bash_match` against the EXACT surface the
+// derivation binds to, instead of trusting the hook name alone. See
+// `checkWorkflowGateWiring`'s header for the "right name, wrong trigger"
+// gap this closes.
+export const MERGE_MCP_MATCH = "mcp__agent-tasks__pull_requests_merge";
+// Byte-identical to templates.ts's `review-before-merge-bash` trigger
+// (verified against the parsed FULL_TEMPLATE at authoring time; pinned
+// by tests/runtime/workflow-policies.test.ts's parity assertion so the
+// two cannot silently drift apart).
+export const MERGE_BASH_MATCH = "(^|\\n|;|\\||&|\\()\\s*(\\w+=\\S+\\s+)*gh pr merge\\b";
+/**
+ * True when `workflow.steps` contains a `review_subagent` step with
+ * `spawn: "required"` at an index earlier than some `merge` step
+ * (not necessarily adjacent; a `ci_gate` or another step may sit
+ * between them). A workflow with no `merge` step at all, or whose only
+ * `review_subagent` steps are `spawn: "optional"` / `"skip"`, returns
+ * `false`.
+ */
+export function workflowRequiresMergeGate(workflow) {
+    let sawRequiredReview = false;
+    for (const step of workflow.steps) {
+        if (step.kind === "review_subagent" && step.spawn === "required") {
+            sawRequiredReview = true;
+        }
+        else if (step.kind === "merge" && sawRequiredReview) {
+            return true;
+        }
+    }
+    return false;
+}
+/** True when both merge-gate evidence hooks are declared in `manifest.hooks[]`. */
+export function hasWiredMergeGateHooks(manifest) {
+    const hookNames = new Set(manifest.hooks.map((h) => h.name));
+    return hookNames.has(REVIEW_EVIDENCE_HOOK_MCP) && hookNames.has(REVIEW_EVIDENCE_HOOK_BASH);
+}
+/**
+ * Canonical key for "does this policy intercept the same surface for the
+ * same evidence?": event + match + bash_match + requires.ledger_tag. Two
+ * policies sharing this key fire on the identical event for the identical
+ * ledger tag, so the derivation treats a hand-authored policy with this
+ * key as a CANDIDATE for standing in for the derived gate. Whether it
+ * actually does is decided by `isEquivalentToDerivedGate` below: it must
+ * also extract its template variables the same way (F4, review round 3)
+ * and be at least as strong (F1, review round 2).
+ */
+function triggerSurfaceKey(policy) {
+    return JSON.stringify({
+        event: policy.trigger.event,
+        match: policy.trigger.match ?? null,
+        bash_match: policy.trigger.bash_match ?? null,
+        ledger_tag: policy.requires?.ledger_tag ?? null,
+    });
+}
+/**
+ * Canonical form of `trigger.extract` for equality: key-sorted so two
+ * maps that declare the same variables from the same paths compare equal
+ * regardless of authoring order. `null` when the policy extracts nothing.
+ *
+ * F4 (review round 3): `extract` was NOT part of the dedupe key before,
+ * so a hand-authored block policy on the derived surface that extracted
+ * `PR_NUMBER` from a WRONG path (say `toolArgs.pr` instead of
+ * `toolArgs.prNumber`) counted as equivalent, suppressed the derived
+ * gate, and then evaluated its own `review:${PR_NUMBER}` against an
+ * unresolved variable. Under `risk.degraded_fail_posture: fail_open` that
+ * is an allow with "template variables unresolved": the merge went
+ * through with no review evidence at all. A differently-extracting policy
+ * no longer dedupes: the derived gate is produced as well, both apply,
+ * and `findWeakGatePolicyOverlaps` names the mismatch.
+ */
+function extractKey(policy) {
+    const extract = policy.trigger.extract;
+    if (extract === undefined)
+        return null;
+    const sorted = {};
+    for (const key of Object.keys(extract).sort()) {
+        const value = extract[key];
+        if (value !== undefined)
+            sorted[key] = value;
+    }
+    return JSON.stringify(sorted);
+}
+/**
+ * True when a hand-authored policy sharing the derived gate's trigger
+ * surface + ledger_tag is strong enough to stand in for it: `enforcement:
+ * "block"`, no `when:` risk/environment scoping, and not `operator_only:
+ * true` (which carries no `requires:`/ledger_tag at all, so it would not
+ * normally share a key, but the check is defensive since operator_only
+ * would otherwise read as "block" and pass the enforcement check alone).
+ *
+ * F1 (review round 2, 99f47307 Slice 1): before this, `triggerSurfaceKey`
+ * alone decided dedupe, so a hand-authored `enforcement: "warn"` policy
+ * (or a `block` policy scoped down via `when:` to only some environments)
+ * on the identical surface silently suppressed the derived BLOCK gate: a
+ * `spawn: "required"` workflow step that LOOKED enforced actually
+ * degraded to warn-only, or to unenforced outside the `when:` scope,
+ * with no diagnostic anywhere. A weaker match no longer dedupes: the
+ * derived block gate is ALSO produced (both apply), and
+ * `findWeakGatePolicyOverlaps` surfaces the overlap so validate/doctor
+ * can flag it instead of leaving it silent.
+ */
+function isAtLeastAsStrongAsDerivedGate(policy) {
+    return (policy.enforcement === "block" &&
+        policy.when === undefined &&
+        policy.operator_only !== true);
+}
+/**
+ * Why `policy` does NOT qualify as at-least-as-strong (see
+ * `isAtLeastAsStrongAsDerivedGate`), in a form suitable for a diagnostic
+ * message. `null` when the policy DOES qualify (nothing weak to report).
+ */
+function weaknessReason(policy) {
+    if (isAtLeastAsStrongAsDerivedGate(policy))
+        return null;
+    if (policy.enforcement !== "block")
+        return `enforcement: ${policy.enforcement}`;
+    if (policy.when !== undefined)
+        return "when: (risk/environment-scoped)";
+    if (policy.operator_only === true)
+        return "operator_only: true";
+    return "weaker than a plain block gate";
+}
+/**
+ * Why a hand-authored policy on the derived gate's surface does NOT stand
+ * in for it, or `null` when it does (same surface, same extract, at least
+ * as strong). Strength is reported before an extract mismatch: a warn
+ * policy with a wrong extract path is first and foremost a warn policy.
+ */
+function nonEquivalenceReason(handPolicy, derivedGate) {
+    const weakness = weaknessReason(handPolicy);
+    if (weakness !== null)
+        return weakness;
+    const handExtract = extractKey(handPolicy);
+    const gateExtract = extractKey(derivedGate);
+    if (handExtract !== gateExtract) {
+        return `trigger.extract differs (${handExtract ?? "none"} vs derived ${gateExtract ?? "none"})`;
+    }
+    return null;
+}
+function buildMcpMergeGatePolicy(workflowName) {
+    return {
+        name: `workflow:${workflowName}:review-before-merge`,
+        description: `Derived from workflows[] (workflow "${workflowName}"): a review_subagent step ` +
+            `with spawn: "required" precedes a merge step, so block PR merges unless a ` +
+            "ledger entry tagged review:<pr-number> exists for this session.",
+        trigger: {
+            event: "PreToolUse",
+            match: MERGE_MCP_MATCH,
+            extract: { PR_NUMBER: "toolArgs.prNumber" },
+        },
+        requires: { ledger_tag: "review:${PR_NUMBER}" },
+        hook: REVIEW_EVIDENCE_HOOK_MCP,
+        enforcement: "block",
+        producers: [
+            {
+                kind: "mcp",
+                verb: "mcp__grounding-mcp__ledger_add",
+                example: '{sessionId:"${SESSION_ID}", type:"fact", content:"review:${PR_NUMBER}: <verdict + key findings + nits>", source:"Agent(general-purpose) review"}',
+                description: "Spawn a review subagent against the PR diff, capture its verdict, then persist a ledger entry tagged with the PR number. The content should be self-contained enough for an auditor to read without re-opening the chat.",
+            },
+        ],
+        ux: {
+            cannot: "You cannot merge PR #${PR_NUMBER} yet.",
+            required: ["a recorded review of PR #${PR_NUMBER}"],
+            run: ['harness record review --pr ${PR_NUMBER} "<summary>"'],
+        },
+    };
+}
+function buildBashMergeGatePolicy(workflowName) {
+    return {
+        name: `workflow:${workflowName}:review-before-merge-bash`,
+        description: `Derived from workflows[] (workflow "${workflowName}"): a review_subagent step ` +
+            'with spawn: "required" precedes a merge step, so block `gh pr merge` unless a ' +
+            "ledger entry tagged review:<branch> exists for this session.",
+        trigger: {
+            event: "PreToolUse",
+            match: "Bash",
+            bash_match: MERGE_BASH_MATCH,
+        },
+        requires: { ledger_tag: "review:${BRANCH}" },
+        hook: REVIEW_EVIDENCE_HOOK_BASH,
+        enforcement: "block",
+        producers: [
+            {
+                kind: "mcp",
+                verb: "mcp__grounding-mcp__ledger_add",
+                example: '{sessionId:"${SESSION_ID}", type:"fact", content:"review:${BRANCH}: <verdict + key findings + nits>", source:"Agent(general-purpose) review"}',
+                description: "Spawn a review subagent against the branch diff, capture its verdict, then persist a ledger entry tagged with the branch name. Mirror of the review-before-merge producer for the gh-cli surface.",
+            },
+        ],
+        ux: {
+            cannot: "You cannot merge the PR for branch ${BRANCH} via `gh pr merge` yet.",
+            required: ["a recorded review of the PR for branch ${BRANCH}"],
+            run: ['harness record review --pr <pr> "<summary>"'],
+        },
+    };
+}
+// F7 (review round 2): a registry of every `Policy` object this module has
+// ever handed back from `deriveWorkflowGatePolicies`. `WeakSet` keys on
+// object identity, not value equality, deliberately: two DIFFERENT
+// workflows can derive value-identical-looking policies with different
+// names, and a hand-authored policy could theoretically share a derived
+// policy's exact shape too (nothing stops an operator hand-copying one
+// into `policies:`). Identity is the only unambiguous "did THIS module
+// produce THIS object" test. `harness export`/`list`/`doctor` use
+// `isDerivedPolicy` to distinguish "declared by the operator" from
+// "derived from workflows[]" without re-deriving and re-comparing.
+const derivedPolicyRegistry = new WeakSet();
+/** True when `policy` is an object this module derived (see `withDerivedPolicies`). */
+export function isDerivedPolicy(policy) {
+    return derivedPolicyRegistry.has(policy);
+}
+/**
+ * The hand-authored slice of `manifest.policies`: everything the operator
+ * wrote under `policies:`, none of the workflow-derived entries. Works on
+ * either view (see module doc); on a hand-authored view it is the
+ * identity.
+ */
+export function handAuthoredPolicies(manifest) {
+    return manifest.policies.filter((p) => !isDerivedPolicy(p));
+}
+/**
+ * The ONE walk that decides, per qualifying workflow and per surface,
+ * whether a gate is derived and which hand-authored policies overlap it.
+ * `deriveWorkflowGatePolicies` and `findWeakGatePolicyOverlaps` are both
+ * projections of this result, so they cannot disagree about what was
+ * derived (F1, review round 3: the overlap finder used to re-implement
+ * the walk without the `seen` set, and warned about a "derived" gate that
+ * a strong hand-authored policy had in fact suppressed).
+ *
+ * Only HAND-authored policies feed the walk (`handAuthoredPolicies`), so
+ * the result is the same whether the input is the hand-authored or the
+ * derived view.
+ */
+function deriveWorkflowGates(manifest) {
+    const empty = { policies: [], overlaps: [] };
+    if (!hasWiredMergeGateHooks(manifest))
+        return empty;
+    const hand = handAuthoredPolicies(manifest);
+    const bySurface = new Map();
+    for (const policy of hand) {
+        const key = triggerSurfaceKey(policy);
+        const bucket = bySurface.get(key);
+        if (bucket)
+            bucket.push(policy);
+        else
+            bySurface.set(key, [policy]);
+    }
+    // Surfaces already covered: by an equivalent hand-authored policy (F1 +
+    // F4: at least as strong AND extracting the same way), or by a gate an
+    // earlier workflow in this same manifest already derived.
+    const seen = new Set();
+    const derived = [];
+    const overlaps = [];
+    for (const workflow of manifest.workflows) {
+        if (!workflowRequiresMergeGate(workflow))
+            continue;
+        const candidates = [
+            { policy: buildMcpMergeGatePolicy(workflow.name), surface: MERGE_MCP_MATCH },
+            { policy: buildBashMergeGatePolicy(workflow.name), surface: "`gh pr merge` (Bash)" },
+        ];
+        for (const { policy: candidate, surface } of candidates) {
+            const key = triggerSurfaceKey(candidate);
+            if (seen.has(key))
+                continue;
+            const sharing = bySurface.get(key) ?? [];
+            const reasons = sharing.map((hp) => ({
+                handPolicy: hp,
+                reason: nonEquivalenceReason(hp, candidate),
+            }));
+            if (reasons.some((r) => r.reason === null)) {
+                // An equivalent hand-authored policy already gates this surface;
+                // nothing is derived, so there is nothing to overlap with either.
+                seen.add(key);
+                continue;
+            }
+            derived.push(candidate);
+            seen.add(key);
+            for (const { handPolicy, reason } of reasons) {
+                if (reason === null)
+                    continue;
+                overlaps.push({
+                    workflowName: workflow.name,
+                    derivedPolicyName: candidate.name,
+                    surface,
+                    handPolicyName: handPolicy.name,
+                    reason,
+                });
+            }
+        }
+    }
+    return { policies: derived, overlaps };
+}
+/**
+ * Derive the merge-gate `Policy` pair for every workflow that needs one
+ * and does not already have an equivalent policy (hand-authored, or
+ * derived from an earlier workflow in the same manifest) intercepting
+ * the same surface for the same evidence tag.
+ *
+ * Returns `[]` when `manifest.hooks[]` is missing either evidence hook
+ * (see module doc: that gap is a `validate` error, not silent
+ * derivation of an unenforceable policy) or when no workflow declares
+ * a `spawn: "required"` review step followed by a merge step.
+ */
+export function deriveWorkflowGatePolicies(manifest) {
+    return deriveWorkflowGates(manifest).policies;
+}
+/**
+ * Every hand-authored policy that shares an ACTUALLY DERIVED gate's
+ * trigger surface + ledger_tag but does not stand in for it: weaker
+ * (F1, review round 2) or extracting its variables differently (F4,
+ * review round 3). Both policies apply in that case, and the overlap is
+ * worth flagging: an operator reading `enforcement: warn` on a
+ * `two-reviewers-required`-shaped policy might reasonably believe THAT
+ * is the only gate on the surface. `src/cli/validate/checks.ts` turns
+ * each entry into a warning Diagnostic; `src/cli/doctor/index.ts`
+ * renders the same list in the Workflows section.
+ *
+ * Mirrors `deriveWorkflowGatePolicies` exactly (same walk, same `seen`
+ * set): a surface an equivalent hand-authored policy already covers
+ * derives nothing and therefore reports nothing, even when a second,
+ * weaker policy sits on it too. Returns `[]` when the evidence hooks are
+ * not wired or no workflow needs a gate.
+ */
+export function findWeakGatePolicyOverlaps(manifest) {
+    return deriveWorkflowGates(manifest).overlaps;
+}
+/**
+ * The ONE place `workflows[]` gets folded into `manifest.policies` (F2,
+ * review round 2). Before this, `src/cli/loader.ts#loadManifest` inlined
+ * the append, so every OTHER manifest consumer that parses the manifest
+ * a different way (`src/cli/validate/index.ts`'s `loadMergedRaw` +
+ * `parseManifest`, notably) saw a manifest with no derived policies at
+ * all, and `apply` and `validate` diverged. See the module doc for the
+ * full list of readers and which view each one takes.
+ *
+ * Idempotent and view-agnostic (review round 3): the derivation runs on
+ * `handAuthoredPolicies(manifest)` only and any derived entries already
+ * present are replaced, so calling this on an already-derived view yields
+ * the same policy names with no duplicates. Returns the input object
+ * unchanged when there is nothing to derive and nothing to replace.
+ *
+ * Registers each derived `Policy` object in the module-level
+ * `derivedPolicyRegistry` (F7) so `isDerivedPolicy` can later distinguish
+ * it from a hand-authored one (used by `harness export`'s filter and
+ * `list`/`doctor`'s "(derived from workflows[])" marker).
+ */
+export function withDerivedPolicies(manifest) {
+    const hand = handAuthoredPolicies(manifest);
+    const derivedPolicies = deriveWorkflowGatePolicies(manifest);
+    if (derivedPolicies.length === 0 && hand.length === manifest.policies.length)
+        return manifest;
+    for (const policy of derivedPolicies)
+        derivedPolicyRegistry.add(policy);
+    return { ...manifest, policies: [...hand, ...derivedPolicies] };
+}
+/**
+ * The hand-authored view of a manifest that may carry derived policies:
+ * what `harness export` emits and what the `.last-apply` manifest
+ * snapshot stores, so nothing that gets written out or re-read later
+ * carries a derived policy as if the operator had declared it. Returns
+ * the input object unchanged when it carries no derived policy.
+ */
+export function withoutDerivedPolicies(manifest) {
+    const hand = handAuthoredPolicies(manifest);
+    if (hand.length === manifest.policies.length)
+        return manifest;
+    return { ...manifest, policies: hand };
+}
+//# sourceMappingURL=workflow-policies.js.map

package/dist/runtime/workflow-policies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-policies.js","sourceRoot":"","sources":["../../src/runtime/workflow-policies.ts"],"names":[],"mappings":"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"}