Document scaffolded-to-embedded file mapping to prevent drift detection misses #116

What happened

PR #109 updated .opencode/skills/always-on-guidance/SKILL.md via the v0.17.0 scaffold deployment but did not update the byte-identical embedded copy at internal/agentkit/content/skills/always-on-guidance/SKILL.md. This broke TestSkillFiles_DriftDetection (byte-compares the two copies) and TestAlwaysOnGuidance_StructuralHardening.

The fullsend review agent (run 34944276471) found 14 medium/low findings but missed this CRITICAL issue entirely. The human reviewer em-redhat caught it 2 days later using the repo's local /uf.review-pr command, which had access to CI status showing Build and Test: FAIL. The author fixed it by reverting the scaffolded copy to match the embedded one.

The relationship between scaffolded files (.opencode/) and their embedded copies (internal/agentkit/content/) is enforced by drift detection tests but is not documented in AGENTS.md or CLAUDE.md. Neither the review agent nor the PR author was prompted to check both locations.

What could go better

If the scaffolded-to-embedded file mapping were documented in AGENTS.md (which all agents read), reviewers would be prompted to check both locations when either changes. The Go convention pack already mentions drift detection as a pattern (TC-007: "Implement drift detection tests to ensure embedded assets match their canonical source files"), but without documenting which specific files are paired, reviewers cannot apply this rule.

Confidence: High that documentation would help. The pattern is well-established in this repo (multiple test files enforce it), but the mapping is implicit — you have to read the test code to discover it. Making it explicit in developer documentation is a low-cost, high-signal improvement.

Uncertainty: Adding documentation does not guarantee the review agent will act on it. The review agent may still miss the connection if it does not cross-reference changed files against the documented mapping. However, it raises the floor — any reviewer who reads AGENTS.md will know to check.

Proposed change

Add a "Mirrored Files" or "Drift Detection Mapping" section to AGENTS.md documenting the paired file relationships. Example:

## Drift Detection (Mirrored Files)

The following scaffolded files have byte-identical embedded copies
under `internal/agentkit/content/`. Changes to either location
MUST be synchronized. `TestSkillFiles_DriftDetection` enforces
parity at CI time.

| Scaffolded Path | Embedded Path |
|----------------|---------------|
| `.opencode/skills/always-on-guidance/SKILL.md` | `internal/agentkit/content/skills/always-on-guidance/SKILL.md` |
| `.opencode/agents/*.md` | `internal/agentkit/content/agents/*.md` |
| `.opencode/commands/*.md` | `internal/agentkit/content/commands/*.md` |

When reviewing or implementing changes to files in either column,
always verify the corresponding copy is updated. Run `make check`
to confirm drift detection tests pass.

The exact file pairs should be verified against the current TestSkillFiles_DriftDetection test implementation.

Validation criteria

1. The next scaffold deployment PR to this repo should either (a) receive a review finding about embedded copy sync from the review agent, or (b) the PR author should proactively sync both copies, citing the documented mapping.
2. Run grep -r 'Drift Detection\|Mirrored Files' AGENTS.md returns the new section.
3. The documented mapping matches the actual file pairs checked by TestSkillFiles_DriftDetection.

Generated by retro agent from #109