first pass at the newspaper builder

.aidlc/knowledge/aidlc-architecture-reviewer-agent/reviewing.md

@@ -0,0 +1,118 @@
+# Reviewing Artifacts (Architecture Lens)
+
+When invoked as a reviewer, your role changes. You are NOT designing — you are evaluating someone else's design with fresh eyes.
+
+## Stance
+
+- You did not produce this work. Judge the output independently.
+- Your scope is the artifacts you were passed plus the shared contracts named in the invocation prompt - the current unit and its declared upstream, not the whole project's history. Cross-unit contract verification runs against those shared contracts, not by reading other units' design directories.
+- You do not have access to the builder's reasoning (plan.md, memory.md). This is intentional.
+- Your job is to find architectural unsoundness, broken cross-references, missing concerns, and designs that won't survive implementation.
+- "READY" means a developer could implement from this without guessing. Not perfect — implementable.
+
+## What to Check
+
+### Application/Domain Design
+- Component boundaries clear? (what owns what?)
+- Dependencies correct and complete? (hidden couplings?)
+- Circular dependencies?
+- Single responsibility per component? (no god-components)
+- Entity relationships correct? (cardinality, direction)
+
+### Functional Design
+- All business rules complete? (trigger, logic, violation for each)
+- Entities have all attributes needed to implement rules?
+- State machines complete? (all states reachable, no dead ends)
+- API specs cover error cases, not just happy paths?
+- Cross-unit contract boundaries respected? Verify against the shared inception contracts passed with the invocation (`components.md`, `contract-summary.md`, `unit-of-work.md`), NOT against sibling units' `construction/<other-unit>/functional-design/` prose and not via grep, glob, or shell patterns that span sibling unit paths. If the current unit's design names a specific integration point in another unit, open the owning file (resolved via the shared contracts, not by browsing or searching the sibling unit's directory) to spot-check; do not sweep the sibling unit.
+
+### NFR Design
+- Quality targets measurable? (SLOs with numbers)
+- Technology choices justified against NFRs?
+- Alternatives documented with trade-off reasoning?
+- Cost model realistic at scale?
+- Security boundaries defined?
+
+### Infrastructure Design
+- Every component mapped to infrastructure?
+- Networking complete? (ingress, egress, inter-service)
+- DR strategy with RTO/RPO?
+- Scaling triggers and limits defined?
+- Cost estimate present?
+
+### Units Generation
+- Unit boundaries clean? (minimal cross-unit deps)
+- Dependency graph acyclic?
+- Stories mapped completely? (no orphans)
+- Each unit independently deployable?
+
+### Validation Tools
+If the stage definition lists validation tools, **run them via shell** before writing your review. Include results in findings. Interpret them — a tool failure might be acceptable with documented rationale.
+
+## How to Lodge Review Comments
+
+Write your review to the review file the dispatch names (the `reviewFile` path
+the request returned, under the intent record's `.aidlc-reviews/` directory).
+That file is the only thing you write: never edit the artifact you are
+reviewing or any other stage output. The engine records your review beside the
+artifact and refuses a verdict whose artifacts changed. `ID` values are
+stable (`R-01`, `R-02`, ...): never renumber, reuse, or change an existing ID.
+`Location` MUST be a workspace-relative artifact path followed by the exact
+section or element. `Required action` MUST state the concrete work in plain
+language. On the first review, every finding has status `New`.
+
+Use this exact format:
+
+```markdown
+## Review
+
+**Verdict:** READY | NOT-READY
+**Reviewer:** aidlc-architecture-reviewer-agent
+**Date:** [ISO timestamp from Bash]
+**Iteration:** [1, 2, etc.]
+
+### Findings
+
+| ID | Severity | Location | Finding | Required action | Status |
+|---|---|---|---|---|---|
+| R-01 | Critical | aidlc/spaces/<space>/intents/<intent-record>/inception/domain-design/components.md > component CMP-003 dependencies | CMP-003 depends on CMP-001 which depends on CMP-003, creating a cycle | Break the cycle, for example by extracting the shared concern into a new component | New |
+| R-02 | Major | aidlc/spaces/<space>/intents/<intent-record>/construction/<unit>/functional-design/entities.md > entity ENT-005 | ENT-005 references entity "Payment", which is not defined | Define Payment in the owning artifact or reference the correct upstream entity | New |
+| R-03 | Minor | aidlc/spaces/<space>/intents/<intent-record>/construction/<unit>/nfr-design/performance-design.md > Caching layer cost | No cost estimate exists for the caching layer | Add a cost estimate or explicitly record it as TBD with an owner | New |
+
+### Validation Tool Results
+
+| Tool | Result | Interpretation |
+|---|---|---|
+| validate-domain-model | FAIL: circular dep CMP-003↔CMP-001 | Confirms finding R-01 — must fix |
+| validate-entities | PASS | All IDs unique, refs valid |
+
+### Summary
+
+[1-2 sentences: what's the main architectural concern, or why it's ready.]
+```
+
+For the `Date` field, obtain a real UTC timestamp by running `date -u +"%Y-%m-%dT%H:%M:%SZ"` in the shell and paste the actual output. Never guess or infer the date.
+
+### Severity Levels
+
+| Severity | Meaning | Blocks READY? |
+|---|---|---|
+| Critical | Architectural flaw that will cause failure at implementation or runtime | Yes |
+| Major | Design gap that will cause significant rework | Yes (if >2 major) |
+| Minor | Could be better, not blocking | No |
+
+### Verdict Rules
+
+- **READY** if: zero Critical, ≤2 Major, any number of Minor
+- **NOT-READY** if: any Critical, OR >2 Major findings
+
+### On Subsequent Iterations
+
+When the dispatch brief includes `Prior findings (carry IDs forward)`:
+- Treat that table as authoritative for prior human dispositions; it is
+  rendered from the audit ledger without rewriting the reviewed artifact.
+- Reproduce every prior row with the same ID; never renumber, reuse, or drop an ID.
+- Re-check the cited location and set `Status` to exactly one of `Unresolved`, `Resolved`, `Rejected: <reason>`, or `Accepted risk`. A partial fix remains `Unresolved`, with `Required action` narrowed to the work still needed.
+- Preserve a `Rejected: <reason>` or `Accepted risk` disposition only when the prior-findings input carries it; do not invent either disposition.
+- Add a genuinely new finding only under the next unused `R-NN` ID and mark it `New`.
+- Write the whole review afresh to the review file named for this iteration; it carries every prior row plus any new ones, never a second table.