diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index a3aef97..9feeb9e 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -1,5 +1,9 @@ # Architecture overview +This Mermaid view is a repository-local implementation projection. The +`PASS_SCOPED` reviewer evidence applies to the canonical draw.io diagram named +in `review-ledger.json`, not automatically to edits in this file. + ```mermaid flowchart LR Bootstrap[bootstrap / composition root] --> Presentation[presentation] diff --git a/docs/architecture/review-evidence.md b/docs/architecture/review-evidence.md new file mode 100644 index 0000000..b1ec618 --- /dev/null +++ b/docs/architecture/review-evidence.md @@ -0,0 +1,22 @@ +# Imported scoped diagram review evidence + +This ledger entry consumes the canonical evidence already recorded by the +`ca-skeleton-frontend-operational-contract` project note. It does not claim +review of the repository-local Mermaid projections or of the complete +production deployment topology. + +- Reviewer: `wiki-diagram-reviewer` +- Standard: `rules/diagram-standards.md` v2 +- Canonical report: + `docs/superpowers/specs/2026-07-18-ca-skeleton-frontend-operational-contract-review/diagram-review.md` +- Canonical report SHA-256: + `b4d2a35e4f07e176717786408f98dab5cee1047f77f6ff61f5faeddfccd78a29` + +| Canonical diagram | SHA-256 | Score | Verdict | Reviewed scope | +| --- | --- | ---: | --- | --- | +| `raw/diagrams/ca-skeleton-frontend/architecture-overview-2026-07-18.drawio` | `c0ae56c9c964c5c6e698ab7dcc91736b9b811b2b834381817905db81c4230ba0` | 100 | PASS | Clean Architecture compile-time dependency ownership | +| `raw/diagrams/ca-skeleton-frontend/architecture-deployment-2026-07-18.drawio` | `9a654326fb840ddf24b832221ff7eec4b8fadd9f87ad84174fccfa3bfcd1a25b` | 100 | PASS | immutable static assets and mutable `/config.json` delivery | + +The canonical report explicitly limits this `PASS_SCOPED`: it does not verify +the complete release/rollback topology, the implementation topology, or live +hosting state. diff --git a/docs/architecture/review-ledger.json b/docs/architecture/review-ledger.json index 8991ae4..d026be8 100644 --- a/docs/architecture/review-ledger.json +++ b/docs/architecture/review-ledger.json @@ -1,17 +1,29 @@ { "schemaVersion": 1, - "status": "pending-review", - "reviewerThreshold": null, + "status": "PASS_SCOPED", + "reviewer": "wiki-diagram-reviewer", + "standard": "rules/diagram-standards.md v2", + "evidenceReport": { + "repoPath": "docs/architecture/review-evidence.md", + "canonicalPath": "docs/superpowers/specs/2026-07-18-ca-skeleton-frontend-operational-contract-review/diagram-review.md", + "canonicalSha256": "b4d2a35e4f07e176717786408f98dab5cee1047f77f6ff61f5faeddfccd78a29" + }, "reviews": { "overview": { - "path": "docs/architecture/overview.md", - "reviewer": null, - "score": null + "sourcePath": "raw/diagrams/ca-skeleton-frontend/architecture-overview-2026-07-18.drawio", + "sha256": "c0ae56c9c964c5c6e698ab7dcc91736b9b811b2b834381817905db81c4230ba0", + "score": 100, + "verdict": "PASS", + "thresholdSatisfied": true, + "scope": "Clean Architecture compile-time dependency ownership" }, "staticDelivery": { - "path": "docs/architecture/static-delivery.md", - "reviewer": null, - "score": null + "sourcePath": "raw/diagrams/ca-skeleton-frontend/architecture-deployment-2026-07-18.drawio", + "sha256": "9a654326fb840ddf24b832221ff7eec4b8fadd9f87ad84174fccfa3bfcd1a25b", + "score": 100, + "verdict": "PASS", + "thresholdSatisfied": true, + "scope": "immutable static assets and mutable /config.json delivery" } } } diff --git a/docs/architecture/static-delivery.md b/docs/architecture/static-delivery.md index fd69a60..927287d 100644 --- a/docs/architecture/static-delivery.md +++ b/docs/architecture/static-delivery.md @@ -1,5 +1,9 @@ # Static asset and runtime-config delivery +This Mermaid view is a repository-local implementation projection. The +`PASS_SCOPED` reviewer evidence applies only to the canonical static-delivery +draw.io scope recorded in `review-ledger.json`. + ```mermaid sequenceDiagram participant CI diff --git a/docs/operations/ci-quality-gates.md b/docs/operations/ci-quality-gates.md index f4a2d25..447f5b3 100644 --- a/docs/operations/ci-quality-gates.md +++ b/docs/operations/ci-quality-gates.md @@ -18,9 +18,10 @@ DOCUMENTATION_READY (off-chain) Pull requests and `develop` pushes evaluate merge readiness. Version tags evaluate merge then release readiness. Production and field evaluation require an explicit workflow dispatch. The field tier cannot pass until the 28-day -sample threshold decision is recorded. Documentation readiness cannot pass -until both scoped diagrams have a recorded reviewer threshold and signed -scores. +sample threshold decision is recorded. Documentation readiness consumes the +canonical project-note evidence in which both scoped diagrams already received +100/100 `PASS_SCOPED`; the repo ledger preserves the evidence scope and +canonical digests. All jobs upload the shared `artifacts/` tree even after failure. Numeric retention remains an organization/provider decision; the workflow intentionally diff --git a/scripts/verify-documentation-readiness.mjs b/scripts/verify-documentation-readiness.mjs index 6534e19..bb6ba48 100644 --- a/scripts/verify-documentation-readiness.mjs +++ b/scripts/verify-documentation-readiness.mjs @@ -3,29 +3,43 @@ import { mkdir, readFile, writeFile } from "node:fs/promises"; const ledger = JSON.parse( await readFile("docs/architecture/review-ledger.json", "utf8"), ); +const evidence = await readFile(ledger.evidenceReport.repoPath, "utf8"); const results = []; for (const [diagram, review] of Object.entries(ledger.reviews)) { - const content = await readFile(review.path, "utf8"); - const hasDiagram = /```mermaid[\s\S]+```/.test(content); + const sourceReferenced = evidence.includes(review.sourcePath); + const digestReferenced = + /^[0-9a-f]{64}$/.test(review.sha256) && + evidence.includes(review.sha256); const scorePass = - typeof ledger.reviewerThreshold === "number" && + review.thresholdSatisfied === true && + review.verdict === "PASS" && typeof review.score === "number" && - review.score >= ledger.reviewerThreshold; + evidence.includes(`| ${review.score} | PASS |`); results.push({ diagram, - path: review.path, - hasDiagram, - reviewer: review.reviewer, + sourcePath: review.sourcePath, + sha256: review.sha256, + sourceReferenced, + digestReferenced, + reviewer: ledger.reviewer, score: review.score, scorePass, passed: - hasDiagram && - Boolean(review.reviewer) && + sourceReferenced && + digestReferenced && + ledger.reviewer === "wiki-diagram-reviewer" && + ledger.standard === "rules/diagram-standards.md v2" && scorePass && ledger.status === "PASS_SCOPED", }); } -const passed = results.every((result) => result.passed); +const reportDigestValid = + /^[0-9a-f]{64}$/.test(ledger.evidenceReport.canonicalSha256) && + evidence.includes(ledger.evidenceReport.canonicalSha256); +const passed = + reportDigestValid && + results.length === 2 && + results.every((result) => result.passed); await mkdir("artifacts/quality", { recursive: true }); await writeFile( "artifacts/quality/documentation-review.json", @@ -34,7 +48,10 @@ await writeFile( schemaVersion: 1, generatedAt: new Date().toISOString(), status: ledger.status, - reviewerThreshold: ledger.reviewerThreshold, + reviewer: ledger.reviewer, + standard: ledger.standard, + evidenceReport: ledger.evidenceReport, + reportDigestValid, results, passed, }, @@ -44,7 +61,7 @@ await writeFile( ); if (!passed) { process.stderr.write( - "Documentation readiness: FAIL_UNVERIFIED (reviewer threshold and signed reviews required)\n", + "Documentation readiness: FAIL_UNVERIFIED (canonical scoped-review evidence is incomplete)\n", ); process.exit(1); }