feat: add deterministic KB release gates

CODEX.md

@@ -99,6 +99,13 @@ python3 -m pytest tests/test_search_cli_mvp_10.py -q
 
 Additional safe test commands are listed in `RUNBOOK.md`.
 
+KB release gate validation:
+
+```bash
+python3 -m pytest tests/test_kb_release_gate.py -q
+python3 scripts/check_kb_release_candidate.py --governance-dir docs/kb_release --scope governance-only --mode candidate --json
+```
+
 ## 7. Generated artifact policy
 
 - `input/raw` is source material and must remain unchanged unless explicitly approved.

README.md

@@ -271,6 +271,42 @@ For local markdown reading or search:
 python3 scripts/search_kb.py "variance analysis" --path publish/markdown_kb/full_kb.md --limit 5
 ```
 
+## KB Release Candidate Gates
+
+Use the deterministic release gate checker after compact package generation:
+
+```bash
+python3 scripts/check_kb_release_candidate.py \
+  --package-dir publish/chatgpt_project_compact \
+  --governance-dir docs/kb_release \
+  --scope full \
+  --mode candidate \
+  --json
+```
+
+Governance-only check:
+
+```bash
+python3 scripts/check_kb_release_candidate.py \
+  --governance-dir docs/kb_release \
+  --scope governance-only \
+  --mode candidate \
+  --json
+```
+
+Promotion mode is stricter and requires an acceptance decision:
+
+```bash
+python3 scripts/check_kb_release_candidate.py \
+  --package-dir publish/chatgpt_project_compact \
+  --governance-dir docs/kb_release \
+  --scope full \
+  --mode promotion \
+  --json
+```
+
+The checker does not build or refresh generated outputs. It uses no network, LLM, Ollama, Gemini, embeddings, or vector DB.
+
 For Obsidian:
 
 1. Copy or open `publish/obsidian/` as a vault or inside an existing vault.

RUNBOOK.md

@@ -107,3 +107,23 @@ rg -n "active|historical|source of truth" CURRENT_SCOPE.md
 rg -n "input/raw|workspace|publish" DATA_CONTRACTS.md
 rg -n "pytest|network|Ollama|Gemini|approval" RUNBOOK.md
 ```
+
+## KB release gate validation
+
+Targeted deterministic checker tests:
+
+```bash
+python3 -m pytest tests/test_kb_release_gate.py -q
+```
+
+Governance-only release gate check:
+
+```bash
+python3 scripts/check_kb_release_candidate.py \
+  --governance-dir docs/kb_release \
+  --scope governance-only \
+  --mode candidate \
+  --json
+```
+
+The checker is deterministic and does not build or refresh generated outputs. If the package directory is absent, package/full scope returns blocked for the missing package; governance-only scope can pass without real `publish/**`.

docs/kb_release/ACCEPTANCE_DECISION_TEMPLATE.md

@@ -0,0 +1,52 @@
+# Acceptance Decision Template
+
+Canonical machine-readable block:
+
+```yaml
+acceptance:
+  quality_status: pass
+  decision: accepted
+  promote_to_strong: yes
+```
+
+# Acceptance Decision
+
+Package:
+Version:
+Date:
+Owner:
+
+## Gate results
+
+| Gate | quality_status | reason | unsupported_claims | required_revision |
+|---|---|---|---|---|
+
+## Blockers
+
+-
+
+## Residual risks
+
+-
+
+## Known gaps
+
+-
+
+## Decision
+
+accepted / revise / blocked
+
+## Promote to strong
+
+yes / no
+
+## Next step
+
+-
+
+Promotion rule:
+
+```text
+promote_to_strong = yes only if all gates pass and decision = accepted
+```

docs/kb_release/CODEX_HANDOFF_SPEC.md

@@ -0,0 +1,32 @@
+# Codex Handoff Spec
+
+Use this final report format for KB release gate work:
+
+```markdown
+changed files
+- ...
+
+commands run
+- ...
+
+test results
+- ...
+
+unresolved conflicts
+- ...
+
+whether AGENTS.md still needs manual review
+- yes/no, with one short reason
+
+blockers
+- ...
+
+residual risks
+- ...
+
+rollback
+- ...
+
+acceptance status
+- pass / partial / fail / blocked
+```

docs/kb_release/EVAL_RUN_TEMPLATE.md

@@ -0,0 +1,26 @@
+# Eval Run Template
+
+```yaml
+eval_id:
+date:
+task_type:
+input_summary:
+context_package_used:
+model_class:
+output_type:
+evidence_status:
+unsupported_claims:
+judge_verdict:
+revision_required:
+revision_applied:
+final_quality_status:
+limitations:
+owner_project:
+next_step:
+```
+
+Quality status:
+
+- pass
+- revise
+- blocked

docs/kb_release/KB_CARD_PASSPORT.md

@@ -0,0 +1,44 @@
+# KB Card Passport
+
+Required fields:
+
+```yaml
+card_id:
+card_type:
+source_id:
+title:
+summary:
+evidence:
+confidence:
+review_status:
+risks:
+limitations:
+owner:
+created_at:
+updated_at:
+revisit_trigger:
+```
+
+## Allowed Confidence
+
+- strong
+- medium
+- weak
+- unsupported
+
+## Allowed Review Status
+
+- accepted
+- candidate
+- review_required
+- weak
+- unsupported
+- deprecated
+- duplicate_candidate
+
+## Rules
+
+- Missing `source_id` is `revise` or `blocked` depending on mode.
+- `unsupported` cannot be promoted to strong.
+- `weak` cannot be promoted as fact.
+- Every accepted card must have evidence and limitations.

docs/kb_release/KB_RELEASE_GATES.md

@@ -0,0 +1,39 @@
+# KB Release Gates
+
+Gate result schema:
+
+```yaml
+gate_name:
+quality_status: pass | revise | blocked
+reason:
+unsupported_claims:
+required_revision:
+residual_risks:
+```
+
+## Required Gates
+
+| Gate | Purpose |
+|---|---|
+| governance package exists | `docs/kb_release/` is available. |
+| candidate package exists | Candidate package directory is available when package/full scope is checked. |
+| required files gate | Required governance or compact package files are present. |
+| boundary gate | Active source/include markers do not reference forbidden raw/private/generated materials. |
+| card passport gate | Required card passport fields are documented. |
+| confidence/review status gate | Confidence and review status values are documented. |
+| weak/unsupported promotion gate | Weak or unsupported evidence is not promoted as supported knowledge. |
+| negative eval gate | Required negative eval cases are present. |
+| acceptance decision gate | Promotion has an accepted decision block. |
+| promotion readiness gate | Strong promotion is allowed only after accepted gates. |
+
+## Aggregation
+
+Aggregation rule:
+
+```text
+blocked > revise > pass
+```
+
+If any gate is blocked, overall status is `blocked`.
+If no gate is blocked but at least one gate is `revise`, overall status is `revise`.
+Only all-pass gives `pass`.

docs/kb_release/KB_RELEASE_METHOD.md

@@ -0,0 +1,35 @@
+# KB Release Method
+
+## Flow
+
+```text
+existing compact KB workflow
+  -> candidate package
+  -> deterministic gates
+  -> smoke QA / negative eval readiness
+  -> acceptance decision
+  -> strong package readiness
+```
+
+The existing compact KB workflow produces `publish/chatgpt_project_compact/` when a generated-output task is explicitly approved. This governance layer only validates a candidate directory when one is provided.
+
+## Release Meaning
+
+- Candidate package: compact package ready for deterministic checking.
+- Strong package: accepted status after all gates pass and an acceptance decision is present.
+- Strong is status after gates, not a manual folder.
+
+## Exclusions
+
+The strong package must not include:
+
+- raw transcripts;
+- chunks;
+- clean notes;
+- source-card dumps;
+- logs or temp files;
+- embeddings or vector DB artifacts;
+- `.env`;
+- private finance, client, credential, or operational data.
+
+Real promotion is a separate generated-output task and is not performed by the checker.

docs/kb_release/KB_SCORING_RUBRIC.md

@@ -0,0 +1,21 @@
+# KB Scoring Rubric
+
+| Criterion | 0 | 1 | 2 |
+|---|---|---|---|
+| Reusability | one-off | useful for one scenario | useful 5+ times or 3+ scenarios |
+| Specificity | generic | partly relevant | directly relevant to KB / ChatGPT / Codex |
+| Actionability | note only | advice | rule / checklist / gate |
+| Evidence clarity | no source | partial source | source_id + confidence + review_status |
+| Compression quality | raw/noisy | partly compressed | compact, reusable, no noise |
+
+## Decision Matrix
+
+| Score | Decision |
+|---|---|
+| 9-10 | candidate |
+| 7-8 | compress + judge |
+| 5-6 | keep in full KB |
+| 0-4 | archive |
+| blocker | reject |
+
+Scoring cannot override blockers.