ckb/docs/decisions/0013-kept-answers-and-secret-guards.md
Michał Kopeć cb56da51e5 Template 1.22.0: agent-knowledge release 1
Seven features from the 2026-10-31 agent-knowledge research, no schema
change (kb_schema_version stays 1.5):

- F1 session-start hook: session_start.py --hook, start_hook.py, opt-in
  via session.start_hook in ckb.yaml (D-0011)
- F2 kept answers in outputs/answers/, lint check 16 (D-0013)
- F3 ingest check-in before writing; batch mode skips it
- F5 open threads in workload notes, collected at session start (D-0012)
- F6 dedup_inbox.py: duplicates reported before ingest
- F19 lint check 15 for secrets and <private> spans, --secrets before
  every sync commit, redaction in saved conversations (D-0013)
- F20 context budget: lint_report.py --budget, budget in ckb.yaml

Smoke test covers every new script. Docs updated in EN and PL.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 19:25:02 +01:00

72 lines
3.6 KiB
Markdown

---
type: decision
tldr: Answers worth keeping go to outputs/answers/ with fingerprinted sources and a Gaps section and reach the wiki only through a normal ingest; committed text is scanned for credential shapes and <private> spans by lint and before every sync commit, never auto-fixed, with a line-hash allowlist for harmless matches.
status: accepted
decided_on: 2026-11-02
decided_by: Michał Kopeć
affects: AGENTS.md, .agents/skills/ckb-retrieve/SKILL.md, .agents/skills/ckb-ingest/SKILL.md, .agents/skills/ckb-lint/, .agents/skills/ckb-sync-changes/SKILL.md, .agents/skills/ckb-add-conversation/scripts/save_conversation.py, docs/MANUAL.md
confidence: 0.8
quality: 0.8
last_updated: 2026-11-02
freshness_window_days: 365
retention: high
---
# D-0013 — Kept answers live in outputs/; secrets and private spans are guarded
**Status:** Accepted · **Decided:** 2026-11-02 · **Deciders:** Michał Kopeć
## Context
Two features from the 2026-10-31 research report touch the same boundary,
what may become shared, committed knowledge:
- **F2, keep answers.** Karpathy's LLM-wiki pattern files good answers back
as pages. Written straight into `wiki/`, an answer would skip the check-in,
the blast radius and the fingerprints that every other page goes through.
- **F19, secret and privacy guards.** Every file in a KB is committed and
usually pushed. The sync skill already flagged secret-looking *file names*
but never looked inside files, and a saved conversation copied everything
verbatim.
## Decision
1. **Kept answers are outputs.** On request, `ckb-retrieve` writes
`outputs/answers/YYYY-MM-DD_<slug>.md` (`type: answer`) with the answer,
`## Sources` fingerprints of the pages and files it rests on, and a
`## Gaps` section. It updates an existing answer to the same question
instead of writing a second. Lint check 16 reports a kept answer whose
sources moved.
2. **Filing back is an ingest.** The answer is copied into `raw/inbox/` and
ingested like any source. Retrieval never writes `wiki/` pages.
3. **Lint check 15 scans committed text** in `wiki/`, `outputs/` (not the
gitignored exports), `workload/` and `raw/` for credential shapes, and
`wiki/` for `<private>` spans. A finding shows four characters, never
the secret. It is never auto-fixed, because the remedy is rotation.
`--quick` counts findings at session start, and `ckb-sync-changes` runs
`--secrets` before staging and stops on a hit.
4. **Allowlist by line hash.** `.secrets-allow` holds `<path> <hash>` pairs.
The hash covers that line's text, so editing the line brings the finding
back, and a moved line stays allowed.
5. **`<private>` spans** are dropped by ingest, never quoted by retrieval, and
redacted from saved conversations in both the JSONL and the Markdown.
JSONL lines without a span stay byte-identical.
## Alternatives considered
- **Kept answers under `wiki/answers/`** was rejected: they would be pages
that bypassed ingest's checks, and they would need log entries.
- **A git pre-commit hook for secrets** was rejected for now: per-machine
hooks have to be installed, while the sync skill and session-start check
run everywhere.
- **Auto-removing a found secret** was rejected: removal without rotation
gives a false sense of safety.
## Consequences
- Retrieval keeps its read-only character apart from two named exceptions:
query gaps and kept answers.
- Pattern lists produce false positives. The allowlist is the outlet, and
the bash/PowerShell fallbacks use a smaller pattern set than Python.
- Redaction removes only the span. A private value the agent repeated
elsewhere in the session is still saved, and the skill says so.