Strengthen guidance so agents consider partials when introducing duplicated content

[williamthorsen]

Problem

During implementation of #537 (unify artifact frontmatter), the orchestrated coder introduced ~25 byte-identical copies of the PR-resolution dispatch snippet across skill and subagent files. The orchestrated reviewers did not flag the duplication; the code-simplification-reviewer flagged it but its recommendation (replace with pointers to pr-resolution.md) was rejected on plan-doctrine grounds (the plan deliberately chose verbatim embedding because LLM agents don't reliably follow doc indirection at execution time). The doctrine premise — "verbatim in installed output requires verbatim in source" — was actually false in this codebase: the partials feature (#571, commit 3a980f9d) lets authors maintain one source while preserving verbatim installed output. No agent in the pipeline raised partials as an option.

The user caught this manually after wrap-up. Had they not, the duplication would have shipped and started drifting immediately.

Context

The partials feature (packages/agents/content/_partials/README.md is the canonical reference) supports:

• Cross-cutting partials in content/_partials/
• Subagent-shared partials in content/subagents/_partials/
• Skill-shared partials in content/skills/_partials/
• Skill-internal partials in content/skills/{name}/_partials/

The expander inlines partials at install time. The installed .md output is byte-identical to a verbatim hand-copied version — meaning partials are the correct DRY mechanism in this codebase even when "verbatim execution context" is a requirement. Several subagents already use the feature (e.g., aspect-code-reviewer.md includes _partials/review-writes-scaffold.md).

The lapse happened at multiple layers (planner, coder, reviewers, plan-doctrine override), but every relevant orchestrated subagent already has a step 1 to "Read ~/.agents/AGENTS.md, .agents/PROJECT.md." This means PROJECT.md is the single touchpoint where a proactive rule reaches all layers. Among the reviewers, only the simplifier did flag duplication and recommend a remediation — but the recommendation was wrong (pointer-indirection instead of partials), so it needs reasoning guidance beyond what PROJECT.md alone provides.

A separate ticket (#588) tracks the frontmatter-specific DRY decision; this ticket is purely about avoiding the next similar lapse.

Solution

Two complementary additions:

1. Project-scoped guidance in .agents/PROJECT.md — add a "Content authoring" subsection inside the existing ### Agents section (placed after "Content directory," before "The orchestration system"). The subsection notes that packages/agents/content/ supports partials (with a pointer to _partials/README.md) and states the rule:

   Content that appears identically in 2+ skill/subagent files should be a partial whenever parallel copies would drift if maintained separately. Treat partials as the prose analogue of subroutines.

   It also notes that partials produce byte-identical installed output, so the "verbatim execution context" objection does not apply.

2. Generic reviewer principle in code-simplification-reviewer.md — add one bullet to the existing "Simplification principles" list:

   Consult project DRY mechanisms before recommending pointer-indirection. When flagging duplication, check whether the project documents a single-source mechanism (e.g., partials, includes, snippets, macros) in its agent guidance. Pointer-indirection is appropriate only when the duplicated content must reach the reader verbatim and the project lacks a way to single-source it.

   The principle is codebase-agnostic; the codeassembly-specific "use partials" rule lives in PROJECT.md, which the simplifier already reads at step 1.

Together these changes cover both proactive partial use (PROJECT.md guidance, visible to all subagents at step 1) and corrective review reasoning (simplifier principle for the case where duplication is found but the wrong remediation is forming).

Acceptance criteria

• .agents/PROJECT.md has a "Content authoring" subsection inside ### Agents, placed between "Content directory" and "The orchestration system."
• The subsection states the 2+ files / drift / subroutine-analogy rule and points to packages/agents/content/_partials/README.md as the canonical reference.
• code-simplification-reviewer.md has the new "Consult project DRY mechanisms" bullet in its "Simplification principles" list.
• The new simplifier principle contains no codebase-specific paths (stays portable across repos).
• No other reviewer, planner, or coder subagent definitions are modified.