diff --git a/.agents/skills/monday-delivery-status/SKILL.md b/.agents/skills/monday-delivery-status/SKILL.md new file mode 100644 index 000000000..7a6caa10d --- /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. 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 + +- **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 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. + +## 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..69aa0c9a8 --- /dev/null +++ b/.agents/skills/monday-research-evidence-audit/SKILL.md @@ -0,0 +1,39 @@ +--- +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; + - venue admission or verifier receipt and ready-catalog identity when required; + - cohort/partition and `ResearchSnapshot` digest; + - 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`, `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. + +## 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 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-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..1e2a3cb66 --- /dev/null +++ b/.agents/skills/monday-worktree-audit/SKILL.md @@ -0,0 +1,35 @@ +--- +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. 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`. +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 + +- 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`. +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. 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." 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.