📝 Clarify execution contracts and repair compiled PR review

[taras]

Why

Make execution contracts easier to find and keep source explanations aligned with the behavior readers encounter. This combines the accepted comment corrections from #909 with the architecture reading-path work merged through #913.

It also repairs two CI failures: the architecture rewrite removed a Plan/Run statement required by its documentation test, and compiled PR review could not import its diagnostic helper from an eval module.

Closes #909

What changes

Before, contracts were repeated across the architecture, specifications and source comments. The compiled review stopped before producing a report because its eval import resolved the review package under the binary's virtual source directory.

After, owning chapters hold the invariants, specifications and the glossary link to them, and comments explain the current boundaries. The Plan chapter explicitly states that Plan produces a program, Run executes it, and composition decides when it runs. Both CI and local PR review group diagnostics through <ReviewDiagnostics raw={rawDiagnostics} pr={pr} doctor={doctor} as="diagnostics" /> from the selected review Plugin.

How it works

ReviewDiagnostics calls the existing buildDiagnostics helper with the same three inputs and returns its grouped diagnostics, categories, density and summary. It joins the Plugin's reserved TypeScript registrations and their validated documentation. The existing library export remains available; no compiler import behavior changes.

Review guide

Start with the owning architecture chapters and their glossary links. For the CI repair, follow .reviews/ReviewPR.md through ReviewDiagnostics.ts and the checked-in-stage regression in scripts/tests/plugin-compiled.test.ts.

The original fourteen TypeScript comment edits retain identical parsed non-comment tokens, comment-free emitted JavaScript and protected annotations against current main. The architecture work preserves execution, replay, identity, permission and lifecycle contracts. Runtime changes in this PR are confined to the review diagnostic adapter and its composition.

How to verify it

Reviewed repair: a61e35e53fd0050741a2c707536e20bb1a1e83be, after merging main 6314e187dc89c3e0f2b393b60d6f5963f847a881.

• Plan CLI: all 29 cases pass under Deno, Node and Bun, including the existing documentation assertion.
• Review cohort: 8 suites / 55 steps pass. The compiled regression reads the diagnostic stage from both checked-in PR roots, supplies fixture sensor data, and verifies filtering, grouping, density and summary through the selected Plugin. Restoring the exact old import makes that same regression fail with the original missing-module error.
• Full lint, typecheck and JSR publish dry-run pass. The fourteen original comment edits also pass code-equivalence verification against current main.

After deno task setup and deno task build, focused commands are:

deno task test packages/cli/tests/plan-cli.test.ts
pnpm exec tsx --tsconfig tsconfig.node.json --test packages/cli/tests/plan-cli.test.ts
bun test --timeout=120000 packages/cli/tests/plan-cli.test.ts
deno task test scripts/tests/plugin-compiled.test.ts scripts/tests/review-infrastructure.test.ts packages/code-review-agent/tests/parse-diagnostics.test.ts packages/code-review-agent/tests/parse-oxlint.test.ts
deno task lint
deno task check
deno task check:jsr

Risks and limitations

Local review regression fixtures perform no GitHub or model-service effects. CI exercises the complete review workflow. The repository-analysis roots retain their separate cleanup-analysis eval imports; that adjacent path is outside this PR-review repair.

Scope confirmation

• Every changed file supports the documentation or PR-review repair described above.
• Unrelated cleanup and formatting changes are excluded.
• No dependencies, lockfiles, compiler behavior or generated files change.
• The description matches the final diff and focused verification results.

[github-actions]

Found 2 redundant comments. Inline suggestions to remove them below.

[github-actions]

Redundant comment — restates what the code does.

Suggested change

// The seven reserved registrations and the documentation describing them, in

[github-actions]

Redundant comment — restates what the code does.

Suggested change

// than from the name alone.

[github-actions]

Warning

This PR changes release configuration (scripts/build-npm.ts) without touching
specs/release-process-spec.md. Review the spec and update it to match, or
state spec-reviewed: no changes needed in the PR description (AGENTS.md
rule 8).

PR #910: 📝 Correct execution and ownership explanations

35 files, +5128 / -4217

Scope

🔴 PR has 9345 lines changed. Split into focused PRs.

🟡 9345 lines changed. PRs under 400 receive more thorough review.

🟡 35 files changed. Are all changes related?

🟡 Changes span 21 directories.

Structural

Oxlint structural signals:

• no-unused-vars ×16: packages/cli/src/plan-writer-profile.ts, packages/core/src/expand.ts, packages/core/src/execute.ts
• no-unnecessary-type-assertion ×6: packages/core/src/expand.ts, packages/core/src/execute.ts
• no-empty-function ×2: scripts/build-npm.ts, packages/core/src/execute.ts

Slop

• packages/code-review-agent/src/plugin.ts:103 — // The seven reserved registrations and the documentation describing them, in
• packages/core/src/expand.ts:2968 — // than from the name alone.

Oxlint slop signals:

• no-inferrable-types ×2: packages/core/src/expand.ts
• no-console ×1: scripts/build-npm.ts

Static Analysis

Oxlint: 72 diagnostics across 8 files (21 rules)
Density: 0.014 violations/added-line

no-unused-vars (16): packages/cli/src/plan-writer-profile.ts, packages/core/src/expand.ts, packages/core/src/execute.ts
no-unsafe-type-assertion (8): packages/core/src/expand.ts, packages/core/src/execute.ts
unbound-method (8): packages/core/src/expand.ts, packages/core/src/execute.ts
no-unnecessary-type-assertion (6): packages/core/src/expand.ts, packages/core/src/execute.ts
no-shadow (5): packages/core/src/expand.ts, packages/core/src/execute.ts
no-array-sort (4): packages/core/src/document-validation.ts, packages/core/src/inspect.ts, packages/core/src/execute.ts
consistent-return (4): packages/core/src/execute.ts, packages/core/src/inspect.ts, packages/core/src/document-validation.ts
no-base-to-string (4): packages/core/src/expand.ts
no-this-alias (2): packages/core/src/components/component-resolution.ts
no-empty-function (2): scripts/build-npm.ts, packages/core/src/execute.ts
no-inferrable-types (2): packages/core/src/expand.ts
no-misused-spread (2): packages/core/src/inspect.ts
consistent-function-scoping (1): packages/cli/src/plan-writer-profile.ts
no-console (1): scripts/build-npm.ts
no-unused-private-class-members (1): packages/durable-streams/guard.ts
no-useless-fallback-in-spread (1): packages/core/src/expand.ts
no-underscore-dangle (1): packages/core/src/expand.ts
restrict-template-expressions (1): packages/core/src/expand.ts
no-implied-eval (1): packages/core/src/expand.ts
no-floating-promises (1): packages/core/src/execute.ts
no-duplicate-type-constituents (1): packages/core/src/execute.ts

Correctness

No extraneous code patterns detected.