[kyle-sexton]

Refs: melodic-software/claude-code-plugins#6085

Summary

Adds the team working rules (grounding a recommendation, Basis: labels, bulk mutation, less-is-more, plain agent-run commands) to conventions/engineering/. A new engineering-standards component syncs the affected files plus a thin index into docs/standards/ of every target that already takes pr-body-contract-rule: .github, ci-runner, ci-workflows, claude-code-account-rotation, claude-code-plugins, codex-plugins, dotfiles, github-iac, medley and provisioning. The index follows the standards contract 1.0.2 (claude-code-plugins docs/conventions/standards/), so planning and review skills load only the files whose Applies when row matches the task.

Fix

• Extended six existing files, each with its own part: source-authority-tiers.md (grounding a recommendation), documentation-and-citations.md (Basis: labels), concise-prose.md (literal over figurative wording), simpler-code.md (build only what someone acts on, no needless bottleneck, precedent is not a reason to keep something), reference-dont-duplicate.md (history lives in version control), deterministic-work-execution.md (plain agent-run commands).
• Added bulk-mutation.md (scope sets blast radius, count first, unattended runs still need consent); no existing file covered count-before-act.
• Added the index source components/engineering-standards/standards-index.md and the engineering-standards component, mapping all eight files to docs/standards/, and added it to managed: for the 10 targets.
• Rewrote every relative link in the seven synced files as an absolute https://github.com/melodic-software/standards/blob/main/... URL. A relative link would point at a file the target lacks and fail its lychee lane. Each target path and anchor was checked against origin/main.
• The index is managed: the engine has no seed-once mode. A target that wants its own layout relocates the team layer through .claude/standards.yaml standards_dir, or moves the component to locally-owned.
• Added the eight new destinations to both managed-files-guard.yml and managed-files-guard-fleet.yml path lists.
• conventions/README.md records the sync in "How this is consumed"; conventions/engineering/README.md lists bulk-mutation.md.

Effect on merge: the next sync opens a PR in each of the 10 targets adding docs/standards/ (8 files). None of them has docs/standards/ today (checked with gh api on each default branch). dotfiles' .chezmoiignore already ignores docs, so nothing renders into home directories.

Verification

• distribution/sync-manifest.sh validate: valid (43 components, 13 targets).
• distribution/sync-manifest.sh plan --targets melodic-software/claude-code-plugins: lists docs/standards/README.md plus the seven standards files.
• bash distribution/sync-manifest.test.sh: pass.
• bash components/managed-files-guard/managed-files-guard.test.sh: pass, 0 failures.
• node --test components/runner-policy/runner-policy.test.mjs: 298 pass, 0 fail; npm run lint:runner-policy: pass.
• check-claude-settings-targets.test.sh, lychee.test.sh, code-review-rules.sh file: pass.
• lychee --offline --config lychee.toml over all markdown: 0 errors.
• markdownlint, typos, editorconfig-checker, gitleaks (pre-commit and manual): clean.
• The index has one Applies when row per synced file (7).

Related

• docs(upstream): re-audit the pstack record and evaluate the five pstack lanes it never assessed claude-code-plugins#6085: the effort this belongs to (Refs only; this PR does not close it).
• Merge order across the effort: the github-iac labels PR, then this PR, then the claude-code-plugins integration PR, which adds a thin AGENTS.md pointer at docs/standards/ once this sync lands.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EmhpzPTBtpF5XxAUFa2Fr9

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-11T06:06:47.950724Z	d7627c9	Draft marked ready

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

Claude finished @kyle-sexton's task in 1m 9s —— View job

---

Security review: no findings

• Gather context (PR diff, changed files)
• Run skip-gate check
• Review changed files for security-relevant surface
• Check instruction-surface deletions against protected classes
• Report findings or clear bill of health

Scope reviewed (git diff origin/main...HEAD, 13 files, +189/-23): new/edited prose convention docs under conventions/engineering/, a new standards index (components/engineering-standards/standards-index.md), conventions/README.md, and CI-config path-list additions in distribution/sync-manifest.yml, components/managed-files-guard/managed-files-guard.yml, and components/managed-files-guard/managed-files-guard-fleet.yml.

Analysis:

• This is documentation-and-manifest content only — no executable code, no application logic, no auth/authz paths, no input handling, no secrets or tokens introduced. Scanned the diff for exfiltration/injection patterns (curl, eval, tokens, secrets, suspicious URLs) with nothing matching outside an unmodified pre-existing README line.
• distribution/sync-manifest.yml: the new engineering-standards component maps known, literal source paths to known, literal destination paths (docs/standards/...) for a fixed list of targets already in the manifest. No path-traversal-shaped values, no dynamic/templated paths.
• managed-files-guard*.yml: the diff only adds 8 new paths to the guarded/managed-file lists — this tightens coverage, it doesn't loosen any existing guard.
• Instruction-surface check: several touched files are standing-instruction prose read by agents (conventions/engineering/*.md, conventions/README.md). I checked every changed line for deletion, narrowing, or softening of an existing rule. The content diff is additive (new sections: "Keep agent-run commands plain," "Count first, then act," "Label the basis of a recommendation," etc.) or cosmetic (rewriting relative markdown links to absolute https://github.com/.../blob/main/... URLs so the synced copies resolve correctly in target repos that lack the other files — same target, same meaning, not a control change). No rule was removed or weakened, so no instruction-exception-register match. (Note: docs/conventions/instruction-exception-register/README.md is not present in this checkout, so this is reasoning by consequence per the skill's fallback, not a lookup against the register text itself.)

No CRITICAL, IMPORTANT, or SUGGESTION security findings on this PR.

[claude]

Claude finished @kyle-sexton's task in 5m 53s —— View job

---

CI code review — PR #765

• Gather context (diff vs origin/main, AGENTS.md, REVIEW.md, distribution/governance-process.md, docs/component-lifecycle.md)
• Review changed files for correctness and alignment
• Post findings

Scope checked

13 changed files: the 6 extended conventions/engineering/*.md files, new bulk-mutation.md, the new engineering-standards component (distribution/sync-manifest.yml, components/engineering-standards/standards-index.md), both managed-files-guard*.yml path lists, and the two README.md index updates.

What held up:

• The 10 targets that gained engineering-standards are exactly the targets that already carry pr-body-contract-rule — verified by reading every target entry in distribution/sync-manifest.yml, no omission or extra.
• Every relative link inside the 7 synced files was rewritten to an absolute github.com/melodic-software/standards/blob/main/... URL — confirmed no ](<relative>.md) links remain in those 7 files, and every linked path/anchor (enforceability-tiers.md#routing-a-recurring-finding, ../review/testing.md#verification-honesty, documentation-and-citations.md#time-bound-external-claims-need-a-recheck-trigger, etc.) exists.
• Both managed-files-guard path lists add the same 8 docs/standards/* destinations, correctly byte-sorted into the existing ASCII-sorted list.
• I could not run distribution/sync-manifest.sh validate, the managed-files-guard.test.sh suite, markdownlint, or lychee myself (no tool permission to execute project scripts in this session), so the Verification section's listed command results are author-claimed and unverified by me, not independently confirmed.

Finding

Missing required cross-doc-reconciliation self-attestation for a normative-doc change.
distribution/governance-process.md#L46-L76 makes this repo's own process explicit: before a change to a normative doc (any file in conventions/ that another doc cites or assumes) merges, "the author runs the check and states in the pull request that no other normative doc was left contradicting the change," and that this is "required, not optional, precisely because nothing else backstops it" (no mandatory second reviewer in this org). AGENTS.md's own Code Review Rules list restates this as a rule CI does not enforce.

This PR modifies six normative docs (source-authority-tiers.md, documentation-and-citations.md, concise-prose.md, simpler-code.md, reference-dont-duplicate.md, deterministic-work-execution.md) and adds a seventh (bulk-mutation.md), each introducing a new rule (e.g. "Label the basis of a recommendation," "No bottleneck without a reason," "History lives in version control," "Keep agent-run commands plain"). Neither the PR body nor the commit message contains the required attestation that no other normative doc was checked and left contradicting these additions. I ran a spot cross-reference search myself (serialization/locking, sleep/polling, literal-vs-figurative wording, PowerShell-timing) and found no actual contradiction, but the self-review statement this repo's governance doc requires as the sole control is still absent from the PR, so the control itself was skipped even though the check appears to have held.

Fix this →

No other correctness, mapping, or link-integrity issues found in the diff.

[github-actions]

claude-security-review has reviewed this pull request through cef5f2f; a later push is reviewed from there.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d7627c9e3b

ℹ️ 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".

[github-actions]

claude-review has reviewed this pull request through cef5f2f; a later push is reviewed from there.

[claude]

Claude finished @kyle-sexton's task in 2m 40s —— View job

---

Review in progress

• Gather context (incremental diff, PR context)
• Invoke /review:code-review criteria
• Adversarial verification of candidate finding(s)
• Post findings as inline PR comments
• Final summary

Reviewing only the incremental change since d7627c9 (per lane scope): components/engineering-standards/README.md, conventions/engineering/documentation-and-citations.md, conventions/engineering/reference-dont-duplicate.md.

[claude]

Claude finished @kyle-sexton's task in 1m 1s —— View job

---

Security review (incremental): no findings

• Gather context (.claude-lane/incremental.diff, prior review state at d7627c9)
• Run skip-gate check, including instruction-surface lens on narrowed rules
• Review changed files for security-relevant surface
• Report findings or clear bill of health

Scope reviewed (this lane last reviewed d7627c9; only what changed since then, 3 files, +11/-1 net across two modified files plus one new file):

• components/engineering-standards/README.md (ADDED) — the component's admission-evidence record.
• conventions/engineering/documentation-and-citations.md — scopes the "Label the basis of a recommendation" rule to presentations made "from now on" (replies, PR/issue bodies, decision records), explicitly excluding pre-existing tracked prose and convention documents, which rest on their sources footer instead.
• conventions/engineering/reference-dont-duplicate.md — exempts evidence records (a manifest's adoption/rollout/canary notes, ADRs, admission evidence, changelogs) from the "History lives in version control" ban on dated history asides, where the date is itself the evidence a decision rests on.

Analysis:

• components/engineering-standards/README.md is prose only — an admission-evidence record with no executable content, no secrets, no paths with traversal-shaped values, and no new trust boundary. Not security-relevant.
• The two convention-doc edits each narrow a standing instruction (the Basis: label rule's scope, and the history-note ban's scope), which puts them in the instruction-surface lens rather than the prose-only skip path. docs/conventions/instruction-exception-register/README.md is not present in this checkout, so per the skill's fallback this is reasoning by consequence, not a lookup against the register text — noting that explicitly rather than skipping the check.
• Consequence check: both rules are documentation/epistemic-hygiene conventions (traceability of a recommendation's basis; avoiding stale duplicated history notes), not technical controls — no authn/authz gate, no input validation, no secret handling, no injection-relevant behavior is gated by either rule. Narrowing their scope changes what a human reviewer or future convention-reading agent treats as a required citation or a disallowed comment; it does not open a code-execution, data-access, or credential-handling path, and no other mechanism in the tree was relying on the pre-narrowing wording to block an action. Both edits directly and only resolve the two correctness findings from the earlier Codex review on this PR (the universal Basis: requirement the catalog itself violated, and the unconditional history-note ban that contradicted required evidence-keeping elsewhere in the repo) — the narrowing is a reconciliation of a self-contradiction, not a removal of a safeguard.
• No new or modified manifest paths, guard lists, workflow files, or executable code in this incremental diff (distribution/sync-manifest.yml and both managed-files-guard*.yml are unchanged since d7627c9, already reviewed then).

No CRITICAL, IMPORTANT, or SUGGESTION security findings in the incremental scope.