Validate Content product impact in pull requests

[3mdistal]

Problem

PR #2511 gave Content a repository-native product graph: stable Feature and Capability IDs, explicit lifecycle states, and deterministic catalog validation. Future pull requests still have no consistent way to say which of those accepted contracts they affect or whether they also change a product record.

Inferring impact from transitive imports would make ordinary framework, dependency, CI, and infrastructure work look like Content work. Leaving the question entirely to prose or an agent verdict would be inconsistent and too subjective to enforce. Contributors need a small deterministic declaration and reviewers need exact, repairable findings before any stronger policy is considered.

Approach

Add a two-week advisory pull-request check that asks materially Content-affecting changes to declare their product lane, exact Feature and Capability IDs, record obligation, and proof. The check validates those references against the product graph, compares Feature and Capability state across the pull request's merge base and exact head, and reports deterministic findings without blocking the pull request.

Applicability is intentionally bounded. Direct changes to Content-owned product surfaces enter automatically. Shared-framework changes remain quiet unless they include direct Content evidence, introduce a deterministic Content contract failure, or carry a valid declaration naming a real Content contract.

This is declaration and graph validation, not a semantic merge judge. It never edits the roadmap, writes back to the pull request, tags product owners, or makes an LLM verdict blocking.

What changed

• Added a strict parser for one fenced content_product_impact declaration, including exact lane, ID, record-change, proof, and rationale validation.
• Reused the Add Content product knowledge graph and developer skill #2511 catalog loader to validate head IDs, detect newly invalid Content records, and report exact Feature roadmap_status and Capability state transitions.
• Materialized isolated base and head snapshots from one resolved merge base, including the Content developer skill and linked non-Markdown files, so validation cannot borrow files from the live checkout.
• Added one read-only pull_request workflow that executes an immutable checker revision and treats the exact candidate checkout only as data. It fetches the exact upstream base revision for fork pull requests and receives no secrets, environment, persisted Git credentials, or write permission.
• Added a workflow-policy guard registered in pnpm guards that pins the runner, actions, permissions, GitHub expressions, checkout topology, upstream fetch, install command, and checker entrypoint.
• Taught contributors how to declare and repair Content product impact in the Content developer skill.

Product impact declaration

content_product_impact:
  lane: local_refinement
  features:
    - content.feature.evolve-systems-safely
  capabilities:
    - content.template.governance
  record_change: none
  proof:
    - pnpm test:content-product-impact
    - pnpm test:content-product-docs
    - pnpm guard:content-product-docs
    - pnpm guard:workspace-skills
    - pnpm fmt:check
    - pnpm typecheck
    - pnpm guards
  rationale: This adds advisory repository conformance around the accepted Content graph without changing a runtime product contract or product record.

Safety and operations

• The advisory window begins only after this PR lands and runs for two weeks. During calibration, deterministic findings remain non-blocking and semantic review remains outside this workflow and non-blocking.
• The workflow emits structured JSON, a job summary, and copyable warnings. Input and infrastructure failures fail loudly; product-impact findings themselves exit successfully.
• The check does not comment, label, assign or request reviewers, modify product records, change branch protection, or notify on uncertain shared-framework classifications.
• No application UI, Action, server route, schema, stored data, migration, package release, deployment, credential, or Content changelog entry changes in this PR.
• Rollback is removal of the workflow, checker, guard registration, and developer-skill guidance. The pilot writes no durable product or pull-request state that needs reversal.

Calibration should record which pull requests were applicable or quiet, each deterministic finding and repair, unexplained false positives or misses, and the share of findings that remained reproducible. Promotion to blocking requires a separate change after the window and only for rules with deterministic inputs, exact repairs, and no unexplained observed false positives.

Verification

Evidence on exact head bd308501ea468d0f55b1b72aaf61a3bb87935c3a:

• pnpm test:content-product-impact — 30/30 tests passed, covering declaration parsing, bounded applicability, exact transitions, isolated revision snapshots, merge-base selection, fork base-fetch policy, loud input failures, and workflow trust-boundary regressions.
• pnpm test:content-product-docs — 14/14 tests passed, confirming the reused product graph remains valid.
• pnpm typecheck passed across the workspace.
• pnpm guards passed all 37 checks, including the independently registered Content conformance workflow guard.
• Exact-head CI passed, including Advisory Content product impact, Content parity, Content DB tests, Security guards, build, typecheck, fast-test lanes, and the standalone Chat browser lane.
• Automated review and repair completed with no unresolved high- or medium-priority correctness or security findings.
• Historical calibration classified Fix Content route commits on slow networks #2372, fix(content): preserve database property context #2391, Keep Content database preview action menu interactive #2407, feat(content): add personal sidebar ordering #2423, and Add Content product knowledge graph and developer skill #2511 as directly applicable, while Ignore build/ and .output/ in the remaining template gitignores #2475, Expose async cross-app polling handles to MCP callers #2486, feat(core): add template materialize --out #2451, Restore exact-PR builds in trusted acceptance #2456, and chore: version packages [skip netlify] #2518 stayed quiet without a hand-authored valid declaration.

Manual product browser QA was skipped because this PR changes repository validation, CI, and developer guidance rather than Content UI or runtime behavior.

Review focus

• Is the automatic Content perimeter narrow enough to include direct product surfaces without treating transitive framework imports as product impact?
• Does the immutable-controller and inert-candidate design prevent pull-request code or package scripts from controlling the advisory verdict?
• Are merge-base resolution, revision-isolated snapshots, and fork base fetching sufficient to compare the exact product records the pull request actually changes?
• Do malformed inputs fail loudly while advisory findings and uncertain shared-framework cases remain non-blocking and non-notifying?
• Are the two-week measurements strong enough to support a later, separate decision about promoting only proven deterministic rules?

Follow-ups

• Operational monitoring: run the two-week advisory calibration and record applicability, findings, repairs, false positives, and misses.
• Later product decision: decide after calibration whether any proven deterministic rule warrants a separate blocking-policy change.
• Optional semantic calibration: any agent review performed during the window stays outside this workflow, quiet when uncertain, and non-blocking.

This PR is intentionally separate from #2511 and remains unmerged until a later Land decision.

[github-actions]

Here's a visual recap of what changed:

Open the full interactive recap

[builder-io-integration]

Builder reviewed your changes — looks good ✅

Review Details

Code Review Summary

This revision fixes the remaining fork pull-request reliability issue by adding a dedicated step that fetches the exact upstream target SHA into the candidate repository before the trusted controller computes the merge base. The workflow now separates the immutable controller from inert candidate data, uses pinned actions and a hosted runner, enforces read-only permissions and exact revisions, and validates the new fetch command through the workflow guard. The snapshot checker continues to validate isolated base/head materializations and clean them up reliably. Risk: High, due to CI execution and revision-boundary security, but no confirmed high- or medium-severity issues remain.

Review Result

• ✅ Previous fork base-revision finding is fixed; its stale review thread was resolved.
• ✅ Four independent agents found no additional confirmed issues.
• ✅ The concern about iterating all files returned by git ls-tree is not a confirmed vulnerability: Git tree paths are repository-controlled valid paths, snapshot files are intentionally materialized for linked assets, and the temporary destination is isolated.

🧪 Browser testing: Skipped — PR only modifies backend/config/docs/tests, no UI impact.