refactor(planning): harden planning route and metadata guards - #81
Merged
Conversation
c-wri
marked this pull request as ready for review
April 19, 2026 19:21
c-wri
enabled auto-merge
April 19, 2026 19:22
Why: - durable control-plane and delivery surfaces needed an explicit durable metadata rule so planning tags stop leaking into standards, metadata, and branch naming - ordinary work also needed a documented branch tree policy so branch roots stay reviewable and consistent What: - add the durable-versus-planning surface rule across the standards docs - document the approved `<root>/<slug>` ordinary branch tree and durable delivery metadata rules - route AGENTS and checkpoint or review commands through the updated policy Checks: - make docs-check - make naming-check
Why: - planning-only repo work needed a reusable entrypoint so agents stop inferring planning behavior from execution skills - the touched workflow skills also needed explicit handoffs so broader planning work routes cleanly before execution starts What: - add the general repo-local `planning` skill and its UI metadata - update docs, implementation, and PR review skills to hand planning-only work to that route - extend the repo skill tests to cover the new planning skill and handoff text Checks: - make pytest ARGS='--no-cov -q tests/unit/test_repo_agent_skills.py'
Why: - the durable branch and delivery metadata rules were only documented, so invalid branch names and planning tags could still slip through local hooks and PR checks - the review runner also needed branch-name context so the existing `pr-metadata` status could enforce the full policy without adding a new check What: - add shared branch-root and durable-metadata validation in the message standards helpers plus commit and PR validators - validate branch names before PR lookup in the pre-push hook and thread the current branch through review execution and PR workflow plumbing - extend the targeted validator, hook, executor, and workflow tests Checks: - make pytest ARGS='--no-cov -q tests/unit/test_pr_metadata_validator.py' - make pytest ARGS='--no-cov -q tests/unit/test_commit_message_validator.py' - make pytest ARGS='--no-cov -q tests/unit/test_pre_push_hook.py' - make pytest ARGS='--no-cov -q tests/unit/test_review_verification_executor.py' - make pytest ARGS='--no-cov -q tests/unit/test_review_verification_workflows.py'
Why: - docs-audit still expected the older broad forward-target wording and would drift from the updated engineering standard - the repo needed that alignment without widening pytest ownership over live docs policy What: - narrow the engineering policy-alignment expectation to the updated planning-versus-durable wording - keep the docs-audit change scoped to the existing policy-alignment rule Checks: - make pytest ARGS='--no-cov -q tests/unit/test_docs_audit.py' - make pytest ARGS='--no-cov -q tests/contract/test_standards_guards.py'
Why: - the local PR review runner accepted PR title and body overrides but did not carry a branch-name override into the review context, so the new branch validation path was not fully wired outside the GitHub workflow - direct make pytest subset runs also inherited the global coverage gate, which made narrow local reruns fail even though coverage enforcement already belongs to the quality and PR-review runners What: - add --branch-name support to tools.run_pr_review_checks and pass it into the review execution context - make the direct pytest Make target default to --no-cov, update the commit standard example, and align the docs-audit policy check with that direct-runner behavior - add regression coverage for the branch-name override path and pin the Makefile no-cov default in the standards guard suite Checks: - make docs-audit - make pytest ARGS='-q tests/unit/test_run_pr_review_checks.py tests/contract/test_standards_guards.py' - make pytest ARGS='--no-cov -q tests/contract/test_standards_guards.py tests/unit/test_run_pr_review_checks.py tests/unit/test_review_verification_executor.py tests/unit/test_review_verification_workflows.py tests/unit/test_pre_push_hook.py tests/unit/test_pr_metadata_validator.py' - make pr-review
Why: - the general planning route still read like a thin redirect, which left planning-specific standards under-specified for later agents after compaction - durable metadata validation still allowed spelled-out planning labels through, the test-surface rule conflicted with allowed synthetic validator fixtures, and the commit standards branch note contradicted the enforced branch policy What: - reshape the repo's general `planning` skill and its metadata to match the existing workflow-skill depth while carrying scope, verification, checkpoints, assumptions, and compaction recovery - extend durable metadata validation and the existing metadata suites so spelled-out planning labels are rejected on branch, commit, and PR metadata - align `AGENTS.md`, `docs/standards/implementation.md`, and `docs/standards/commits.md` with the durable metadata and branch-policy wording while still allowing synthetic validator and audit fixtures on synthetic inputs - strengthen the existing skill and metadata tests rather than adding a new enforcement surface Checks: - make pytest ARGS='-q tests/unit/test_commit_message_validator.py tests/unit/test_pr_metadata_validator.py tests/unit/test_pre_push_hook.py tests/unit/test_repo_agent_skills.py tests/unit/test_review_verification_executor.py tests/unit/test_run_pr_review_checks.py' - markdownlint docs/standards/commits.md - make pr-review-full
c-wri
force-pushed
the
docs/standards-skill-hardening
branch
from
April 19, 2026 19:24
edf2c2b to
7096140
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why:
What:
planningskill plus its mirrored metadata so planning work hands off cleanly to execution workflowsChecks:
Issue linkage:
Included checkpoints:
docs(standards): add durable metadata policydocs(skills): add repo planning routeci(metadata): enforce branch and metadata policytest(policy): align engineering policy audit wordingfix(review): wire branch-aware local review checksrefactor(planning): harden planning route and metadata guards