Reports and remediation
Canonical report JSON, approval, deterministic exports, patch proposals, static rescans, and human-controlled GitHub pull requests.
Canonical first
Versioned Pydantic JSON is the report source of truth. UI views and every export render from the same revision. Agent prose never becomes an export without schema validation, evidence validation, and adjudication.
The report includes executive summary, coverage, architecture-impact dispositions, compliance evidence assessment, architecture diagnostics, comparable history, trust boundaries, threat model, active findings, evidence-gated exclusions, remediation plan, SBOM reference, and an evidence appendix.
The compliance section uses supported, partial, gap, not applicable, and unknown. It is an evidence mapping, not legal advice or certification. The diagnostic section describes the quality of Hyperoru's current understanding separately from weaknesses in the customer system. The history section distinguishes structural removal from a fact that was simply not re-observed because collection coverage changed.
Read coverage before the verdict
Start with the architecture and the connected sources, then inspect the evidence behind each finding. A report with no findings is useful only when the relevant checks completed with usable evidence.
| Check state | What it means | What to do next |
|---|---|---|
| Succeeded | The check returned a usable report without reported analysis gaps. It can still contain findings. | Review the findings and their evidence. |
| Partial | Some analysis could not finish, such as a source file that could not be parsed. Usable findings are retained. | Inspect the coverage gap, correct its cause, and run a fresh review. |
| Failed | The check failed, produced no usable report, or its report could not be verified. | Resolve the reported failure and rerun the review. |
Missing required checks are also coverage gaps. Hyperoru's release gate requires all twelve repository checks, a completed review, and no recorded coverage gaps. It evaluates findings at the selected risk threshold against the exact reviewed revision. Connecting a cloud account or selecting a repository does not by itself prove coverage.
Incomplete evidence cannot establish a clean result
If a file cannot be analyzed, Hyperoru keeps findings from the files it could analyze and records what is missing. Those gaps also prevent a remediation rescan from passing verification.
Export pipeline
| Format | Derivation |
|---|---|
| JSON | canonical schema serialization |
| Markdown | deterministic renderer from JSON |
| Mermaid | approved constructs from canonical graph views |
| SVG / PNG | server-rendered Mermaid, sanitized before storage |
| DOCX | deterministic OOXML template |
| conversion from the verified DOCX |
Exports validate schema, links, diagram syntax, SVG safety, text extraction, pagination, and representative visual regressions. Format-specific failures are retryable without rerunning the audit.
Remediation flow
- A Developer or Analyst requests remediation for a confirmed finding.
- The Remediation Engineer proposes a bounded diff and identifies every touched file.
- The patch is applied in a disposable working copy.
- All twelve repository checks rerun against the patched working copy. Verification requires complete, validated reports, absence of the original finding, and no newly introduced high or critical findings. Builds and tests are not executed.
- An Analyst, Admin, or Owner reviews and approves the proposal.
- The connected GitHub App receives a short-lived, project-scoped write token and creates one branch and pull request.
- Hyperoru records pull-request state but never merges automatically.
Workflow changes require explicit approval
The GitHub App includes Workflow write permission, but Hyperoru adds it to the short-lived publication token only when an approved, validated patch changes .github/workflows/. Audits never receive write access.