From 456b61c46990e21e2b32910354b82badca47b5e4 Mon Sep 17 00:00:00 2001 From: Sonic Shih Date: Mon, 3 Aug 2026 10:05:01 +0800 Subject: [PATCH 1/4] docs: simplify Monday agent instructions (refs #640) --- AGENTS.md | 236 +++++++++++++++++------------------------------------- 1 file changed, 75 insertions(+), 161 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 63a2beaf8..aecbadaca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,163 +1,77 @@ # Monday Agent Instructions -## Working Defaults - -- Work autonomously on clear, reversible tasks. Ask only before a destructive, - irreversible, or genuinely ambiguous action. -- Verify claims from repository, runtime, or deployed-state evidence. Preserve - unrelated user changes. -- Prefer the installed Matt Pocock engineering skills. Use the narrowest match: - `to-prd` for product definition, `triage` for intake, `diagnosing-bugs` for - root cause, `tdd` for behavior changes, `implement` for an approved change, - and `code-review` before merge. -- Do not default to Superpowers or require the user to name a Matt skill. Use - another installed skill only when it more directly matches the request or the - user explicitly asks for that workflow. - -## Mandatory Matt Engineering Flow - -Every development request must explicitly enter through the appropriate Matt -Pocock skill before code, deployment configuration, or runtime changes begin. -Do not treat a long conversation, a TODO list, or a dirty worktree as a -substitute for a scoped work item. - -- For a multi-step or multi-session outcome, first use `to-prd`, then - `to-issues`; each issue gets its own branch, change contract, acceptance - evidence, and out-of-scope boundary. -- For an approved issue, use `implement`, which drives `tdd`, then finish with - `code-review` before commit or PR. -- For an incoming report, use `triage`; for a defect or runtime drift, use - `diagnosing-bugs` to establish a focused failing proof before proposing a - fix. -- For a small, already-specified behavior change, use `tdd` directly; state - why a PRD is unnecessary in the PR description. -- Before starting a new issue, re-state the current PRD/issue contract and - stop if the requested work would add a different behavior, trust domain, or - rollout unit. Create or update the relevant issue instead of extending the - active one. - -### GitHub Issue Lifecycle - -- GitHub issue metadata is authoritative. Local PRD/epic files may add context - but must not gate issue status, close, or reopen operations. -- Publish issue bodies through `--body-file`; do not encode multiline Markdown - as escaped shell text. Every issue must have exactly one category (`bug` or - `enhancement`) and one triage state. Use `tracking` for PRD/parent issues and - `runtime` for contracts that require live mutation or evidence. -- Record parent/sub-issue and blocked-by relationships with GitHub's native - issue relationships. Prose sections remain readable summaries, not the - dependency source of truth. -- Partial or stacked work uses `Refs #N`. Only a PR targeting `main` that - completes the whole code contract may use `Closes #N`. The same restriction - applies to the `close`, `fix`, and `resolve` keyword families in commit - messages. -- A `runtime` or `tracking` issue is never closed by a PR. Runtime closure - requires target, controller, candidate/configuration, rollback, stop-rule, - result, and cleanup evidence. Parent closure requires a separate acceptance - audit after its final direct sub-issue closes. - -For the Polymarket research lane specifically, collector deployment, cohort and -snapshot construction, evaluator/MCTS execution, and result publication are -separate issues. A deployment gate must not become an excuse to modify research -logic, and a research issue must not change a production collector. - -## Karpathy-Inspired Coding Principles - -- **Think Before Coding.** State material assumptions explicitly. When ambiguity - would change behavior or scope, present the plausible interpretations and ask - rather than choosing silently. Surface tradeoffs and push back when a simpler - approach is sufficient. -- **Simplicity First.** Prefer the minimum code that solves the requested - problem. Do not add speculative features, single-use abstractions, - unrequested flexibility, or handling for scenarios excluded by proven - invariants. Never simplify away validation, security, data-loss prevention, - or other trust-boundary checks. -- **Surgical Changes.** Every changed line must trace to the request. Match the - existing style; do not refactor, reformat, or remove unrelated code. Remove - only the imports, variables, or functions made obsolete by the current change. -- **Goal-Driven Execution.** Define success criteria before non-trivial work; - reproduce bugs with a focused test, preserve before/after checks for - refactors, and loop until focused validation passes. For multi-step work, use - a brief `step -> verification` plan. - -## Pull Request Scope Guardrail - -A pull request is one behavior contract and one rollout/rollback unit. Do not -combine independently reviewable work merely because it shares a broad goal. - -Before opening a PR, record in its description a one-sentence change contract, -its acceptance evidence, and explicit out-of-scope work. Split the work when -any of these is true: - -- it crosses trust domains (Research, Governance, Runtime) without one - inseparable end-to-end contract; -- a collector/data contract, execution/risk policy, readiness/deployment, or - promotion rule can be merged, reverted, or tested independently; -- it needs different reviewers or has more than one separately testable - failure mode; -- it would exceed an available review-tool limit. Confirm that limit before - opening the PR and keep below it. - -At 25 changed files or 750 non-generated lines, stop and assess a split. Split -unless an inseparable end-to-end safety contract requires atomic delivery. An -atomic exception needs an explicitly named reviewer approval and must explain -why each part cannot be safely merged and rolled back on its own. - -Use a stacked PR only for a real dependency. State its base PR and merge order. -After each layer's base is merged, that layer must compile and remain -fail-closed on its own; otherwise keep the inseparable safety contract atomic. -Put review fixes in the focused PR that owns the behavior; do not append them -to an unrelated umbrella branch. Keep lockfiles, generated artifacts, and -mechanical renames with the PR that requires them. - -Every PR description must include: change contract, out of scope, dependency -or merge order, focused validation, and rollout/rollback impact; write `None` -where a field does not apply. A safety boundary needs a targeted counterexample -test, not only workspace compilation. - -## Concurrent Work Control - -- A section, issue, and PR are one independently mergeable and rollbackable - behavior contract unless a declared stacked dependency says otherwise. -- Before any write for a new contract, create a dedicated worktree under - `.worktrees/codex/` using approved worktree tooling. Use a - `codex/` branch from the declared integration base; record the exact - base SHA rather than assuming `main` is the correct base. -- Before delegation, record the contract, write owner, worktree path, branch, - base SHA, allowed files, and declared dependency. Do not share a writable - worktree between agents, even when their file lists do not overlap. -- Store that record in the worktree-private path returned by - `git rev-parse --git-path agent-worktree.yml`; it must not be committed or - replace the shared policy documents. -- A worktree status report must distinguish active, dirty, and prunable - entries. Removing a worktree or branch requires explicit user authorization. -- Each branch, worktree, and PR has exactly one write owner at a time. Record - the owner and current head before delegating; reviewers and researchers are - read-only unless ownership is explicitly transferred. -- Before every edit, commit, push, rebase, or merge, re-read the branch name, - `HEAD`, worktree status, and PR head. Stop if any value moved unexpectedly; - never absorb an unexplained concurrent change into the current PR. -- Do not run writable agents on overlapping files or the same dependency lane. - A predecessor PR must merge before its dependent branch is rewritten or - promoted, unless the stack and merge order were declared in advance. -- A behavior fix belongs to one PR only. Close or archive stale experiments - before another implementation of the same contract is promoted. -- Runtime, deployment, and collector cutover commands require one named - controller. Other tasks may inspect them read-only until control is handed - over explicitly. - -## Branch and Worktree Lifecycle - -- Keep GitHub's `delete_branch_on_merge` enabled. After verifying a merge, - confirm that the remote head branch is gone; delete it manually only if - auto-delete did not run. Then use `git fetch --prune` to remove stale local - tracking refs without touching local branches or worktrees. -- A closed-but-unmerged PR is not cleanup-safe by default. First classify it as - superseded, intentionally abandoned, or work to resume; only the first two - may be deleted with explicit authorization. -- Before deleting a local branch or worktree, record its PR state, HEAD, - upstream/push state, and whether its worktree is clean. A dirty worktree - must be reviewed and either committed as its own contract, explicitly kept, - or explicitly discarded; never delete it merely to reduce branch count. -- After a cleanup pass, report active, dirty, and prunable worktrees plus the - local and remote branch counts. +## Mission and authority + +- Monday is one Rust-first, multi-venue system. Research lives in + `rust_hft/alpha-harness`, acquisition in `rust_hft/tools/collector`, prediction + markets in `rust_hft/prediction-markets`, and runtime/risk/execution in + `rust_hft/apps/live`, `rust_hft/risk-control`, and `rust_hft/execution-gateway`. +- Research may emit typed candidates and signed deployment envelopes. It may not + submit orders, change risk limits, or resume a paused runtime. Live stays + disabled until a separately reviewed runtime contract proves every gate. +- Follow the nearest nested `AGENTS.md`; prediction-market work also follows + `rust_hft/prediction-markets/AGENTS.md`. + +## Fast workflow + +- Work autonomously on clear, reversible tasks. Preserve unrelated user changes; + ask only before destructive, irreversible, or genuinely ambiguous actions. +- Use the lightest workflow that preserves evidence: + - Read-only/status: inspect and answer directly; no PRD, issue, branch, or worktree. + - Small specified change: no PRD or issue; focused failing check, minimum patch, + focused validation, then diff review. + - Defect or runtime drift: use `diagnosing-bugs` to prove the cause first. + - Multi-step or multi-session outcome: use `to-prd`, then `to-issues`. + - Approved issue: use `implement`, which drives `tdd`, then `code-review`. +- Prefer the narrowest applicable Matt Pocock skill. Use another skill only when + it fits better or the user asks for it. + +## Durable guards from repeated failures + +- Refresh `origin/main` and live GitHub/runtime state before claims or new work. + A local checkout, old green run, or screen view is not current truth. +- Keep Code, CI, merge, release, runtime, and readback as separate states. Claim + only the latest state backed by an exact SHA/digest and direct readback. +- One change is one independently testable and rollbackable behavior. Do not mix + Research, Governance, and Runtime. Keep collector deployment, cohort/snapshot, + evaluator/MCTS, and result publication as separate rollout units. +- Never replace missing real data with fixtures, fabricate completeness, weaken a + fail-closed gate, or call a successful preparation step terminal evidence. +- Publishing an issue, PR, artifact, image, or job is not completion. Read back + its relationships, checks, immutable identity, terminal result, and output. + +## Scope and ownership + +- One active contract has one writer and one writable branch/worktree; when + published, it has one PR. Reuse a clean, owned worktree only for the same + contract; otherwise create a recorded `codex/` worktree from the base SHA. +- Record `agent-worktree.yml`. Before edits, commits, rebases, pushes, or merges, + re-read branch, `HEAD`, status, and PR head; stop on movement or overlapping ownership. +- Do not delete branches or worktrees without explicit authorization and exact + checks for dirty files, unpushed commits, PR state, and active ownership. +- A PR is one behavior and rollback unit. Use the PR template. At 25 changed files + or 750 non-generated lines, split unless a named reviewer approves an atomic exception. +- GitHub metadata is authoritative. Follow `docs/agents/issue-tracker.md`, issue + templates, lifecycle checks, and `/pm:issue-close`. Runtime/tracking issues + close from their own evidence, never from a PR. +- Runtime, deployment, and collector cutovers require one named controller, + exact target/candidate/configuration/rollback identities, stop rules, and readback. + +## Focused validation + +- Run the smallest check that can disprove the change, then the owning crate or + workflow check. Do not compile the full workspace for ordinary changes. +- From `rust_hft/`, use `cargo test -p --locked` and scoped Clippy. + Run `cargo metadata --locked --no-deps` only after workspace-graph changes. +- For instruction, workflow, or shell changes, run `git diff --check` plus the + closest contract test. Run `.github/scripts/agent-worktree-preflight.sh` in a + managed worktree. Report unrelated or unavailable checks separately. + +## Repeated workflows become skills + +- Keep this file as a router. After the same multi-step workflow succeeds twice, + package it as `.agents/skills//SKILL.md` instead of adding its procedure here. +- One skill owns one job and states triggers, inputs, steps, stop conditions, + verification, and output. Reuse repository scripts/docs; do not copy them. +- Validate skills manually before scheduling or write access. Runtime skills stay + fail-closed and never broaden user authority. From 1a3a82a6efe3e458f362aedaeb385e8ae9e63eb3 Mon Sep 17 00:00:00 2001 From: Sonic Shih Date: Mon, 3 Aug 2026 10:11:43 +0800 Subject: [PATCH 2/4] docs: add recurring Monday audit skills (refs #639) --- .../skills/monday-delivery-status/SKILL.md | 39 +++++++++++++++++++ .../monday-delivery-status/agents/openai.yaml | 4 ++ .../monday-research-evidence-audit/SKILL.md | 38 ++++++++++++++++++ .../agents/openai.yaml | 4 ++ .agents/skills/monday-worktree-audit/SKILL.md | 32 +++++++++++++++ .../monday-worktree-audit/agents/openai.yaml | 4 ++ 6 files changed, 121 insertions(+) create mode 100644 .agents/skills/monday-delivery-status/SKILL.md create mode 100644 .agents/skills/monday-delivery-status/agents/openai.yaml create mode 100644 .agents/skills/monday-research-evidence-audit/SKILL.md create mode 100644 .agents/skills/monday-research-evidence-audit/agents/openai.yaml create mode 100644 .agents/skills/monday-worktree-audit/SKILL.md create mode 100644 .agents/skills/monday-worktree-audit/agents/openai.yaml diff --git a/.agents/skills/monday-delivery-status/SKILL.md b/.agents/skills/monday-delivery-status/SKILL.md new file mode 100644 index 000000000..94301f4cf --- /dev/null +++ b/.agents/skills/monday-delivery-status/SKILL.md @@ -0,0 +1,39 @@ +--- +name: monday-delivery-status +description: Report Monday delivery truth as separate Code, CI, merge, release, runtime, and readback states with exact live identities. Use for status questions such as "现在卡在哪里", "是否完成", "能否上线", PR/CI triage, release checks, deployment checks, or any claim that work has shipped. +--- + +# Monday Delivery Status + +Produce a read-only status report. Never infer a later state from an earlier one. + +## Workflow + +1. Identify the requested branch, PR, release, service, and environment. If the user names only a local change, start from the current branch and `HEAD`. +2. Read local branch, `HEAD`, worktree status, and upstream without changing files. +3. Refresh live GitHub evidence. Read the PR head SHA, merge state, required checks, reviews, target branch, and latest relevant workflow or release artifact. +4. Read deployment and runtime state only when the target and access path are known. Record the deployed image/SHA, configuration identity, health, and named controller if present. +5. Read the final external artifact or service independently. A publish command or healthy process is not readback. +6. Mark each state `passed`, `failed`, `pending`, `blocked`, or `unknown`. Use `unknown` when direct evidence is unavailable. + +## State contract + +- **Code**: exact commit exists and focused local validation is known. +- **CI**: required checks for that exact PR head finished successfully. +- **Merge**: GitHub reports the exact head merged into the intended base. +- **Release**: an artifact or image exists and its immutable identity matches the merged commit. +- **Runtime**: the intended environment runs that immutable identity with the intended configuration. +- **Readback**: an independent query observes the expected terminal output or service behavior. + +Do not collapse runner outages, code failures, mergeability, approval, deployment, or runtime health into one "CI failed" or "done" result. + +## Stop conditions + +- Stop mutation entirely; this Skill never reruns CI, merges, deploys, restarts, or changes configuration. +- Stop and report `blocked` if branch or PR head moves during the audit. +- Report authentication, network, or permission gaps as `unknown`; do not reuse stale screenshots or old green runs. + +## Output + +Return one row per state with: `State | Result | Exact identity | Direct evidence | Blocker/next check`. +End with one sentence naming the earliest incomplete state; that is the current blocker. diff --git a/.agents/skills/monday-delivery-status/agents/openai.yaml b/.agents/skills/monday-delivery-status/agents/openai.yaml new file mode 100644 index 000000000..79892582c --- /dev/null +++ b/.agents/skills/monday-delivery-status/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Monday Delivery Status" + short_description: "Separate live delivery states with exact evidence" + default_prompt: "Use $monday-delivery-status to report the current delivery state of this Monday change." diff --git a/.agents/skills/monday-research-evidence-audit/SKILL.md b/.agents/skills/monday-research-evidence-audit/SKILL.md new file mode 100644 index 000000000..f11c5e1d1 --- /dev/null +++ b/.agents/skills/monday-research-evidence-audit/SKILL.md @@ -0,0 +1,38 @@ +--- +name: monday-research-evidence-audit +description: Audit Monday research evidence from authenticated input through snapshot, Mission admission, evaluator output, immutable publication, and independent readback. Use when checking research E2E readiness or completion, ResearchSnapshot, evaluator/MCTS results, sealed holdout evidence, OSS artifacts, cohort completeness, or claims that a research run succeeded. +--- + +# Monday Research Evidence Audit + +Audit existing evidence only. Do not collect data, run evaluation, publish results, or touch production. + +## Workflow + +1. Name one research contract, venue/instrument, time window, and expected terminal artifact. +2. Follow immutable identities through every stage: + - authenticated input manifest and source digest; + - cohort/partition and `ResearchSnapshot` digest; + - admitted typed Mission and policy/configuration digest; + - evaluator or MCTS run identity and terminal result; + - immutable result bundle and checksum; + - independent OSS or artifact-store readback of the same bytes and checksum. +3. At each boundary, compare both the referenced identity and the actual content. Record `passed`, `missing`, `mismatch`, `stale`, or `not applicable`. +4. Check that fixtures, synthetic substitutes, unrelated collector health, CI success, and preparation logs are not being used as terminal research evidence. +5. The overall result passes only when every required boundary passes for the same contract and window. + +## Safety boundaries + +- Never fabricate missing history or completeness. Mark unreconstructable data `missing` and state the excluded window. +- Never use research authority to start collectors, alter deployment, submit orders, change risk limits, or enable Paper/Shadow/Live. +- Do not treat collector deployment, snapshot construction, evaluation, and publication as one rollout unit. +- Do not expose credentials or secret material; record only authenticated status and immutable public identities. + +## Stop conditions + +Stop following a branch when an identity breaks or cannot be read back. Continue checking independent branches only if that helps locate multiple gaps; the terminal result remains incomplete. + +## Output + +Return `Stage | Result | Expected identity | Observed identity | Evidence | Gap` for the six stages above. +End with `Overall: passed` or `Overall: incomplete`, followed by the earliest broken boundary and the smallest read-only check needed next. diff --git a/.agents/skills/monday-research-evidence-audit/agents/openai.yaml b/.agents/skills/monday-research-evidence-audit/agents/openai.yaml new file mode 100644 index 000000000..0315c576c --- /dev/null +++ b/.agents/skills/monday-research-evidence-audit/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Monday Research Evidence Audit" + short_description: "Audit the research chain without mutations" + default_prompt: "Use $monday-research-evidence-audit to audit this Monday research evidence chain." diff --git a/.agents/skills/monday-worktree-audit/SKILL.md b/.agents/skills/monday-worktree-audit/SKILL.md new file mode 100644 index 000000000..70f48b798 --- /dev/null +++ b/.agents/skills/monday-worktree-audit/SKILL.md @@ -0,0 +1,32 @@ +--- +name: monday-worktree-audit +description: Classify Monday Git worktrees as active, dirty, or Git-prunable without deleting or cleaning them. Use for worktree inventory, branch cleanup planning, disk-usage review, stale-worktree questions, ownership conflicts, or before any request to remove a worktree or branch. +--- + +# Monday Worktree Audit + +Produce a read-only inventory. Classification is not deletion authorization. + +## Workflow + +1. From the repository, run `.github/scripts/agent-worktree-preflight.sh report`. +2. Read `git worktree list --porcelain` and preserve each exact path, branch or detached `HEAD`, and Git's `prunable` marker. +3. For every dirty entry, report changed and untracked paths without modifying them. +4. For any cleanup candidate, additionally read its ownership record, exact `HEAD`, upstream/push state, open or closed PR state, merge state, and active-session use. +5. Classify: + - `active`: registered and clean, or current ownership/use is present; + - `dirty`: tracked or untracked changes exist; + - `prunable`: Git itself marks the administrative worktree record prunable. +6. Keep `cleanup-safe` separate from those three states. It requires explicit user authorization plus clean state, no unpushed work, resolved PR disposition, no active owner/session, and a recorded recovery identity. + +## Stop conditions + +- Never run worktree removal, branch deletion, reset, clean, prune, or discard commands. +- If ownership, push state, PR disposition, or active use is unknown, keep the entry and mark cleanup safety `unknown`. +- A merged or newer PR never makes a nearby dirty worktree safe to remove. + +## Output + +Return totals for `active`, `dirty`, and `prunable`, followed by: +`Path | Branch/HEAD | State | Dirty/unpushed | PR | Owner/use | Cleanup safety | Reason`. +List only evidence-backed cleanup candidates in a separate final section; do not recommend deletion without an exact authorized path list. diff --git a/.agents/skills/monday-worktree-audit/agents/openai.yaml b/.agents/skills/monday-worktree-audit/agents/openai.yaml new file mode 100644 index 000000000..6a8c9256f --- /dev/null +++ b/.agents/skills/monday-worktree-audit/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Monday Worktree Audit" + short_description: "Classify worktrees safely without cleanup" + default_prompt: "Use $monday-worktree-audit to classify the current Monday worktrees." From 05d5811f869576b470bb6ff8234391c5e67af18f Mon Sep 17 00:00:00 2001 From: Sonic Shih Date: Mon, 3 Aug 2026 10:20:10 +0800 Subject: [PATCH 3/4] docs: tighten audit identity contracts (refs #639) --- .agents/skills/monday-delivery-status/SKILL.md | 4 ++-- .agents/skills/monday-worktree-audit/SKILL.md | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.agents/skills/monday-delivery-status/SKILL.md b/.agents/skills/monday-delivery-status/SKILL.md index 94301f4cf..b198e6627 100644 --- a/.agents/skills/monday-delivery-status/SKILL.md +++ b/.agents/skills/monday-delivery-status/SKILL.md @@ -13,7 +13,7 @@ Produce a read-only status report. Never infer a later state from an earlier one 2. Read local branch, `HEAD`, worktree status, and upstream without changing files. 3. Refresh live GitHub evidence. Read the PR head SHA, merge state, required checks, reviews, target branch, and latest relevant workflow or release artifact. 4. Read deployment and runtime state only when the target and access path are known. Record the deployed image/SHA, configuration identity, health, and named controller if present. -5. Read the final external artifact or service independently. A publish command or healthy process is not readback. +5. Read the final external artifact or service independently. Verify that its immutable identity and configuration match `Runtime`; otherwise mark `Runtime` or `Readback` `unknown`. A publish command or healthy process is not readback. 6. Mark each state `passed`, `failed`, `pending`, `blocked`, or `unknown`. Use `unknown` when direct evidence is unavailable. ## State contract @@ -23,7 +23,7 @@ Produce a read-only status report. Never infer a later state from an earlier one - **Merge**: GitHub reports the exact head merged into the intended base. - **Release**: an artifact or image exists and its immutable identity matches the merged commit. - **Runtime**: the intended environment runs that immutable identity with the intended configuration. -- **Readback**: an independent query observes the expected terminal output or service behavior. +- **Readback**: an independent query observes the expected terminal output or service behavior from the same deployed immutable identity and configuration. Do not collapse runner outages, code failures, mergeability, approval, deployment, or runtime health into one "CI failed" or "done" result. diff --git a/.agents/skills/monday-worktree-audit/SKILL.md b/.agents/skills/monday-worktree-audit/SKILL.md index 70f48b798..ad0ec9dbf 100644 --- a/.agents/skills/monday-worktree-audit/SKILL.md +++ b/.agents/skills/monday-worktree-audit/SKILL.md @@ -14,9 +14,10 @@ Produce a read-only inventory. Classification is not deletion authorization. 3. For every dirty entry, report changed and untracked paths without modifying them. 4. For any cleanup candidate, additionally read its ownership record, exact `HEAD`, upstream/push state, open or closed PR state, merge state, and active-session use. 5. Classify: - - `active`: registered and clean, or current ownership/use is present; + - `active`: registered, clean, and not Git-prunable; - `dirty`: tracked or untracked changes exist; - `prunable`: Git itself marks the administrative worktree record prunable. + Record ownership or session use only in `Owner/use`; it never changes `State`. 6. Keep `cleanup-safe` separate from those three states. It requires explicit user authorization plus clean state, no unpushed work, resolved PR disposition, no active owner/session, and a recorded recovery identity. ## Stop conditions From 00c6220c4595a33d46205411292df9e631a56427 Mon Sep 17 00:00:00 2001 From: Sonic Shih Date: Mon, 3 Aug 2026 10:26:11 +0800 Subject: [PATCH 4/4] docs: align audit skills with repository evidence (refs #639) --- .agents/skills/monday-delivery-status/SKILL.md | 4 ++-- .agents/skills/monday-research-evidence-audit/SKILL.md | 9 +++++---- .agents/skills/monday-worktree-audit/SKILL.md | 10 ++++++---- 3 files changed, 13 insertions(+), 10 deletions(-) diff --git a/.agents/skills/monday-delivery-status/SKILL.md b/.agents/skills/monday-delivery-status/SKILL.md index b198e6627..7a6caa10d 100644 --- a/.agents/skills/monday-delivery-status/SKILL.md +++ b/.agents/skills/monday-delivery-status/SKILL.md @@ -18,11 +18,11 @@ Produce a read-only status report. Never infer a later state from an earlier one ## State contract -- **Code**: exact commit exists and focused local validation is known. +- **Code**: exact commit exists and focused local validation passed; any failed focused check makes this state `failed`. - **CI**: required checks for that exact PR head finished successfully. - **Merge**: GitHub reports the exact head merged into the intended base. - **Release**: an artifact or image exists and its immutable identity matches the merged commit. -- **Runtime**: the intended environment runs that immutable identity with the intended configuration. +- **Runtime**: the intended environment runs that immutable identity with the intended configuration and passing health checks. - **Readback**: an independent query observes the expected terminal output or service behavior from the same deployed immutable identity and configuration. Do not collapse runner outages, code failures, mergeability, approval, deployment, or runtime health into one "CI failed" or "done" result. diff --git a/.agents/skills/monday-research-evidence-audit/SKILL.md b/.agents/skills/monday-research-evidence-audit/SKILL.md index f11c5e1d1..69aa0c9a8 100644 --- a/.agents/skills/monday-research-evidence-audit/SKILL.md +++ b/.agents/skills/monday-research-evidence-audit/SKILL.md @@ -12,12 +12,13 @@ Audit existing evidence only. Do not collect data, run evaluation, publish resul 1. Name one research contract, venue/instrument, time window, and expected terminal artifact. 2. Follow immutable identities through every stage: - authenticated input manifest and source digest; + - venue admission or verifier receipt and ready-catalog identity when required; - cohort/partition and `ResearchSnapshot` digest; - - admitted typed Mission and policy/configuration digest; - - evaluator or MCTS run identity and terminal result; + - admitted typed Mission, policy/configuration digest, and selected evaluator repository/binary/OCI identity; + - evaluator or MCTS run identity, receipt-bound runtime identity, terminal result, and sealed-holdout isolation evidence; - immutable result bundle and checksum; - independent OSS or artifact-store readback of the same bytes and checksum. -3. At each boundary, compare both the referenced identity and the actual content. Record `passed`, `missing`, `mismatch`, `stale`, or `not applicable`. +3. At each boundary, compare both the referenced identity and the actual content. Record `passed`, `missing`, `mismatch`, `stale`, `unknown`, or `not applicable`. Use `unknown` for authentication, network, permission, or other observability gaps; reserve `missing` for verified absence. 4. Check that fixtures, synthetic substitutes, unrelated collector health, CI success, and preparation logs are not being used as terminal research evidence. 5. The overall result passes only when every required boundary passes for the same contract and window. @@ -34,5 +35,5 @@ Stop following a branch when an identity breaks or cannot be read back. Continue ## Output -Return `Stage | Result | Expected identity | Observed identity | Evidence | Gap` for the six stages above. +Return `Stage | Result | Expected identity | Observed identity | Evidence | Gap` for the seven stages above. End with `Overall: passed` or `Overall: incomplete`, followed by the earliest broken boundary and the smallest read-only check needed next. diff --git a/.agents/skills/monday-worktree-audit/SKILL.md b/.agents/skills/monday-worktree-audit/SKILL.md index ad0ec9dbf..1e2a3cb66 100644 --- a/.agents/skills/monday-worktree-audit/SKILL.md +++ b/.agents/skills/monday-worktree-audit/SKILL.md @@ -11,14 +11,15 @@ Produce a read-only inventory. Classification is not deletion authorization. 1. From the repository, run `.github/scripts/agent-worktree-preflight.sh report`. 2. Read `git worktree list --porcelain` and preserve each exact path, branch or detached `HEAD`, and Git's `prunable` marker. -3. For every dirty entry, report changed and untracked paths without modifying them. -4. For any cleanup candidate, additionally read its ownership record, exact `HEAD`, upstream/push state, open or closed PR state, merge state, and active-session use. -5. Classify: +3. Enumerate local branches with `git for-each-ref refs/heads` and report branches not attached to any worktree separately. +4. For every dirty entry, report changed and untracked paths without modifying them. +5. For any cleanup candidate, additionally read its ownership record, exact `HEAD`, upstream/push state, open or closed PR state, merge state, and active-session use. +6. Classify worktrees exactly once, using the preflight report as authoritative: - `active`: registered, clean, and not Git-prunable; - `dirty`: tracked or untracked changes exist; - `prunable`: Git itself marks the administrative worktree record prunable. Record ownership or session use only in `Owner/use`; it never changes `State`. -6. Keep `cleanup-safe` separate from those three states. It requires explicit user authorization plus clean state, no unpushed work, resolved PR disposition, no active owner/session, and a recorded recovery identity. +7. Keep `cleanup-safe` separate from those three states. It requires explicit user authorization plus clean state, no unpushed work, resolved PR disposition, no active owner/session, and a recorded recovery identity. ## Stop conditions @@ -30,4 +31,5 @@ Produce a read-only inventory. Classification is not deletion authorization. Return totals for `active`, `dirty`, and `prunable`, followed by: `Path | Branch/HEAD | State | Dirty/unpushed | PR | Owner/use | Cleanup safety | Reason`. +Then list unattached branches as `Branch | HEAD | Upstream/unpushed | PR | Owner/use | Cleanup safety | Reason`. List only evidence-backed cleanup candidates in a separate final section; do not recommend deletion without an exact authorized path list.