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

3.6 KiB

type tldr status decided_on decided_by affects confidence quality last_updated freshness_window_days retention
decision 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. accepted 2026-11-02 Michał Kopeć 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 0.8 0.8 2026-11-02 365 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.