unknown-knowledge 2.1.0

package/payload/docs/boundaries.md

@@ -0,0 +1,60 @@
+# Guarantees and boundaries
+
+What the kit promises, what it deliberately does not, and which of its rules
+are yours to change. Each section names the decision that pinned it — the
+full record is in the kit's decision log, and the seeded copy of every rule
+below lives in `protocol/AGENTS.md`.
+
+## What the kit will never catch (D-008)
+
+The kit catches **conceptual drift**: names, value sets, and pointers — the
+map disagreeing with the artifact. A registry gained a value no concept
+knows; a concept enumerates a value the source dropped; a pointer dangles at
+a file that moved.
+
+It will **never** catch **behavioral drift**: logic bugs, inverted
+conditions, a wrong calculation behind a correctly-named function, a
+registry whose values are all present and all handled badly. Behavior is
+your test suite's job. Budget your trust accordingly: a green validator run
+means the map matches the code, not that the code is right.
+
+## The engine never executes your code (D-014)
+
+The engine only ever **reads your files lexically**. It never imports,
+evals, or runs repo content; JSON and YAML are parsed as data, never
+loaded as code; it makes no network calls. The one child process the
+engine spawns is `git` (in `survey-map.js`, to list tracked files) — it
+reads git's index, never your code. This is the answer to "does this tool
+run our code in CI?": no — guaranteed by design and pinned by a grep test
+in the kit's own CI. Any future adapter that would break it (e.g. a
+remote-config fetch at validate time) must be explicitly opt-in.
+
+## Findings privacy — the capture content policy
+
+Findings, misses, and gaps are committed YAML fragments: permanent git
+history **in your repo**, reviewable in PRs like any other change — and
+they never leave it. The kit has no runtime and no telemetry; nothing is
+collected or sent anywhere.
+
+The capture policy is what keeps the fragments safe to commit: summaries
+carry **concept IDs and file paths only** — never verbatim user text,
+quoted session content, or secrets; the `session` field is an opaque ID.
+This strips context by design — a finding is a signal that something
+disagreed, not a transcript of the disagreement. The SSOT is the artifact
+the finding points at; anyone judging a finding follows the pointer and
+reads the source.
+
+## Preflight conduct is yours to set (D-011)
+
+Verdicts are deterministic engine facts; **what a session does about a
+verdict is policy in markdown you own**. The place to edit is the
+CLIENT-EDITABLE conduct table in `protocol/AGENTS.md`
+("Conduct-on-verdict policy"): the recommended default is
+quarantine-and-continue, and a stricter shop may edit `quarantined` to
+fail-stop — that is the sanctioned edit, made by normal PR through your
+steward gate.
+
+The non-editable floor: the engine's verdicts, exit codes, and evidence are
+computed facts, not policy — and no policy edit may tell an agent to bypass
+a gate, trust a quarantined concept's claims, or treat exit 2 (a check that
+never ran) as anything but a stop.

package/payload/docs/ci-wiring.md

@@ -0,0 +1,109 @@
+# CI wiring — validators in CI, attribution on PRs
+
+> Commands run from the **repo root** with the kit dir at its default name
+> `unknown-knowledge/`; substitute your chosen name if it differs. The CI
+> snippets below are honest templates: written to be correct, **not executed
+> against every CI product** — adapt runners, images, and paths to your
+> setup, then watch the first run.
+
+The kit never wires CI at init (D-006) — CI systems churn; your pipeline is
+yours. But at team scale CI stops being optional in practice: session-level
+preflight is a sufficient gate for a small team, not for hundreds of
+engineers. Wire the two validators in.
+
+## What may gate, and what never does
+
+- `engine/validate.js` and `engine/validate-values.js` are blocking-grade
+  and MAY gate a merge. Exit codes: 0 = clean, 1 = findings, 2 = the check
+  never ran. Fail the job on both 1 and 2 — **a check that never ran is a
+  blocking defect, never a silent pass** (a non-zero exit fails the job by
+  default in every system below, so the templates need no special casing).
+- `engine/preflight.js` with no `--concepts` checks store health only — add
+  it as a third gating step if you want the store verdict pinned in CI.
+- `engine/audit.js` is advisory (never blocking): it drafts proposals for
+  human review, and presenting it as a required check would flip the whole
+  protocol from proposal-first to gate-first. Keep it out of CI. Its
+  `--fail-on-findings` flag exists for a human's local run — never a CI
+  default.
+
+The engine needs Node ≥ 22 and its one library dependency, `js-yaml`,
+resolvable in the checkout (see the seeded README) — the templates below
+install dependencies for that reason. It reads your files lexically — it
+never executes your code and never touches the network
+(`docs/boundaries.md`) — so the jobs need no secrets, tokens, or extra
+permissions.
+
+## GitHub Actions
+
+```yaml
+# .github/workflows/knowledge-gates.yml — untested template, adapt.
+name: knowledge-gates
+on: pull_request
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm ci # js-yaml must resolve; use `npm install js-yaml` if you keep no lockfile
+      - run: node unknown-knowledge/engine/validate.js --root .
+      - run: node unknown-knowledge/engine/validate-values.js --root .
+```
+
+## GitLab CI
+
+```yaml
+# .gitlab-ci.yml fragment — untested template, adapt.
+knowledge-gates:
+  image: node:22
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  script:
+    - npm ci # js-yaml must resolve; use `npm install js-yaml` if you keep no lockfile
+    - node unknown-knowledge/engine/validate.js --root .
+    - node unknown-knowledge/engine/validate-values.js --root .
+```
+
+## Xcode Cloud
+
+Xcode Cloud runs custom scripts from `ci_scripts/`; its images ship no Node
+runtime, so the script installs one.
+
+```sh
+#!/bin/sh
+# ci_scripts/ci_post_clone.sh — untested template, adapt.
+set -e
+brew install node
+npm ci --prefix "$CI_PRIMARY_REPOSITORY_PATH" # js-yaml must resolve
+node "$CI_PRIMARY_REPOSITORY_PATH/unknown-knowledge/engine/validate.js" --root "$CI_PRIMARY_REPOSITORY_PATH"
+node "$CI_PRIMARY_REPOSITORY_PATH/unknown-knowledge/engine/validate-values.js" --root "$CI_PRIMARY_REPOSITORY_PATH"
+```
+
+## PR drift attribution (D-012) — whose findings are these?
+
+Filtering validation down to the concepts a PR touched is rejected by
+design: any gap in the reverse index (folder pointers, renames, module
+adds/deletes) turns the filter into a false all-clear, which is worse than
+no check. Attribution instead diffs **two honest whole-store runs** — the
+finding set at the PR's merge-base against the set at HEAD. Both validators
+emit stable, sorted JSON precisely so this diff means something.
+
+```sh
+git worktree add /tmp/kk-base "$(git merge-base HEAD origin/main)"
+
+# Exit 1 just means findings exist — attribution wants the sets, not the gate.
+node unknown-knowledge/engine/validate.js --json --root /tmp/kk-base > /tmp/base.json || true
+node unknown-knowledge/engine/validate.js --json --root . > /tmp/head.json || true
+
+# Right side only = drift this PR introduced; left side only = drift it fixed.
+diff <(jq -S '.findings' /tmp/base.json) <(jq -S '.findings' /tmp/head.json)
+
+git worktree remove /tmp/kk-base
+```
+
+Run the same pair with `engine/validate-values.js` for value drift. In a CI
+gate, fail on findings the diff attributes to the PR rather than on the raw
+exit code — the baseline may legitimately be red while the map catches up,
+and a PR should answer for its own drift, not the backlog's.

package/payload/docs/steward-guide.md

@@ -0,0 +1,238 @@
+# Steward guide — owning the loop
+
+> Commands run from the **repo root** with the kit dir at its default name
+> `unknown-knowledge/`; substitute your chosen name if it differs.
+> Procedures live in the skills and in `protocol/AGENTS.md` — this guide
+> tells you what the steward decides and points at where each procedure is
+> defined; it never restates one.
+
+## The role
+
+A small group or rotation owns the improvement loop; the ordinary engineer
+invokes nothing — the protocol rides along in their sessions. The steward:
+
+- runs `/knowledge-reflect` on cadence — weekly, daily at high finding
+  volume (procedure: `protocol/skills/knowledge-reflect.md`);
+- triages the reverse audit's drafted concepts — audit output is advisory
+  (never blocking), so every draft waits for your judgment;
+- gates `/kb-build` promotions — the knowledge store's only write path is
+  cited and human-gated (`protocol/skills/kb-build.md`);
+- accepts decision entries (final `D-NNN` assignment, below).
+
+The heartbeat is `/knowledge-audit` (`protocol/skills/knowledge-audit.md`):
+days-since-last-reflect, open-fragment counts, top quarantined concepts — a
+lapsed rotation is visible instead of silent. The engine side of triage is
+one command; `--today` is passed explicitly because diffable output never
+reads the wall clock:
+
+```
+node unknown-knowledge/engine/audit.js --root . --json --today 2026-07-09 --stale-days 90
+```
+
+## Reflect lands as a PR
+
+Reflect emits a recommendation list — each item a concrete diff with its
+corroborating findings attached; you approve or reject **per item**, and
+approved diffs land as a normal PR. That is the design, not a convenience:
+even the improvement loop's own changes pass the review and CI your org
+already trusts, and rejections leave a recorded reason instead of a
+disappeared suggestion.
+
+## CODEOWNERS — scope the human gate
+
+Gate the stores, the protocol, and the engine; leave the logs alone:
+
+```
+# CODEOWNERS — steward review scoped to the governed surfaces.
+/unknown-knowledge/ontology/   @your-org/knowledge-stewards
+/unknown-knowledge/knowledge/  @your-org/knowledge-stewards
+/unknown-knowledge/decisions/  @your-org/knowledge-stewards
+/unknown-knowledge/protocol/   @your-org/knowledge-stewards
+/unknown-knowledge/engine/     @your-org/knowledge-stewards
+# logs/ is deliberately absent: findings ride nearly every agent-assisted
+# PR. Requiring steward review there drowns the rotation in rubber-stamping
+# — or teaches engineers to delete fragments to unblock merges, and capture
+# dies. Logs must never require steward review.
+```
+
+## Suppressions hygiene
+
+`unknown-knowledge/suppressions.yaml` silences known-noise audit findings.
+Each entry is **strictly** `{ term, sourcePath, reason, date }`, exact match
+only — no patterns, no expiry (D-013). Two properties to lean on:
+
+- **Fails open.** A malformed entry (or an unparseable file) warns and
+  suppresses nothing, so the findings it would have hidden resurface — a
+  suppression can hide less than you meant, never more.
+- **Exact match is self-expiring.** A suppression stops matching the moment
+  the file moves or the term changes; that is a feature, not fragility.
+
+The JSON report carries the full suppressed list — sweep it on reflect
+cadence and prune entries whose `reason` no longer holds.
+
+## ID collision — two branches mint the same K-id
+
+Published IDs are immutable — never renumbered (PRD §3.5). When two
+branches both mint `K-210`, the merge is textually clean and the duplicate
+surfaces on main; the **later-merging PR renumbers its own entry**, never
+the one already published:
+
+1. Rebase onto main and run the structural validator — it reports the
+   `duplicate-id` finding:
+
+   ```
+   node unknown-knowledge/engine/validate.js --root .
+   ```
+
+2. Re-mint your entry at a free id within the owning class's range (mint
+   with gaps, per the store's `_rules.yaml`).
+3. Update your branch's own inbound refs to the new id — `used-by`,
+   `relates-to`, and any `consulted:` refs in findings your branch appended.
+4. Re-run both validators; green means the renumber is complete.
+
+## Decisions authoring
+
+The write path is the "Decisions-authoring path" in `protocol/AGENTS.md`:
+anyone — agent or human — drafts a `proposed` entry with a provisional
+date-suffixed id through the normal PR gate. Your half is acceptance: assign
+the final `D-NNN` within range, and hold the append-mostly line — status
+transitions never rewrite `context`/`decision`, and supersession chains must
+resolve and stay acyclic.
+
+## Phoenix events — re-filing a drifted subtree
+
+Sometimes the material is fine and the shelf is wrong: one class holds two kinds
+of thing that no longer share a reader, or a name stopped meaning what it says.
+A phoenix event fixes that in bulk, under review, without breaking a single
+citation.
+
+It is a PR like any other, carrying four things: the Decisions entry that
+sanctions it (copy `templates/decisions/phoenix-event.yaml`), the registry
+mintings the new values need, the mapping at `knowledge/_phoenix/<event>.yaml`,
+and the leaf rewrites — which you never make by hand:
+
+```
+node unknown-knowledge/engine/phoenix.js P-001 --root .            # dry run: plan it, write nothing
+node unknown-knowledge/engine/phoenix.js P-001 --root . --apply    # write, only if the plan is clean
+```
+
+What to check when you review one:
+
+- **The mapping is complete.** Every leaf in the declared scope must be mapped,
+  split, or explicitly carried forward. The engine refuses the event and names
+  the leaf otherwise — it will not half-apply, so a rejected event leaves the
+  store exactly as it found it.
+- **Each row's `why` earns its move.** On a split this is the whole substance:
+  the class-level rule cannot say why L-000117 went to ingest and its neighbour
+  went to patterns, so the rows have to.
+- **The diff is two lines per leaf.** `edition` and the one facet. If a leaf's
+  citations, body, or `id` appear in the diff, something is wrong — the engine
+  rewrites single frontmatter lines and copies every other byte through.
+- **The mapping stays.** Do not delete it after the event lands. It is what lets
+  the validator confirm every edition above 1 was sanctioned, reading only the
+  working tree. A leaf's edition must equal `1 + the events that moved it`, and
+  `validate.js` reports `unaccounted-edition` when it does not.
+
+Identity never moves. Accession ids are untouched, so every citation into the
+subtree — decisions entries, catalog rows, leaf cross-references — stays valid
+across the event. If a proposal needs an id renamed or reissued, it is not a
+phoenix event.
+
+## Findings are lossy, by design
+
+Keep the corroboration math honest by knowing what the log is not:
+
+- **Capture strips context deliberately.** Summaries carry concept IDs and
+  file paths only — never verbatim user text (see `docs/boundaries.md`).
+  The SSOT is the artifact the finding points at, never the finding's
+  prose: to judge a cluster, follow the pointers and read the source.
+- **Findings travel only with merged PRs.** Abandoned branches lose theirs.
+  Corroboration tolerates a lossy denominator — treat finding counts as
+  signal, never as census.
+
+## Trust graduation — narrowing inspection, and un-narrowing it
+
+Autonomy is graduated per change-category, never global, never per leaf, and
+never assumed (the gate rules in `protocol/AGENTS.md`). The category is the
+unit because it is the only thing evidence can be about: "this leaf has been
+right ten times" says nothing about the eleventh leaf, which is a different
+claim by a different author, whereas "alias additions have been approved
+unmodified ten cycles running" is evidence about a class of edit.
+
+The observable basis is what reflect already records: **per-item approval
+outcomes by category** (approved / approved-with-modification / rejected).
+
+### The category table
+
+`decisions/_registries/graduation-categories.yaml` declares every change
+category and its eligibility. It is filed under `decisions/` because
+graduation governs the change *process* — the team's truth anchor (D-003) —
+not the knowledge itself. Two shapes:
+
+- **`eligible`**, with a threshold **N**: mechanical categories, where the
+  edit is checkable by reading it and a clean run is evidence about the next
+  one. Alias additions, verified bumps, `paths` edges, see-also links.
+- **`gated`**, permanently: judgment categories. New domain classes,
+  contradicts/supersedes edges, authority assignments, and **anything
+  citation-bearing**. These never graduate, however long the streak — the
+  streak answers a different question than the one they ask. A correct
+  authority assignment ten times over says the assigner has been careful, not
+  that the eleventh source's trustworthiness can go unread.
+
+Every row carries a warrant and cites a Decisions entry, like any registry
+value. A malformed table is a hard error (exit 2), not a finding: graduation
+checks judged against a table the engine could not read are checks that never
+ran.
+
+### v1 analytics are MANUAL — the engine does not compute the counts
+
+State this plainly to anyone reading a green validator: **the engine does not
+compute approved-unmodified counts and never decides whether a threshold was
+met.** It checks that the entry is well-formed, that its category is declared,
+and that the category is not gated. *You* count the cycles and judge them
+against N. The `observed-cycles` field is your written record of that count,
+kept so a reviewer can weigh the judgment — no code asserts it. A clean
+validation run is not agreement that a graduation was earned.
+
+### Recording one
+
+Copy `templates/decisions/trust-graduation.yaml`, and record the graduation as
+a `decisions/` entry of category `trust`. The entry carries a typed
+`graduation:` block naming the category and your observed count.
+
+```
+node unknown-knowledge/engine/validate.js --root .
+```
+
+### Revocation is automatic on ANY defect
+
+**Any defect found in a graduated category revokes it.** Not "a serious
+defect", not "a pattern of defects" — one is enough, and the response is
+mechanical so it cannot be argued down. The warrant for sampling a category
+was that it had stopped producing surprises; one surprise is the evidence that
+it has not. Record it with `templates/decisions/trust-revocation.yaml`; the
+category returns to full inspection and its streak restarts at zero.
+
+Revoking is deliberately the cheapest entry in the store to write. Narrowing
+inspection takes a counted streak and a written rationale; restoring it takes
+noticing one defect. If revoking were as laborious as graduating, the
+laborious thing would quietly not get done and the boundary would only ever
+move one way. Revoking is always allowed — including for a gated category,
+where it is a no-op that records the standing position. Only *graduating* a
+gated category is refused.
+
+### Citation spot-checks stay in the sampling plan at every trust level
+
+Whatever a category has earned, **citation spot-checks continue at every trust
+level**, including the most graduated. A citation is a claim about the world
+that the store cannot check for itself; no streak of clean mechanical edits is
+evidence that the citations are sound. Graduation only ever answers the
+mechanical question.
+
+### Provenance — tracing a bad skill revision
+
+Entries carry `provenance` (`author`, `skill-version`), and the validator
+surfaces it in both JSON and human output. When a defect turns out to come
+from a bad skill vintage rather than a bad judgment, this is what makes every
+entry that vintage wrote findable rather than guessed at — a bad skill
+revision is traceable like any other defect.

package/payload/engine/audit.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * engine/audit.js — the entry shim (UCS-956).
+ *
+ * This file statically imports NOTHING. That is its entire job.
+ *
+ * Node exits 1 on an unhandled ES module load error, and exit 1 means FINDINGS
+ * (PRD §5). A SyntaxError in a lib/ module, or a missing `js-yaml`, must not
+ * tell an agent that the check ran and found problems. So the engine is reached
+ * only through `import()`, where a load failure is an ordinary catchable
+ * rejection rather than a process-level crash.
+ *
+ * Both specifiers are string literals naming the engine's own files. D-014
+ * forbids importing REPO CONTENT — the client's code — and nothing here can
+ * name it: there is no variable to point somewhere else.
+ *
+ * The command lives in commands/audit.js. Its invocation path is unchanged.
+ */
+try {
+  const [{ boot }, command] = await Promise.all([
+    import('./lib/boot.js'),
+    import('./commands/audit.js'),
+  ]);
+  // exitCode, never process.exit(): exit() drops queued async stdout writes, so
+  // piped --json output would truncate at the pipe buffer — corrupt output
+  // wearing a clean exit code. Node exits on its own once stdout drains.
+  process.exitCode = await boot('audit', command);
+} catch (error) {
+  // The engine could not be loaded, so no check ran. Exit 2 — never 1.
+  // Hardcoded, because reading it from lib/exit-codes.js is the very thing
+  // that may have just failed.
+  process.stderr.write(`audit: internal failure — the engine could not be loaded\n${error?.stack ?? error}\n`);
+  process.exitCode = 2;
+}