QA Checklist Baseline

Source: ~/ALAI/products/Plock/docs/demo-readiness/04-qa-checklist-baseline.md

---

PLOCK — QA Checklist Baseline

Date: 2026-03-14
Purpose: Define the deterministic review checklist that must be applied to every PLOCK demo-readiness document before it is treated as usable input for planning, QA, demo prep, or backlog generation.

---

1. Why This Exists

PLOCK documentation work has already shown two failure modes:

1. documents can be generated from conflicting or stale sources, and
2. tasks can claim deliverables were created when the files do not actually exist.

This checklist prevents both.

A document is not considered approved because:

• an agent says it wrote it,
• a task says done, or
• the text sounds plausible.

A document is approved only if:

• the file exists,
• the path is correct,
• the content matches the requested deliverable,
• the claims are grounded in authoritative sources,
• contradictions have been checked,
• and the document passes the go/no-go review below.

---

2. Review Scope

Apply this checklist to every document under:

• ~/ALAI/products/Plock/docs/demo-readiness/

At minimum, this includes:

• 00-canonical-source-of-truth.md
• 01-user-stories-baseline.md
• 02-feature-baseline.md
• 03-gaps-and-next-steps.md
• 04-qa-checklist-baseline.md
• any later files added to the same package

---

3. Authority Order

When a demo-readiness document makes a claim, validate it using this precedence:

1. Actual code and repo structure
2. Runtime configuration and DB migrations
3. BUILD-BLUEPRINT.md
4. README.md
5. Runbooks / security / ops docs
6. ADRs
7. PRD / GTM / Regulatory docs
8. docs/API-SPEC.md only if verified against code
9. Never use stale/conflicting docs as canonical truth

Explicit stale-doc rule

docs/ARCHITECTURE.md is currently treated as stale/conflicting and must not be used as a canonical architecture source until rewritten or formally re-approved.

---

4. Required QA Outcome Labels

Each reviewed document must end in one of these states:

• PASS — safe to use as canonical planning input
• PASS WITH NOTES — usable, but with explicit caveats recorded
• FAIL — not safe to use; must be corrected before downstream work
• BLOCKED — cannot be reviewed properly because source evidence is missing or inaccessible

No silent approval is allowed.

---

5. Pre-Review Checks

Before reading content, verify:

5.1 File existence

• The file exists on disk.
• The file is readable.
• The filename matches the intended deliverable exactly.

5.2 Path correctness

• The file is located under the expected canonical path.
• If the task specified an exact path, the file is at that exact path.
• A similarly named file elsewhere does not count as pass.

5.3 Index discoverability

• docs/demo-readiness/INDEX.md links the file if it belongs in the canonical package.
• docs/INDEX.md points to the canonical package when appropriate.

5.4 Basic format sanity

• Markdown renders as a coherent document.
• Headings are structured.
• The document is not obviously truncated.
• Placeholder/TBD/filler text is either resolved or clearly marked as unresolved risk.

---

6. Artifact Verification Checklist

A document automatically fails if any of the following are true:

• claimed file does not exist
• wrong filename
• wrong directory
• empty or near-empty content
• content unrelated to requested deliverable
• generic narrative that does not match the task contract
• references to files, modules, or paths that do not exist without explicit “unverified” marking

Required artifact review questions

• Does the file exist exactly where promised?
• Is this the exact deliverable requested?
• Does the document content materially satisfy the task?
• Is it specific to PLOCK, not generic boilerplate?

---

7. Content Evidence Checklist

Every substantive claim should be supported by at least one of:

• repo path
• code module
• migration
• config file
• runbook/security/ADR reference
• product/business doc reference

Minimum evidence standard

For each major section, the reviewer should be able to answer:

• What source supports this claim?
• Is that source authoritative?
• Does the claim overstate what the source proves?

Preferred evidence style

Use explicit references such as:

• backend/src/main/kotlin/...
• backend/src/main/resources/db/migration/...
• frontend/mfe-*
• docs/PRD.md
• docs/RLS-AUDIT.md
• README.md
• BUILD-BLUEPRINT.md

---

8. Contradiction Check

The reviewer must actively search for contradictions between the reviewed document and stronger sources.

Mandatory contradiction checks

Verify the document does not incorrectly describe PLOCK as:

• Next.js instead of React/Vite MFEs
• Express instead of Ktor
• Prisma instead of Exposed + Flyway
• Supabase/Upstash as primary current stack without proof
• organization_id as the current tenant model where repo reality shows warehouse_id

Contradiction rule

If a claim conflicts with code or stronger docs, the document fails unless the conflict is explicitly called out as historical/stale context.

---

9. User Story and Feature Traceability Check

Every story or feature-oriented document must support traceability.

For user-story documents

Check that stories are:

• grounded in PRD and/or real code domains
• labeled clearly (exists, partial, planned or equivalent)
• not invented purely from marketing language
• not duplicated under different names without explanation

For feature documents

Check that each major feature maps back to at least one of:

• a route/service/module
• a migration/schema element
• a frontend MFE/module
• a product doc with explicit “planned” labeling

Required traceability rule

A feature that has no code evidence may still appear only if it is clearly labeled planned and anchored to an authoritative product/business doc.

---

10. Source-of-Truth Compliance Check

The reviewed document must align with 00-canonical-source-of-truth.md.

Reviewer must verify:

• repo reality is treated as primary
• docs/ARCHITECTURE.md is not treated as canonical truth
• docs/API-SPEC.md is used carefully and only with verification caveat if needed
• agent-generated narrative is not cited as authoritative evidence

Automatic fail if the document:

• treats agent output as primary evidence
• uses stale architecture claims as current truth
• ignores stronger repo evidence

---

11. Security Hygiene Check

Every demo-readiness document that touches environments, infra, auth, secrets, integrations, or deployment must be reviewed for security hygiene.

Required checks

• No real secrets or secret-like material are copied into the doc.
• No environment variable values are presented in a way that looks reusable as production material.
• Any reference to infrastructure/README.md must respect the known hygiene issue around secret-like examples.
• If secret examples are mentioned, they must be described as hygiene risks, not copied forward as acceptable practice.
• Auth, token, encryption, and tenant-isolation claims must match real security docs/code where possible.

Automatic fail examples

• document repeats secret-looking example values as if acceptable
• document instructs users to commit secrets
• document misstates RLS/tenant isolation model
• document weakens existing security posture in prose without evidence

---

12. Canonical Path and Naming Check

The canonical package should remain predictable.

Reviewer should verify:

• numbering is consistent
• filenames are descriptive and stable
• index references are correct
• no duplicate “canonical” documents exist with competing names

Naming rule

If a document supersedes another document, the relationship must be explicit. Confusing parallel variants should fail review or be flagged for consolidation.

---

13. Acceptance Criteria by Document Type

13.1 Canonical source-of-truth docs

Must:

• identify authoritative vs stale sources
• define precedence clearly
• match repo reality
• explicitly quarantine stale architecture assumptions

13.2 User-story docs

Must:

• identify user roles clearly
• phrase stories in a usable operational way
• mark maturity/status
• avoid unsupported invention
• allow later mapping to features and backlog

13.3 Feature baseline docs

Must:

• group features coherently
• distinguish exists vs partial vs planned
• reference code/docs evidence
• capture key risks/contradictions

13.4 Gap / next-step docs

Must:

• separate current fact from recommendation
• prioritize gaps clearly
• define execution order
• avoid pretending that future work already exists

13.5 QA docs

Must:

• be deterministic
• define pass/fail rules
• include evidence expectations
• include final review workflow and go/no-go outcome

---

14. Reviewer Workflow

Use this exact workflow:

Step 1 — Confirm artifact

• file exists
• path is exact
• file is readable

Step 2 — Confirm task-fit

• compare document against requested deliverable
• reject generic filler or off-target content

Step 3 — Check evidence

• scan each major section for source grounding
• verify stronger-source precedence is respected

Step 4 — Check contradictions

• compare against repo reality and known stale-doc risks
• record any mismatch explicitly

Step 5 — Check traceability

• ensure user stories/features/gaps can be traced to evidence

Step 6 — Check security hygiene

• especially for env, infra, auth, tokens, integrations, deployment

Step 7 — Record verdict

Document one of:

• PASS
• PASS WITH NOTES
• FAIL
• BLOCKED

Step 8 — Record remediation

If not PASS, specify:

• exact issue
• exact file/section
• exact correction needed
• whether downstream work must pause

---

15. Review Record Template

Use this template for every reviewed document:

## QA Review Record
- Document:
- Path:
- Reviewer:
- Date:
- Verdict: PASS | PASS WITH NOTES | FAIL | BLOCKED

### Artifact Check
- Exists:
- Correct path:
- Correct filename:
- Indexed:

### Evidence Check
- Primary sources used:
- Any unsupported claims:

### Contradiction Check
- Conflicts found:
- Stale-doc contamination found:

### Traceability Check
- User-story traceability:
- Feature traceability:

### Security Hygiene Check
- Secret-like material copied: yes/no
- Security posture accurately described: yes/no

### Notes / Remediation
- 

---

16. Go / No-Go Checklist

A demo-readiness document is GO only if all answers below are yes:

• Does the file exist at the exact canonical path?
• Does it match the requested deliverable?
• Is it grounded in authoritative sources?
• Does it avoid stale architecture assumptions?
• Are major claims evidence-backed?
• Are features/stories/gaps traceable?
• Are security-sensitive claims hygienic and accurate?
• Is the document specific enough to be used downstream?

If any answer is no, the outcome is NO-GO.

---

17. Package-Level Go / No-Go Rule

The full docs/demo-readiness/ package is not ready for downstream backlog generation until:

• core baseline documents exist,
• each has passed review,
• no unresolved P0 contradiction remains,
• and no document relies on stale architecture as current truth.

Package-level blockers

Any of these are automatic package-level NO-GO:

• missing canonical file
• unresolved architecture contradiction
• unverified API assumptions treated as fact
• security hygiene issue copied into canonical docs
• major feature/story claims without evidence

---

18. Decision

This checklist is the minimum deterministic QA gate for PLOCK demo-readiness documentation.

No document in this package should be treated as approved planning input until it passes this checklist with an explicit recorded verdict.