Files
gstack/lib/result-codes-capy.ts
T
Garry Tanandcapy-ai[bot] 0b656a171d Check a question against the owner's earlier answers before asking it again (GST-3025) (#4467)
An agent can now check a draft question against the owner's earlier
answers before sending it, so the owner isn't asked again about
something they already said yes to.

Why: owners repeat "don't ask me, just do it" across threads, because
each new session forgets earlier answers. In a four-day sample, about 1%
of 444 asks were repeats this could skip, so a two-week pilot decides
whether it's kept.

Nothing to do: the new command is opt-in, and no existing command,
install output or factory rule changes.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Review-Finding: p1/specialist-batched#1 reader=testing
Review-Finding: p1/specialist-batched#2 reader=state-machines
Review-Finding: p1/red-team#1 reader=red-team
Review-Finding: p1/red-team#2 reader=red-team
Review-Finding: p3/outside-voice#1 reader=outside-voice
Review-Finding: p3/outside-voice#2 reader=outside-voice
2026-11-17 23:13:14 +00:00

204 lines
15 KiB
TypeScript

/**
* Result codes for gstack's Capy adaptations: the per-thread approval record
* (gstack-approvals), the Captain brief (gstack-owner-brief render --captain),
* PR screenshots (gstack-pr-shots), the installer's launch file and the Captain's pre-archive check and
* issue close on land (gstack-archive-check; R86, R91). Kept beside lib/result-codes.ts (which
* spreads this table into RESULT_CODES) so the owner module stays within the
* module-size ratchet; the same rules apply: one stable docs/troubleshooting.md
* anchor, a summary and a fix clause each.
*/
import type { ResultCode } from './result-codes';
export const CAPY_RESULT_CODES = {
APPROVAL_RECORD_INVALID: {
anchor: 'approval-record-invalid',
summary: 'an approval row is missing a required field, holds a value outside its enum, or exceeds a length cap',
fix: 'rerun gstack-approvals add with every required flag (--ask, --words, --scope, --by) inside the caps it names; nothing was written',
},
APPROVAL_RECORD_SECRET: {
anchor: 'approval-record-secret',
summary: 'a field of the approval row matched the secret scanner, so the row was refused and nothing was written',
fix: 'record the words with the secret removed (write [redacted] in its place) or ask the person to restate them; the refusal names the field and rule, never the text',
},
APPROVAL_RECORD_NO_BRANCH: {
anchor: 'approval-record-no-branch',
summary: 'the approval record is kept per branch, and HEAD is detached or this is not a git repository',
fix: 'check out the branch the work ships from, or pass --branch <name>',
},
APPROVAL_RECORD_UNAVAILABLE: {
anchor: 'approval-record-unavailable',
summary: 'no approval record exists on this machine and the state root is ephemeral with no Drive mirror, so an empty table could be a lost one',
fix: 'restore the record (copy it back from the thread report, or run on the machine that holds it), or set up the Capy Drive mirror; the section says "Record unavailable" instead of "No approvals recorded"',
},
APPROVAL_RECORD_WRITE_FAILED: {
anchor: 'approval-record-write-failed',
summary: 'the approval record or its Drive mirror could not be written',
fix: 'check the path and permission the line names (the state root must be writable), then rerun; a failed append wrote nothing',
},
APPROVAL_IMPORT_UNANSWERED: {
anchor: 'approval-import-unanswered',
summary: 'the autoplan run has no answered gate to import',
fix: 'answer the gate first (gstack-autoplan answer ... --by human|agent:<id>), then rerun the import; it is idempotent, so a retry imports nothing twice',
},
OWNER_ANSWERS_NO_DRIVE: {
anchor: 'owner-answers-no-drive',
summary: 'no owner Drive folder (user-<owner>) is mounted on this Capy machine, so there is no record to read or write',
fix: 'run from a thread the owner owns, or pass --owner <name> for a mounted user-<name> folder; until then every ask goes to the owner',
},
OWNER_ANSWERS_AMBIGUOUS: {
anchor: 'owner-answers-ambiguous',
summary: 'more than one user-* Drive folder is mounted, so the owner is not known',
fix: 'pass --owner <name> naming the owner whose record this is; nothing was read or written',
},
OWNER_ANSWERS_INVALID: {
anchor: 'owner-answers-invalid',
summary: 'a row, an ask file or a flag is missing a required value, holds a value outside its format, or exceeds a length cap',
fix: 'rerun with the flags the help names (an action and target are one lower-case token each; scope is all, repo:<owner>/<name> or captain:<name>); nothing was written',
},
OWNER_ANSWERS_SECRET: {
anchor: 'owner-answers-secret',
summary: 'a field matched the secret scanner, so the row was not written',
fix: 'remove the key, token or personal data from that field (the error names the field and rule, never the text) and rerun',
},
OWNER_ANSWERS_WRITE_FAILED: {
anchor: 'owner-answers-write-failed',
summary: 'the record directory could not be written',
fix: 'check the path gstack-owner-answers status prints and its permissions, then rerun; a failed write removed its file, and an empty file left by a crash is named by status and must be removed',
},
OWNER_ANSWERS_NOT_FOUND: {
anchor: 'owner-answers-not-found',
summary: 'no row with that id is in the owner record',
fix: 'gstack-owner-answers list --all shows every row id; rerun with one of them',
},
OWNER_ANSWERS_CONFLICT: {
anchor: 'owner-answers-conflict',
summary: 'a row for the same source, action, target and scope already records different words, author or limits, or the row named to supersede is already replaced',
fix: 'check which words the owner actually said at that source; record a correction with supersede <row id> on the current row, never a second add',
},
OWNER_ANSWERS_SELF_VERIFY: {
anchor: 'owner-answers-self-verify',
summary: 'the actor that recorded a row tried to verify it',
fix: 'a second actor reads the cited thread event and runs verify --by <its own name>; a row its recorder verified is never takeable',
},
OWNER_ANSWERS_NOT_TAKEABLE: {
anchor: 'owner-answers-not-takeable',
summary: 'a taken decision was logged against a row that cannot be taken',
fix: 'send the ask to the owner instead (log it as asked); screen only proposes rows it can take, and the detail says why this one cannot',
},
CAPTAIN_BRIEF_INCOMPLETE: {
anchor: 'captain-brief-incomplete',
summary: 'the plan lacks one or more of the sections the Captain brief needs (ELI5 on a run whose gate carries it, Before → after, Why it matters, What caused this work, Big decisions), so the brief is not ready for approval',
fix: 'add the named sections to the plan, revise the run if the plan is under review, and render again; --allow-incomplete prints a preview that still says it is not ready',
},
PR_SHOTS_INPUT_NOT_FOUND: {
anchor: 'pr-shots-input-not-found',
summary: 'a before/after input does not exist: the file, the base ref, the path at that ref, or the heading on both sides',
fix: 'check the ref, path and heading the line names (gstack-pr-shots reads tracked files and repository-local captures only)',
},
PR_SHOTS_INPUT_REFUSED: {
anchor: 'pr-shots-input-refused',
summary: 'an input was refused before rendering: it matched the secret scanner, is binary, is too large, lies outside the repository and state root, or names an option-like ref',
fix: 'remove the secret from the capture (the line names the side, line and rule, never the text), or point at a tracked text file inside the repository',
},
PR_SHOTS_IDENTICAL: {
anchor: 'pr-shots-identical',
summary: 'the before and after inputs are the same, so there is no change to picture',
fix: 'pick the file or section this change actually touched (git diff --stat origin/<base>...HEAD lists them)',
},
PR_SHOTS_RENDER_FAILED: {
anchor: 'pr-shots-render-failed',
summary: 'a browser was available but rendering shot.html failed',
fix: 'read the renderer transcript the line names; screenshot shot.html with your own browser at 880px width, or use the text fallback in text.md',
},
LAUNCH_FILE_UNWRITABLE: {
anchor: 'capy-install-launch-file-unwritable',
summary: 'the install passed but its launch file (the sourceable GSTACK_LAUNCH_FILE beside the verdict) could not be written, so the run is a fail: no caller is handed only the launch line to re-type',
fix: 'make the verdict directory under the state root writable, or set GSTACK_STATE_ROOT to a writable directory, then re-run bin/gstack-capy-install',
},
PROJECT_FLOOR_UNMET: {
anchor: 'project-floor-unmet',
summary: 'the installed gstack is below the floor the project declares (min_gstack_version in its .gstack/ship-policy.json); the row is a WARN and the trailer stays ok, because a floor is a project rule, not a security minimum',
fix: 'run the install command the row names (the Capy skill installer fast-forwards a clean checkout to origin in one step; gstack-upgrade elsewhere) before the first workflow, or lower the floor in the project',
},
PROJECT_NODE_PIN_UNMET: {
anchor: 'project-node-pin-unmet',
summary: "the Node on PATH does not satisfy the project's Node pin while every Bun pin is met; the pins row is a WARN and the trailer stays ok, because gstack runs on Bun and the project's own tests may select their Node (nvm, CI)",
fix: "put a Node that satisfies the pin first on PATH (the Capy skill installer installs an exact pin into gstack's runtime store and launches it through the GSTACK_LAUNCH PATH), or change the pin in the project",
},
PIN_UNREASONED: {
anchor: 'pin-unreasoned',
summary: 'a Capy session start found the checkout more than 24 hours behind origin\'s default branch and pinned (GSTACK_CAPY_SELF_UPGRADE=off, GSTACK_CAPY_AUTO_UPGRADE=0, a detached HEAD or another branch) with no recorded reason, so it overrode the pin and fast-forwarded (R75)',
fix: 'nothing when the pin was not deliberate; to keep a pin, record why: GSTACK_PIN_REASON=<why> for the session, or git -C <checkout> config gstack.pinReason "<why>"',
},
UPGRADE_SKIPPED: {
anchor: 'upgrade-skipped',
summary: 'the install-mode session was behind origin and its session-start fast-forward was skipped (dirty, diverged or pinned checkout, a live lease, or gstack-upgrade missing); the row is a WARN with the reason and the trailer stays ok with a behind= note, because a gap above the supported minimum is never a hard fail',
fix: 'run the fix the row names (bin/gstack-upgrade after clearing its refusal, or the Capy skill installer) before the next workflow, since any behind= of 1 or more calls for it; below the supported minimum the bootstrapper fails revision instead',
},
PLAN_RECORD_MISSING: {
anchor: 'plan-record-missing',
summary: 'the PR body has no Plan: line, so the PR reads as Plan: required and nothing shows its plan step (GST-1751)',
fix: "copy the brief's Plan line into the PR body with gstack-approvals render --plan \"<line>\": Plan: approved: <run id or row id>, or Plan: exempt: <reason>; then rerun",
},
PLAN_UNRESOLVED: {
anchor: 'plan-unresolved',
summary: 'Plan: approved: <token> (or a public repo\'s approved (record r-<id>)) names no approval row this machine can read, or a row that is a ruling or grant rather than a plan approval',
fix: 'gstack-approvals import --autoplan <run dir> --by "<owner>" after the owner answered (or gstack-approvals add with their words for a plan approved outside /autoplan), then cite the run id or row id and rerun',
},
PLAN_NOT_APPROVED: {
anchor: 'plan-not-approved',
summary: 'the Plan line says required, or the cited plan row is pending or rejected, or its gate was answered in an agent\'s own words instead of the owner\'s',
fix: 'finish the plan step: relay the gate to the owner through the Captain, answer it with their exact words (--owner-reply), import it, and cite the run; nothing was written',
},
PLAN_EXEMPT_UNKNOWN: {
anchor: 'plan-exempt-unknown',
summary: 'Plan: exempt: names a reason crew/docs/captain.md does not list (bug fix, s1, flaky, stamp, changelog-resolve, cap-repin, audited-list, read-only, or crew:<rule>)',
fix: "use the exemption the brief names, spelled as listed; a change none of them covers is a feature: Plan: required",
},
PLAN_STORE_UNAVAILABLE: {
anchor: 'plan-store-unavailable',
summary: 'Plan: approved: needs the approval store, and this machine has neither the state root\'s approvals nor a Drive mirror, so missing cannot be told apart from unreadable',
fix: 'run ready on the lane machine that imported the approval, or gstack-approvals sync there so the Drive mirror holds it; land checks the READY note and does not need the store',
},
QUEUE_PLAN_MISMATCH: {
anchor: 'queue-plan-mismatch',
summary: 'land found a READY note with no plan record, or a note whose Plan line differs from the PR body\'s, under plan_record: require',
fix: 'the lane fixes the PR body\'s Plan line if needed and reruns gstack-ship-queue ready --pr <n> at the pin, which resolves the line and writes the record into the note',
},
ARCHIVE_READS_STALE: {
anchor: 'archive-reads-stale',
summary: 'the Capy reads handed to gstack-archive-check are older than 15 minutes (or dated in the future), so they may not show what the thread holds now',
fix: 'rerun the archive program from crew/docs/captain.md#no-orphaned-work, which reads tools.thread.get and tools.issue.read again and stamps read_at with now(); nothing was archived',
},
ARCHIVE_READS_UNPARSED: {
anchor: 'archive-reads-unparsed',
summary: 'gstack-archive-check could not fully read the Capy reads (missing, empty or truncated output, or a line or state it does not know), so it cannot say the thread is clean',
fix: 'pass the raw tools.thread.get result and the raw tools.issue.read text unedited and read every page of a multi-page issue list; tools.thread.get lists at most 20 PRs and cannot page, so a thread that has held more cannot be proven clean and stays unarchived; nothing was archived',
},
ARCHIVE_THREAD_MISMATCH: {
anchor: 'archive-thread-mismatch',
summary: 'the reads file holds another thread than --thread names',
fix: 'read the thread you are archiving and pass its code to --thread; nothing was archived',
},
ARCHIVE_PR_NOT_MERGED: {
anchor: 'archive-pr-not-merged',
summary: 'gstack-archive-check landed was run on a PR GitHub does not report as merged, so no issue closes',
fix: 'run it after gstack-ship-queue land prints MERGED for this PR; close nothing until then',
},
ARCHIVE_GH_READ_FAILED: {
anchor: 'archive-gh-read-failed',
summary: 'gh could not read a PR gstack-archive-check needs, or answered for another PR, so the check fails closed',
fix: 'check `gh auth status` and the repository, then rerun (at most 2 times); if it still fails, leave the thread unarchived (or the issue open) and tell the Captain',
},
ARCHIVE_PR_STATE_UNKNOWN: {
anchor: 'archive-pr-state-unknown',
summary: 'gh pr view returned a PR state other than OPEN, CLOSED or MERGED (empty or unknown), so the PR may still be open and the check fails closed',
fix: 'rerun once; if gh still prints that state, check `gh --version` and the PR on GitHub, leave the thread unarchived (or the issue open) and tell the Captain',
},
ARCHIVE_POLICY_UNREADABLE: {
anchor: 'archive-policy-unreadable',
summary: 'gstack-archive-check landed found no usable .gstack/plain-titles.json (missing, invalid or with no codes), so it cannot tell a tracker code from any other ref and closes nothing',
fix: 'run it from the repository root, where .gstack/plain-titles.json lives; if the file is missing or invalid there, fix it on main (docs/ship-policy.md#plain-titles) and rerun; close nothing until then',
},
} satisfies Record<string, ResultCode>;