coilyco-flight-deck/agentic-os

Fork 0

Add a code-review contract validator beside catalog-trifecta #402

New issue

Closed

opened 2026-07-10 03:47:53 +00:00 by coilyco-ops · 3 comments

coilyco-ops commented

2026-07-10 03:47:53 +00:00

Member

Add a code-review contract validator beside catalog-trifecta

The earlier issue was too doc-creation focused. The intended change is a new aos validator and documentation contract. It can be named something other than "trifecta" because the entrypoint set is no longer literally three files.

Goal:

Add an aos pre-commit validator that requires repos to carry a root CODE-REVIEW.md file, or whatever name the repo conventions settle on if the implementation chooses a better durable name.
Treat this as a conceptual sibling to catalog-trifecta: the repo's review doctrine is a required catalog surface, not an optional skill note.
Keep the existing catalog-trifecta behavior intact unless the implementation intentionally renames or generalizes the concept. Do not break repos that only have the current README.md / AGENTS.md / docs/FEATURES.md / .ward/ward.yaml entrypoint set until rollout is handled deliberately.

Required CODE-REVIEW.md content contract:

It always contains code review instructions about enforcing localized invariants and defending against historical issues.
It MUST be updated whenever an issue re-occurs, or whenever an issue large enough to create a full work stop appears.
It SHOULD NOT contain generic purpose review rules like "don't use 1-letter variable names".
It is subject to the same documentation-layout length and placement rules as other root Markdown. Do not carve out an oversized or exempt doc.

Implementation expectations:

Add the validator under agentic_os/pre_commit with an entrypoint in pyproject.toml and .pre-commit-hooks.yaml.
Add focused tests for missing CODE-REVIEW.md, accepted localized/historical content, and rejection or warning for generic-purpose-only content if the implementation can do that robustly.
Update documentation-layout root Markdown allowance intentionally so CODE-REVIEW.md is permitted but still capped.
Update docs that enumerate catalog/documentation surfaces, especially docs/skill-discipline-handbook-hooks.md, docs/documentation-layout-exceptions.md, docs/catalog-caps-reference.md if generated output changes, docs/FEATURES.md, and See also links where useful.
Consider a new name for the generalized entrypoint family. The issue is asking for the concept, not insisting on the word "trifecta".

Acceptance criteria:

Repos can be checked for the existence of CODE-REVIEW.md through a committed aos hook.
The root CODE-REVIEW.md contract is documented as localized invariant and historical-issue defense, not generic review advice.
CODE-REVIEW.md remains under normal documentation-layout caps.
pre-commit run --all-files passes.
The old incorrectly-scoped issue coilyco-flight-deck/agentic-os#401 is superseded by this issue.

Filed by ward agent engineer --harness codex.

— Codex, via ward agent

Add a code-review contract validator beside catalog-trifecta The earlier issue was too doc-creation focused. The intended change is a new aos validator and documentation contract. It can be named something other than "trifecta" because the entrypoint set is no longer literally three files. Goal: * Add an aos pre-commit validator that requires repos to carry a root CODE-REVIEW.md file, or whatever name the repo conventions settle on if the implementation chooses a better durable name. * Treat this as a conceptual sibling to catalog-trifecta: the repo's review doctrine is a required catalog surface, not an optional skill note. * Keep the existing catalog-trifecta behavior intact unless the implementation intentionally renames or generalizes the concept. Do not break repos that only have the current README.md / AGENTS.md / docs/FEATURES.md / .ward/ward.yaml entrypoint set until rollout is handled deliberately. Required CODE-REVIEW.md content contract: * It always contains code review instructions about enforcing localized invariants and defending against historical issues. * It MUST be updated whenever an issue re-occurs, or whenever an issue large enough to create a full work stop appears. * It SHOULD NOT contain generic purpose review rules like "don't use 1-letter variable names". * It is subject to the same documentation-layout length and placement rules as other root Markdown. Do not carve out an oversized or exempt doc. Implementation expectations: * Add the validator under agentic_os/pre_commit with an entrypoint in pyproject.toml and .pre-commit-hooks.yaml. * Add focused tests for missing CODE-REVIEW.md, accepted localized/historical content, and rejection or warning for generic-purpose-only content if the implementation can do that robustly. * Update documentation-layout root Markdown allowance intentionally so CODE-REVIEW.md is permitted but still capped. * Update docs that enumerate catalog/documentation surfaces, especially docs/skill-discipline-handbook-hooks.md, docs/documentation-layout-exceptions.md, docs/catalog-caps-reference.md if generated output changes, docs/FEATURES.md, and See also links where useful. * Consider a new name for the generalized entrypoint family. The issue is asking for the concept, not insisting on the word "trifecta". Acceptance criteria: * Repos can be checked for the existence of CODE-REVIEW.md through a committed aos hook. * The root CODE-REVIEW.md contract is documented as localized invariant and historical-issue defense, not generic review advice. * CODE-REVIEW.md remains under normal documentation-layout caps. * pre-commit run --all-files passes. * The old incorrectly-scoped issue coilyco-flight-deck/agentic-os#401 is superseded by this issue. --- Filed by `ward agent engineer --harness codex`.  — Codex, via `ward agent`

coilyco-ops commented

2026-07-10 03:48:07 +00:00

Author

Member

WARD-RESERVATION: held 🔒

reservation details

Holder: container engineer-codex-agentic-os-402 on host kais-macbook-pro-2.local.

Reserved by ward agent --harness codex (reserved 2026-07-10T03:48:06Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (1h TTL). --force overrides.

Do not comment on or edit this issue to steer the run while it is reserved. The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a new issue, dispatched fresh. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).

run seed context — what this run is carrying (ward#609)

Resolved: coilyco-flight-deck/agentic-os#402 · branch issue-402 · harness codex · workflow direct-main
Run: engineer-codex-agentic-os-402 · ward v0.554.0 · dispatched 2026-07-10T03:48:06Z
Comment thread: 0 included in the pre-flight read, 0 stripped (ward's own automated comments).

Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.554.0).

— Codex, via ward agent

WARD-RESERVATION: held 🔒 <details><summary>reservation details</summary> Holder: container `engineer-codex-agentic-os-402` on host `kais-macbook-pro-2.local`. Reserved by `ward agent --harness codex` (reserved 2026-07-10T03:48:06Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (1h TTL). `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh**. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494). <details><summary>run seed context — what this run is carrying (ward#609)</summary> - **Resolved:** `coilyco-flight-deck/agentic-os#402` · branch `issue-402` · harness `codex` · workflow `direct-main` - **Run:** `engineer-codex-agentic-os-402` · ward `v0.554.0` · dispatched `2026-07-10T03:48:06Z` - **Comment thread:** 0 included in the pre-flight read, 0 stripped (ward's own automated comments). Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.554.0). </details> </details>  — Codex, via `ward agent`

coilyco-ops referenced this issue

2026-07-10 03:48:19 +00:00

Add a conceptual fourth branch beside the README / AGENTS / docs/FEATURE… #401

coilyco-ops referenced this issue from coilyco-flight-deck/ward

2026-07-10 04:02:39 +00:00

Mine warded-agent history for regression tests and review doctrine #934

coilysiren referenced this issue from coilyco-flight-deck/ward

2026-07-10 04:03:12 +00:00

ward release race condition #935

coilyco-ops commented

2026-07-10 04:08:16 +00:00

Author

Member

WARD-OUTCOME: done

details

workflow: direct-to-main; review summary: review gate skipped by ~/.ward/config.yaml default. Implemented a new `code-review-contract` hook, a root `CODE-REVIEW.md`, layout allowance, docs, and tests. Felt straightforward after aligning the bundle validator and size caps. Confidence: high. Surprises: `.ward/ward-kdl.defaults.kdl` needed its canonical newline state fixed, and `docs/features-release-tooling.md` had to be trimmed back under cap. Follow-ups: none.

WARD-OUTCOME: done <details><summary>details</summary> workflow: direct-to-main; review summary: review gate skipped by ~/.ward/config.yaml default. Implemented a new `code-review-contract` hook, a root `CODE-REVIEW.md`, layout allowance, docs, and tests. Felt straightforward after aligning the bundle validator and size caps. Confidence: high. Surprises: `.ward/ward-kdl.defaults.kdl` needed its canonical newline state fixed, and `docs/features-release-tooling.md` had to be trimmed back under cap. Follow-ups: none. </details>

coilyco-ops commented

2026-07-10 08:52:10 +00:00

Author

Member

Closing after verification during the ward/aos usability sweep.

Evidence in current origin/main:

CODE-REVIEW.md exists at repo root.
.pre-commit-hooks.yaml registers code-review-contract.
pyproject.toml exposes check-code-review-contract.
agentic_os/pre_commit/check_code_review_contract.py implements the validator.
tests/test_check_code_review_contract.py covers it.
docs/FEATURES.md and the skill-discipline docs include the new contract surface.
Comment 28229 already reported WARD-OUTCOME: done with workflow: direct-to-main.

This looks landed and the tracker was just stale-open.

Closing after verification during the ward/aos usability sweep. Evidence in current `origin/main`: * `CODE-REVIEW.md` exists at repo root. * `.pre-commit-hooks.yaml` registers `code-review-contract`. * `pyproject.toml` exposes `check-code-review-contract`. * `agentic_os/pre_commit/check_code_review_contract.py` implements the validator. * `tests/test_check_code_review_contract.py` covers it. * `docs/FEATURES.md` and the skill-discipline docs include the new contract surface. * Comment `28229` already reported `WARD-OUTCOME: done` with `workflow: direct-to-main`. This looks landed and the tracker was just stale-open.

coilyco-ops closed this issue

2026-07-10 08:52:10 +00:00