hyb-oa/.trellis/spec/hyb-oa/docs-and-evidence.md

Docs And Evidence

Source Docs

Use docs/文档索引.md and docs/文档事实源状态矩阵.md to locate the current fact owner.

Rules

• Update the existing fact source, module spec, manual or task. A new document needs a distinct purpose and registration in both the docs index and status matrix.
• Keep a verified reusable rule in its owning section; keep run chronology, counts, candidate hashes and unresolved hypotheses in task/evidence. Consolidate repetition without losing unique conditions, exceptions or references. If there is no new reusable lesson, no spec edit is needed; a fixed seven-section layout is not required unless the task/delivery contract requires it.
• Preserve historical Issue CSVs, findings and original receipts. New evidence adds a dated/sourced delta; it does not rewrite the old result. A matching selected-code digest does not establish whole-tree or publication coverage.
• Record relative report references and safe conclusions, not raw payloads, secrets, full accounts, invoice originals or confidential business content. Static validation, runtime behavior, independent review and public/real-data verification remain distinct.

Scenario: Registered Local Evidence Integrity

1. Scope / Trigger

Protect the 14 historical screenshots registered in the archived 07-18 small-team internal-readiness evidence table. Human-reviewed digest-registered artifacts remain evidence even when automated snapshot tests do not read them.

2. Signatures

node scripts/qa/check-trellis-governance.mjs calls validateRegisteredEvidence. Its code-owned registry defines document, artifact directory and expected count; the document's 截图 | SHA-256 table defines filenames and approved hashes.

3. Contracts

Require regular local files, without artifact symlinks or ancestor redirects. Preserve the registered documents/hashes. Before restoring an overwritten file, save the runtime copy and its digest separately. Do not unregister evidence to make a check pass. Private restore-candidate hashes without a public repository file mapping are outside this local check; do not fetch private/production inputs or claim every historical SHA was verified.

4. Validation / Error Matrix

Missing document/table/file, changed digest, invalid row/path, duplicate entry, symlink or reduced registered count fails governance. A match reports the exact verified count; silently shrinking the table is not an acceptable repair.

5. Good / Base / Bad

Verify the registered 14/14 separately from new isolated screenshots. Never replace approved hashes with runtime outputs or claim unmapped private evidence was locally checked.

6. Tests Required

node --test scripts/qa/tests/registered-evidence.test.mjs: intact evidence, overwrite/missing document/table/file/row, duplicate rows, unsafe paths and symlinks. Visual-output isolation and repository snapshot tests separately check the producer and tracked mutations, including an already dirty checkout.

7. Wrong / Correct

Report selected-source, whole-repository and index integrity separately; an unchanged selected-source digest does not prove the worktree is unchanged.

Scenario: Finding Lifecycle And Audit Closeout

1. Scope / Trigger

Use when later code, deployment or external evidence changes a recorded review, audit or trial-run finding's current disposition.

2. Signatures

Canonical ledger fields: findingId, dimension, discoverySeverity, confidence, discoveryStatus, remediationStatus, deploymentStatus, externalVerificationStatus, evidenceRef, businessImpact, controlObjective, safeVerification, followUpWorkPackage. A delta records discoveryCommit, reviewedCommit, changed commits, command/result and environment boundary.

3. Contracts

Preserve discovery baseline/severity/status. Maintain one canonical finding ledger per closeout; duplicate or reclassified component findings retain source references and map to exactly one canonical entry. Record remediation, deployment and external behavior independently: local PASS does not establish deployment, and a build marker does not establish role/device behavior.

When HEAD changes, identify old/new commits, classify the delta and rerun the applicable closeout gates; never relabel old reports as evidence for new inputs. Use relative evidence refs and synthetic fixtures. Unknown or unauthorized production/public/real-device checks remain explicitly pending or externally gated.

4. Validation & Error Matrix

Condition	Recorded state
Local fix verified, not deployed	Remediation may pass; deployment and applicable external behavior remain pending
Open finding with no fix artifact	NO_FIX_TO_DEPLOY, not DEPLOYMENT_PENDING
Static/tooling-only finding	Deployment may be NOT_APPLICABLE; record remediation independently
External verification not required	NOT_REQUIRED only where that verification is inapplicable
Duplicate component finding	Source retained; exactly one canonical ledger mapping

5. Good/Base/Bad Cases

A confirmed historical P0 stays P0/confirmed after local remediation. Do not replace discovery status with RESOLVED or a single resolved field that hides deployment or observation.

6. Tests Required

Task validation, Trellis governance/sensitive scan, document registry audit and git diff --check; verify that the recorded HEAD identifies the evidence-producing checkout. Select additional checks from the changed contract.

7. Wrong vs Correct

Wrong

{"findingId":"F-001","status":"resolved"} loses the discovery and verification states.

Correct

Keep discoverySeverity=P0, discoveryStatus=CONFIRMED, remediationStatus=LOCAL_FIX_VERIFIED, deploymentStatus=DEPLOYMENT_PENDING, externalVerificationStatus=EXTERNAL_BEHAVIOR_PENDING when those facts apply.

Scenario: QA Readiness Report Summaries

1. Scope / Trigger

Shell runners aggregating child launch/patrol/smoke/readiness reports into summary.json, step JSON or privacy findings under artifacts/qa-flow/ or task research.

2. Signatures

Parent output: summary.json; child input: <child-report-dir>/summary.json; step input/output: <step-name>.step.json.

3. Contracts

Use repo-relative reportRef/logRef for repository paths. Include each child's status and finding count; any child finding or non-clean status makes parent findingCount non-zero. Live readiness records local sourceCommit separately from public observedBuildSha; absent/mismatched public identity cannot yield a clean pass attributed to local HEAD.

Allow status/count/mode/conclusion, operational booleans and relative refs. Exclude amounts/prices/costs/balances, bank/invoice details, full accounts, tokens/secrets, raw payload/form values and absolute local paths. Presence reports use safe labels such as adminCredentialReady, never secret-like raw environment-key field names, even with boolean values.

check-pending-ocr.mjs reuses the adapter-backed Prisma client factory and closes both Prisma and its external PostgreSQL pool.

4. Validation & Error Matrix

Child/observation	Parent behavior
PASS and findingCount=0	May remain pass
PASS_WITH_FINDINGS or any child findingCount>0	Record a finding
SKIP, PARTIAL, PAUSED, MISSING	Record manual_or_config
FAIL, BLOCKED, ERROR or blocker-like status	Record finding/blocker according to whether the step is required
Privacy smoke match or secret-like report field	Redacted finding metadata; final summary reflects failure
Missing/unusable public /ready build SHA	manual_or_config finding
Expected/observed public SHA mismatch	manual_or_config or deployment blocker, never clean pass

5. Good/Base/Bad Cases

A parent report exposes child status/count and separate source/public identities. Missing credentials produce PASS_WITH_FINDINGS or manual_or_config/blocking, not clean readiness; exit 0 alone cannot erase a child's findings.

6. Tests Required

• bash -n <runner>.sh; exercise the parent/consuming aggregator with missing credentials. Assert parent PASS_WITH_FINDINGS or blocked, visible child count and privacy step, and absence of full paths/business amount fields.
• Assert safe readiness labels and no raw secret-like environment-key fields.
• Use a synthetic 40-character SHA to assert the public bundle exposes only its 12-character marker; a local HTTP stub verifies readiness reads and compares that marker.

7. Wrong vs Correct

Wrong

A clean parent status with an empty childReports hides a child's findings; a raw credential environment-key name remains unsuitable even with value true.

Correct

A PASS_WITH_FINDINGS summary records sourceCommit, observedBuildSha, buildShaMatches, relative reportRef, and childReports.<name> with its status, relative reportRef and findingCount. Credential presence uses liveSmoke.adminCredentialReady, not a raw credential key.