docs: add the operating discipline guide for repo agents - #9
Conversation
The section sends readers to a codegraph CLI the project does not ship or require.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a9a57c0201
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Never run bare `rk validate` or `rk status` at session start on a mature repo: | ||
| tier 3 output is large and mostly P2 background noise | ||
| (`SHIPPED_SPRINT_MISSING_BASE_SHA` in particular). `--fail-on P0,P1` is the |
There was a problem hiding this comment.
In the stated mature-repository scenario, --fail-on P0,P1 does not reduce the output: the CLI help defines --fail-on as a “severity threshold,” while runValidateCommand still formats every finding unless a display filter or --brief is used. Moreover, SHIPPED_SPRINT_MISSING_BASE_SHA is audit-scoped and is not included by bare rk validate or rk status; the --audit help explicitly says that historical-hygiene rules are off by default. Agents following this guidance can therefore receive the same live P2 output at tier 2, while the cited source of tier-3 noise cannot occur there. Recommend --brief when only the gate result is needed, and distinguish exit thresholds from audit scope and output filtering.
Useful? React with 👍 / 👎.
| the caps are 16 rules and 8 fanout entries. Every tier named in `then.tier`, | ||
| `then.fanout[].tier`, or `extras.routing.*` must appear in `routing.tiers` — | ||
| `rk validate --fail-on P0,P1` surfaces mismatches. |
There was a problem hiding this comment.
When extras.routing.pin_tier or prefer_tier contains a syntactically valid but unconfigured tier, rk validate --fail-on P0,P1 does not inspect it because sprint extras remain opaque to the validators; only routing later warns on stderr and exits successfully with a scored fallback. An unknown tier in extras.routing.fanout is even filtered out by buildHint without a finding. Thus the documented gate can pass and dispatch an unintended tier or incomplete fanout. Add these cross-checks to validation or stop claiming that this command surfaces all such mismatches.
Useful? React with 👍 / 👎.
| extras: | ||
| routing: | ||
| complexity: deep # trivial | standard | deep — ordinal hint | ||
| prefer_tier: standard # soft preference (scorer may override) |
There was a problem hiding this comment.
For a valid prefer_tier, recommend() returns that tier before reaching the score-based fallback, so the scorer never overrides the preference; only a pin or matching policy rule takes precedence. An author following this comment could set standard expecting a sufficiently deep or high-token sprint to be upgraded automatically, but it will remain standard. Describe this as a preference that overrides scoring, while remaining subordinate to pins and rules.
Useful? React with 👍 / 👎.
1 participant
What
docs/agents/operating-discipline.md.Verification