v0.3.0

0.3.0

Security — comprehensive exploit hardening (E01–E28)

Major release closing agent TOCTOU and hook-bypass classes discovered after 0.2.1.

Kernel

• Unstaged tracked edits close the gate — index-only hashing no longer leaves the gate open while working-tree edits await git add / -a
• gatedTreeOid mandatory — legacy gate.json without it never opens for shipping; re-run know-code pass after upgrade
• Shipping requires index tree === gatedTreeOid — blocks partial commits and post-pass tree drift before push
• Push requires HEAD^{tree} === gatedTreeOid — amend/--no-edit with a stale trailer cannot ship a new tree
• Cleanliness via git diff --quiet — never porcelain through git().trim() (which corrupted M file status lines)
• know-code commit / amend reject pathspecs — except gated slices: know-code commit -m "…" -- <files> is allowed only while the index tree still equals gatedTreeOid (see Sliced batches below)

Sliced batches & DevEx

• Sliced batch commits — quiz once, then land a staged batch as multiple know-code commit -m "…" -- <files> slices; the gate stays open under commit drift while the index tree matches gatedTreeOid and no unstaged tracked edits exist
• pass / ask preflight — refuse to run over unstaged tracked edits (quizzing work that isn't in the hash)
• know-code hash --explain — shows which staged files feed the hash and which unstaged/untracked files are excluded
• status staleness detail — stale artifacts show artifact hash vs current hash plus the likely cause instead of a bare "stale"
• doctor local-cli check — warns when bare know-code on PATH is a stale global instead of the local monorepo build
• Actionable gate messages — "Gate seal invalid" split into real causes (unstaged edits, staged tree differs, HEAD moved after seal)
• kc bin alias — every know-code command is also available as kc (kc status, kc commit -m "…"); no popular CLI ships a kc binary, and user shell aliases (e.g. alias kc=kubectl) shadow it harmlessly

Hook-safe partial commits (three git-interaction bugs)

• GIT_INDEX_FILE stripped from kernel git subprocesses — during git commit -- <paths> git exports a temp slice-only index to hooks; the pre-commit check now always hashes the real index (also kills an env-spoofing vector)
• write-tree lock fallback — git holds .git/index.lock mid-commit; materializedTreeOid retries against a temp copy of the index instead of silently returning the empty tree
• COMMIT_EDITMSG pre-written by know-code commit — git only writes it after the pre-commit hook, so the grounded pending-trailer check could never pass on the first commit after pass
• Pre-push accepts the seal-hash trailer — after range seal --rewrite, HEAD trailers carry the seal hash; check --push now accepts it at exactly sealedHeadOid with a grounded seal — and only in push mode: the seal never authorizes a new pending commit through pre-commit
• Fresh pass consumes superseded range seals — a seal/binding from a previous batch permanently blocked any later non-range commit from shipping (with attest on, nothing else ever cleared it); a successful human pass now removes seal artifacts pinned to a non-HEAD commit or to a tip already reachable from origin/<baseBranch> (push happened, seal consumed) — only a just-sealed unpushed tip at HEAD stays rewrite-open

CI & release

• know-code verify workflow is PR-only — on a push to the base branch there is no merge-base ahead of HEAD, so grounded verification is impossible by construction; init --workflow generates PR-only triggers
• Docs deploy on release tags only — the site always matches a published CLI version

Agent hooks (check-shell.sh + gate-cmd.ts)

Deny in agent context (humans stage/commit outside the agent; agents use know-code commit / amend):

Denied	Reason
git commit --amend	Stale trailer / tree rewrite
git commit -a/--all/-u/--update	Auto-stage TOCTOU
git commit with pathspecs / -C / --reuse-message / --fixup / --squash	Stale trailer or silent stage
git add	Stage unreviewed work
git add && git commit	Compound TOCTOU
git push --no-verify / hooksPath on push	Skip pre-push
git merge / cherry-pick / revert / rebase	Implicit commits
git stash apply/pop/branch	Reintroduce unreviewed trees
git reset --hard	Rewrite working tree

Artifacts & config

• enforcePipeline defaults to true — teaching + quiz pipeline required before pass
• Unsigned sealed-head-binding.json ignored when requireAttest: false (cannot bind HEAD alone)
• doctor --strict — fails when git hooks outdated/missing or agent hooks absent; warns on requireAttest: false and legacy gates
• ship runs doctor --strict first

Tests

• Table-driven exploit matrix (exploit-matrix.test.ts) covering E01–E28 helpers + kernel cases
• Sliced-commit e2e through real hooks — pathspec commits with git's temp index and held index.lock against an installed pre-commit hook
• Adversarial suite — forged trailers, agent-minted tokens, stale seals, post-seal drift

Breaking changes

1. Re-run know-code pass once if gate.json lacks gatedTreeOid
2. Agents cannot use raw git add / git merge / etc. — use know-code workflow
3. enforcePipeline: true by default
4. Prefer know-code doctor --strict in CI / before ship
5. Verify workflow triggers on pull_request only — remove push: branches from existing .github/workflows/know-code.yml (grounded verification has no merge-base on pushes to the base branch)