feat(executing-a-branch-plan): add code-quality-principles reference

[tvna]

Summary

Adds skills/executing-a-branch-plan/references/code-quality-principles.md (7 gitapex-filtered code-design principles) and wires it into SKILL.md Step 6 (per-task implementation, all 7) and Step 8 (aggregate refactor pass, one cross-task re-check of "Migrate Callers Then Delete Legacy APIs").

Facts

• executing-a-branch-plan is the only skill in gitapex's merge pipeline authorized to write code; its Step 6/8 had no code-design-principle catalogue to apply (issue body).
• Direct inspection of skills/executing-a-branch-plan/references/ confirmed neither state-management-quality.md nor mechanism-fit.md (cited by the issue as this skill's own existing Step 6/8 reference-file precedent) actually exists in this skill's own directory, and no "if available, apply" phrasing appears in this skill's SKILL.md -- both belong to sibling skills (evaluating-skill-quality, evaluating-deterministic-gate-quality). This skill's own real convention for a bundled reference is an unconditional bracketed link inline in prose; the two added sentences use that convention instead.
• skills/evaluating-skill-quality/scripts/gitapex_check_skill_shape.py against the modified SKILL.md: 58/58 checks PASS, including links-inside-skill/anchor-targets-resolve for the new file and its Step 8 anchor link.
• Full pytest suite (skill-shape-checker unit tests, skill-audit-disclosure gate tests, fixture-coverage gate tests): all green, no regressions.

Assumptions

• The issue's "if available, apply X" citation is a stale/inaccurate precedent reference, not a hard requirement on exact phrasing -- corrected to this skill's own actual reference-link convention (Facts above); the underlying acceptance criterion (one sentence per step, pointing at the new file) is unchanged.

Risk / blast radius

Prose-only, additive change: one new reference file, two one-sentence pointers in an existing SKILL.md. No new Step, no new Stop-boundary bullet, no new named dispatch branch, no change to the Execution log structure, StageDeviated dispatch, or the terminal handoff to drafting-a-pr-to-merge (per issue #1388's own Constraints). No runtime/code dependency.

Rollback

Revert this PR; both edits are prose-only with no downstream code dependency.

Verification

Criterion	Interpretation	Planned ops	Proof method	Result
references/code-quality-principles.md exists with exactly the 7 named principles	Each principle carries a one-line governing statement and a warning-sign example, no additional principles beyond the filtered set	Author the new reference file	Direct read confirms all 7 principles are present, none of the excluded 14 appear, and each has both required parts	PASS
Step 6 references the new file for per-task implementation	Uses this skill's own actual unconditional-reference-link convention (corrected from the issue's inaccurate "if available" citation -- see Facts)	Add one sentence to Step 6 pointing at the new reference file	Direct read confirms the sentence exists	PASS
Step 8 specifically re-checks Migrate Callers Then Delete Legacy APIs	Distinguishes this principle's cross-task nature from the other 6, which are per-task (Step 6)	Add one sentence to Step 8 naming this specific principle for its own cross-task consistency pass	Direct read confirms the sentence exists and names only this one principle	PASS
No CLAUDE.md content is restated or duplicated in the new reference file	The 7 principles are limited to the set that does not overlap CLAUDE.md sections 1-5	Cross-check the drafted principle text against CLAUDE.md's own current sections before finalizing	Direct side-by-side re-read against this repository's current CLAUDE.md sections 1-5 found no restated sentence	PASS

Checklist

• Tests pass locally
• Docs updated if behavior changed (this PR is the docs/skill-definition update)
• Issue number cited in every commit
• If this PR adds/modifies a skills/*/SKILL.md, ..., a ## Skill audit evidence section discloses the required verdicts/waivers
• N/A -- no evals/*/split.md Kept-edit-log entry added
• N/A -- no new Stop-boundary bullets or named dispatch branches added

Skill audit evidence

• battle-testing-a-skill: WAIVED: still additive-only after the Step 8 fix round below -- no new Stop-boundary bullet, no new named dispatch branch, no frontmatter description: change, no new mechanism/label/event-type introduced, no change to any input-handling or trust-boundary logic (this audit's own focus). Matches this repository's own accepted "docs-only, no behavioral change" waiver precedent, distinct from the architecturally significant change (a new label mechanism, new escalation/hang-detection logic) that warranted the full isolated-dispatch audit in issue fix(executing-a-branch-plan): Execution log fails state-management-quality.md's Axis 2/4/6 -- 5 designed fixes not yet implemented #1339/PR fix(executing-a-branch-plan): implement Axis 2/4/6 state-management fixes for Execution log #1342.
• evaluating-skill-quality: WELL-FORMED-NOT-MATURE (real verdict, not waived -- run twice via genuinely isolated claude -p dispatch, per that skill's own Isolation verification registry, against commits 624ca64b and abfe430b). Round 1 found two gaps this PR itself introduced (dimension 2: unjustified sediment in the new reference file's header; dimension 4: Step 6's new instruction had no stated delivery route to the dispatched task agent that must apply it) -- both fixed, both independently re-confirmed clear in round 2's fresh, full walk. Round 2 additionally surfaced three gaps (dimensions 5, 6, 7) confirmed via git diff origin/main...HEAD to predate this PR entirely -- disclosed in ## Independent review verdict below and filed as follow-up rather than bundled into this issue's own explicitly scoped two-file change.

Full detail on both rounds is in the Execution log below.

Related Issue

Closes #1388

Acceptance Criteria Map

Criterion	Interpretation	Planned ops	Proof method	Residual risk
references/code-quality-principles.md exists with exactly the 7 named principles	Each principle carries a one-line governing statement and a warning-sign example, no additional principles beyond the filtered set	Author the new reference file	Direct read confirms all 7 principles are present, none of the excluded 14 appear, and each has both required parts	None identified beyond ordinary wording risk
Step 6 references the new file for per-task implementation	This skill's own actual reference-link convention, not the issue's inaccurate "if available" citation (see Facts)	Add one sentence to Step 6 pointing at the new reference file	Direct read confirms the sentence exists	None identified
Step 8 specifically re-checks Migrate Callers Then Delete Legacy APIs	Distinguishes this principle's cross-task nature from the other 6, which are per-task (Step 6)	Add one sentence to Step 8 naming this specific principle for its own cross-task consistency pass	Direct read confirms the sentence exists and names only this one principle, not a duplicate of Step 6's full list	None identified
No CLAUDE.md content is restated or duplicated in the new reference file	The 7 principles are limited to the set that does not overlap CLAUDE.md sections 1-5	Cross-check the drafted principle text against CLAUDE.md's own current sections before finalizing	A reviewer reading both CLAUDE.md and the new file side by side finds no restated sentence	Wording proximity is a judgment call; a principle stated in different words but the same substance as an existing CLAUDE.md line should still be caught

Execution log

• PlanApproved{run_id: d2daee6} -- Branch Plan approved via in-session operator confirmation (the operator's opening instruction: create this PR and drive it to just before merge), branch published at commit d2daee6 (task-list file: docs/superpowers/plans/2026-08-29-claude-gitapex-pr-1388-yseltw.md).
• TaskCompleted{run_id: d2daee6, task_id: A, commit_sha: 5abbf91c} -- code-quality-principles.md authored; SKILL.md Step 6/8 wired.
• TaskCompleted{run_id: d2daee6, task_id: step8-review, commit_sha: b6c26307} -- Step 8's mandatory two-layer review (fresh refactor/simplify + adversarial dispatches) found 7 real, independently-convergent issues: principles 5 (Model the Domain) and 7 (Foundational Thinking) misrendered against cursor/plugins/pstack's actual definitions (confirmed via primary-source web search) and landing on already-excluded ground; the preamble's "14 excluded" count not adding up (7+13=20, not 21) and misattributing the dedup check; Step 8's own new sentence assigning a behavior-affecting check to the refactor/simplify sub-step, which references/refactor-and-review-gate.md bars from exactly that; Boundary Discipline's warning sign reading as contradicting diagnosing-a-failure's layered-validation technique and CLAUDE.md section 4's defense-in-depth rule; Step 6's parenthetical narrower than the issue's own unconditional criterion; and a stale "five"-reference-file count after this PR's own sixth reference file landed. All 7 fixed in this commit; gitapex_check_skill_shape.py 59/59 PASS, full pytest suite 516 passed.
• origin/main advanced 7 commits during Step 8's review round; merged cleanly (commit 624ca64b), no conflict, no re-verification needed per this skill's own "a clean merge needs no further action" rule.
• TaskCompleted{run_id: d2daee6, task_id: dpm-step8-round1, commit_sha: 208dfa97} -- drafting-a-pr-to-merge Step 8: dispatched evaluating-skill-quality (isolated claude -p) against commit 624ca64b. Verdict: WELL-FORMED-NOT-MATURE, two gaps both introduced by this PR -- dimension 2 (sediment in code-quality-principles.md's header) and dimension 4 (Step 6's new instruction had no delivery route to the dispatched task agent). Both fixed in commit 208dfa97: header trimmed to one sentence pointing at a new spec.references decision entry in metadata/gitapex.yaml; Step 6 now states each task's dispatch prompt cites the reference's path in-band, same as Decision 17's exclusion list.
• TaskCompleted{run_id: d2daee6, task_id: dpm-step8-round2, commit_sha: abfe430b} -- drafting-a-pr-to-merge Step 8 re-run (mandatory re-confirmation, stale verdict not carried forward): fresh isolated evaluating-skill-quality dispatch against commit abfe430b, no prior-verdict framing. Both round-1 gaps independently re-confirmed clear. Fresh full walk additionally found three gaps confirmed (via git diff origin/main...HEAD) to predate this PR: dimension 5 (the origin/main-drift-check procedure is inlined in Step 6 rather than deferred to execution-and-dispatch.md -- correct content, wrong location), dimension 6 (no guard against a second concurrent invocation of this skill against the same Branch Plan; metadata/gitapex.yaml's executionRequirements.tools.write/shell: [] contradicts the skill's own real commit/push/shell-out behavior -- the drift scanner's two heuristic findings are real, its one deterministic finding is a checker false positive, confirmed by direct read of every match), dimension 7 (gitapex_check_task_bash_safety.py's disclosed duplication of hooks/gitapex_check_bash_safety.py has no drift test between the two). None are within issue feat(executing-a-branch-plan): add a code-quality-principles reference (7 principles from pstack, gitapex-filtered), wire into Step 6/8 #1388's own Constraints (two named files, no new Step); filed as follow-up tasks rather than bundled into this PR.

Independent review verdict

• Verdict: CLEAN
• Verified commit: abfe430

Both gaps this PR itself introduced (evaluating-skill-quality dimensions 2 and 4, round 1 against commit 624ca64b) are fixed and independently re-confirmed clear in round 2 (a fresh, genuinely isolated dispatch against the current head, no prior-verdict framing carried in). GitHub Copilot review was requested twice (request_copilot_review, against 624ca64b and abfe430b); Copilot review is Comment-only with no pass/fail signal of its own, and no comment had posted by the time this verdict was recorded -- disclosed rather than treated as full outer-layer coverage.

Round 2's fresh full walk additionally surfaced three gaps (dimensions 5, 6, 7) independently confirmed, via git diff origin/main...HEAD, to predate this PR entirely -- not introduced by the two-file change issue #1388 scoped this PR to, and not bundled in here. See the Execution log above for detail; each is being filed as a separate follow-up task.

Merge gate: independent review

This PR is also subject to the independent-review-pending required
status check (see .github/workflows/independent-review-pending.yml /
.github/scripts/gitapex_gate_independent_review_pending.py). It stays
pending/failing until a ## Independent review verdict section naming
this PR's current head commit is recorded in this body --
drafting-a-pr-to-merge's own Step 8 records it once its independent
review completes. There is nothing for you to do here now: do not
pre-fill this section yourself, and do not remove this note.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: dd5cd69c-0aff-4f51-92cc-4d632e1b34fb

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.57%. Comparing base (9ae5bfb) to head (abfe430).
⚠️ Report is 54 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1458   +/-   ##
=======================================
  Coverage   99.57%   99.57%           
=======================================
  Files         127      127           
  Lines       22539    22539           
  Branches     2766     2766           
=======================================
  Hits        22443    22443           
  Misses         96       96           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.