refactor(planning): harden planning route and metadata guards

.agents/skills/docs-authoring/SKILL.md

@@ -11,8 +11,8 @@ description: >-
 Use this skill for repo documentation and standards work.
 
 Pair it with `markdown` for syntax and low-churn Markdown editing. Invoke
-`issue-workflow` when the task adds issue templates, issue policy, or
-proactive follow-up issue handling.
+`planning` for planning-only work, and use `issue-workflow` when the task adds
+issue templates, issue policy, or proactive follow-up issue handling.
 
 ## Workflow
 
@@ -31,6 +31,8 @@ proactive follow-up issue handling.
 4. Preserve frontmatter, generated markers, and doc type boundaries.
 5. Keep tracked docs and control-plane text neutral, durable, and free of
    scratch workflow bookkeeping.
+   Keep live docs enforcement script-owned; do not add live-repo Markdown or
+   control-plane policy assertions to pytest.
 6. Validate docs changes with:
    - `make docs-check`
 7. When the change touches forward-looking target docs, titles, summaries, or

.agents/skills/implementation-workflow/SKILL.md

@@ -11,8 +11,9 @@ description: >-
 Use this skill for the normal repo implementation path.
 
 Pair it with `markdown` only when the task edits Markdown files. Invoke
-`issue-workflow` when implementation uncovers meaningful out-of-scope repo
-work that should be captured as a follow-up issue.
+`planning` for planning-only work, and use `issue-workflow` when
+implementation uncovers meaningful out-of-scope repo work that should be
+captured as a follow-up issue.
 
 ## Workflow
 
@@ -43,6 +44,8 @@ work that should be captured as a follow-up issue.
    Use the shell-safe commit/PR authoring path from
    `docs/standards/commits.md` whenever the structured metadata includes
    backticks, quotes, or other shell-sensitive text.
+10. Keep durable delivery metadata and ordinary branch names phase-free and
+    roadmap-free.
 
 ## Focus
 

.agents/skills/planning/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: planning
+description: >-
+  Start planning-only repo work with the narrow planning bundle and hand
+  execution to the owning workflow skill once the plan is settled.
+---
+
+# Planning
+
+Use this skill for the repo's general planning path. It is the repo's general planning skill, not a replacement for execution workflows.
+
+Pair it with `markdown` only when the planning task edits Markdown, and hand
+execution off to `docs-authoring`, `implementation-workflow`, `pr-review`, or
+`issue-workflow` once the plan is settled.
+
+## Workflow
+
+1. Read the narrow planning bundle first:
+   - `AGENTS.md`
+   - `docs/README.md`
+   - `docs/status/current-state.md`
+   - `docs/reference/repository-history.md`
+   - `docs/standards/implementation.md`
+   - `docs/standards/delivery-guardrails.md`
+   - `docs/standards/commits.md`
+   - `tools/docs_maintenance/cli.py`
+   - `tools/docs_maintenance/metadata.py`
+2. Confirm the planning surface, the owning execution workflow, and whether the
+   task actually needs roadmap, migration, architecture, or area-specific docs
+   before loading more context.
+3. Keep durable surfaces phase-free and roadmap-free. Keep roadmap-owned phase
+   tags confined to planning and forward-looking docs.
+4. Keep live docs enforcement in the owning script. Use synthetic strings or
+   temp repos for docs-tooling tests instead of turning pytest into the live-
+   repo docs-policy gate.
+5. Write an execution-ready plan with scope, exclusions, execution order,
+   verification inventory or TDD-first tests, bounded checkpoint commits for
+   non-trivial work, and the assumptions or defaults that affect execution.
+6. Keep the plan compaction-safe: prefer concrete file paths, commands, and
+   check ids, explain script-versus-pytest ownership when that boundary
+   matters, and avoid duplicating execution details owned by another workflow
+   skill.
+7. Keep the plan narrow enough to hand execution to an existing workflow skill
+   instead of duplicating that workflow here.
+8. After compaction or context loss, reload the same narrow planning bundle
+   before extending or revising the plan.
+
+## Focus
+
+- planning-only repo work
+- execution-ready plans with clear verification, checkpoints, and assumptions
+- routing and skill handoffs
+- docs-check ownership and validator placement
+- delivery metadata policy

.agents/skills/planning/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Planning"
+  short_description: "Start planning-only repo work with the narrow planning bundle and produce a compaction-safe execution plan."
+  default_prompt: "Use $planning to load tallylot's general planning route before drafting a compaction-safe repo plan or policy change."
+
+policy:
+  allow_implicit_invocation: true

.agents/skills/pr-review/SKILL.md

@@ -30,7 +30,11 @@ Use this skill for repeatable review passes on an active branch or draft PR.
    Do not treat green `tools.run_pr_review_checks` output as a no-findings
    decision by itself; it is only verification evidence for the current
    red-team pass.
-5. Use `issue-workflow`, `docs-authoring`, or `implementation-workflow` when
+5. Review for approved branch-root usage, phase leakage on durable metadata,
+   and docs-policy duplication in pytest.
+6. Use `planning` when a finding points to broader planning rather than a
+   narrow patch.
+7. Use `issue-workflow`, `docs-authoring`, or `implementation-workflow` when
    the repair work moves into those repo-local workflows.
 
 ## Focus

.claude/commands/implementation-checkpoint.md

@@ -29,6 +29,9 @@ Use this route before closing any non-trivial coding task.
      coverage
 5. Confirm tracked docs, templates, and control-plane text stayed neutral and
    did not pick up scratch workflow bookkeeping.
+   Confirm durable delivery metadata stayed phase-free and roadmap-free, branch
+   naming uses an approved `<root>/<slug>` root plus slug, and live docs policy
+   enforcement stayed in the owning scripts rather than duplicated in pytest.
 6. Confirm meaningful out-of-scope repo work is not stranded in notes:
    - search for an existing issue first
    - create the follow-up issue immediately when no suitable issue exists
@@ -92,6 +95,9 @@ Use this route before closing any non-trivial coding task.
     closing the older PR; if the user explicitly requested a one-time
     protected-branch repair, verify the remote branch tip afterward and return
     to PR-only flow.
+    For ordinary delivery work, confirm the active branch uses an approved root
+    from `docs/standards/commits.md` and that branch names, commit messages,
+    PR titles, and PR bodies stay phase-free and roadmap-free.
 
 If a needed structural fix is already obvious and bounded, include it in the
 same checkpoint instead of deferring it.

.claude/commands/pr-review.md

@@ -20,10 +20,17 @@ Use this route for repeatable review passes on an active branch or draft PR.
 3. Re-check every prior fix first, then inspect the next applicable changed
    file group that has not yet been re-checked in the current full review
    cycle.
+   Pay extra attention to:
+   - non-standard branch roots or nested ordinary-work branch trees
+   - roadmap or phase leakage on durable standards, control-plane, or delivery
+     metadata surfaces
+   - docs-policy duplication in pytest when the owning script should enforce it
 4. Repair every finding from that pass before starting the next pass.
    - reload the narrow repo guidance for each repaired area using `AGENTS.md`,
      its task-routing table, and the owning roadmap, architecture, migration,
      or delivery docs identified by that route or by repo search hints
+   - when a finding implies broader planning rather than a narrow local patch,
+     use the repo-local `planning` skill before picking the execution workflow
    - add or tighten tests, docs, automation, and validation where the fix
      belongs instead of leaving the repair in prose alone
    - when a meaningful finding should stay out of the active PR, search for an

.github/workflows/pr-review.yml

@@ -104,13 +104,15 @@ jobs:
         env:
           BASE_SHA: ${{ github.event.pull_request.base.sha }}
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          BRANCH_NAME: ${{ github.event.pull_request.head.ref }}
           PR_TITLE: ${{ github.event.pull_request.title }}
         run: |
           uv run python -m tools.run_review_check \
             --check-id pr-metadata \
             --trigger pull_request \
             --base-sha "$BASE_SHA" \
             --head-sha "$HEAD_SHA" \
+            --branch-name "$BRANCH_NAME" \
             --pr-title "$PR_TITLE" \
             --pr-body-file pr-body.md
 

AGENTS.md

@@ -33,7 +33,8 @@ Do not pre-load every repo doc by default.
 | ---- | ---- |
 | Code placement, typing, modularization, naming | `docs/standards/engineering.md` |
 | Active implementation execution discipline | `docs/standards/implementation.md`, `docs/standards/commits.md` |
-| Repo standards, docs placement, doc authoring rules, or agent-default enforcement changes | `AGENTS.md`, `docs/README.md`, `docs/status/current-state.md`, `docs/reference/repository-history.md`, `docs/standards/implementation.md`, `docs/standards/commits.md`, `tools/docs_maintenance/cli.py`, `tools/docs_maintenance/metadata.py` |
+| Repo standards, docs placement, doc authoring rules, or agent-default enforcement changes | `AGENTS.md`, `docs/README.md`, `docs/status/current-state.md`, `docs/reference/repository-history.md`, `docs/standards/implementation.md`, `docs/standards/delivery-guardrails.md`, `docs/standards/commits.md`, `tools/docs_maintenance/cli.py`, `tools/docs_maintenance/metadata.py` |
+| Planning-only repo work, routing design, skill design, docs-check ownership, validator placement, or delivery metadata policy | `AGENTS.md`, `docs/README.md`, `docs/status/current-state.md`, `docs/reference/repository-history.md`, `docs/standards/implementation.md`, `docs/standards/delivery-guardrails.md`, `docs/standards/commits.md`, `tools/docs_maintenance/cli.py`, `tools/docs_maintenance/metadata.py` |
 | Issue templates, issue-writing policy, or proactive follow-up issue creation | `AGENTS.md`, `docs/standards/issues.md`, `docs/standards/implementation.md`, `docs/standards/delivery-guardrails.md`, `docs/standards/commits.md`, `.claude/commands/issue-workflow.md` |
 | Delivery guardrails, protected-branch behavior, or agent-assisted Git operations | `docs/standards/delivery-guardrails.md`, `docs/standards/commits.md`, `tools/audit_delivery_guardrails.py` |
 | PR review or review-loop recovery | `docs/standards/delivery-guardrails.md`, `docs/standards/implementation.md`, `docs/standards/commits.md`, `.claude/commands/pr-review.md` |
@@ -62,6 +63,11 @@ Do not pre-load every repo doc by default.
 - When editing repo standards, automation, or other control-plane files, use
   the repo-local workflow for the active area and reload the narrow repo
   guidance listed in this file before editing.
+- Planning-only repo work should start with the repo-local `planning` skill,
+  then hand execution off to the owning workflow skill.
+- Route phase-tag policy and docs-check-boundary work through the standards
+  path; keep live docs enforcement in the owning script rather than duplicating
+  that policy in pytest.
 - Keep live repo document checks in script-owned verification surfaces, not in
   pytest:
   - `docs-maintenance` owns generated docs sections, metadata, links, and
@@ -75,6 +81,14 @@ Do not pre-load every repo doc by default.
 - Keep pytest coverage for docs tooling on synthetic strings or temp repos, not
   on the live repo Markdown tree or live control-plane prose.
 - Keep tracked docs, templates, and control-plane text neutral and durable.
+- Planning and forward-looking docs may use roadmap-owned ephemeral tags when
+  the planning surface itself owns them, but durable control-plane, delivery
+  metadata, branch names, code, tooling, filenames, and generated durable
+  examples must stay phase-free and roadmap-free.
+- Keep ordinary test names, assertions, and examples phase-free and
+  roadmap-free. Synthetic tooling fixtures may intentionally mention forbidden
+  roadmap or phase labels only when they are exercising validator or audit
+  behavior on synthetic strings or temp repos.
 - Keep current-state docs accurate to the implemented runtime, and keep
   forward-looking docs detailed enough to implement from without inventing
   missing stage structure later.

Makefile

@@ -61,7 +61,7 @@ help:
 		'  make tool TOOL=docs_maintenance ARGS="sync --check"  Run any tools.<module> entrypoint.' \
 		'' \
 		'Individual tools:' \
-		'  make pytest ARGS="tests/unit/test_x.py -q --no-cov"' \
+		'  make pytest ARGS="tests/unit/test_x.py -q"' \
 		'  make ruff ARGS="check ."' \
 		'  make mypy ARGS="src tools repo_support"' \
 		'  make pyright ARGS=""' \
@@ -143,7 +143,7 @@ pylint:
 	pylint $(ARGS)
 
 pytest:
-	pytest $(ARGS)
+	pytest --no-cov $(ARGS)
 
 actionlint:
 	actionlint $(ARGS)

docs/standards/commits.md

@@ -50,6 +50,44 @@ Subject rules:
 - no trailing period
 - do not use generic summaries such as `cleanup`, `misc fixes`, or
   `update branch`
+- do not use roadmap or phase labels on durable delivery metadata surfaces;
+  use durable repo-area or behavior wording instead
+
+## Standard Branch Tree
+
+Ordinary delivery work uses this branch format:
+
+```text
+<root>/<slug>
+```
+
+Rules:
+
+- use exactly one approved top-level root
+- use exactly one lowercase kebab-case slug after the root
+- use lowercase ASCII only
+- do not add extra slash nesting
+- do not use roadmap or phase labels in either segment
+- do not invent new ordinary-work roots such as `control-plane`
+
+Approved roots:
+
+- `docs`
+- `chore`
+- `ci`
+- `build`
+- `feat`
+- `fix`
+- `refactor`
+- `test`
+- `repair`
+
+Notes:
+
+- this policy governs every ordinary delivery branch that will ship through the
+  normal PR flow
+- `backup/*`, `codex/*`, and similar ad hoc roots are not approved ordinary
+  delivery branches
 
 ## Body Template
 
@@ -128,6 +166,8 @@ Protected-branch rule:
 - if a protected-branch repair exception is explicitly requested, limit that
   exception to the exact repair action, verify the remote branch tip
   immediately afterward, and restore PR-only flow before continuing
+- active ordinary-work branch names must match the approved
+  `<root>/<slug>` tree and stay phase-free plus roadmap-free
 
 PR title rules:
 
@@ -136,6 +176,7 @@ PR title rules:
   and, for a single-commit PR, the squash subject becomes
   `<pr title> (#<pr number>)`
 - do not use generic titles such as `update branch`, `cleanup`, or `misc fixes`
+- do not use roadmap or phase labels in the title
 
 PR body rules:
 
@@ -169,6 +210,8 @@ PR body rules:
   issue-closing keywords unless the user explicitly requests otherwise
 - for a one-commit PR, still list that single commit under
   `Included checkpoints:`
+- do not use roadmap or phase labels in PR bodies; keep delivery metadata
+  phrased in durable repo-area and behavior terms
 
 Merge method rules:
 
@@ -288,6 +331,15 @@ make validate-commit-message ARGS='.git/COMMIT_EDITMSG'
 make validate-commit-message ARGS='--rev-range HEAD~3..HEAD'
 ```
 
+Validate branch names and PR metadata with the repo tooling when needed:
+
+```bash
+python -m tools.validate_pr_metadata \
+  --branch-name docs/standards-skill-hardening \
+  --title 'docs(commits): harden durable metadata policy' \
+  --body "$(cat /tmp/pr-body.md)"
+```
+
 When structured commit messages or PR bodies include backticks, quotes, or
 other shell-sensitive text, use file/stdin authoring forms rather than inline
 `-m` or `--body` arguments so the metadata stays literal. In this repo, use the
@@ -336,10 +388,10 @@ changing CI, packaging, release, or other workflow areas where the local
 verification pass should mirror the final non-draft PR suite before handoff.
 Add `--pr-title`
 plus `--pr-body-file` when you also want the full review run to validate the
-current branch PR title, body, and `Included checkpoints:` list against the
-branch history. Treat `tools.run_quality_gates --full-tests` as an explicit
-full-suite escape hatch rather than the normal agent close-out path, and avoid
-it unless there is a specific reason to use the override. Do not run
+current branch name, PR title, body, and `Included checkpoints:` list against
+the branch history. Treat `tools.run_quality_gates --full-tests` as an
+explicit full-suite escape hatch rather than the normal agent close-out path,
+and avoid it unless there is a specific reason to use the override. Do not run
 `tools.run_quality_gates --full-tests`
 immediately before `tools.run_pr_review_checks --mode full`; the full
 PR-review runner already includes the full quality gate pass plus the extra
@@ -369,7 +421,7 @@ that exact file before treating the checkpoint as closed:
 
 ```bash
 make pylint ARGS='<touched-file>'
-make pytest ARGS='-q --no-cov <touched-test-file>'
+make pytest ARGS='-q <touched-test-file>'
 git show HEAD:<path>
 ```
 

docs/standards/delivery-guardrails.md

@@ -44,6 +44,12 @@ when the higher-layer control is available.
 ## Default Delivery Posture
 
 - protected branches are PR-only branches
+- ordinary delivery branches use the approved `<root>/<slug>` tree from
+  `docs/standards/commits.md`
+- active branch names, commit messages, PR titles, and PR bodies stay
+  phase-free and roadmap-free because they are durable delivery metadata
+- planning and forward-looking docs may still use roadmap-owned ephemeral tags
+  where the planning surface itself owns that reference
 - pull requests open as draft by default
 - a PR becomes ready for review only after the full issue-finding hardening
   loop yields no new meaningful findings
@@ -144,6 +150,13 @@ Encode the repo's delivery rules in versioned artifacts:
 - contract tests that pin the standards
 - templates that match the validators
 
+Keep live docs policy ownership split in code as well as prose:
+
+- tests verify tooling logic and code behavior
+- tests do not serve as the live-repo enforcement surface for docs policy
+- add new live-repo docs assertions to the owning script, not to pytest
+- keep pytest coverage for docs tooling synthetic or temp-repo based
+
 When a delivery failure repeats or has high repair cost, add or tighten a
 machine-checkable guard instead of only adding more prose.
 
@@ -276,11 +289,11 @@ push-to-mainline CI.
 
 - the `commit-messages` PR status validates the branch commit-message range and
   PR metadata on pull requests only
-- the `pr-metadata` PR status validates the pull request title, body, and
-  checkpoint linkage as its own visible required status
+- the `pr-metadata` PR status validates the active branch name, pull request
+  title, body, and checkpoint linkage as its own visible required status
 - the repo-installed `pre-push` hook mirrors `tools.validate_pr_metadata`
-  against the current open pull request before push when `gh pr view` can
-  resolve PR metadata for the branch
+  against the current branch name first, then the current open pull request
+  before push when `gh pr view` can resolve PR metadata for the branch
 - the `plan-pr-review` workflow job audits the diff with
   `tools.audit_pr_review`, publishes the selected checks for transparency, and
   keeps the human review routing visible while choosing planned mode

docs/standards/engineering.md

@@ -904,7 +904,10 @@ Rules:
   docs-maintenance-owned structure, not target-naming rules
 - required `naming_scope` frontmatter/default behavior is
   docs-maintenance-owned frontmatter validation, not target-naming drift
-- forward-target contract docs must stay free of transient planning language
+- planning and forward-looking docs may use roadmap-owned ephemeral tags when
+  the planning surface itself owns that reference
+- durable standards, control-plane, and delivery metadata surfaces must stay
+  free of roadmap-owned phase tags and other ephemeral planning labels
 - keep frontmatter summaries and generated `docs/README.md` blurbs
   content-first; do not lead with page-role or authority-first labels that
   foreground governance instead of the held contract