Align formal product scope with implemented capabilities

README.md

@@ -15,7 +15,8 @@ MVP supports image-only detection:
 - Upload one JPG, PNG, or WebP image.
 - Store the file and image metadata.
 - Create a detection task in a Java backend.
-- Call a Python model service for real inference.
+- Call a versioned Python model-service contract. Local development uses the
+  heuristic runtime; real weights and CUDA verification are server-pending.
 - Store model output, threshold, version, latency, and image hash.
 - Generate a report and detection history.
 - Show model health and registry information.
@@ -28,6 +29,10 @@ Out of scope for MVP:
 - User billing, tenants, RBAC, or complex audit workflows.
 - Custom model training or stacking meta-learners.
 
+Video and expert-ensemble visuals are development showcases, not formal
+product capabilities. See the [product capability matrix](docs/capability-matrix.md)
+for implementation evidence and deferred boundaries.
+
 ## Architecture
 
 ```text

docs/README.md

@@ -9,10 +9,15 @@ Workbench.
   commands.
 - [Documentation Standards](documentation-standards.md): how this repository
   writes and maintains technical documentation.
+- [Architecture Decision Records](adr/README.md): durable cross-cutting
+  decisions, alternatives, and consequences.
 - [Project Worklog](project-worklog.md): what has been built, why it was built,
   how it was verified, and what is deferred.
-- [Improvement Roadmap](project-improvement-roadmap.md): strict interviewer-style
-  gap analysis and the recommended next phases.
+- [Product Capability Matrix](capability-matrix.md): implemented, server-pending,
+  showcase, and non-goal capabilities with verification evidence.
+- [Historical Improvement Roadmap](project-improvement-roadmap.md): superseded
+  early gap analysis retained for development history; use the active long-term
+  roadmap below for current decisions.
 
 ## Runbooks
 

docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,36 @@
+# ADR-0001: Record Cross-Cutting Architecture Decisions
+
+- Status: Accepted
+- Date: 2026-07-11
+- Owners: Project maintainers
+
+## Context
+
+Specifications explain complete product or feature designs, while the worklog
+records branch chronology. Neither gives a concise, immutable answer to why a
+cross-cutting architecture choice exists or what alternatives were rejected.
+
+## Decision
+
+Record durable cross-cutting choices as numbered ADRs under `docs/adr/`. Keep
+each ADR focused on one decision. Supersede accepted decisions with a new ADR
+instead of rewriting project history.
+
+## Consequences
+
+- Reviewers can trace architecture from rationale to implementation commits.
+- Later maintainers can distinguish constraints from accidental code shape.
+- Feature specifications remain readable instead of becoming decision logs.
+- Every meaningful decision adds a small documentation maintenance cost.
+
+## Alternatives Considered
+
+- Use commit messages only: rejected because commits describe changes but do
+  not consistently preserve alternatives and long-term consequences.
+- Put every decision in one architecture document: rejected because updates
+  erase chronology and create a large, difficult review surface.
+
+## Verification
+
+`docs/documentation-standards.md` defines when an ADR is required, and
+`docs/adr/README.md` provides the lifecycle, template, and index.

docs/adr/README.md

@@ -0,0 +1,36 @@
+# Architecture Decision Records
+
+This directory stores short, durable records for cross-cutting architecture
+decisions. Product and feature requirements remain in `docs/superpowers/specs/`.
+
+## Lifecycle
+
+- `Proposed`: under review and not yet binding.
+- `Accepted`: current decision.
+- `Superseded`: replaced by a later ADR named in the record.
+
+Accepted ADR content is not rewritten when preferences change. Add a new ADR
+so readers can follow the project's evolution.
+
+## Template
+
+```markdown
+# ADR-NNNN: Decision Title
+
+- Status: Proposed | Accepted | Superseded
+- Date: YYYY-MM-DD
+- Owners: Project maintainers
+- Superseded by: ADR-NNNN (only when applicable)
+
+## Context
+## Decision
+## Consequences
+## Alternatives Considered
+## Verification
+```
+
+## Index
+
+| ADR | Status | Decision |
+| --- | --- | --- |
+| [ADR-0001](0001-record-architecture-decisions.md) | Accepted | Record durable cross-cutting decisions as ADRs. |

docs/capability-matrix.md

@@ -0,0 +1,48 @@
+# Product Capability Matrix
+
+- Status: Active
+- Owners: Project maintainers
+- Last reviewed: 2026-07-11
+
+This matrix is the reviewer-facing source of truth for product capability
+status. It mirrors `src/config/capabilities.ts` and prevents showcase visuals
+from being mistaken for implemented workflows.
+
+## Status Definitions
+
+| Status | Meaning |
+| --- | --- |
+| `Implemented` | Formal workflow backed by persisted state, code, and tests. |
+| `Server Pending` | Integration boundary exists, but server hardware or runtime evidence is missing. |
+| `Showcase` | Visual concept outside formal product navigation and claims. |
+| `Non-goal` | Deliberately outside the product boundary. |
+
+## Matrix
+
+| Capability | Status | Entry point | Implementation evidence | Verification |
+| --- | --- | --- | --- | --- |
+| Image detection | Implemented | `/detect/image` | Secure ingestion, PostgreSQL outbox, Redis worker, execution lease, persisted report | Java tests, frontend tests, smoke workflow |
+| Model evaluation | Implemented | `/admin/evaluations` | Evaluation runs, samples, metrics, retry state | Java evaluation tests and frontend insight tests |
+| Model registry | Implemented | `/admin/models` | Registry table, endpoint synchronization, health API | Model registry and controller tests |
+| Operational review view | Implemented | `/admin/review` | Read-only failed task, failed evaluation, and wrong-sample aggregation | Frontend build and backend APIs |
+| GPU model runtime | Server Pending | None | Runtime adapter and health contract exist; weights and CUDA evidence do not | Server deployment phase |
+| Video detection concept | Showcase | `/dev/showcase/video-detection` | Static interaction concept using fixture data | Frontend build only; not product evidence |
+| Expert and LoRA concepts | Showcase | `/dev/showcase/image-pipeline` | Static visual concept | Frontend build only; not product evidence |
+| Audio detection | Non-goal | None | None by design | Product boundary review |
+| Model training | Non-goal | None | Existing open-source model integration only | Product boundary review |
+
+The current operational review view is not yet the durable human-review
+workflow. `feature/review-case-workflow` will add claim, resolution, audit, and
+candidate-dataset behavior before that stronger claim is made.
+
+## Maintenance Rule
+
+A capability status change must update all of these in one pull request:
+
+1. `src/config/capabilities.ts` and its tests.
+2. This matrix.
+3. `README.md` when the core product claim changes.
+4. `docs/project-worklog.md` with implementation and verification evidence.
+
+Showcase animation, mock data, or screenshots cannot be used as evidence for
+an `Implemented` capability.

docs/documentation-standards.md

@@ -40,6 +40,34 @@ Use one primary purpose per document.
 Do not mix a tutorial, API reference, and design essay in the same document.
 If a document starts doing two jobs, split it or link to another page.
 
+## Document Lifecycle
+
+Durable specifications and explanation documents must include this metadata
+immediately below the title:
+
+```markdown
+- Status: Draft | Active | Superseded | Historical
+- Owners: Project maintainers
+- Last reviewed: YYYY-MM-DD
+- Superseded by: `path/to/replacement.md` (only when applicable)
+```
+
+Lifecycle meanings:
+
+| Status | Meaning |
+| --- | --- |
+| `Draft` | Proposed content that is not yet the implementation baseline. |
+| `Active` | Current source of truth for implementation and review. |
+| `Superseded` | Replaced by a named newer document and retained for history. |
+| `Historical` | Records completed research or evolution but is not prescriptive. |
+
+Plans use checkboxes instead of lifecycle metadata. Worklog entries use
+chronology. Runbooks are active unless their heading explicitly says otherwise.
+
+When a document becomes superseded, update both documents and `docs/README.md`
+in the same pull request. Never silently delete an architectural decision that
+explains committed code.
+
 ## File Naming
 
 - Use lowercase kebab-case: `project-worklog.md`.
@@ -160,6 +188,33 @@ Should work now.
 For documentation-only branches, `git diff --check` is the minimum verification.
 For code branches, run the relevant test or build command.
 
+## Maintenance Triggers
+
+The same pull request must update durable documentation when code changes any
+of these contracts:
+
+- public API request, response, status, or error behavior;
+- environment variable, default, deployment requirement, or health behavior;
+- formal capability status or user-facing workflow;
+- database or queue state machine and recovery procedure;
+- architecture boundary or dependency ownership;
+- model, dataset, metric, threshold, or performance claim.
+
+A review fails when code and its active durable documentation disagree. Small
+internal refactors that preserve every contract need only a worklog entry when
+they are architecturally meaningful.
+
+## Architecture Decision Records
+
+Use `docs/adr/` for concise cross-cutting decisions whose consequences outlive
+one feature branch. Use a specification for full product or feature design.
+
+- Number ADRs sequentially with four digits.
+- Accepted ADRs are immutable except for factual corrections.
+- Replace a decision by adding a new ADR and marking the old one superseded.
+- Link relevant ADRs from specifications and runbooks.
+- Record alternatives and consequences, not meeting history.
+
 ## Update Checklist
 
 Before committing documentation changes:
@@ -169,6 +224,9 @@ Before committing documentation changes:
 - [ ] Commands are copyable.
 - [ ] Claims are backed by links, code references, or verification commands.
 - [ ] Deferred work is explicit.
+- [ ] Lifecycle metadata and supersession links are correct where required.
+- [ ] API, configuration, capability, and state-machine changes updated their active docs.
+- [ ] A cross-cutting architecture decision has an ADR when needed.
 - [ ] No model weights, uploads, generated reports, or local database files are
       referenced as committed artifacts.
 - [ ] `git diff --check` passes.

docs/project-worklog.md

@@ -737,27 +737,46 @@ Verification:
 
 ---
 
-## Next Recommended Work
-
-Add interview-visible operational observability:
+### 2026-07-11: Product Scope Truthfulness
 
 ```text
-feature/observability-correlation
+refactor/product-scope-truthfulness
 ```
 
-Scope:
+What changed:
 
-- Propagate a correlation id across HTTP requests, outbox events, Redis jobs,
-  model calls, and persisted execution records.
-- Add Micrometer counters and timers for dispatch, retries, queue outcomes,
-  inference latency, and upload rejection reasons.
-- Define structured logging fields without logging image bytes or model raw
-  payloads.
-- Document local metrics endpoints and production exposure boundaries.
+- Established document lifecycle governance and architecture decision records.
+- Added a tested capability registry and reviewer-facing capability matrix.
+- Removed video detection from formal product navigation and moved retained
+  concepts under development showcase routes.
+- Removed fabricated confidence, evidence marks, timelines, and export success
+  behavior from the formal report page.
+- Corrected README model-runtime wording to distinguish implemented integration
+  from server-pending weights and CUDA evidence.
 
-Reason:
+Why:
+
+- Every formal product claim must map to persisted behavior and tests.
+- Showcase quality is useful, but it cannot substitute for backend capability.
+- Reviewers need one maintained place to distinguish current, deferred, and
+  deliberately excluded work.
+
+Verification:
+
+- Frontend policy and report-presentation tests increased the suite from 8 to
+  18 passing tests before final cross-project verification.
+- Frontend lint and production build passed after route and report changes.
+
+---
+
+## Next Recommended Work
+
+Continue with the real evaluation execution boundary:
+
+```text
+feature/evaluation-real-execution-boundary
+```
 
-The project now handles failure and recovery, but operators cannot yet answer
-which request produced a task, where latency accumulated, or how often retries
-and security rejections occur. Correlated traces and bounded metrics turn the
-reliability features into an operable system.
+Replace the default CRC evaluation client, split model calls out of database
+transactions, and add durable evaluation execution ownership without requiring
+real model weights.