feat: harden block updates, routing, and provenance

[hyfdev]

Summary

• Add an MIT license and make the installed pcr-setup snapshot/update boundary explicit.
• Bound the canonical block with ownership markers; reject malformed pairs; preserve clear legacy project rules outside every managed region; stop for confirmation when old methodology and local edits cannot be separated safely.
• Route project areas and hotspots to exact records or headings, prefer executable constraints and code-local rationale where they are stronger, and require durable evidence for factual claims.
• Narrow VOUCHED to explicit human direction, define stable line/section/file scopes, preserve legacy scope, and distinguish newly claimed stamps from inherited target-branch state.
• Sync the English and Chinese documentation, dogfood the new map shape, and add a paired behavior-evaluation procedure for future agent-facing changes.

Why

Dogfooding existing adopters exposed four gaps: re-running a stale installed skill could not obtain the latest block; unmarked legacy blocks could contain project-specific rules; file count did not predict retrieval difficulty for long records; and human approval was being conflated with factual proof. Some durable records also cited temporary or missing evidence.

Compatibility

Manual adoption still requires only Markdown and the two HTML ownership comments. This does not add a /pcr-distill skill or require PCR-specific CI, parsers, schemas, or other adopter tooling. Legacy undated and legacy-position stamps remain valid under their project-defined scope until a human re-vouches or approves migration.

Validation

• All four canonical block copies are byte-identical and contain one correctly ordered marker pair.
• The dogfood map covers all 12 records; relative Markdown links and GitHub-style heading anchors resolve.
• Markdown fences and git diff --check pass.
• A concrete legacy migration review confirms that machud's custom Autonomous work rule survives outside both PCR and Vite+ managed regions, while its project-defined per-decision stamp scope remains unchanged.
• An independent adversarial review found no remaining blocking issue.

Remaining validation

The paired current-vs-candidate agent task experiment described in CONTRIBUTING.md has not been run yet. This PR fixes observed consistency and migration failures, but does not claim measured behavior improvement until those runs exist.

[Copilot]

Pull request overview

This PR tightens the PCR methodology’s update/migration semantics by bounding the canonical adoption block with explicit ownership markers, clarifying the “installed skill is a snapshot” update boundary, and refining provenance (VOUCHED) to mean explicit human acceptance of direction with clearer scope rules. It also updates the worked-example records map and supporting records to emphasize retrieval routing (to exact headings) and “strongest durable form” guidance, while keeping English/Chinese docs in sync.

Changes:

• Add <!-- PCR:START --> / <!-- PCR:END --> markers and update /pcr-setup guidance to safely replace only the owned region (and stop on ambiguous legacy/malformed cases).
• Reframe provenance to “explicit human acceptance of project direction” with explicit line/section/file scoping rules and clearer treatment of legacy/new stamps.
• Update routing and durability guidance (map-to-heading routes, “records vs enforcement”), and sync README + translation + dogfood docs.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
skills/pcr-setup/SKILL.md	Updates setup/update procedure to be marker-bounded, migration-safe, and explicit about skill snapshot vs methodology updates.
README.md	Adds marker-bounded canonical block, clarifies update steps, and refines provenance/routing guidance in the methodology.
README.zh-CN.md	Syncs Chinese doc with updated English methodology text and marker/update semantics.
LICENSE	Adds an MIT license file.
CONTRIBUTING.md	Adds a concrete procedure for evaluating agent-facing changes via paired task runs.
AGENTS.md	Dogfoods the marked canonical block and updates “canonical copies” invariants to include markers + translation.
.agents/docs/README.md	Reshapes the worked-example map into “When changing / Read / Why” routes (including heading-level routing).
.agents/docs/setup-update.md	Updates the update mechanism record to require a fresh skill + marked block replacement, including legacy migration rules.
.agents/docs/records-vs-enforcement.md	Introduces a new record describing where constraints belong (tests/types/CI vs prose records).
.agents/docs/the-map.md	Updates map rationale to focus on retrieval cost and heading-level routes + breadcrumbs.
.agents/docs/starter-set.md	Updates starter set positioning to “recommended, not required” and aligns with durability guidance.
.agents/docs/one-bit-stamp.md	Refines stamp meaning to explicit acceptance of direction and clarifies scope/legacy handling.
.agents/docs/freshness.md	Reframes freshness as multi-signal (routes + evidence + distillation), not date-only detection.
.agents/docs/existing-docs.md	Updates enrollment guidance to include heading-level routes and references “records vs enforcement”.
.agents/docs/distill-draft.md	Updates distillation taxonomy to include route drift, unsupported facts, and “plausible aging” vs mechanical certainty.
.agents/docs/unattended-runs.md	Aligns unattended-run guidance with “stronger durable form” and enforcement placement.
.agents/docs/conventions-not-tooling.md	Clarifies spec boundaries (no PCR-specific tooling) while allowing two HTML markers for safe updates.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.