Skip to main content

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.

No comments to display

Back to top