diff --git a/.agents/skills/ckb-decide/SKILL.md b/.agents/skills/ckb-decide/SKILL.md index f5ea0fa..b46d381 100644 --- a/.agents/skills/ckb-decide/SKILL.md +++ b/.agents/skills/ckb-decide/SKILL.md @@ -10,6 +10,9 @@ description: Record a numbered, append-only decision record in wiki/decisions/, A decision is never rewritten to reflect a later change of mind: a new one supersedes it and both stay on the record. Recording wires supersession in both directions; look-up is scoped to `wiki/decisions/`, not the whole wiki. +It also keeps what the decision was expected to change and, at review, +what actually happened, so a later reader can tell a decision that worked +from one that merely stayed in force. Writes only `wiki/decisions/`, its `index.md` and `log.md`, `wiki/graph/edges.json`, and a pointer line in `wiki/log.md`. @@ -28,6 +31,7 @@ decided_on: 2026-09-01 decided_by: Alice Smith, Bob Jones affects: /wiki/entities/billing-service.md, /wiki/projects/index.md review_on: 2027-03-01 +expected_outcome: Monthly reporting queries run in the billing store, with no second analytics database. supersedes: /wiki/decisions/0003-use-mysql.md confidence: 0.9 quality: 0.8 @@ -66,6 +70,18 @@ What else was on the table and why each was not chosen. A decision record without this is much less useful on re-reading: it's the part that stops the same option being re-proposed every six months. +## Tried + +What was actually built, run or tested on the way here and dropped, with +what was observed. Not the same as *Alternatives considered*: those were +weighed, these were tried. A pilot that read MySQL replicas into a +reporting cache ran for two weeks (2026-08) and missed its nightly window +three times. + +## Outcome + +*(Appended at review, never before. See "Reviewing an outcome".)* + ## Supersession Supersedes [[D-0003]] / [D-0003](/wiki/decisions/0003-use-mysql.md) — MySQL @@ -111,7 +127,10 @@ the append-only rule exists to prevent. | `decided_on` | yes for `accepted`/`rejected`/`reversed` | `YYYY-MM-DD`, the date the call was made. Distinct from `last_updated`, which is when the *page* last changed. A `proposed` decision may have no `decided_on` yet. | | `decided_by` | yes when known | comma-separated names, kept flat and plain so tooling can read it. The body's **Deciders** line carries the dual-links to entity pages. If genuinely unknown, write `unknown` rather than omitting the field — "we don't know who decided this" is itself worth recording. | | `affects` | no | comma-separated project-root-absolute wiki paths this decision constrains. Cheap way to answer "what decisions touch X" without walking the graph. | -| `review_on` | no | `YYYY-MM-DD` to revisit. `ckb-lint` reports these once the date passes. | +| `review_on` | no | `YYYY-MM-DD` to revisit. `ckb-lint` reports these once the date passes, until an `outcome_checked` on or after it records the review. | +| `expected_outcome` | no, preferred with `review_on` | One line: what this decision should change, stated so a later reader can check it ("p95 checkout latency under 300 ms"; not "better performance"). Written **when the decision is recorded**, before anyone knows the result. One added later gets `(added YYYY-MM-DD)` at its end, so nobody mistakes hindsight for a prediction. | +| `outcome` | set at review | `met` / `partly` / `missed` / `unclear`: how what happened compares with `expected_outcome`. | +| `outcome_checked` | set at review | `YYYY-MM-DD` of the latest outcome review. | | `supersedes` / `superseded_by` | when relevant | project-root-absolute path to the other decision. **Always set both sides** (see below). | | `confidence`, `quality`, `last_updated`, `freshness_window_days`, `retention` | as usual | standard page schema. Decisions default to `freshness_window_days: 365` and `retention: high` — a decision record doesn't rot the way a status page does, and it should survive a retention sweep. | @@ -127,6 +146,13 @@ Then check what's missing against this list, in priority order: 3. **When** — a date. "Today" is fine; "last Tuesday's architecture review" is fine, resolve it to a date. 4. **Why** — the rationale, and the alternatives that lost. 5. **Whether it changes an existing decision** — see Step 2. +6. **What it should change** — the `expected_outcome`, and a `review_on` + date by which that should be visible. Offer one from the rationale if + the user gave none ("So by March, reporting runs without a second store? + Shall I put that down to check?"). Never invent it: no answer means no + field. +7. **Anything already tried** — a pilot, a spike, a reverted change. That + goes under `## Tried` with what was observed. Ask for the missing ones in a **single** `AskUserQuestion` round rather than an interview — this is a recording task, not a discovery interview. If the @@ -158,6 +184,14 @@ same subject. If one exists and is still `accepted`: Both directions must be set. A one-sided supersession link is a lint finding, and it breaks the "what changed this?" lookup in the other direction. +**A direction already tried or rejected.** When the new decision picks +something listed under an earlier decision's `## Tried` or `## Alternatives +considered`, or reverses a `rejected` decision, say so and ask what is new +since then: a changed constraint, new evidence, a different model or +setting. Put that answer in the new decision's `## Context`. Coming back to a +direction is fine; coming back without knowing it was tried before is the +mistake this check prevents. + ### Step 3 — Allocate the number and write the page The next number is the highest existing `NNNN` in `wiki/decisions/` plus one, @@ -201,6 +235,33 @@ updated), which deciders had no entity page, and the standard reminder that this is on disk but not committed — "say 'sync changes' when you want it pushed." +## How to run this skill — reviewing an outcome + +Triggered by "review D-0007", "did D-0007 work", or a lint finding that a +`review_on` with an `expected_outcome` has passed. + +1. Read the page: `expected_outcome`, `## Rationale`, `## Tried`. +2. Ask the user what actually happened, or check it against the wiki where + the evidence is recorded there. Cite where the answer came from. +3. Append a dated entry to `## Outcome` (create the section above + `## Supersession` / `## Sources` if missing). Never edit an earlier one: + + ```markdown + ### 2027-03-04 — partly + - **Expected:** Monthly reporting queries run in the billing store, with no second analytics database. + - **Observed:** Monthly reports run in Postgres; the yearly audit export still needs the old warehouse. + - **Evidence:** /wiki/projects/billing.md, ops review 2027-03-02 + - **Checked by:** Ana Reyes + ``` + +4. Set `outcome`, `outcome_checked` and `last_updated`. If another check is + worth making, set a new `review_on` after `outcome_checked`. Otherwise + leave `review_on` as it is: the outcome check closes it. +5. When the outcome says the decision should change, that is a new decision + that supersedes this one (recording, Step 2), and this outcome entry is + its context. Offer it; do not record it unasked. +6. Log it in `wiki/decisions/log.md` (action `UPDATE (outcome review)`). + ## How to run this skill — looking up ### Step 1 — Start at the decisions index @@ -222,7 +283,9 @@ ones. and before that MySQL, changed in September because of reporting" is the useful answer; "we use Postgres" is the impoverished one. Follow `supersedes`/`superseded_by` chains in both directions and present the -history in order. +history in order. Include `outcome` where one is recorded: "in force, and +reviewed in March as having partly met its aim" is a different answer from +"in force". ### Step 3 — Verify against the source before answering @@ -255,10 +318,14 @@ a `wiki/query-gaps.md` entry (`ckb-retrieve` owns that file). ## Rule: decisions are append-only The only edits this skill makes to an *existing* decision page are: -`status`, `superseded_by`, `last_updated`, and — when the user is explicitly +`status`, `superseded_by`, `last_updated`, the outcome fields +(`outcome`, `outcome_checked`, a later `review_on`), a new dated entry +appended to `## Outcome`, and — when the user is explicitly correcting a recording error rather than changing their mind — the factual -metadata fields. Context, Decision, Rationale, Consequences, and Alternatives -are never rewritten to match a later view. +metadata fields. Context, Decision, Rationale, Consequences, Alternatives, Tried, +`expected_outcome`, and earlier Outcome entries are never rewritten to match +a later view. A wrong prediction is the most useful thing on the page; the +reason to write it down first is so that it can turn out wrong. When the user says "actually we changed our mind about D-0003", that is a new decision superseding D-0003, not an edit to D-0003. Say so and record it that diff --git a/.agents/skills/ckb-init/SKILL.md b/.agents/skills/ckb-init/SKILL.md index c2e4065..fce67a5 100644 --- a/.agents/skills/ckb-init/SKILL.md +++ b/.agents/skills/ckb-init/SKILL.md @@ -315,8 +315,9 @@ generic structure: generic - directory tree, cascade priority, frontmatter summary, no project content). Set `last_updated` to today. - **`wiki/log.md`** - header and explanation only, no entries. -- **`wiki/error-book.md`** - copy verbatim (already generic: empty table - + placeholder note). Set `last_updated` to today. +- **`wiki/error-book.md`** - copy verbatim (already generic: the entry + format in a comment + a placeholder note, no problems). Set + `last_updated` to today. - **`wiki/entities/index.md`** - header + placeholder note, no entries. - **`wiki/graph/index.md`** - header + pointer to `edges.json`, the edge vocabulary table and its conventions **verbatim** (`ckb-ingest`, @@ -342,6 +343,37 @@ If the template source's `wiki/` holds scaffold files beyond this list, carry them over the same way - empty, structure only. The list above is what the schema requires, not a cap. +#### Step 8b - Offer to carry experience from this KB (only when run inside one) + +A new KB starts with no lessons and an empty error book, so it can repeat +mistakes this KB has already learned from. When this skill runs inside a +populated KB whose `wiki/lessons.md` or `wiki/error-book.md` has entries, ask +once: + +> "This KB has N lessons and M error-book problems. Carry any into the new +> KB? (all / pick / none)" + +Default to none, and never carry anything unasked. On *pick*, list each +lesson's heading and **Context** and each error-book entry's heading and +status, and take the user's choice. For each one carried: + +- **Lesson** → the new KB's `wiki/lessons.md` (create it as `ckb-profile` + does), unchanged except for an added + `- **Carried from:** , recorded there YYYY-MM-DD` line. + Skip struck-through lessons. +- **Error-book problem** → the new KB's `wiki/error-book.md` with all its + attempt rows, the heading kept, and a `- **Carried from:** , YYYY-MM-DD` line under **Opened**. Its status becomes `watching` + whatever it was: nothing has been checked in the new setting yet. +- Set `review: needs_update` on both files so someone in the new KB checks + what was carried, and add one entry to the new `wiki/log.md` naming the + source KB and the count. + +Profiles (`workload/profiles/`) and personal lessons are never carried: they +belong to people, not to a KB. A lesson whose **Applies when** names this +KB's own projects or sources rarely makes sense elsewhere. Point that out +when the user picks one. + Do not carry over any entity pages, graph edges, log entries, or overview content specific to this project - the whole point is an empty KB with the same shape. @@ -443,6 +475,7 @@ Tell the user: - The `VERSION` the new KB starts on, and what was decided for `LICENSE`'s copyright line. - Whether a git repo was initialized in the target, or why not. +- What experience was carried (Step 8b): counts, or "none". - Next step: "Drop material into `raw/inbox/` and say 'Ingest' to populate the wiki for the first time." ## Edge cases diff --git a/.agents/skills/ckb-lint/SKILL.md b/.agents/skills/ckb-lint/SKILL.md index 9522597..c413869 100644 --- a/.agents/skills/ckb-lint/SKILL.md +++ b/.agents/skills/ckb-lint/SKILL.md @@ -117,11 +117,15 @@ from the vocabulary, a `decided_on` date where the status implies one, a `decided_by` (`unknown` counts — an omitted field doesn't), `affects` targets and supersession links that resolve, supersession set on **both** sides, `status: superseded`/`reversed` matched by a `superseded_by`, unique -four-digit decision numbers, and any `review_on` date that has passed. Fix -those directly — they're mechanical. A `review_on` that has come due is not a -defect, though: report it so the user can decide whether to revisit, and never -change a decision's substance yourself (`ckb-decide` → decisions are -append-only). +four-digit decision numbers, an `outcome` from `met`/`partly`/`missed`/`unclear` +with a dated `outcome_checked`, and any `review_on` date that has passed +with no `outcome_checked` on or after it. Fix the structural ones +directly — they're mechanical. A `review_on` that has come due is not a +defect, though: report it so the user can decide whether to revisit. When +the page has an `expected_outcome`, the finding says so: that review is +"did it do what we expected?", answered through `ckb-decide`'s outcome +review. Never change a decision's substance yourself (`ckb-decide` → +decisions are append-only). The *semantic* half stays yours: when two pages appear to cover the same entity or the same choice, check for contradictions. If one is clearly @@ -159,9 +163,40 @@ duplicate log entries directly — these are the safest auto-fixes on the list. Record any systemic issue found above (a repeated broken pattern, a recurring format mismatch, the same kind of orphan appearing again) in -`wiki/error-book.md` with its root cause, the fix applied, and the derived -constraint that should prevent recurrence. A one-off, isolated issue -doesn't need an Error Book entry — this is for patterns, not incidents. +`wiki/error-book.md`. A one-off, isolated issue doesn't need an entry — +this is for patterns, not incidents. The file's comment block holds the +format; the rules: + +1. **Problem first, then attempt.** An entry (`## E — `) is + a hypothesis about *why*, and holds every attempt made against it. Read + the open entries before writing. When one already explains the finding, + append an attempt row to it. Open a new entry only when none does. +2. **Write the expectation before the result.** Each attempt states what + it should stop, in terms the next lint run can confirm ("no more + orphans under `wiki/projects/`"), with `Observed: pending`. +3. **Close the loop on later runs.** On every lint run, check each + `pending` attempt against this run's findings and fill in `held`, + `recurred` or `partly`, with the date. When the problem recurs, the old + row stays as written and a new attempt is added. A tested fix that did + not hold is evidence, not clutter. Try the same fix again only when + something has changed, and say what changed in the new row. +4. **Context on every attempt**: the agent/model and the template + `VERSION` it ran under. When the model or template has changed since an + attempt, treat its result as something to recheck, not a settled fact. +5. **Status**: `open` while it recurs; `watching` once an attempt held but + fewer than two later runs have confirmed it; `resolved` after that. Add a + `Constraint:` line once one is known, and propose it for `AGENTS.md` if + it should bind every session (never edit `AGENTS.md` from here). +6. **Merging**: two entries with the same root cause are merged into the + older one. Move the attempt rows across, marked `(from E4)`, and leave + the newer heading as an alias, `## E4 → E2 — merged YYYY-MM-DD`, so + links and log entries that name E4 still resolve. + +An error book from before schema 1.8 (a single table) stays as it is under +an `## Earlier entries` heading. New entries use the format above; old rows +are moved into an entry only when a new attempt joins them. + +Every change to the file is a `wiki/` change, logged under Rule B. ### 10 — External source config check diff --git a/.agents/skills/ckb-lint/scripts/lint_report.py b/.agents/skills/ckb-lint/scripts/lint_report.py index 243aaf8..7c61dfe 100644 --- a/.agents/skills/ckb-lint/scripts/lint_report.py +++ b/.agents/skills/ckb-lint/scripts/lint_report.py @@ -51,6 +51,7 @@ LIBS = REPO_ROOT / "libs" RESERVED = {"index.md", "log.md"} DEFAULT_REFRESH_DAYS = 30 DECISION_STATUSES = {"proposed", "accepted", "rejected", "superseded", "reversed"} +DECISION_OUTCOMES = {"met", "partly", "missed", "unclear"} # -------------------------------------------------------------------------- @@ -319,15 +320,32 @@ def check_decisions(docs, root, today): if not doc.fm.get("decided_by", "").strip(): findings.append(f"{rel}: no `decided_by` — record `unknown` rather than omitting it") + # Expected vs observed outcome (schema 1.8): a review is done once + # `outcome_checked` is on or after `review_on`. + outcome = doc.fm.get("outcome", "").strip().lower() + if outcome and outcome not in DECISION_OUTCOMES: + findings.append( + f"{rel}: `outcome: {outcome}` is not one of {', '.join(sorted(DECISION_OUTCOMES))}" + ) + checked_raw = doc.fm.get("outcome_checked") + checked = as_date(checked_raw) if checked_raw else None + if checked_raw and checked is None: + findings.append(f"{rel}: `outcome_checked` is not a YYYY-MM-DD date: {checked_raw!r}") + if checked and not outcome: + findings.append(f"{rel}: `outcome_checked` set but no `outcome`") + expected = doc.fm.get("expected_outcome", "").strip() + review = doc.fm.get("review_on") if review: review_date = as_date(review) if review_date is None: findings.append(f"{rel}: `review_on` is not a YYYY-MM-DD date: {review!r}") - elif review_date <= today: + elif review_date <= today and not (checked and checked >= review_date): findings.append( f"{rel}: due for review — `review_on: {review_date.isoformat()}` " f"passed {(today - review_date).days}d ago" + + ("; check `expected_outcome` against what happened and record `outcome`" + if expected else "") ) # Supersession links must resolve and must be reciprocal. diff --git a/.agents/skills/ckb-lint/scripts/session_start.py b/.agents/skills/ckb-lint/scripts/session_start.py index 624da62..09652e1 100644 --- a/.agents/skills/ckb-lint/scripts/session_start.py +++ b/.agents/skills/ckb-lint/scripts/session_start.py @@ -18,6 +18,7 @@ What it prints, one line each (plus the tail of the latest workload note): threads: N open ... unticked `- [ ]` under "Open threads" in workload/ notes; only when any profile: workload/profiles/.md the session identity's own profile, printed; only when it exists lessons: N new in wiki/lessons.md KB lessons dated after your previous workload note; only when any + upstream lessons: N in linked//... the same for each linked KB's lessons, read-only, ranked below local ones workload: (last block follows) latest workload/ note by filename date Exit 0 unless the repo root is not a KB. Python 3.8+, standard library only. @@ -269,23 +270,46 @@ def profile_lines(root, slug): "project rules leave room"] + [" " + l if l else "" for l in body] -def lessons_lines(root, slug, today): - """KB lessons dated after this person's previous workload note (all of them - on a first session), so a lesson someone else recorded is not missed.""" - path = root / "wiki" / "lessons.md" +def read_lessons(path): + """(date, rule) for each lesson heading, skipping struck-through ones + (`~~rule~~ — dropped/merged …`): those stay on the record but are not + advice any more.""" if not path.is_file(): return [] - lessons = LESSON_RE.findall(path.read_text(encoding="utf-8-sig", errors="replace")) - prev = None - if slug and (root / "workload").is_dir(): - dates = [f.name[:10] for f in (root / "workload").glob(f"*_{slug}_summary.md") if f.name[:10] < today.isoformat()] - prev = max(dates) if dates else None - new = [(d, t) for d, t in lessons if prev is None or d > prev] - if not new: - return [] + found = LESSON_RE.findall(path.read_text(encoding="utf-8-sig", errors="replace")) + return [(d, t) for d, t in found if not t.startswith("~~")] + + +def previous_note(root, slug, today): + """Date of this person's latest workload note before today, or None.""" + if not slug or not (root / "workload").is_dir(): + return None + dates = [f.name[:10] for f in (root / "workload").glob(f"*_{slug}_summary.md") if f.name[:10] < today.isoformat()] + return max(dates) if dates else None + + +def lessons_lines(root, slug, today): + """KB lessons dated after this person's previous workload note (all of them + on a first session), so a lesson someone else recorded is not missed; then + the same for each linked KB's lessons, marked upstream (prior experience + from another setting, ranked below every local lesson).""" + prev = previous_note(root, slug, today) since = f"since your note of {prev}" if prev else "— first session here" - out = [f"lessons: {len(new)} in wiki/lessons.md {since} -> read the ones that bear on this session"] - out += [f" - {d} — {t}" for d, t in new[-THREADS_SHOWN:]] + out = [] + new = [(d, t) for d, t in read_lessons(root / "wiki" / "lessons.md") if prev is None or d > prev] + if new: + out.append(f"lessons: {len(new)} in wiki/lessons.md {since} -> read the ones that bear on this session") + out += [f" - {d} — {t}" for d, t in new[-THREADS_SHOWN:]] + linked = root / "linked" + if linked.is_dir(): + for kb in sorted(p for p in linked.iterdir() if p.is_dir()): + up = [(d, t) for d, t in read_lessons(kb / "wiki" / "lessons.md") if prev is None or d > prev] + if not up: + continue + rel = f"linked/{kb.name}/wiki/lessons.md" + out.append(f"upstream lessons: {len(up)} in {rel} {since} -> another KB's experience; " + "local lessons win; check its Context before relying on one") + out += [f" - {d} — {t}" for d, t in up[-THREADS_SHOWN:]] return out diff --git a/.agents/skills/ckb-profile/SKILL.md b/.agents/skills/ckb-profile/SKILL.md index c5ffb88..583517e 100644 --- a/.agents/skills/ckb-profile/SKILL.md +++ b/.agents/skills/ckb-profile/SKILL.md @@ -73,9 +73,17 @@ most, offer once: "Want me to keep that as a lesson?" - **Why:** - **Applies when:** - **Scope:** person | KB +- **Context:** , template [, ] - **Recorded by:** Name ``` +**Context** records the situation the lesson was learned in: the agent and +model the session ran under (`unknown` if you cannot tell), the template +`VERSION`, and, when it matters, the project or kind of material. A lesson +learned while one model kept skipping a step may not hold for the next +model. Without this line there is no way to tell which lessons to +recheck after a change. + Ask which scope when it is not obvious: - **Person** — how this person likes to work. Append to `## Lessons` in @@ -93,6 +101,34 @@ Suggest that once; do not edit `AGENTS.md` from here. The session-start brief lists KB lessons dated after the person's previous workload note. Read the ones that bear on the task. +**How to apply a lesson.** A lesson is prior experience, not a rule of the +same rank as `AGENTS.md`: + +- Check its **Context** against the current session. The same model, + template major version and kind of task means it applies as written. A + different one means it is a strong hint: follow it unless the current + evidence says otherwise, and if it turns out not to hold, say so and offer + to strike it through or narrow its **Applies when**. +- A lesson with no **Context** line (recorded before schema 1.8) is read + as context unknown. +- When two lessons conflict, the one whose context is closer to the + current session wins. Mention the conflict once and offer to merge or + narrow them. + +**Upstream lessons.** The brief also lists lessons from `linked//wiki/lessons.md`, +marked `upstream`. They are read-only (Rule A) and rank below every local +lesson. They describe another KB's setting, so apply them as above with the +context treated as different. To make one local, on request ("adopt that +lesson"), copy it into `wiki/lessons.md` with today's date and one extra +line, `- **Carried from:** linked/, recorded there YYYY-MM-DD`, then +set `review: needs_update` and log it like any KB lesson. `ckb-init` +carries lessons into a new KB the same way. + +**Merging**: when two lessons say the same thing, keep the older one, add +`- **Also recorded:** YYYY-MM-DD (merged)` to it, and strike through the +newer one with `~~rule~~ — merged into "" YYYY-MM-DD`. Both +stay, so a link or log entry naming either still finds it. + **Forgetting**: a lesson is never deleted silently. Strike it through (`~~rule~~ — dropped YYYY-MM-DD: why`) so the record survives. A KB lesson change is logged under Rule B. diff --git a/.agents/skills/ckb-upgrade/SKILL.md b/.agents/skills/ckb-upgrade/SKILL.md index 7b73c55..122ecdd 100644 --- a/.agents/skills/ckb-upgrade/SKILL.md +++ b/.agents/skills/ckb-upgrade/SKILL.md @@ -429,6 +429,22 @@ template's scaffold if it is missing, and add its routing row to `wiki/index.md`. Topic pages themselves are never generated by a migration; `ckb-consolidate` proposes and builds them on request. +**b5. Schema 1.7 → 1.8: outcomes, attempts, lesson context.** Every 1.8 +addition is optional (D-0023), so a 1.7 page is already a valid 1.8 page. +- **`wiki/error-book.md`** — if it holds the old single table with rows, + put the table, unchanged, under an `## Earlier entries` heading. Then add + the 1.8 entry-format comment above it from the template's scaffold, and + update the `tldr`. Never convert old rows into problem entries: an + attempt's expected result was never written down, and making one up now + would be hindsight presented as a prediction. An empty table is replaced + by the scaffold. +- **Decisions** — do not backfill `expected_outcome`. Offer once: "N + decisions have a `review_on` and no expected outcome. Want to add one to + each? It will be marked `(added )`." Apply only on a yes, one + decision at a time with the user's wording. +- **Lessons** — do not backfill **Context**; a lesson without one is read + as context unknown (`ckb-profile`). + **c. Bump `wiki/index.md`'s `kb_schema_version`** to the template's current value, once every page has been checked. diff --git a/AGENTS.md b/AGENTS.md index 675265d..73fa026 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -187,12 +187,14 @@ evidence: follow it to its members before grounding an answer. Pages with `type: decision` live in `wiki/decisions/` as `NNNN-slug.md` and add `status` (`proposed`/`accepted`/`rejected`/`superseded`/`reversed`), -`decided_on`, `decided_by`, and optionally `affects` and `review_on`. They are +`decided_on`, `decided_by`, and optionally `affects`, `review_on` and +`expected_outcome` (what the decision should change, written when it is made, +checked at review into `outcome`/`outcome_checked`). They are append-only: never rewrite a decision's substance to match a later change of mind — record a new decision that supersedes it, and set both `supersedes` and `superseded_by`. `ckb-decide` owns the format. -`wiki/index.md` alone also carries `kb_schema_version`, currently `"1.7"` +`wiki/index.md` alone also carries `kb_schema_version`, currently `"1.8"` for the base contract. An installed module may raise it additively by declaring `requires_kb_schema` and contributing optional types and fields; `ckb-module` applies that bump at install time. Detailed schema migration diff --git a/README.md b/README.md index c5a59b5..8da1ce1 100644 --- a/README.md +++ b/README.md @@ -262,7 +262,12 @@ with them), printed into their own session-start brief and nobody else's. "Remember this" or "lesson: …" records a lesson: a personal one in the profile, a KB-wide one in `wiki/lessons.md`, which waits for a second person's review. Precedence is `AGENTS.md`, then a project's `## Rules`, then -the profile. Skill: `.agents/skills/ckb-profile/SKILL.md`. +the profile. Each lesson records the context it was learned in (agent/model, +template version), so after a model or template change the agent rechecks +it instead of treating it as settled. Lessons from KBs under `linked/` +appear in the brief as upstream, ranked below local ones, and a new KB can +start with lessons carried from the one that created it. Skill: +`.agents/skills/ckb-profile/SKILL.md`. ### Kept Answers An answer that took real work can be kept on request in @@ -287,6 +292,10 @@ what was decided, `decided_by` whom, `decided_on` what date, why, the alternatives that lost, and what it `affects`. A `status` field (`proposed`/`accepted`/`rejected`/`superseded`/`reversed`) says whether it is actually in force, and an optional `review_on` date marks it for revisiting. +An optional `expected_outcome`, written when the decision is made, says what +it should change; at review the agent records what actually happened +(`outcome: met/partly/missed/unclear`) in an appended `## Outcome`, and a +`## Tried` section keeps what was built or tested and dropped on the way. Decision pages are **append-only**. When the choice changes, a *new* decision supersedes the old one - `supersedes`/`superseded_by` are set on both sides, @@ -298,7 +307,7 @@ Postgres, and before that MySQL, changed in September because of reporting". "what decisions touch Y" are direct lookups. The `ckb-decide` skill records decisions and answers questions about them; `ckb-lint` checks their structure (status vocabulary, required dates, two-sided supersession, unique numbers, -overdue reviews). +overdue reviews, unrecorded outcomes). ### Query Gaps If the cascade cannot answer a question, the agent records or proposes a @@ -365,7 +374,7 @@ source or it doesn't. `## Notes` is the inverse guarantee - on pages the agent regenerates (connector indexes, code maps), it is the one place an annotation survives the next rebuild. -`wiki/index.md` alone also carries `kb_schema_version` (currently `"1.7"`), declaring +`wiki/index.md` alone also carries `kb_schema_version` (currently `"1.8"`), declaring which revision of this schema the wiki was authored against - bump minor for additive optional fields, major for breaking changes. @@ -491,8 +500,12 @@ source citations, and consistency with the rest of the wiki. Pages below ### Error Book Systematic errors (orphan links, formatting issues, cross-page contradictions) -are recorded in `wiki/error-book.md` with root cause, applied fix, and a -reusable constraint to prevent recurrence. Two-layer repair: +are recorded in `wiki/error-book.md`, one entry per recurring problem. Each +entry names the suspected root cause and keeps every fix tried against it: +what changed, what it was expected to stop (written before the result was +known), what later lint runs actually saw, and the model and template +version it ran under. Fixes that did not hold stay on the record, so the +same fix is not tried again blind. Two-layer repair: - **Layer 1** - deterministic auto-fix for structural issues - **Layer 2** - agent reasoning pass for semantic/cross-page issues diff --git a/README.pl.md b/README.pl.md index 25bb175..58f5415 100644 --- a/README.pl.md +++ b/README.pl.md @@ -274,8 +274,12 @@ Każda osoba może mieć profil w `workload/profiles/` (rola, jak z nią pracować), wypisywany w podsumowaniu startu jej własnej sesji i niczyjej innej. „Remember this” albo „lesson: …” zapisuje lekcję: osobistą w profilu, dla całej KB w `wiki/lessons.md`, gdzie czeka na przegląd drugiej osoby. -Pierwszeństwo: `AGENTS.md`, potem `## Rules` projektu, potem profil. Skill: -`.agents/skills/ckb-profile/SKILL.md`. +Pierwszeństwo: `AGENTS.md`, potem `## Rules` projektu, potem profil. Każda +lekcja zapisuje kontekst, w którym powstała (agent/model, wersja szablonu), +więc po zmianie modelu lub szablonu agent ją sprawdza, zamiast uznawać za +pewnik. Lekcje z baz w `linked/` pojawiają się w podsumowaniu jako +zewnętrzne, poniżej lokalnych, a nowa KB może zacząć od lekcji przeniesionych +z bazy, która ją utworzyła. Skill: `.agents/skills/ckb-profile/SKILL.md`. ### Zachowane odpowiedzi Odpowiedź, która wymagała prawdziwej pracy, można na prośbę zachować w @@ -303,6 +307,10 @@ ekspert to słabsze twierdzenie niż zapisany. (`affects`). Pole `status` (`proposed`/`accepted`/`rejected`/`superseded`/`reversed`) mówi, czy decyzja faktycznie obowiązuje, a opcjonalna data `review_on` oznacza ją do przeglądu. +Opcjonalne `expected_outcome`, zapisane w chwili podjęcia decyzji, mówi, co +ma ona zmienić; przy przeglądzie agent zapisuje, co faktycznie się stało +(`outcome: met/partly/missed/unclear`) w dopisywanej sekcji `## Outcome`, a +sekcja `## Tried` zachowuje to, co zbudowano lub przetestowano i porzucono. Strony decyzji są **tylko do dopisywania**. Gdy wybór się zmienia, *nowa* decyzja zastępuje starą — `supersedes`/`superseded_by` ustawiane są po obu @@ -391,7 +399,7 @@ zgadza, albo nie. `## Notes` daje odwrotną gwarancję — na stronach regenerowanych przez agenta (indeksy konektorów, mapy kodu) to jedyne miejsce, w którym adnotacja przetrwa kolejną przebudowę. -Sam `wiki/index.md` dodatkowo zawiera `kb_schema_version` (obecnie `"1.7"`), +Sam `wiki/index.md` dodatkowo zawiera `kb_schema_version` (obecnie `"1.8"`), deklarujący, według której wersji tego schematu wiki została napisana — zwiększaj wersję pomniejszą dla dodatkowych opcjonalnych pól, główną dla zmian łamiących kompatybilność. @@ -542,9 +550,13 @@ są oznaczane do przeglądu lub przepisywane podczas kolejnego lintowania. ### Księga błędów (Error Book) Systematyczne błędy (uszkodzone linki, problemy z formatowaniem, -sprzeczności między stronami) są zapisywane w `wiki/error-book.md` wraz z -przyczyną, zastosowaną naprawą i ograniczeniem wielokrotnego użytku -zapobiegającym powtórce. Naprawa dwuwarstwowa: +sprzeczności między stronami) są zapisywane w `wiki/error-book.md`, jeden +wpis na powracający problem. Wpis nazywa podejrzewaną przyczynę i zachowuje +każdą wypróbowaną naprawę: co zmieniono, czemu miało to zapobiec (zapisane, +zanim znany był wynik), co faktycznie pokazały kolejne przebiegi lintu oraz +model i wersję szablonu, przy których to działało. Naprawy, które nie +zadziałały, zostają w zapisie, więc ta sama naprawa nie jest próbowana +ponownie na ślepo. Naprawa dwuwarstwowa: - **Warstwa 1** — deterministyczna automatyczna naprawa problemów strukturalnych - **Warstwa 2** — przebieg rozumowania agenta dla problemów diff --git a/VERSION b/VERSION index 276cbf9..197c4d5 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2.3.0 +2.4.0 diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 716d7a5..2f5cc6a 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -34,14 +34,14 @@ without asking. ## Contents -1. [Current page schema (1.7)](#current-page-schema-kb_schema_version-17) +1. [Current page schema (1.8)](#current-page-schema-kb_schema_version-18) 2. [KB schema version history](#kb-schema-version-history) 3. [Template version history](#template-version-history) 4. [Migrating between versions](#migrating-between-versions) --- -## Current page schema (`kb_schema_version: "1.7"`) +## Current page schema (`kb_schema_version: "1.8"`) ### Frontmatter — every non-reserved page @@ -83,7 +83,10 @@ add: | `decided_on` | for `accepted`/`rejected`/`reversed` | `YYYY-MM-DD`, the date the call was made. | | `decided_by` | when known | Comma-separated names. Where genuinely unknown, write `unknown` rather than omitting the field - "we don't know who decided this" is itself worth recording. | | `affects` | no | Comma-separated wiki paths this decision constrains. | -| `review_on` | no | `YYYY-MM-DD` to revisit. Lint reports these once the date passes. | +| `review_on` | no | `YYYY-MM-DD` to revisit. Lint reports these once the date passes, until an `outcome_checked` on or after it. | +| `expected_outcome` | no | *(1.8)* One line: what the decision should change, written when it is recorded. One added later ends with `(added YYYY-MM-DD)`. | +| `outcome` | at review | *(1.8)* `met` / `partly` / `missed` / `unclear`, against `expected_outcome`. Validated by lint. | +| `outcome_checked` | at review | *(1.8)* `YYYY-MM-DD` of the latest outcome review; the dated entry itself is appended to the body's `## Outcome`. | Decision records are **append-only**. A decision is never rewritten to match a later change of mind: record a new one that supersedes it, and both stay on @@ -208,7 +211,7 @@ improving it (in-degree is used as a ranking signal). | `wiki/index.md` | 1.1 | Routing table; the only page carrying `kb_schema_version` | | `wiki/overview.md` | 1.1 | High-level map of the KB | | `wiki/log.md` | 1.1 | Reverse-chronological change log for `wiki/` | -| `wiki/error-book.md` | 1.1 | Systemic issues with root cause and fix | +| `wiki/error-book.md` | 1.1 | Recurring problems (since 1.8: one entry per root cause, with every attempt, its expected and observed result and context) | | `wiki/entities/` | 1.1 | Typed entity pages | | `wiki/graph/` | 1.1 | `edges.json` plus the vocabulary in `index.md` | | `wiki/query-gaps.md` | 1.2 | Questions the wiki could not answer, driving demand-driven ingest | @@ -225,6 +228,21 @@ navigation stays lazy. ## KB schema version history +### 1.8 — 2026-11-18 · improvement memory + +[D-0023](decisions/0023-improvement-memory.md), after Google's +Self-Improvement Memory (arXiv 2611.18856). Additive: +- **Error book by problem**: `## E — ` entries with status + and an attempts table (date, change, Expected, Observed, Context); merged + entries stay as `## E4 → E2` aliases. +- **Decisions**: optional `expected_outcome`, `outcome`, `outcome_checked`; + optional body sections `## Tried` and an append-only `## Outcome`. +- **Lessons**: a `Context:` line (agent/model, template version), optional + `Carried from:` and `Also recorded:` lines. + +**Migration** (`ckb-upgrade` Step 7 b5): an old error-book table is kept +under `## Earlier entries`; nothing is backfilled. + ### 1.7 — 2026-11-02 · topic summaries [D-0016](decisions/0016-topic-summaries-and-consolidation.md). A new optional @@ -346,7 +364,8 @@ docs. Independent of the content schema above. | Version | Date | What landed | Schema | |---|---|---|---| -| **2.3.0** | 2026-11-12 | Branch and version flow (D-0022): a new `dev` integration branch where all work lands; `VERSION` and the changelog change only when `dev` is merged into `experimental`, `test` or `main` (paths `dev` → `experimental` → `test` → `main`, `dev` → `test` → `main`, `dev` → `main`), and a version keeps its number when promoted; `main` is merged back into `dev`, `test` and `experimental` after a release; `1.x` keeps its own fixes. `experimental` becomes the *preview* channel; `dev` is not a channel, and `ckb-init`/`ckb-upgrade` offer `experimental` when asked for it. Also **profile skills** in `user-skills/`, installed once per person rather than per KB: `ckb-create` builds a KB with the fetched template's `ckb-init`, commits on `main` and pushes to an empty remote; `ckb-join` clones a KB by URL and checks git identity, symlinks, `linked/` mounts and Python without committing. Neither is copied into a KB. Both manuals gain a section on them | 1.7 | +| **2.4.0** | 2026-11-18 | Improvement memory (D-0023, schema 1.8), after Google's Self-Improvement Memory paper. **Error book** (`ckb-lint` check 9): one entry per recurring problem with every attempt, what it was expected to stop (written first), what later runs observed (`pending` → `held`/`recurred`/`partly`) and the model/template it ran under; lint fills in pending observations each run, retries a failed fix only with something new, merges entries into aliases; new scaffold. **Decisions** (`ckb-decide`): `expected_outcome` asked for when recording, a new "reviewing an outcome" procedure appending to `## Outcome` and setting `outcome`/`outcome_checked`, a `## Tried` section, and a check when a new decision picks a direction already tried or rejected. `lint_report.py` validates the outcome vocabulary, closes a due review once `outcome_checked` ≥ `review_on`, and asks for the outcome when an `expected_outcome` is set. **Lessons** (`ckb-profile`): a `Context:` line and rules for applying a lesson from another context, adopting upstream lessons, merging. `session_start.py` lists new lessons from `linked//wiki/lessons.md` as `upstream lessons:` and skips struck-through lessons. **`ckb-init`** Step 8b offers to carry lessons and error-book problems into a new KB. **`ckb-upgrade`** b5 migration. Template ADRs may carry the same fields. Deferred: a self-improvement loop over the template (needs evals). Rejected: loading the whole record into context. Tests: `tests/unit/test_sim_memory.py` | 1.8 | +| 2.3.0 | 2026-11-12 | Branch and version flow (D-0022): a new `dev` integration branch where all work lands; `VERSION` and the changelog change only when `dev` is merged into `experimental`, `test` or `main` (paths `dev` → `experimental` → `test` → `main`, `dev` → `test` → `main`, `dev` → `main`), and a version keeps its number when promoted; `main` is merged back into `dev`, `test` and `experimental` after a release; `1.x` keeps its own fixes. `experimental` becomes the *preview* channel; `dev` is not a channel, and `ckb-init`/`ckb-upgrade` offer `experimental` when asked for it. Also **profile skills** in `user-skills/`, installed once per person rather than per KB: `ckb-create` builds a KB with the fetched template's `ckb-init`, commits on `main` and pushes to an empty remote; `ckb-join` clones a KB by URL and checks git identity, symlinks, `linked/` mounts and Python without committing. Neither is copied into a KB. Both manuals gain a section on them | 1.7 | | 2.2.0 | 2026-11-11 | New opt-in `convert` module (D-0021): skill `ckb-convert` and `convert.py` (stdlib; needs pandoc, LibreOffice optional). `convert` turns any KB Markdown file into `.docx`, `.odt`, PDF or HTML in a named house style, `templates/styles/.docx` (pandoc's reference document; optional `.odt`/`.css`). PDF and ODT are made by LibreOffice from the styled `.docx` (private profile), so every format looks the same; without it PDF falls back to a pandoc PDF engine and says the style wasn't applied. The copy is cleaned for outside readers: frontmatter → title/author (no e-mail)/date/lang, a leading `# H1` → title, template comments dropped, `[[wikilinks]]` and KB-path links → text (`--keep-links`), code blocks untouched. An existing output is refused without `--force`. **Styles without fonts by hand:** `new-style` copies pandoc's default reference and sets body/heading font, size, heading colour, paper (A4/Letter) and margins in `styles.xml`, the theme and the body `sectPr` in schema order; `--from` takes a company `.docx`/`.dotx` (content type rewritten, macros refused); `edit-style`, `check-style` (styles pandoc uses that a template lacks), `styles`, `doctor`. Scaffold `templates/styles/README.md`; settings `style`, `format`, `out_dir`, `toc`, `number_sections`, `keep_links` via `default_config`; routed by the module's `AGENTS.md` block, after `ckb-voice`. Tests: `tests/unit/test_convert.py`, eval `ckb-module/install-convert`. No schema change | 1.7 | | 2.1.0 | 2026-11-11 | New opt-in `voice` module (D-0020): skill `ckb-voice`, no script. Every prose file written under the configured `apply_to` paths (default `outputs/answers/`, `outputs/documents/`, `outputs/reports/`, `PROJECT-OVERVIEW*`; `outputs/okf/` and `outputs/starlight/` skipped) is rewritten in a voice before it is saved, whichever skill drafted it; the hook is the module's `AGENTS.md` block, so no core skill changed for it. **Profiles are wiki pages**, `wiki/voice/.md` (`type: voice-profile`, `voice_of: team/person/third-party`, Tone, Formality, Sentence style, Keep, Avoid, Audience, Opinions, Sample, `## Sources`, protected `## Notes`), created and logged by calibration from sample documents; standing preferences said in passing update one field. **Settings** in `ckb.yaml` (`mode: auto/ask/off`, `profile`, `writer`, `apply_to`, `skip`, `chat`); profile precedence: named in the request, then `voice:` on the person's `workload/profiles/` page, then the default. **Frozen spans** (frontmatter except a new `voice:` field, Sources, Crux and quotes with attributions, Notes/Rules, contradiction markers, ``, code, paths, links, numbers, names, a template's headings) are diffed before writing; a vague claim is flagged, never cut. `writer:` hands the rewrite to another installed skill such as a personal `ghost-writer`, with fallback. Rules adapted from that skill. `ckb-module` reads a manifest's `default_config` into the entry's `config:` and keeps edited values on reinstall. New type `voice-profile` and field `voice`, additive, no schema bump | 1.7 | | 2.0.9 | 2026-11-11 | Tests only. Golden outputs for both exporters on the clean fixture: the exact file list (`tests/expected/okf-files.txt`, 15 files; `starlight-files.txt`, 17) and the summary each prints (`okf-report.txt`, `starlight-report.txt`, including the OKF conformance verdict). Content is not compared, because OKF stamps the export date. This closes the last item of the 2.0.0 script review | 1.7 | diff --git a/docs/CHANGELOG.pl.md b/docs/CHANGELOG.pl.md index 7ceb925..dcdb514 100644 --- a/docs/CHANGELOG.pl.md +++ b/docs/CHANGELOG.pl.md @@ -35,14 +35,14 @@ przechodzi przez wersję główną bez pytania. ## Spis treści -1. [Aktualny schemat strony (1.7)](#aktualny-schemat-strony-kb_schema_version-17) +1. [Aktualny schemat strony (1.8)](#aktualny-schemat-strony-kb_schema_version-18) 2. [Historia wersji schematu KB](#historia-wersji-schematu-kb) 3. [Historia wersji szablonu](#historia-wersji-szablonu) 4. [Migracja między wersjami](#migracja-między-wersjami) --- -## Aktualny schemat strony (`kb_schema_version: "1.7"`) +## Aktualny schemat strony (`kb_schema_version: "1.8"`) ### Frontmatter — każda strona niezastrzeżona @@ -85,7 +85,10 @@ dodają: | `decided_on` | dla `accepted`/`rejected`/`reversed` | `YYYY-MM-DD`, data podjęcia decyzji. | | `decided_by` | gdy wiadomo | Nazwiska po przecinku. Gdy naprawdę nie wiadomo, wpisz `unknown` zamiast pomijać pole — „nie wiemy, kto to zdecydował" samo w sobie warto zapisać. | | `affects` | nie | Ścieżki wiki po przecinku, które ta decyzja ogranicza. | -| `review_on` | nie | `YYYY-MM-DD` do ponownego rozważenia. Lint zgłasza je po przekroczeniu daty. | +| `review_on` | nie | `YYYY-MM-DD` do ponownego rozważenia. Lint zgłasza je po przekroczeniu daty, dopóki nie ma `outcome_checked` w tym dniu lub później. | +| `expected_outcome` | nie | *(1.8)* Jeden wiersz: co decyzja ma zmienić, zapisany przy jej zapisie. Dodany później kończy się `(added RRRR-MM-DD)`. | +| `outcome` | przy przeglądzie | *(1.8)* `met` / `partly` / `missed` / `unclear` względem `expected_outcome`. Sprawdzane przez lint. | +| `outcome_checked` | przy przeglądzie | *(1.8)* `RRRR-MM-DD` ostatniego przeglądu wyniku; sam datowany wpis trafia do sekcji `## Outcome`. | Rekordy decyzji są **tylko do dopisywania**. Decyzji nigdy nie przepisuje się pod późniejszą zmianę zdania: zapisz nową, która ją zastępuje, a obie zostają @@ -212,7 +215,7 @@ rankingowym). | `wiki/index.md` | 1.1 | Tabela routingu; jedyna strona niosąca `kb_schema_version` | | `wiki/overview.md` | 1.1 | Mapa KB z lotu ptaka | | `wiki/log.md` | 1.1 | Dziennik zmian `wiki/` w odwrotnej chronologii | -| `wiki/error-book.md` | 1.1 | Problemy systemowe wraz z przyczyną i naprawą | +| `wiki/error-book.md` | 1.1 | Powracające problemy (od 1.8: jeden wpis na przyczynę, z każdą próbą, jej oczekiwanym i zaobserwowanym wynikiem oraz kontekstem) | | `wiki/entities/` | 1.1 | Typowane strony encji | | `wiki/graph/` | 1.1 | `edges.json` plus słownik w `index.md` | | `wiki/query-gaps.md` | 1.2 | Pytania, na które wiki nie umiało odpowiedzieć, napędzające ingest sterowany popytem | @@ -229,6 +232,21 @@ nawigacja pozostaje leniwa. ## Historia wersji schematu KB +### 1.8 — 2026-11-18 · pamięć ulepszeń + +[D-0023](decisions/0023-improvement-memory.md), na wzór Self-Improvement +Memory Google'a (arXiv 2611.18856). Addytywnie: +- **Księga błędów według problemów**: wpisy `## E — ` ze + statusem i tabelą prób (data, zmiana, Expected, Observed, Context); + scalone wpisy zostają jako aliasy `## E4 → E2`. +- **Decyzje**: opcjonalne `expected_outcome`, `outcome`, `outcome_checked`; + opcjonalne sekcje `## Tried` i dopisywana `## Outcome`. +- **Lekcje**: wiersz `Context:` (agent/model, wersja szablonu), opcjonalne + `Carried from:` i `Also recorded:`. + +**Migracja** (`ckb-upgrade` krok 7 b5): stara tabela księgi błędów zostaje +pod `## Earlier entries`; nic nie jest uzupełniane wstecz. + ### 1.7 — 2026-11-02 · podsumowania tematów [D-0016](decisions/0016-topic-summaries-and-consolidation.md). Nowy opcjonalny @@ -354,7 +372,8 @@ Niezależna od schematu treści powyżej. | Wersja | Data | Co weszło | Schemat | |---|---|---|---| -| **2.3.0** | 2026-11-12 | Przepływ gałęzi i wersji (D-0022): nowa gałąź integracyjna `dev`, na którą trafia cała praca; `VERSION` i changelog zmieniają się tylko przy scaleniu `dev` do `experimental`, `test` albo `main` (ścieżki `dev` → `experimental` → `test` → `main`, `dev` → `test` → `main`, `dev` → `main`), a wersja zachowuje numer przy promocji; po wydaniu `main` jest scalana z powrotem do `dev`, `test` i `experimental`; `1.x` ma własne poprawki. `experimental` staje się kanałem *podglądowym*; `dev` nie jest kanałem, a `ckb-init`/`ckb-upgrade` proponują zamiast niej `experimental`. Do tego **skille profilowe** w `user-skills/`, instalowane raz na osobę, a nie na KB: `ckb-create` buduje KB za pomocą `ckb-init` z pobranego szablonu, robi commit na `main` i push do pustego zdalnego repozytorium; `ckb-join` klonuje KB po URL i sprawdza tożsamość git, dowiązania, montowania `linked/` i Pythona, bez commitów. Żaden nie jest kopiowany do KB. Oba podręczniki mają o nich sekcję | 1.7 | +| **2.4.0** | 2026-11-18 | Pamięć ulepszeń (D-0023, schemat 1.8), na wzór Self-Improvement Memory Google'a. **Księga błędów** (sprawdzenie 9 `ckb-lint`): jeden wpis na powracający problem z każdą próbą naprawy, tym, czemu miała zapobiec (zapisane najpierw), co pokazały kolejne przebiegi (`pending` → `held`/`recurred`/`partly`) i przy jakim modelu/szablonie; lint uzupełnia oczekujące obserwacje w każdym przebiegu, ponawia nieudaną naprawę tylko z czymś nowym, scala wpisy w aliasy; nowy szkielet. **Decyzje** (`ckb-decide`): `expected_outcome` przy zapisie, nowa procedura przeglądu wyniku dopisująca do `## Outcome` i ustawiająca `outcome`/`outcome_checked`, sekcja `## Tried` i sprawdzenie, gdy nowa decyzja wybiera kierunek już wypróbowany lub odrzucony. `lint_report.py` sprawdza słownik wyników, zamyka zaległy przegląd, gdy `outcome_checked` ≥ `review_on`, i prosi o wynik, gdy jest `expected_outcome`. **Lekcje** (`ckb-profile`): wiersz `Context:` i zasady stosowania lekcji z innego kontekstu, przejmowania lekcji z baz zewnętrznych, scalania. `session_start.py` wypisuje nowe lekcje z `linked//wiki/lessons.md` jako `upstream lessons:` i pomija przekreślone. **`ckb-init`** krok 8b proponuje przeniesienie lekcji i problemów z księgi błędów do nowej KB. **`ckb-upgrade`** migracja b5. ADR-y szablonu mogą mieć te same pola. Odłożone: pętla samodoskonalenia szablonu (wymaga ewaluacji). Odrzucone: ładowanie całego zapisu do kontekstu. Testy: `tests/unit/test_sim_memory.py` | 1.8 | +| 2.3.0 | 2026-11-12 | Przepływ gałęzi i wersji (D-0022): nowa gałąź integracyjna `dev`, na którą trafia cała praca; `VERSION` i changelog zmieniają się tylko przy scaleniu `dev` do `experimental`, `test` albo `main` (ścieżki `dev` → `experimental` → `test` → `main`, `dev` → `test` → `main`, `dev` → `main`), a wersja zachowuje numer przy promocji; po wydaniu `main` jest scalana z powrotem do `dev`, `test` i `experimental`; `1.x` ma własne poprawki. `experimental` staje się kanałem *podglądowym*; `dev` nie jest kanałem, a `ckb-init`/`ckb-upgrade` proponują zamiast niej `experimental`. Do tego **skille profilowe** w `user-skills/`, instalowane raz na osobę, a nie na KB: `ckb-create` buduje KB za pomocą `ckb-init` z pobranego szablonu, robi commit na `main` i push do pustego zdalnego repozytorium; `ckb-join` klonuje KB po URL i sprawdza tożsamość git, dowiązania, montowania `linked/` i Pythona, bez commitów. Żaden nie jest kopiowany do KB. Oba podręczniki mają o nich sekcję | 1.7 | | 2.2.0 | 2026-11-11 | Nowy opcjonalny moduł `convert` (D-0021): skill `ckb-convert` i `convert.py` (biblioteka standardowa; wymaga pandoca, LibreOffice opcjonalnie). `convert` zamienia dowolny plik Markdown z bazy na `.docx`, `.odt`, PDF lub HTML w nazwanym stylu firmowym, `templates/styles/.docx` (dokument referencyjny pandoca; opcjonalnie `.odt`/`.css`). PDF i ODT robi LibreOffice ze sformatowanego `.docx` (osobny profil), więc wszystkie formaty wyglądają tak samo; bez niego PDF robi silnik PDF pandoca, z informacją, że styl nie został zastosowany. Kopia jest czyszczona dla czytelnika spoza bazy: frontmatter → tytuł/autor (bez e-maila)/data/język, początkowy `# H1` → tytuł, komentarze szablonu usunięte, `[[wikilinki]]` i linki do ścieżek bazy → tekst (`--keep-links`), bloki kodu bez zmian. Istniejący plik wynikowy nie jest nadpisywany bez `--force`. **Style bez ręcznego wybierania czcionek:** `new-style` kopiuje domyślny dokument referencyjny pandoca i ustawia czcionkę tekstu i nagłówków, rozmiar, kolor nagłówków, format papieru (A4/Letter) i marginesy w `styles.xml`, motywie i `sectPr` treści, w kolejności wymaganej przez schemat; `--from` przyjmuje firmowy `.docx`/`.dotx` (typ zawartości przepisany, makra odrzucane); `edit-style`, `check-style` (style używane przez pandoca, których brakuje w szablonie), `styles`, `doctor`. Szkielet `templates/styles/README.md`; ustawienia `style`, `format`, `out_dir`, `toc`, `number_sections`, `keep_links` przez `default_config`; kierowanie przez blok modułu w `AGENTS.md`, po `ckb-voice`. Testy: `tests/unit/test_convert.py`, eval `ckb-module/install-convert`. Bez zmiany schematu | 1.7 | | 2.1.0 | 2026-11-11 | Nowy opcjonalny moduł `voice` (D-0020): skill `ckb-voice`, bez skryptu. Każdy plik prozy zapisywany pod ścieżkami `apply_to` (domyślnie `outputs/answers/`, `outputs/documents/`, `outputs/reports/`, `PROJECT-OVERVIEW*`; `outputs/okf/` i `outputs/starlight/` pominięte) jest przed zapisem przepisywany wybranym głosem, niezależnie od tego, który skill go przygotował; podpięcie to blok modułu w `AGENTS.md`, więc żaden skill bazowy się nie zmienił. **Profile to strony wiki**, `wiki/voice/.md` (`type: voice-profile`, `voice_of: team/person/third-party`, Tone, Formality, Sentence style, Keep, Avoid, Audience, Opinions, Sample, `## Sources`, chronione `## Notes`), tworzone i logowane przez kalibrację z przykładowych dokumentów; stałe preferencje wypowiedziane przy okazji zmieniają jedno pole. **Ustawienia** w `ckb.yaml` (`mode: auto/ask/off`, `profile`, `writer`, `apply_to`, `skip`, `chat`); kolejność profilu: nazwany w prośbie, potem `voice:` na stronie osoby w `workload/profiles/`, potem domyślny. **Zamrożone fragmenty** (frontmatter poza nowym polem `voice:`, Sources, Crux i cytaty z atrybucjami, Notes/Rules, znaczniki sprzeczności, ``, kod, ścieżki, linki, liczby, nazwy, nagłówki szablonu) są porównywane przed zapisem; ogólnikowe twierdzenie jest zgłaszane, nigdy wycinane. `writer:` przekazuje przepisywanie innemu zainstalowanemu skillowi, np. osobistemu `ghost-writer`, z powrotem do `ckb-voice`, gdy go brak. Reguły zaadaptowane z tego skilla. `ckb-module` wpisuje `default_config` z manifestu do `config:` wpisu i przy reinstalacji zachowuje zmienione wartości. Nowy typ `voice-profile` i pole `voice`, addytywnie, bez zmiany schematu | 1.7 | | 2.0.9 | 2026-11-11 | Tylko testy. Złote wyniki obu eksportów na czystym fixture: dokładna lista plików (`tests/expected/okf-files.txt`, 15 plików; `starlight-files.txt`, 17) i podsumowanie, które każdy wypisuje (`okf-report.txt`, `starlight-report.txt`, z werdyktem zgodności OKF). Treść nie jest porównywana, bo OKF wpisuje datę eksportu. To zamyka ostatni punkt przeglądu skryptów 2.0.0 | 1.7 | diff --git a/docs/MANUAL.md b/docs/MANUAL.md index d4d85cb..f67a384 100644 --- a/docs/MANUAL.md +++ b/docs/MANUAL.md @@ -302,6 +302,16 @@ marks the old one superseded - without touching the old page's reasoning. Anything you leave out, it asks for in one round; if you're mid-flow, say so and it records what you gave it and tells you which fields it left open. +It also asks what the decision should change and when you'd expect to see +it ("reporting runs in Postgres alone by March"). That goes down *before* +anyone knows the result, as `expected_outcome` with a `review_on` date. +When the date comes, lint reminds you; say "review decision 7" and the agent +records what actually happened (met, partly, missed, unclear) in the +page's `## Outcome`, without touching anything written earlier. Anything +you built or tested and dropped on the way goes under `## Tried`. If a +later decision picks one of those again, the agent points that out and asks +what has changed since. + Then ask about them however you like: > "What did we decide about the billing database?" @@ -365,7 +375,9 @@ This runs a health check across the whole wiki: that source, since it tells you who to chase - pages whose source has actually changed get flagged - see below - quotes that no longer appear in the source they cite get flagged -- recurring systemic issues get written into `wiki/error-book.md` +- recurring systemic issues get written into `wiki/error-book.md`, one + entry per problem with every fix tried, what each was expected to stop, + and what the following lint runs saw - credentials committed by accident (keys, tokens, private keys, a password in a URL) anywhere in `wiki/`, `outputs/`, `workload/` or `raw/`, and any `` passage that leaked into a wiki page, get flagged - never @@ -951,6 +963,14 @@ Nothing becomes a lesson unless you ask. A lesson that should bind everyone always belongs in `AGENTS.md`; the agent will suggest that rather than edit it. Skill: `.agents/skills/ckb-profile/SKILL.md`. +Each lesson notes the context it came from: the agent/model and the template +version. After a model or template change, the agent treats older lessons +as strong hints to recheck rather than settled facts. If your KB links +another KB under `linked/`, that KB's new lessons appear in your brief as +*upstream*; they rank below your own, and "adopt that lesson" copies one in. +When you create a new KB from this one, `ckb-init` offers to carry lessons +and error-book problems across. + ### Save a conversation Every new session gets a title the agent picks from your first message diff --git a/docs/MANUAL.pl.md b/docs/MANUAL.pl.md index 7d46db0..bd36939 100644 --- a/docs/MANUAL.pl.md +++ b/docs/MANUAL.pl.md @@ -314,6 +314,15 @@ zastąpioną — nie ruszając jej uzasadnienia. O to, czego nie podasz, dopyta jednej turze; jeśli jesteś w środku pracy, powiedz to, a zapisze, co ma, i wskaże, które pola zostawił otwarte. +Zapyta też, co decyzja ma zmienić i kiedy powinno to być widać („raporty +działają na samym Postgresie do marca”). Zapisuje to *zanim* znany jest +wynik, jako `expected_outcome` z datą `review_on`. Gdy data nadejdzie, lint +przypomni; powiedz „review decision 7”, a agent zapisze, co faktycznie się +stało (met, partly, missed, unclear) w sekcji `## Outcome`, nie ruszając +niczego zapisanego wcześniej. To, co po drodze zbudowano lub przetestowano i +porzucono, trafia do `## Tried`. Jeśli późniejsza decyzja znów wybiera coś +stamtąd, agent to zauważy i zapyta, co się od tego czasu zmieniło. + Potem pytaj, jak chcesz: > „Co zdecydowaliśmy w sprawie bazy danych billingu?" @@ -382,7 +391,9 @@ To uruchamia przegląd kondycji całej wiki: patrz niżej - cytaty, których nie ma już w źródle, na które się powołują, zostają oflagowane -- powtarzające się problemy systemowe trafiają do `wiki/error-book.md` +- powtarzające się problemy systemowe trafiają do `wiki/error-book.md`, + jeden wpis na problem, z każdą wypróbowaną naprawą, tym, czemu miała + zapobiec, i tym, co pokazały kolejne przebiegi lintu - przypadkowo zacommitowane dane uwierzytelniające (klucze, tokeny, klucze prywatne, hasło w adresie URL) gdziekolwiek w `wiki/`, `outputs/`, `workload/` lub `raw/`, a także fragment ``, który trafił na @@ -995,6 +1006,14 @@ Nic nie staje się lekcją, jeśli o to nie poprosisz. Lekcja, która ma zawsze obowiązywać wszystkich, należy do `AGENTS.md`; agent to zasugeruje, zamiast go edytować. Skill: `.agents/skills/ckb-profile/SKILL.md`. +Każda lekcja zapisuje kontekst, z którego pochodzi: agenta/model i wersję +szablonu. Po zmianie modelu lub szablonu agent traktuje starsze lekcje jako +mocne wskazówki do sprawdzenia, a nie pewniki. Jeśli twoja KB podpina inną +w `linked/`, nowe lekcje tamtej pojawiają się w twoim podsumowaniu jako +*zewnętrzne* (upstream); są niżej niż twoje, a „adopt that lesson” kopiuje +jedną do ciebie. Przy tworzeniu nowej KB z tej `ckb-init` proponuje +przeniesienie lekcji i problemów z księgi błędów. + ### Zapisywanie rozmowy Każda nowa sesja dostaje tytuł, który agent sam wybiera na podstawie diff --git a/docs/decisions/0023-improvement-memory.md b/docs/decisions/0023-improvement-memory.md new file mode 100644 index 0000000..24f3e5d --- /dev/null +++ b/docs/decisions/0023-improvement-memory.md @@ -0,0 +1,125 @@ +--- +type: decision +tldr: Schema 1.8 keeps the KB's own improvement history the way Google's Self-Improvement Memory does: error-book entries per recurring problem with every attempt, its expected and observed result and its context; decisions with an expected_outcome checked at review and a ## Tried section; lessons with a Context line, upstream lessons from linked KBs, lessons carried into a new KB, and merges that keep aliases. A self-improvement loop over the template is deferred until evals exist; loading the whole record into context unretrieved is rejected. +status: accepted +decided_on: 2026-11-18 +decided_by: Michał Kopeć +affects: AGENTS.md, wiki/index.md, wiki/error-book.md, wiki/decisions/index.md, .agents/skills/ckb-lint/, .agents/skills/ckb-decide/, .agents/skills/ckb-profile/, .agents/skills/ckb-init/, .agents/skills/ckb-upgrade/ +review_on: 2027-02-18 +expected_outcome: By the review, at least one error-book problem in a real KB has two or more attempts with a filled-in Observed column, and at least one decision with an expected_outcome has had its outcome recorded; if neither has happened, the format is too heavy and should be cut back. +confidence: 0.7 +quality: 0.8 +last_updated: 2026-11-18 +freshness_window_days: 365 +retention: high +--- + +# D-0023 — Improvement memory: attempts, expected outcomes, lesson context + +**Status:** Accepted · **Decided:** 2026-11-18 · **Deciders:** Michał Kopeć + +## Context + +Yu et al., *Self-Improvement Memory Enables Continual Recursive +Self-Improvement* (Google, arXiv 2611.18856, 2026-11-13), studies agents +that improve their own harness. When the model or the task changes, the +improved harness alone does not say why each change was made or whether it +worked. Their Self-Improvement Memory (SIM) keeps, per recurring problem, +every attempt with its rationale, the tasks it was **predicted** to fix +(written before evaluation), what it actually fixed, and the setting it ran +in. Continuing with SIM beat continuing with the harness alone in all ten +of their settings (+2.36 points on average across ten paired coding runs, +p = 0.003). The record helped most by keeping the *reason* for an inherited +change, so the next optimizer adapted it instead of reverting it, and by +keeping failed attempts so they were not retried blind. + +A Cascade KB already improves itself in small ways: lint records systemic +issues in the error book, people record lessons, decisions record why. At +2.2.0 none of these held SIM's three working parts. The error book was one +row per incident. Nothing wrote down an expected result before the result +was known. Lessons did not say which model or template they were learned +under. + +## Decision + +Schema 1.8. Every addition is optional and additive. + +1. **Error book by problem.** `wiki/error-book.md` holds one entry per + recurring problem (`## E — `, status + `open`/`watching`/`resolved`, a `Constraint:` once known), each with a + table of attempts: date, what changed, **Expected** (written first), + **Observed** (`pending`, then `held`/`recurred`/`partly` with a date), + **Context**. Lint check 9 appends to an existing problem before opening a + new one, fills in pending observations on each run, and never rewrites an + attempt. Old single-table error books are kept as `## Earlier entries`. +2. **Expected outcomes on decisions.** `expected_outcome` (one line, written + when the decision is recorded; one added later is marked `(added + YYYY-MM-DD)`), and at review `outcome` (`met`/`partly`/`missed`/`unclear`), + `outcome_checked` and a dated entry appended to `## Outcome`. Lint + validates the vocabulary and treats a review as done once + `outcome_checked` is on or after `review_on`. +3. **Context on lessons and attempts.** A lesson carries `- **Context:** + , template [, setting]`. A lesson from a different + context is a strong hint to recheck, not a rule; a lesson without one is + context unknown. +4. **What was tried.** Decision records gain an optional `## Tried` section, + for what was built or tested and dropped, kept apart from *Alternatives + considered* (weighed, not tried). Template ADRs use it too. Picking a + direction that is listed as tried, or reversing a rejected decision, + makes `ckb-decide` ask what is new since then. +5. **Experience across KBs.** The session brief lists new lessons from each + `linked//wiki/lessons.md` as `upstream`, ranked below local ones + and read-only. "Adopt that lesson" copies one in with a `Carried from:` + line. `ckb-init`, run inside a populated KB, offers once to carry chosen + lessons and error-book problems into the new KB; carried problems become + `watching`, both files `review: needs_update`. Profiles are never carried. +6. **Merges keep aliases.** A merged error-book entry stays as + `## E4 → E2 — merged YYYY-MM-DD`, and its attempts move across marked + `(from E4)`. A merged lesson is struck through with `merged into ""` + and the survivor gets `Also recorded:`. Struck-through lessons are no + longer listed in the brief. + +## Tried + +Nothing was piloted before this decision. The paper's results come from +harness optimisation on benchmarks, not from knowledge bases, so how well +this transfers is the open question. See `review_on` and `expected_outcome` +above. + +## Alternatives considered + +- **A self-improvement loop for the template** — the paper's own setting: + propose edits to skills, score them on an eval set, check a held-out + split and earlier passing cases, keep the winners, all with SIM recording + the attempts. **Deferred, to consider later.** It needs a behavioural eval + set first (the routing and retrieval evals already listed as gaps). Once + one exists, use the paper's two lessons: hold out part of the eval set, + and check whether previously passing cases still pass after a change. +- **Load the whole record into context, unretrieved** — SIM gives the + optimizer the full memory every round with no retrieval or truncation. + **Rejected.** It works for one optimizer's notes, which stay small. A + KB's error book, lessons and decisions grow without bound and compete + with the context budget lint enforces (check 19). The brief already lists + new lessons; the rest is read index-first when a task bears on it. +- **Machine-readable JSON for the error book**, as SIM stores it. + Rejected: every other KB record is Markdown that people edit and review, + and nothing needs to parse attempts automatically yet. +- **Backfilling expected outcomes and lesson context on upgrade.** Rejected: + a prediction written after the result is hindsight, and a guessed context + is worse than an honest "unknown". + +## Consequences + +- Recording a decision asks one more question (what it should change), and + lint asks for an outcome when a review comes due. That is more friction; + the review date above checks whether it is used. +- The error book becomes longer and more useful only if lint really goes + back to pending attempts. The skill says so; nothing in a script enforces + it. +- A KB that links others sees their lessons in its brief, which may be + noise if the KBs differ a lot. Upstream lessons rank last and are only + listed, never applied unasked. + +## Sources + +- `https://arxiv.org/abs/2611.18856` — Yu et al., 2026-11-13, read 2026-11-18 (§3.2, §3.3, App. D.2–D.3, F.6) diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 0397039..982329e 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -10,6 +10,10 @@ but they live here, in the template layer, because: pages the content layer is allowed to delete. `ckb-upgrade` carries this folder along with the rest of the template layer. + +Since D-0023 these records may carry `expected_outcome`, `## Tried` and an +appended `## Outcome`, like any decision: write what a change should do +before it ships, and check it when `review_on` comes. `ckb-decide` never writes here — it is not a place for a KB's project decisions. | # | Decision | @@ -36,3 +40,4 @@ but they live here, in the template layer, because: | [D-0020](0020-voice-module.md) | Opt-in `voice` module: outgoing prose (kept answers, documents, reports, the project overview) is rewritten in a voice whose profile is a wiki page in `wiki/voice/`; settings in `ckb.yaml`; routed by the `AGENTS.md` block, not per-skill edits; frozen spans never change, vague claims are flagged rather than cut; `writer:` plugs in an external rewriting skill | | [D-0021](0021-convert-module.md) | Opt-in `convert` module: Markdown becomes Word/ODT/PDF/HTML through pandoc in a named house style, a reference `.docx` in `templates/styles/` built from a few settings or copied from a company `.docx`/`.dotx`; PDF and ODT go through LibreOffice from the styled `.docx`; KB links and frontmatter are cleaned in the copy; the Markdown stays the source | | [D-0022](0022-dev-branch-and-merge-versioning.md) | All work lands on `dev`; `VERSION` changes only when `dev` is merged into `experimental`, `test` or `main`, a version keeps its number when promoted, `main` is merged back after a release, `1.x` keeps its own fixes, and `dev` is not a channel | +| [D-0023](0023-improvement-memory.md) | Schema 1.8: error book per recurring problem with every attempt, its expected and observed result and context; decisions with `expected_outcome` checked at review and a `## Tried` section; lessons with context, upstream lessons from `linked/`, lessons carried by `ckb-init`, merges with aliases; a self-improvement loop deferred until evals exist; loading the whole record unretrieved rejected | diff --git a/tests/unit/test_sim_memory.py b/tests/unit/test_sim_memory.py new file mode 100644 index 0000000..2ebca3b --- /dev/null +++ b/tests/unit/test_sim_memory.py @@ -0,0 +1,109 @@ +"""Schema 1.8 (D-0023): decisions carry an expected outcome checked at review, +and the session brief lists upstream lessons from linked KBs and skips +struck-through ones.""" +import json +import shutil +import subprocess +import sys +import tempfile +import unittest +from datetime import date +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +FIX = ROOT / "tests/fixtures/minimal-kb" +SCRIPTS = ROOT / ".agents/skills/ckb-lint/scripts" +LINT = SCRIPTS / "lint_report.py" +TODAY = "2026-11-18" +sys.path.insert(0, str(SCRIPTS)) +import session_start # noqa: E402 + +DECISION = ("---\ntype: decision\ntldr: {n}\nstatus: accepted\ndecided_on: 2026-09-01\n" + "decided_by: A\n{extra}---\n\n# D-{n}\n") + + +class DecisionOutcomes(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.tmp = tempfile.TemporaryDirectory() + kb = Path(cls.tmp.name) / "kb" + shutil.copytree(str(FIX), str(kb)) + d = kb / "wiki" / "decisions" + d.mkdir(exist_ok=True) + pages = { + "0091-expects.md": "review_on: 2026-11-01\nexpected_outcome: Fewer orphans.\n", + "0092-checked.md": "review_on: 2026-11-01\nexpected_outcome: Fewer orphans.\n" + "outcome: partly\noutcome_checked: 2026-11-10\n", + "0093-plain-due.md": "review_on: 2026-11-01\n", + "0094-bad-outcome.md": "outcome: great\noutcome_checked: 2026-11-10\n", + "0095-no-outcome.md": "outcome_checked: 2026-11-10\n", + "0096-old-check.md": "review_on: 2026-11-15\nexpected_outcome: X.\n" + "outcome: met\noutcome_checked: 2026-11-10\n", + } + for name, extra in pages.items(): + (d / name).write_text(DECISION.format(n=name[:4], extra=extra), encoding="utf-8") + idx = d / "index.md" + old = idx.read_text(encoding="utf-8") if idx.is_file() else "# Decisions\n" + idx.write_text(old + "".join(f"\n- [{n}]({n})" for n in pages) + "\n", encoding="utf-8") + r = subprocess.run([sys.executable, str(LINT), "--json", "--today", TODAY], cwd=str(kb), + capture_output=True, text=True, encoding="utf-8") + cls.findings = json.loads(r.stdout)["trees"][0]["decisions"] + + @classmethod + def tearDownClass(cls): + cls.tmp.cleanup() + + def about(self, name): + return [f for f in self.findings if name in f] + + def test_due_review_with_expectation_asks_for_outcome(self): + (f,) = self.about("0091") + self.assertIn("due for review", f) + self.assertIn("record `outcome`", f) + + def test_outcome_checked_after_review_on_closes_it(self): + self.assertEqual(self.about("0092"), []) + + def test_plain_due_review_unchanged(self): + (f,) = self.about("0093") + self.assertIn("due for review", f) + self.assertNotIn("expected_outcome", f) + + def test_outcome_vocabulary(self): + self.assertTrue(any("`outcome: great`" in f for f in self.about("0094"))) + + def test_checked_without_outcome(self): + self.assertTrue(any("no `outcome`" in f for f in self.about("0095"))) + + def test_check_before_review_on_does_not_close_it(self): + self.assertTrue(any("due for review" in f for f in self.about("0096"))) + + +LESSONS = ("---\ntype: lessons\ntldr: Lessons.\n---\n\n# Lessons\n\n" + "### 2026-11-01 — {a}\n- **Scope:** KB\n\n" + "### 2026-11-02 — ~~{b}~~ — dropped 2026-11-05: no longer true\n- **Scope:** KB\n") + + +class UpstreamLessons(unittest.TestCase): + def test_local_and_upstream_listed_struck_skipped(self): + with tempfile.TemporaryDirectory() as t: + root = Path(t) + (root / "wiki").mkdir() + (root / "wiki/lessons.md").write_text(LESSONS.format(a="Local rule", b="Dead local"), encoding="utf-8") + up = root / "linked" / "parent" / "wiki" + up.mkdir(parents=True) + (up / "lessons.md").write_text(LESSONS.format(a="Parent rule", b="Dead parent"), encoding="utf-8") + out = "\n".join(session_start.lessons_lines(root, None, date(2026, 11, 18))) + self.assertIn("lessons: 1 in wiki/lessons.md", out) + self.assertIn("Local rule", out) + self.assertIn("upstream lessons: 1 in linked/parent/wiki/lessons.md", out) + self.assertIn("Parent rule", out) + self.assertNotIn("Dead", out) + + def test_nothing_without_lessons(self): + with tempfile.TemporaryDirectory() as t: + self.assertEqual(session_start.lessons_lines(Path(t), None, date(2026, 11, 18)), []) + + +if __name__ == "__main__": + unittest.main() diff --git a/wiki/decisions/index.md b/wiki/decisions/index.md index da5c1b7..1e692f0 100644 --- a/wiki/decisions/index.md +++ b/wiki/decisions/index.md @@ -22,4 +22,7 @@ number and its page, and the newer decision points back at it. ## Open questions Decisions still at `proposed`, and any decision whose `review_on` date has -passed, are the ones worth chasing. `ckb-lint` reports both. +passed without an `outcome_checked` on or after it, are the ones worth +chasing. `ckb-lint` reports both. A decision with an `expected_outcome` is +reviewed by comparing it with what happened (`ckb-decide`, "review +D-NNNN"); the result is appended to its `## Outcome`. diff --git a/wiki/error-book.md b/wiki/error-book.md index 0f365ea..8ad4a5a 100644 --- a/wiki/error-book.md +++ b/wiki/error-book.md @@ -1,15 +1,34 @@ --- type: error-book -tldr: Table of known ingest/lint errors, root causes, and the constraints derived from them. -last_updated: 2026-10-09 +tldr: Recurring ingest/lint problems, each with every fix tried against it, what each fix was expected to change, and what it actually did. +last_updated: 2026-11-18 --- # Error Book -Records systematic compilation errors, their root causes, -and the reusable constraints derived from them. +One entry per **recurring problem**, not per incident. Each entry names the +root cause as a hypothesis and keeps every attempt to fix it, in order, +including the ones that did not work. Before opening a new entry, check +whether an existing one already explains the failure and append to it +instead. `ckb-lint` (check 9) owns the format. -| Date | Error | Root Cause | Fix / Constraint | -|------|-------|-----------|------------------| + + +*(No problems recorded yet.)* diff --git a/wiki/index.md b/wiki/index.md index 3445560..cc1283a 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -1,5 +1,5 @@ --- -kb_schema_version: "1.7" +kb_schema_version: "1.8" --- # Knowledge Base Index