Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions .agents/skills/gsd-loop-review/scripts/sync-outcomes.mjs
Original file line number Diff line number Diff line change
@@ -1,14 +1,18 @@
#!/usr/bin/env node

import { existsSync } from "node:fs";
import { existsSync, readFileSync } from "node:fs";
import { fileURLToPath, pathToFileURL } from "node:url";

const sourceModule = fileURLToPath(new URL("../../../../lib/outcomes.mjs", import.meta.url));
const bundledModule = fileURLToPath(new URL("./runtime/outcomes.mjs", import.meta.url));
const modulePath = existsSync(bundledModule) ? bundledModule : sourceModule;
const { parseOutcomeArguments, syncIssueOutcomes } = await import(pathToFileURL(modulePath));
const { fingerprintContract, parseOutcomeArguments, syncIssueOutcomes } = await import(pathToFileURL(modulePath));

try {
if (process.argv[2] === "fingerprint") {
console.log(fingerprintContract(readFileSync(0, "utf8")));
process.exit(0);
}
const options = parseOutcomeArguments(process.argv.slice(2));
const changed = syncIssueOutcomes({ cwd: process.cwd(), ...options });
const state = changed ? options.state : `already ${options.state}`;
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
/.memdb/
14 changes: 7 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ global skill directory.
| `gsd:ready` | human | merge (issue closes) | Approved for the build queue |
| `gsd:blocked` | builder | human | One specific question awaits an answer |
| `gsd:rework` | reviewer | builder or reviewer | Verdict has blocking findings |
| `gsd:approved` | reviewer | reviewer on a new head or blocking verdict | Evidence complete and issue outcomes checked; merge is yours |
| `gsd:approved` | reviewer | reviewer under the [approval invalidation rules](loop/review.md#choose-what-to-audit) | Evidence complete and issue outcomes checked; merge is yours |
| `gsd:escalated` | either | human | Out of automation until a human resolves it |

## Quick start
Expand Down Expand Up @@ -106,7 +106,7 @@ the support matrix, and recovery.

## Your four duties

The loop is deliberately incapable of doing these:
The playbooks reserve these actions for humans:

1. Apply `gsd:ready` after reading a filed issue — nothing builds without it.
2. Answer `gsd:blocked` questions, then remove the label.
Expand Down Expand Up @@ -137,11 +137,11 @@ for the exact publisher settings and procedure.

## Design notes

- **One head and linked issue, one verdict.** Trusted verdict comments open
with `gsd-loop verdict for <sha> issue #<number>`; that head-and-issue pair
is never re-audited, and crashed passes repair issue checkboxes and labels
from the existing verdict instead. New commits invalidate checked outcomes
until the new head is independently approved.
- **One head, linked issue, and contract version, one verdict.** Trusted
verdicts identify the commit, issue number, and issue-body fingerprint.
Crashed passes repair checkboxes and labels from matching evidence.
New commits or contract edits require a fresh review. Outcome checkbox
changes alone preserve the fingerprint.
- **Crash-anywhere recovery.** The builder reconstructs state from git and
GitHub (dirty trees, orphaned `gsd/NNN-*` branches, stale claims) rather
than from memory, so a pass can die on any line without wedging the queue.
Expand Down
15 changes: 14 additions & 1 deletion lib/outcomes.mjs
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { createHash } from "node:crypto";
import { BlockedError, UsageError } from "./errors.mjs";
import { checked, parseJson, runProcess } from "./process.mjs";

Expand Down Expand Up @@ -32,12 +33,16 @@ export function parseOutcomeArguments(values) {
for (let index = 0; index < options.length; index += 1) {
const option = options[index];
const value = options[index + 1];
if (!["--repo", "--pr", "--head"].includes(option) || !value || value.startsWith("--")) {
if (!["--repo", "--pr", "--head", "--contract"].includes(option) || !value || value.startsWith("--")) {
throw new UsageError(`invalid outcomes option: ${option ?? ""}`.trim());
}
if (option === "--repo") parsed.repo = value;
if (option === "--pr") parsed.pullRequest = Number(value);
if (option === "--head") parsed.expectedHead = value;
if (option === "--contract") {
if (!/^[0-9a-f]{64}$/.test(value)) throw new UsageError("--contract requires SHA256");
parsed.expectedContract = value;
}
index += 1;
}
if (!Number.isInteger(parsed.issue) || parsed.issue < 1) {
Expand Down Expand Up @@ -120,6 +125,10 @@ export function transformOutcomeChecklist(body, state) {
return lines.join("\n");
}

export function fingerprintContract(body) {
return createHash("sha256").update(transformOutcomeChecklist(body, "pending")).digest("hex");
}

function pullRequestEvidence({ cwd, repo, pullRequest, run }) {
const output = checked("gh", [
"pr", "view", String(pullRequest),
Expand Down Expand Up @@ -184,12 +193,16 @@ export function syncIssueOutcomes({
issue,
pullRequest,
expectedHead,
expectedContract,
state,
run = runProcess,
}) {
const options = { cwd, repo, issue, pullRequest, expectedHead, run };
assertExpectedPullRequest(options);
const original = issueBody(options);
if (expectedContract !== undefined && fingerprintContract(original) !== expectedContract) {
throw new BlockedError(`issue #${issue} contract changed; verdict evidence is stale`);
}
const updated = transformOutcomeChecklist(original, state);
if (updated === original) {
assertExpectedPullRequest(options);
Expand Down
6 changes: 4 additions & 2 deletions loop/build.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,8 +127,10 @@ pushes run from there — the main tree never changes branches.
- A verdict's first line must pin both its SHA and linked issue as
`gsd-loop verdict for COMMIT_SHA issue #ISSUE`; ignore comments by any other
author or pinned to another issue.
- Trusted verdict SHA already matches the head? The label outlived its verdict
(fixes were pushed but the label removal died). Re-fetch the final PR head as
- Trusted verdict SHA matches the head? Its blocking findings still apply.
Keep `gsd:rework` and continue with the repair below.
- Trusted verdict SHA differs from the head? New commits need review.
Re-fetch the final PR head as
`HEAD_SHA` and run
`node LINKAGE_SYNC ISSUE --repo OWNER/REPO --pr NUMBER --head HEAD_SHA`.
Only after that guard passes, drop `gsd:rework`, stop — the reviewer will take
Expand Down
59 changes: 44 additions & 15 deletions loop/review.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,36 +44,60 @@ gh api graphql --paginate --slurp \
}' > PR_EVIDENCE
```

Resolve current linkage before interpreting the trail. Search every comment
Resolve current linkage and fetch the current issue body before interpreting
any verdict. Save the exact body for this audit and fingerprint it:

```bash
gh issue view ISSUE --repo OWNER/REPO --json body | jq -j .body > ISSUE_BODY
if ! CONTRACT_SHA=$(node OUTCOME_SYNC fingerprint < ISSUE_BODY); then
CONTRACT_SHA=
fi
```

If the body cannot be read or `CONTRACT_SHA` is empty, approval has no valid
contract evidence. Before stopping, re-fetch the PR head and resolve linkage
again using "Establish the contract." Only if the head still equals `HEAD_SHA`
and the same `OWNER/REPO` issue is still linked, remove `gsd:approved` if present.
If either check fails or cannot be completed, stop without changing labels.
Report the pass as blocked with the read or validation error and whether approval
was removed. Do not synchronize outcomes, match verdicts, or audit an invalid
contract. A label removal failure also blocks the pass; never report that approval
was removed unless the command succeeded.

The fingerprint ignores outcome checkbox state but covers all other issue
content. Keep this value fixed throughout the audit. A verdict without the
matching `Contract: CONTRACT_SHA` second line is stale, including older verdicts
that have no fingerprint. Invalidate its approval and audit the current contract.

Search every comment
authored by `REVIEWER_LOGIN`, not only the last matching comment:

```bash
VERDICT_HEADER="gsd-loop verdict for HEAD_SHA issue #ISSUE"
jq --arg reviewer "$REVIEWER_LOGIN" --arg header "$VERDICT_HEADER" \
jq --arg reviewer "$REVIEWER_LOGIN" --arg header "$VERDICT_HEADER" --arg contract "Contract: $CONTRACT_SHA" \
'[.[].data.repository.pullRequest.comments.nodes[]
| select(.author.login == $reviewer and ((.body | split("\n")[0]) == $header))]' \
| select(.author.login == $reviewer and ((.body | split("\n")[0]) == $header) and ((.body | split("\n")[1]) == $contract))]' \
PR_EVIDENCE
```

- An exact first line `gsd-loop verdict for HEAD_SHA issue #ISSUE` covering
both the current head and currently linked issue means don't re-audit.
- Exact matches for both header lines above mean don't re-audit.
Synchronize that issue's outcomes to `complete` for an approved verdict or
`pending` for any blocking/escalated verdict, then reinstate whatever labels
the verdict dictates. Post nothing. A verdict pinned to another issue is
stale and must never drive repair.
- A trusted `gsd-loop linkage block for HEAD_SHA` is not a verdict. If the
issue is still unlinked, repair the linkage-block labels and post nothing.
If linkage now exists, continue to a normal audit of that SHA.
- No trusted verdict anywhere in the trail covers the current head and issue →
- No trusted verdict anywhere in the trail covers the current head, issue, and contract →
auditable. Searching the full trail prevents an A→B→A head sequence from
creating a second verdict for A.
creating a second verdict for A when the linked issue and contract are unchanged.

Never trust a marker from any other author, including one that copies the
authenticated login into its text.

Resolve the linked issue before checking CI, using the linkage rules under
"Establish the contract." For a new head, invalidate earlier outcome evidence
before auditing it:
"Establish the contract." For a new head or changed contract, invalidate earlier
outcome evidence before auditing it:

```bash
node OUTCOME_SYNC ISSUE pending --repo OWNER/REPO --pr NUMBER --head HEAD_SHA
Expand All @@ -90,7 +114,8 @@ changes only `O-N` checkboxes in `## Outcomes`. GitHub has no conditional
Update Issue mutation, so an edit in the narrow interval between the final
pre-write body check and `gh issue edit` can still be overwritten; the
immediate post-write check detects many such races but cannot make the update
atomic. If the command is unavailable or fails, report the pass as blocked;
atomic. If the command is unavailable or fails, use the same guarded approval
removal described at the contract-read boundary, then report the pass as blocked;
never edit the issue body with an ad-hoc text transform. After it succeeds,
re-fetch the head and remove `gsd:approved`; a changed head stops the pass
before label mutation. Missing `gsd:approved` is a no-op. If this changes the
Expand Down Expand Up @@ -256,6 +281,7 @@ One comment via `gh pr comment NUMBER --body-file`:

```md
gsd-loop verdict for COMMIT_SHA issue #ISSUE
Contract: CONTRACT_SHA

Required CI: passing | failing | none configured
Merge state: <mergeStateStatus verbatim — CLEAN, DIRTY, BEHIND, BLOCKED, ...>
Expand Down Expand Up @@ -301,13 +327,16 @@ Immediately after posting the verdict and before changing labels, synchronize
the linked issue against the same head SHA. An approval checks every outcome:

```bash
node OUTCOME_SYNC ISSUE complete --repo OWNER/REPO --pr NUMBER --head HEAD_SHA
node OUTCOME_SYNC ISSUE complete --repo OWNER/REPO --pr NUMBER --head HEAD_SHA --contract CONTRACT_SHA
```

Any blocking or escalated verdict uses `pending` instead. If synchronization
fails after the comment is posted, stop without changing labels and report the
pass as blocked. The next pass recognizes the reviewer-authored
SHA-and-issue-pinned verdict anywhere in the trail and repairs the checklist
Use the same `--contract CONTRACT_SHA` guard when repairing an existing verdict.
Any blocking or escalated verdict uses `pending` instead, with the same guard.
If synchronization fails after posting a verdict or while repairing an existing
verdict, use the same guarded approval removal described at the contract-read
boundary, then report the pass as blocked. Do not apply the verdict's labels.
The next pass recognizes the reviewer-authored
SHA-, issue-, and contract-pinned verdict anywhere in the trail and repairs the checklist
and labels without posting a second verdict. After every synchronization,
re-fetch `headRefOid` once more before changing labels; a head change stops the
pass with no label mutation.
Expand Down
33 changes: 33 additions & 0 deletions tests/outcomes_test.mjs
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
import { spawnSync } from "node:child_process";
import assert from "node:assert/strict";
import {
fingerprintContract,
parseOutcomeArguments,
syncIssueOutcomes,
transformOutcomeChecklist,
Expand Down Expand Up @@ -398,3 +400,34 @@ assert.throws(
);

console.log("outcome checklist synchronization passed");

// A verdict for an older contract must not complete the current issue.
assert.throws(() => syncIssueOutcomes({
cwd: "/tmp/project", repo: "octocat/project", issue: 1, pullRequest: 2,
expectedHead: "abc123", state: "complete", expectedContract: "0".repeat(64),
run: noOpRun,
}), /contract changed/);

const contract = fingerprintContract(issueBody);
assert.equal(contract, fingerprintContract(transformOutcomeChecklist(issueBody, "complete")));
for (const amended of [
issueBody.replace("## Exclusions", "- [ ] O-3 — new requirement\n\n## Exclusions"),
issueBody.replace("no delete command", "no network access"),
]) {
assert.notEqual(fingerprintContract(amended), contract);
}
assert.equal(syncIssueOutcomes({
cwd: "/tmp/project", repo: "octocat/project", issue: 1, pullRequest: 2,
expectedHead: "abc123", state: "complete", expectedContract: contract,
run: noOpRun,
}), false);
assert.equal(parseOutcomeArguments([
"1", "complete", "--repo", "octocat/project", "--pr", "2", "--head", "abc1234",
"--contract", contract,
]).expectedContract, contract);
const fingerprintCommand = spawnSync(process.execPath, [
new URL("../.agents/skills/gsd-loop-review/scripts/sync-outcomes.mjs", import.meta.url).pathname,
"fingerprint",
], { input: issueBody, encoding: "utf8" });
assert.equal(fingerprintCommand.status, 0, fingerprintCommand.stderr);
assert.equal(fingerprintCommand.stdout.trim(), contract);
4 changes: 0 additions & 4 deletions tests/playbook_contract_test.sh
Original file line number Diff line number Diff line change
Expand Up @@ -82,11 +82,7 @@ grep -q 'never create a duplicate' "$BUILD"
grep -q 'leave the worktree in place' "$BUILD"

repair_section=$(sed -n '/^## Repair queue takes priority/,/^## Choose an issue/p' "$BUILD")
recovery_section=$(printf '%s\n' "$repair_section" |
sed -n '/Trusted verdict SHA already matches/,/Can.t check out the branch/p')
printf '%s\n' "$repair_section" | grep -q 'dependency manifest or lockfile'
printf '%s\n' "$recovery_section" |
grep -q 'node LINKAGE_SYNC ISSUE --repo OWNER/REPO --pr NUMBER --head HEAD_SHA'
if printf '%s\n' "$repair_section" | grep -q 'issue contract or repository guidance'; then
echo 'dependency audits must not depend on an opt-in issue contract' >&2
exit 1
Expand Down
Loading