Add opt-in structured review result to local review (#69)

capabilities/structured-output/capability.yaml

@@ -0,0 +1,16 @@
+capability: structured-output
+summary: >-
+  Opt-in machine-readable rendering of an already-finalized review: one
+  schema-versioned JSON result appended after the unchanged human report.
+loads: on-activation
+activation:
+  - the invocation resolves structured_review_result to true
+adapters: [local, github]
+files:
+  - shared/policies/structured-output.md
+requires: [review-kernel]
+never:
+  - changing a finding, severity, coverage, or the mechanical Decision
+  - replacing or reordering the human-readable report
+  - inventing an identity value that was not computed
+benchmark: tests/reference/review/review_result.py

docs/ARCHITECTURE.md

@@ -466,8 +466,9 @@ and no packaged Skill resource depends on them.
   recorded in the model
   ([`review-result/README.md`](review-result/README.md) →
   [`review-result/review-result-model.md`](review-result/review-result-model.md),
-  #67, with a test-only validator). No packaged Skill resource is changed;
-  versioning (#68) and runtime emission (#69/#70) are deferred — see
+  #67, with a test-only validator). Versioning is #68;
+  `local-code-review` emits the result opt-in (#69, packaged
+  `structured-output.md`); GitHub emission (#70) is deferred — see
   "Future work" below.
 - **Candidate-finding validation model** — the `observation → candidate
   claim → validated finding → severity` reasoning contract: the
@@ -657,8 +658,8 @@ or runbook implements them today:
   renders it in human output. The #67 schema
   ([`review-result/README.md`](review-result/README.md)) now carries
   `confidence`, `severity`, `location`, and the rest as a formal contract
-  for machine consumers; its versioning policy (#68), Skill wiring and
-  runtime emission (#69/#70), and consumers (#71) are still unbuilt.
+  for machine consumers; its versioning policy (#68) and local emission
+  (#69) are built; GitHub emission (#70) and consumers (#71) are still unbuilt.
 - **Repository-intelligence retrieval and a packaged relationship-influence
   field** — the repository-intelligence model (#129, "Repository-development
   instrumentation" above) is a design record and a test-only reference

docs/features/README.md

@@ -32,6 +32,7 @@ each Skill's own README
 | [GitHub publication & review authorization](github-review-publication.md) | one canonical publication mode — `PASSIVE` / `SEMI` / `ACTIVE` — self-review, and the optional machine-readable status/check | `github-pr-review` | default is non-mutating `PASSIVE`; an explicit `ACTIVE` request is itself sufficient authorization to publish, subject to reviewer independence + GitHub permission | [`review-action-authorization.md`](../../skills/github-pr-review/policies/review-action-authorization.md), [`review-output.md`](../../skills/github-pr-review/policies/review-output.md), [`review-status-enforcement.md`](../../skills/github-pr-review/policies/review-status-enforcement.md) |
 | [Coding-agent fix prompt](fix-prompt.md) | appending a ready-to-run implementation prompt to qualifying findings | `local-code-review` | explicitly requested (`include_fix_prompt`, default off); output only | [`remediation-guidance.md`](../../shared/policies/remediation-guidance.md) |
 | [Reviewer Brief](reviewer-brief.md) | a private, caller-facing handoff — what changed, user-provided focus, manual review focus, open questions — appended to every result and structurally excluded from GitHub publication | `github-pr-review` | always on; presentation only over already-finalized analysis | [`reviewer-brief.md`](../../skills/github-pr-review/policies/reviewer-brief.md) |
+| [Structured review result](structured-review-result.md) | appending one schema-versioned machine-readable JSON result (findings, coverage, decision, reviewed SHA) after the unchanged human report | `local-code-review` | explicitly requested (`structured_review_result`, default off); output only | [`structured-output.md`](../../shared/policies/structured-output.md), [`invocation-options.md`](../../shared/policies/invocation-options.md) |
 | [Severity descriptions](severity-description.md) | expanding the compact `P0` / `P1` / `P2` finding-headline code to include its short canonical parenthetical (`Critical` / `Blocking` / `Non-Blocking`) | `github-pr-review` | explicitly requested (`include_severity_description`, default off — compact); presentation only | [`invocation-options.md`](../../shared/policies/invocation-options.md), [`review-output.md`](../../skills/github-pr-review/policies/review-output.md) |
 
 ## Not a feature guide

docs/features/structured-review-result.md

@@ -0,0 +1,55 @@
+# Structured review result
+
+## What it does
+
+When enabled, `local-code-review` appends one **machine-readable JSON
+result** after its normal human report — the same findings, coverage, and
+`REVIEW CLEAN` / `CHANGES REQUIRED` / `REVIEW INCOMPLETE` decision, in the
+schema-versioned shape defined for review results. The document carries
+`schema_version` and the reviewed head SHA. It is normalized internally to
+the `structured_review_result` option (default `false`).
+
+Without it, the report is exactly the default human report.
+
+## When it is useful
+
+- A script, dashboard, or another agent needs to consume the review
+  without parsing prose.
+
+## Which Skill(s)
+
+`local-code-review` only. `github-pr-review` does not emit it yet
+(tracked separately).
+
+## Default, conditional, or requested
+
+**Explicitly requested; default off.** Set from the current invocation
+only: `structured_review_result=true`, the bare option name, *"include a
+structured review result"*, or the fixed phrases *"machine-readable review
+result"* / *"review result as JSON"*. Vague wording such as *"give me
+JSON"* does not enable it.
+
+## How to invoke it
+
+```text
+/local-code-review
+structured_review_result=true
+```
+
+## Limitations & safety boundaries
+
+- **Output only.** Findings, severities, coverage, and the mechanical
+  decision are identical on and off; the human report is unchanged and
+  still comes first.
+- `reviewed_head_sha` is `null` when the reviewed target includes
+  uncommitted changes, because a commit SHA cannot identify them.
+- It is not emitted for an ungraded outcome (for example an unresolved
+  Jira reference) or when the report itself was withheld.
+- Nothing is written to a file or published; it is returned inside the
+  one report.
+
+## Canonical semantics
+
+[`shared/policies/structured-output.md`](../../shared/policies/structured-output.md)
+· [`shared/policies/invocation-options.md`](../../shared/policies/invocation-options.md)
+· schema and versioning: [`../review-result/README.md`](../review-result/README.md).

docs/review-result/README.md

@@ -10,7 +10,8 @@ are repository-development docs: **not** packaged into either Skill
 archive, and no packaged Skill resource depends on them.
 `github-pr-review` can emit a review result on explicit request ([#70](https://github.com/amirbena/code-review-skill/issues/70),
 [`structured-output.md`](../../skills/github-pr-review/policies/structured-output.md));
-`local-code-review` emission is [#69](https://github.com/amirbena/code-review-skill/issues/69).
+`local-code-review` emits one on request ([#69](https://github.com/amirbena/code-review-skill/issues/69),
+[`structured-output.md`](../../shared/policies/structured-output.md)).
 
 ## Document map
 

docs/review-result/review-result-model.md

@@ -15,7 +15,7 @@ this record is the bug.
 Not packaged: no packaged Skill resource depends on this record, the
 schema, or the example (see [`../../AGENTS.md`](../../AGENTS.md), "Packaged
 Skills are independent of repository-level instructions").
-`github-pr-review` emits one on explicit request; local emission is pending — see section 7.
+`github-pr-review` and `local-code-review` each emit one on explicit request — see section 7.
 
 ## 1. Files
 
@@ -119,16 +119,19 @@ schema failing.
 | Concern | Owner |
 | --- | --- |
 | Versioning policy and compatibility rules for `schema_version` | [`schema-versioning.md`](schema-versioning.md) ([#68](https://github.com/amirbena/code-review-skill/issues/68)) |
-| Skill wiring and runtime emission of a result | [#69](https://github.com/amirbena/code-review-skill/issues/69), [#70](https://github.com/amirbena/code-review-skill/issues/70) |
+| Local Skill emission (opt-in `structured_review_result`; packaged restatement in [`structured-output.md`](../../shared/policies/structured-output.md), pinned to this schema by a drift test) | [#69](https://github.com/amirbena/code-review-skill/issues/69) |
+| GitHub Skill emission | [#70](https://github.com/amirbena/code-review-skill/issues/70) |
 | Consumers of the result | [#71](https://github.com/amirbena/code-review-skill/issues/71) |
 | Parent capability | [#44](https://github.com/amirbena/code-review-skill/issues/44) |
 
 `github-pr-review` emits the result on explicit request, returned to the
 caller only, with PR-specific field population owned by its
 [`structured-output.md`](../../skills/github-pr-review/policies/structured-output.md)
-([#70](https://github.com/amirbena/code-review-skill/issues/70)). Until
-[#69](https://github.com/amirbena/code-review-skill/issues/69) lands,
-`local-code-review` still produces only its existing Markdown output, and
+([#70](https://github.com/amirbena/code-review-skill/issues/70)).
+`local-code-review` emits it on explicit request, with its field population
+and identity minting owned by the shared
+[`structured-output.md`](../../shared/policies/structured-output.md)
+([#69](https://github.com/amirbena/code-review-skill/issues/69)); its
 [`finding.md`](../../shared/templates/finding.md)'s note that a
 machine-readable renderer would be "another projection of the same fields"
 is what this schema is the first instance of.

scripts/packaging/generate_package_manifest.py

@@ -100,6 +100,7 @@ class Entry(NamedTuple):
     Entry("shared/policies/invocation-options.md", None),
     Entry("shared/policies/remediation-guidance.md", "remediation"),
     Entry("shared/policies/remediation-scope-boundary.md", "remediation"),
+    Entry("shared/policies/structured-output.md", "structured-output"),
     Entry("shared/policies/specialist-depth.md", "specialist-depth"),
     Entry("shared/policies/security-deepening.md", "specialist-depth"),
     Entry("shared/policies/distributed-systems-deepening.md", "specialist-depth"),

scripts/packaging/package-manifest.json

@@ -32,6 +32,7 @@
     { "source": "shared/policies/invocation-options.md", "destination": "shared/policies/invocation-options.md" },
     { "source": "shared/policies/remediation-guidance.md", "destination": "shared/policies/remediation-guidance.md" },
     { "source": "shared/policies/remediation-scope-boundary.md", "destination": "shared/policies/remediation-scope-boundary.md" },
+    { "source": "shared/policies/structured-output.md", "destination": "shared/policies/structured-output.md" },
     { "source": "shared/policies/specialist-depth.md", "destination": "shared/policies/specialist-depth.md" },
     { "source": "shared/policies/security-deepening.md", "destination": "shared/policies/security-deepening.md" },
     { "source": "shared/policies/distributed-systems-deepening.md", "destination": "shared/policies/distributed-systems-deepening.md" },

shared/policies/README.md

@@ -33,6 +33,7 @@ packaged Skill is installed; they do not depend on this repository.
 | [`failure-retry-recovery.md`](failure-retry-recovery.md) | The signal-triggered failure-state, retry-safety, and recovery pass, and the applicability-gated observability hierarchy that decides whether a missing detection/diagnosis signal is itself a finding. |
 | [`architectural-placement.md`](architectural-placement.md) | Whether changed code is correctly placed within the surrounding execution lifecycle: the semantic-risk trigger vocabulary, bounded ring-by-ring context expansion, stop conditions, and the evidence requirement for a placement finding. Also owns the bounded, analogue-based trigger for an undocumented structural/organizational responsibility-placement pattern. |
 | [`api-contract-compatibility.md`](api-contract-compatibility.md) | The API/contract compatibility depth owner: recognizing a changed repository contract, classifying its change shape as compatible / breaking / context-dependent, and the fail-closed rule for an unresolvable consumer surface. |
+| [`structured-output.md`](structured-output.md) | The opt-in machine-readable review result: activation, placement after the unchanged human report, the serialization of the finalized review, and finding-identity minting. Currently consumed by `local-code-review` only. |
 | [`severity.md`](severity.md) | The single P0/P1/P2 severity each finding receives and the mechanical severity → decision derivation. |
 | [`verdict-consistency.md`](verdict-consistency.md) | The read-only, pre-render/pre-publish check that a rendered or submitted decision signal agrees with `severity.md`'s already-finalized mechanical derivation; withhold-and-report on a detected mismatch, never self-correct or warn-and-continue. |
 | [`evidence.md`](evidence.md) | Every finding must rest on concrete repository evidence; what counts as evidence. |

shared/policies/invocation-options.md

@@ -62,6 +62,13 @@ language interpretation.
   anchor (`github-pr-review`'s `finding-placement.md` is unchanged and
   remains authoritative for placement), or publication ordering — only the
   wording of an inline finding.
+- `structured_review_result` — local-only, default `false`; when `true`,
+  `local-code-review` appends one schema-versioned machine-readable JSON
+  result after its unchanged human report, per
+  [`structured-output.md`](structured-output.md).
+  `github-pr-review` normalizes it for parity but has no structured result
+  surface, so it has no effect there. Output-only: it never changes scope,
+  findings, severity, coverage, or the mechanical Decision.
 - `include_severity_description` — default `false` for both Skills;
   controls whether `github-pr-review`'s reader-visible severity-legend
   parenthetical (`P0 (Critical)` / `P1 (Blocking)` / `P2 (Non-Blocking)`)
@@ -122,7 +129,8 @@ underscores treated as equivalent inside the option name:
 
 The finite vocabulary is the five canonical option concepts: `fix prompt`,
 `fix guidance`, `finding details`, `human review output`, and `severity
-description`. Ordinary
+description`. The local-only `structured review result` concept is recognized
+by its own fixed phrase set below. Ordinary
 mentions, questions about an option, quoted examples, and vague requests such
 as “make it helpful”, “be detailed”, or “make it nicer” are ambiguous and do
 not set a flag. Do not use sentiment, urgency, severity, prior turns, or a
@@ -218,6 +226,27 @@ the severity-legend parenthetical renders; it never changes whether
 severity is shown, whether the headline is emphasized, or any semantics
 owned by `severity.md`.
 
+### `structured_review_result` phrasings
+
+Alongside the canonical `structured_review_result=true|false` assignment and
+the bare option name (`structured_review_result`, `structured review
+result`, `structured-review-result`), it recognizes a small, fixed set of
+explicit phrasings (case-insensitively, whitespace-flexible):
+
+- affirmative: `machine-readable review result`, `review result as json`;
+- negative: `no machine-readable review result`, `human report only`.
+
+Text naming `structured review result` (any of the spellings above) belongs
+to this option alone: it is never also read as the `structured review`
+negative phrase of `human_review_output`, so requesting both a senior-style
+review and a structured result sets both.
+
+This phrase set is exhaustive. Anything outside it — "give me json", "make
+it parseable", a question about the option — is ambiguous and does not set
+the flag; the default `false` then applies. When both an affirmative and a
+negative phrasing appear, the values conflict and the option falls through
+to the default.
+
 Resolve each option independently with this precedence:
 
 ```text