fix(review): persist 422 inline failures as overview receipts

.github/workflows/opencode-review-dispatch.yml

@@ -5625,6 +5625,8 @@ jobs:
 
           create_pull_review_with_payload() {
             local event="$1" body="$2" review_payload_file="$3" fallback_body_file="$4"
+            local source_body_file="${5:-}"
+            local control_json="${6:-}"
             local gh_error_file
             local rewritten_payload_file
             local review_response_file
@@ -5640,6 +5642,10 @@ jobs:
             emit_review_body_to_action_log "$event" "$body" "$review_payload_file"
             if ! post_pull_review_with_retry "inline review" "$review_write_token" "$review_payload_file" "$gh_error_file" "$review_response_file"; then
               warn_gh_publication_failure "pull review inline comments" "$gh_error_file"
+              if [ -n "$source_body_file" ] && [ -n "$control_json" ]; then
+                build_inline_comment_failure_body \
+                  "$source_body_file" "$fallback_body_file" "$control_json" "$gh_error_file" || true
+              fi
               rm -f "$gh_error_file" "$review_response_file"
               if [ "${REVIEW_PUBLICATION_STALE_HEAD:-}" = "1" ]; then
                 printf '::error::OpenCode inline review publication stopped because PR head advanced beyond %s.\n' "$HEAD_SHA"
@@ -5766,12 +5772,20 @@ jobs:
           build_inline_comment_failure_body() {
             local body_file="$1"
             local output_file="$2"
-
-            {
-              cat "$body_file"
-              printf '\n## Inline comment publishing failed\n\n'
-              printf 'GitHub did not accept the inline review comments for the cited finding lines, so OpenCode did not copy suggested diffs into this PR-level body. Re-run the review after the findings are anchored to changed diff lines, or inspect the workflow log/control JSON and apply the changes manually.\n'
-            } >"$output_file"
+            local control_json="$3"
+            local error_file="${4:-}"
+            local -a fallback_args
+
+            fallback_args=(
+              python3 "$GITHUB_WORKSPACE/scripts/ci/opencode_inline_comment_fallback.py"
+              --control "$control_json"
+              --body "$body_file"
+              --output "$output_file"
+            )
+            if [ -n "$error_file" ]; then
+              fallback_args+=(--error-file "$error_file")
+            fi
+            "${fallback_args[@]}"
           }
 
           publish_request_changes_from_control() {
@@ -5785,8 +5799,8 @@ jobs:
             fallback_body_file="$(mktemp)"
             format_request_changes_body "$control_json" "$body_file"
             build_request_changes_review_payload "$control_json" "$body_file" "$payload_file"
-            build_inline_comment_failure_body "$body_file" "$fallback_body_file"
-            create_pull_review_with_payload "REQUEST_CHANGES" "$(cat "$body_file")" "$payload_file" "$fallback_body_file"
+            build_inline_comment_failure_body "$body_file" "$fallback_body_file" "$control_json"
+            create_pull_review_with_payload "REQUEST_CHANGES" "$(cat "$body_file")" "$payload_file" "$fallback_body_file" "$body_file" "$control_json"
             rm -f "$body_file" "$payload_file" "$fallback_body_file"
           }
 

AGENTS.md

@@ -2,3 +2,10 @@
 
 <!-- CWL-ENTRY -->
 > **Agents: read the master context FIRST.** Before any work, read [`docs/CWL-MASTER-CONTEXT.md`](docs/CWL-MASTER-CONTEXT.md) (mission · naruon-as-platform + inter-component UML · cross-cutting disciplines · conventions · roadmap · current state), the live **GitHub Project #1** <https://github.com/orgs/ContextualWisdomLab/projects/1> (work/roadmap source of truth), the full spec **ContextualWisdomLab/naruon#974**, and operate the Project per [`docs/agent-github-project-protocol.md`](docs/agent-github-project-protocol.md). The repo/Project — not any private agent memory — is the source of truth.
+Materialize accepts only exact SHA-256 pins or a bounded relative `-r` include (no `.`/`..`); a lone `--require-hashes` directive is not trust evidence. See [`docs/doctoring/review-inline-comment-422-fallback.md`](docs/doctoring/review-inline-comment-422-fallback.md).
+
+Finding paths with backticks or HTML metacharacters are not trusted 422 receipts.
+After a batch 422, retry comments one at a time, capped at 20.
+422 receipt phrases cite leftover JSON `errors[].code` next to `message`.
+Leftover overview receipts sanitize path and phrase so a leftover cannot close the HTML comment or reopen a suggestion fence.
+Leftover overview paths that contain `-->`, `<!--`, or a suggestion fence are omitted.

ARCHITECTURE.md

@@ -0,0 +1,80 @@
+# Architecture — ContextualWisdomLab `.github`
+
+This repository is the organization control plane. It is not naruon and it
+does not own product data. Sibling products remain standalone modules; this
+repo publishes org profile assets, reusable required workflows, and the
+review/merge schedulers those products consume.
+
+## System context
+
+```mermaid
+flowchart LR
+  Buyer["Commercial buyer / reviewer"]
+  Agents["Agents on AGENTS.md"]
+  Project["GitHub Project #1"]
+  Hub["This repo: org .github"]
+  Products["Owned products<br/>naruon · orchestrator · engines"]
+  Runner["Required workflows in each repo context"]
+
+  Buyer --> Hub
+  Agents --> Project
+  Agents --> Hub
+  Project --> Hub
+  Hub --> Runner
+  Runner --> Products
+  Products -->|"standalone or as module"| Buyer
+```
+
+## 422 receipt phrase gate
+
+```mermaid
+flowchart TD
+  Err["gh api review write error"]
+  Kind{"HTTP 422 line or JSON errors[].message?"}
+  Phrase["Receipt: GitHub HTTP 422"]
+  Generic["Receipt: GitHub review write failed"]
+
+  Err --> Kind
+  Kind -->|"yes"| Phrase
+  Kind -->|"no"| Generic
+```
+
+CWE-1288: a bare `422` substring is not an HTTP status.
+
+## Control-plane data flow
+
+```mermaid
+sequenceDiagram
+  participant PR as Pull request
+  participant RW as Required workflows
+  participant OC as OpenCode reviewer
+  participant SV as sandboxed_verify / web E2E
+  participant MS as Merge scheduler
+
+  PR->>RW: pull_request_target on trusted base
+  RW->>OC: bounded evidence + NVIDIA NIM / OpenCode
+  OC->>SV: PoC command in isolated copy
+  SV-->>OC: redacted stdout/stderr + command metadata
+  OC-->>PR: APPROVE or request changes
+  MS->>PR: merge only on current-head approval + green checks
+```
+
+## Trust boundaries
+
+- Required review workflows execute **base-branch** scripts.
+- Reviewer agents stay `edit: deny`.
+- Logs redact credential shapes. They do not mask operational PII.
+- LLM and scheduled agents bind `NVIDIA_NIM_API_KEY`. They never use
+  `COPILOT_GITHUB_TOKEN`.
+- Rust remains the psychometric arithmetic owner.
+
+## Quality gates
+
+`scripts/ci/` ships with 100% statement/branch coverage and 100%
+docstrings.
+
+## Related durable documents
+
+- [`docs/CWL-MASTER-CONTEXT.md`](docs/CWL-MASTER-CONTEXT.md)
+- [`docs/doctoring/review-inline-comment-422-fallback.md`](docs/doctoring/review-inline-comment-422-fallback.md)
+- [`docs/agent-github-project-protocol.md`](docs/agent-github-project-protocol.md)

CHANGELOG.md

@@ -13,6 +13,14 @@ Semantic Versioning where the repository publishes a release.
 
 ### Fixed
 
+- Omitted leftover 422-fallback paths that contain `-->`, `<!--`, or a suggestion fence so a leftover cannot close `<!-- opencode-review-overview -->` or reopen an applyable GitHub suggestion block (CWE-116).
+- Sanitized leftover overview receipt path and phrase so a leftover cannot close `<!-- opencode-review-overview -->` or reopen a GitHub suggestion fence (CWE-116).
+- Materialized base Python locks only when every package line is an exact SHA-256 pin or a bounded relative `-r`/`--requirement` include. A lone `--require-hashes` directive, a dotted include such as `./lock.txt`, or `-r other-hashes.txt` no longer enters the trusted build context.
+- After a batch GitHub 422, retried OpenCode inline comments one at a time, capped at 20, and recorded leftover `path:line` rows past that cap so surviving hunks still attach instead of dropping the entire review thread or opening unbounded `gh api` writes.
+- Cited leftover GitHub JSON `errors[].code` next to `errors[].message` in 422 overview receipts so authors see both the refused reason and the leftover machine code (`invalid`, `custom`) that caused the attach to fail.
+- Omitted finding paths that contain backticks or HTML metacharacters (`<`, `>`, `&`) from 422 overview receipts so a hostile path cannot break out of the Markdown receipt fence. Digit-only line strings remain accepted.
+- Stored each refused OpenCode inline comment as a durable overview receipt that pairs the trusted `path:line` with the GitHub 422 error phrase from `gh api` stderr or JSON `errors[].message`. A `422` substring inside a SHA or issue number is no longer labeled as HTTP 422 (CWE-1288). Receipt phrases now escape backticks and HTML metacharacters before they are written into the overview body.
+- Named each trusted `path:line` in the OpenCode GitHub 422 inline-comment fallback so a refused attach still tells the author the exact current-head location instead of a generic “cited finding lines” sentence.
 - Bounded the Strix quality self-test's deterministic timeout fixtures to 3-second process and 5-second fake-sleep budgets so exact-head policy evidence completes inside the existing job limit without changing production Strix scanner timeouts, providers, credentials, or review semantics.
 - Allowed commas and ASCII parentheses in the bounded Strix changed-file path policy so legal tracked Packrat fixtures can receive exact-head security analysis, while rejecting raw `..` components before normalization and keeping controls, backslashes, whitespace ambiguity, and shell punctuation fail-closed.
 - Bound each review-agent invocation key to the wrapper's complete canonical payload, including the base branch and requesting actor; altered fields with a valid-format key now fail before durable-leader election or forwarding, and wrapper write permission is job-scoped.

CLAUDE.md

@@ -63,6 +63,9 @@ Details: `README.md` and `PR_GOVERNANCE_AUDIT.md`.
   dependency sets (see below).
 - `fuzz/` + `.clusterfuzzlite/` — Atheris fuzz targets for the review-output normalizer and the
   ClusterFuzzLite discovery marker.
+- `ARCHITECTURE.md` — control-plane mermaid (system context, 422
+  phrase gate, review sequence, trust boundaries). Reconstruct from the
+  repo, not private agent memory.
 - `docs/` — master context, Project protocol, `org-required-workflow-rollout.md`,
   `scorecard-governance.md`, SBOM inventory.
 - `.jules/` — recorded performance (`bolt.md`) and security (`sentinel.md`) learnings from past work

docs/doctoring/review-inline-comment-422-fallback.md

@@ -0,0 +1,83 @@
+# GitHub 422 inline-comment fallback cites trusted path:line
+
+검토 기준일: **2026-08-13**
+
+## Incident
+
+When GitHub rejects an OpenCode `REQUEST_CHANGES` review because one or more
+inline comments cannot attach, the publisher already falls back to a PR-level
+body and does not copy suggested diffs into that body. The fallback sentence
+said only “the cited finding lines.” Authors then had to open the workflow log
+or control JSON to learn *which* `path:line` GitHub refused (GitHub, n.d.-a,
+n.d.-b). That is weaker than the line-anchored review artifact modern code
+review expects (Bacchelli & Bird, 2013).
+
+## Decision
+
+Leftover overview paths that contain `-->`, `<!--`, or a suggestion fence are omitted so a leftover cannot close the HTML comment.
+Materialize accepts only exact SHA-256 pins or a bounded relative `-r` include; a lone `--require-hashes` line is not lock evidence.
+
+Leftover overview receipts sanitize path and phrase; a leftover cannot close the HTML comment or reopen a suggestion fence.
+
+`scripts/ci/opencode_inline_comment_fallback.py` reads the trusted control
+JSON, keeps first-seen safe relative `path` plus positive integer `line`
+pairs, and appends them to the fallback body as `` `path:line` `` list
+items. Unsafe paths (`..`, absolute, drive, backslash) and non-positive
+lines are omitted. An empty location set is stated explicitly.
+
+After a refused attach, the publisher first checks that the failure is
+HTTP 422 (not a bare `422` substring; CWE-1288), splits the batch
+`comments` array into at most 20 single-comment review payloads
+(`OPENCODE_INLINE_COMMENT_RETRY_LIMIT`, default 20), and retries each
+with the same write helper. Comments past that cap are recorded as not
+retried. Remaining failures still rebuild the fallback from the
+`gh api` error file and writes durable receipts into the OpenCode
+overview comment (`<!-- opencode-review-overview -->`). Each receipt is
+`` `path:line` — GitHub HTTP 422: <phrase> ``. The phrase prefers JSON
+`errors[].message` (for example `pull_request_review_thread.path is
+invalid`) plus leftover `errors[].code` when present, and otherwise
+the first `HTTP 422` line. URLs are stripped and
+the phrase is bounded to 240 characters. Backticks and HTML
+metacharacters are escaped before the phrase is written into the
+overview body.
+
+The publisher calls this helper from `build_inline_comment_failure_body`
+with the same control object used to build the inline `comments` array.
+Suggested diffs stay out of the PR-level body.
+
+CWE-1288: the receipt phrase is `GitHub HTTP 422` only from an
+`HTTP 422` line or JSON `errors[].message`. A bare `422` substring
+(commit SHA, issue number) must not be labeled as a GitHub 422.
+
+## Verification contract
+
+- `tests/test_opencode_inline_comment_fallback.py` pins safe-pair extraction,
+  the exact location list, GitHub JSON `errors[].message` phrases, HTTP 422
+  line fallback, empty-set sentence, CLI success with `--error-file`, and
+  fail-closed unreadable control or error input.
+- `tests/test_opencode_agent_contract.py` and
+  `scripts/ci/test_strix_quick_gate.sh` pin the workflow call with
+  `$control_json`.
+
+## Rollback
+
+If GitHub later accepts off-diff comments, keep citing the attempted
+`path:line` in the fallback. Do not restore a location-free sentence.
+
+## References (APA 7th)
+
+MITRE. (2026). *CWE-1288: Improper validation of syntactic correctness of
+input*. https://cwe.mitre.org/data/definitions/1288.html
+
+Bacchelli, A., & Bird, C. (2013). Expectations, outcomes, and challenges of
+modern code review. In *Proceedings of the 35th International Conference on
+Software Engineering* (pp. 712–721). IEEE.
+https://doi.org/10.1109/ICSE.2013.6606617
+
+GitHub. (n.d.-a). *Create a review for a pull request*. GitHub Docs. Retrieved
+August 13, 2026, from
+https://docs.github.com/en/rest/pulls/reviews#create-a-review-for-a-pull-request
+
+GitHub. (n.d.-b). *Create a review comment for a pull request*. GitHub Docs.
+Retrieved August 13, 2026, from
+https://docs.github.com/en/rest/pulls/comments#create-a-review-comment-for-a-pull-request

scripts/ci/materialize_base_python_requirements.py

@@ -87,6 +87,58 @@ def _is_candidate_lock_name(name: str) -> bool:
     )
 
 
+
+def _is_candidate_lock_path(path: pathlib.PurePosixPath) -> bool:
+    """Return whether one safe tracked path can name a pip requirements lock.
+
+    In addition to conventional ``requirements*.txt`` names, repositories often
+    keep concrete environment closures as direct children such as
+    ``requirements/ci.txt`` or ``service/requirements/package.txt``. Only direct
+    ``.txt`` children of a directory named ``requirements`` gain this path-based
+    eligibility; content must still pass the independent complete hash-pin
+    validation before it reaches the trusted image build context.
+    """
+    return _is_candidate_lock_name(path.name) or (
+        path.suffix == ".txt" and path.parent.name == "requirements"
+    )
+
+
+def _is_bounded_requirement_include(line: str) -> bool:
+    """Return whether one requirements include names a bounded relative file.
+
+    Includes are accepted only as a two-token ``-r``/``--requirement`` form
+    whose target is itself a candidate lock path written as a normalized
+    relative POSIX path. Absolute paths, ``.`` or ``..`` components, double
+    slashes, URLs, option-like targets, shell/Windows path separators,
+    fragments, queries, extra inline options or hashes, and includes of
+    non-lock files are rejected before a base-owned file can enter the
+    trusted build context.
+    The downstream installer still proves that the candidate is an independently
+    complete hash closure; this predicate grants syntax eligibility only.
+    """
+    fields = line.split()
+    if len(fields) != 2 or fields[0] not in {"-r", "--requirement"}:
+        return False
+    target = fields[1]
+    if (
+        target.startswith(("-", "~"))
+        or "\\" in target
+        or ":" in target
+        or "?" in target
+        or "#" in target
+    ):
+        return False
+    include_path = pathlib.PurePosixPath(target)
+    return (
+        bool(include_path.parts)
+        and target == include_path.as_posix()
+        and not include_path.is_absolute()
+        and "." not in include_path.parts
+        and ".." not in include_path.parts
+        and _is_candidate_lock_path(include_path)
+    )
+
+
 def _requirement_lines(content: bytes) -> list[str]:
     """Return logical requirement lines, joining backslash line-continuations.
 
@@ -107,26 +159,27 @@ def _requirement_lines(content: bytes) -> list[str]:
 
 
 def _is_hash_pinned(content: bytes) -> bool:
-    """Return whether content carries hash pins and is safe to preflight.
-
-    Discovery is content-based rather than name-based so hash-pinned locks in any
-    location (a service subdirectory, ``requirements-dev.txt``,
-    ``requirements-test.txt``) can be considered for offline coverage, while an
-    unpinned or PR-mutable requirements file is still excluded from the networked
-    build context. Hash syntax cannot prove that a file includes every transitive
-    dependency, so the trusted image installer separately preflights every
-    candidate as an independent ``--require-hashes`` closure. An empty file
-    carries no installable dependency and is not materialized.
+    """Return whether content carries only trusted pins or bounded includes.
+
+    Discovery is content-based rather than name-based so exact hash-pinned locks
+    in service subdirectories and role-specific requirements files can be
+    considered for offline coverage. Candidate syntax is deliberately stricter
+    than a substring search: each package line must be an exact ``==`` pin with
+    one or more complete SHA-256 hashes, or a bounded relative requirements
+    include. A global ``--require-hashes`` directive is not trust evidence by
+    itself. The downstream installer separately preflights every candidate as an
+    independent ``pip --require-hashes`` closure, so syntax eligibility never
+    substitutes for dependency-closure proof.
     """
     lines = _requirement_lines(content)
-    if not lines:
+    requirement_lines = [line for line in lines if line != "--require-hashes"]
+    if not requirement_lines:
         return False
-    return any(line == "--require-hashes" for line in lines) or all(
-        "--hash=" in line or line.startswith(("-r ", "--requirement "))
-        for line in lines
+    return all(
+        _is_fully_hash_pinned_requirement(line)
+        or _is_bounded_requirement_include(line)
+        for line in requirement_lines
     )
-
-
 def _is_fully_hash_pinned_requirement(line: str) -> bool:
     """Return whether one uv-export line is an exact package pin with SHA-256 hashes."""
     fields = re.split(r"\s+(?=--hash=)", line)