A knowledge harness for AI-assisted client work, where outcomes change what gets retrieved next time.
Read top-down for what it does. Read bottom-up for why you can trust it. EXEC-OS is the same architecture applied to executive decisions — shown alongside because the correspondence is the point.
Read OS.md first — it is the kernel spec, and everything else implements it.
Northwind Instruments does not exist. Every entity, knowledge record, signal and calendar entry is invented to exercise the mechanism. No real client, engagement, person or commercial term appears anywhere, and none ever will — a published repository is the wrong place for an account knowledge store.
What is real is the machinery: the kernel, the ontology, the promotion ladder, the scoring function, and
bin/reinforce.ps1. The weights inreinforcement/weights.yamlwere produced by running that script against the signal log in this repo, not written by hand.
Most "AI knowledge bases" are a folder of markdown and a prayer. They accumulate, they never forget, nothing is ever wrong, and within a few months retrieval quality is declining monotonically while the folder grows.
The missing pieces are a namespace, an expiry, a confidence that is earned rather than asserted, and a feedback loop from what actually worked.
One objection, traced through the whole stack. Every step is a real directory.
a buyer complains about seat pricing in a public forum
│
① LISTEN sources/ → observation, trust 0.50, never a fact yet
│
② RESOLVE semantic/ → "NWI" and "Northwind Inst" are one entity id
│
③ RECORD knowledge/candidate/ → written. Never auto-loads into client work
│
④ CONFIRM a DIFFERENT source class (a sales call, not a second thread)
│ → knowledge/validated/
│
⑤ FRAME context/ → this run: comparison page, technical evaluator,
│ intent = disqualify, must_concede = deploy speed
│
⑥ BOOT registry/ → the project manifest declares what it mounts
│
⑦ RANK score() → 0.40 sim · 0.20 trust · 0.15 fresh · 0.25 rl
│ fills the context budget, stops at the line
│
⑧ GATE channels/ → is this surface publish or listen?
│ does every claim have a validated source?
│ ── refuse here, or continue ──
│
⑨ PRODUCE the comparison page
│
⑩ SIGNAL reinforcement/signals.jsonl → accepted | edited | rejected | reused
│ mount_miss | contradiction | refused_policy
│
⑪ WEIGH bin/reinforce.ps1 → rl(k) changes. Step ⑦ behaves differently next time
│
⑫ CHECK eval/ → did the gates fire? is trust calibrated?
did retrieval regress?
Steps ③ and ④ are the ones people skip, and skipping them is how an unrepresentative sample becomes a fact. A confirmation has to come from a different source class — three threads on the same forum are one observation, not three.
Step ⑧ is the one that makes it a system rather than a generator. A refusal is a logged outcome, not an error.
Step ⑪ is why it is an OS. Nothing else here loops. The output of step ⑩ changes the behavior of step ⑦, which means the same question asked next quarter retrieves differently because of what happened this quarter.
1. Projects mount knowledge, they don't contain it. A manifest is a mount table. The same brand-token record serves a build, a QBR deck and a net-new pitch — and it improves for all three whenever any one of them uses it. Knowledge scoped inside a project dies with the project.
2. Outcomes change retrieval. Weights are 25% of the score that decides what enters the context window. A fact that has proven useful outranks one that is merely relevant — the entire reason to have a reinforcement layer rather than a vector search.
The kernel is the only silent layer — that is the definition, not an omission. Semantic has the fewest tasks and the highest leverage: an entity-resolution bug poisons every layer above it.
gtm-os/
OS.md the kernel: invariants, boot protocol, scoring
semantic/ ring 1 — the only namespace
ontology.yaml 12 entity types, trust table, TTL defaults, policies
entities/*.yaml canonical entities with alias lists
knowledge/ ring 2 — facts, tiered by confidence
canon/ load-bearing. 2 confirmations or 1 measured win
validated/ confirmed, loads normally
candidate/ observed once. Never auto-loads into client work
_deprecated/ things we believed that turned out false. Kept on purpose
sources/ ring 2.5 — surfaces you LISTEN to. Never generate here
src.ai-visibility.md whether answer engines name you, and citing what
src.community.md Reddit, HN, Stack Overflow — objection mining
src.review-platforms.md G2, Capterra — verified-buyer sentiment
context/ ring 2.7 — per-run frame. Composed, logged, stored nowhere
reinforcement/ ring 3 — outcomes change retrieval
signals.jsonl append-only. Never edited
weights.yaml DERIVED — regenerate, don't hand-edit
notes.md interpretation, where a rerun won't overwrite it
plays/ sequences that have run at least once
eval/ ring 3.5 — is the machinery still telling the truth
golden-set.md retrieval regression
reliability.md seeded errors, trust calibration, drift
channels/ ring 4.5 — surfaces you PUBLISH to, with refusals
POLICY.md the publish/listen split and its legal basis
ch.docs · ch.comparison · ch.research · ch.case-study · ch.linkedin
registry/ ring 4/5 — skills and projects
runtime/ ring 6 — ephemeral. Never promoted to knowledge
templates/ copy these to start something new
bin/ reinforce.ps1 · reinforce.py
pwsh bin/reinforce.ps1 # recompute weights from signals + knowledge frontmatter
pwsh bin/reinforce.ps1 -Check # dry run; prints, writes nothingbin/reinforce.py is the portable equivalent. Standard library only, by design.
Daily: boot a project, do the work, append a signal. Weekly: recompute, run the eval
checks. Monthly: read _deprecated/.
Seven signals, five records. The interesting output is not the ranking — it is the refusal.
The trust gate held a promotion. k.nw.phase-overlap earned a measured win and would
have reached canon on usefulness alone. The ladder refused, in its own words:
HELD: 1 measured win(s) but trust 0.3 is below 0.5 - needs human confirmation
It is an inference about a client's dependency structure, not something the client confirmed. Promoting it would let the system launder its own reasoning into fact. That guard was added after an earlier run recommended the promotion — the script found a real hole in the design.
A negative signal improved the store. k.nw.brand-tokens took a -0.4 when naive use
of the palette failed a colorblind check. It stayed canon, and the failure produced
k.nw.chart-colorblind, which then earned the cleanest promotion in the round.
Full read: reinforcement/notes.md.
A contradiction rate of zero and a refusal rate of zero are failure signals, not clean bills of health. Facts in a real market conflict; a store that never records one is either not ingesting enough or resolving conflicts silently. A gate that has never refused anything is almost certainly misconfigured.
Same principle as _deprecated/ being empty. A system in which nothing is ever wrong is a
system that is not being tested honestly. See eval/README.md.
- People. A live instance carries
person.*entities with roles and dispositions. - The dashboard and its renderer. Derived artifacts don't belong in a repository.
- Real commercial terms. No SOWs, rates, or engagement economics.
Working, in use, and small. Five records over seven signals exercises the machinery and
comes nowhere near validating the scoring weights. Treat the four coefficients in
score() as a starting hypothesis — eval/golden-set.md is what
makes them safe to change.