Operant Studio
OPER-179

docs(rules): add admission-contract.md + ticket-filing-checklist.md

Band
SMALL
Suggested
Justin Cooke

Body

feature_id: FEAT-studio-agent-rules

## Context

On [REDACTED-DOB] the filing agent admitted OPER-176/177/178 and POR-778 without the admission-contract fields (`band`, `module`, `writeSets`, `verificationCmd`, `hasMigration`, `phiInScope`) and without plan docs for the Safeguard tickets. All four bounced to `NEEDS_RESCOPE` on the first `PATCH status=PLANNING_VALIDATED`.

Root cause: the individual rules (`build-risk-matrix.md`, `explore-plan-execute.md`, `admission-gate.md`) each implied the requirements, but no single file listed them in one place a filing agent could run through as a checklist. Compaction summaries stripped the field requirements, and the filing agent inferred fields from grepping recently-DONE tickets rather than reading a codified rule.

This ticket ships two new rule files + cross-links so the failure class cannot recur:

- `.claude/rules/admission-contract.md` — enumerates every field the admission gate reads, split by tier
- `.claude/rules/ticket-filing-checklist.md` — hub checklist a filing agent runs before POSTing

Plan doc for this ticket: `docs/plans/OPER-179-admission-contract-rules.md` (to be authored by the plan subagent as the first execution step — this ticket is Sandbox tier so the plan doc is optional, but the drafts are already written and attached below).

## Acceptance Criteria

- [ ] New file `.claude/rules/admission-contract.md` with the content from the attached draft (`/home/user/workspace/oper-admission-rules-draft/new/admission-contract.md`).
- [ ] New file `.claude/rules/ticket-filing-checklist.md` with the content from the attached draft (`/home/user/workspace/oper-admission-rules-draft/new/ticket-filing-checklist.md`).
- [ ] `.claude/rules/explore-plan-execute.md` — insert the "Plan doc lands BEFORE ticket admission" subsection per the attached diff (`/home/user/workspace/oper-admission-rules-draft/edits/explore-plan-execute.diff`). Inserts immediately after "The main session reads the plan, asks the user to approve, then begins execution."
- [ ] `.claude/rules/build-risk-matrix.md` — append the "Related rules" section per the attached diff (`/home/user/workspace/oper-admission-rules-draft/edits/build-risk-matrix.diff`).
- [ ] `CLAUDE.md` — add both new rules to the "Rules (auto-loaded from `.claude/rules/`)" index per the attached diff (`/home/user/workspace/oper-admission-rules-draft/edits/CLAUDE.md.diff`).
- [ ] Run `.claude/operant-studio/update.sh` locally to verify the addendum block regenerates cleanly with the two new rules listed.
- [ ] Open PR with title `docs(rules): add admission-contract.md + ticket-filing-checklist.md`. Do NOT auto-merge — user reviews before merge.

## Risk classification

Sandbox (Risk 3 / Reach 4). Docs-only change to `.claude/rules/` and `CLAUDE.md`. No code paths, no schema, no runtime behavior. Failure mode is "the rules are worded poorly and the next filing agent misinterprets them" — caught by human PR review, not by tests.

## Depends on

None. Ships independently.

## Blocks

- Retroactive plan docs for OPER-176, OPER-177, POR-778 (blocked because those plan docs should be written by whoever picks up those tickets, following the new rule)
- Any future ticket filing — this rule set is what the filing agent will read

## Out of scope

- Retroactively writing plan docs for OPER-176 / OPER-177 / POR-778 (separate work under those tickets)
- Adding admission-gate validator code changes (the validator already enforces these fields — this ticket documents what it enforces)
- Modifying `feature-map-and-depmap.md`, `phi-handling.md`, `prisma-schema.md`, `multi-tenant-rls.md`, `pr-size-budget.md`, `edge-safety.md` — cross-references from those files can be a follow-up if desired


---
<!-- admission-rejected -->
**Admission rejected (unknown_feature_id):** feature_id=FEAT-studio-agent-rules is not declared in the feature-map.md of any admission-enabled product owned by this team.

Valid feature_ids for product studio (products/studio/feature-map.md):

- FEAT-studio-agent-workers
- FEAT-studio-audit
- FEAT-studio-audit-log
- FEAT-studio-branch-protection-rulesets
- FEAT-studio-coverage-policy
- FEAT-studio-dependency-map-policy
- FEAT-studio-dispatcher
- FEAT-studio-env-protection
- FEAT-studio-fabricated-evidence-tripwire
- FEAT-studio-guard-inventory
- FEAT-studio-incident-runbook
- FEAT-studio-mutation-testing
- FEAT-studio-phi-guard
- FEAT-studio-pipeline-observability
- FEAT-studio-planning-validation
- FEAT-studio-platform
- FEAT-studio-product-manifest
- FEAT-studio-qa
- FEAT-studio-qa-projects
- FEAT-studio-review-rounds

... and 2 more; see products/studio/feature-map.md

Attachments

Loading attachments…

Comments

Loading comments…