Files changed: - AGENTS.md - CHANGES.md - INSTALL.md - README.md - VERSION - docs/knowledge-and-commitment.md - instructions/dev/doc-pull-through.md - instructions/setup-instance.md - instructions/upgrade-instance.md - tools/README.md
This commit is contained in:
torben committed
1 parent
44909c9e47
commit
1d695f6536
10 files changed
+296
-24
No files matched your search
@@ -142,19 +142,21 @@ background consulted in passing, not a rule to follow; anything that would bind
|
||||
type, index, lint or provenance; `dist export` ships it verbatim and no other `tools/wikitool`
|
||||
command touches it.
|
||||
|
||||
Five pages are reached from this file, each by link rather than automatically:
|
||||
Six pages are reached from this file, each by link rather than automatically:
|
||||
[docs/pipeline-rationale.md](docs/pipeline-rationale.md) (why the pipeline has four stages),
|
||||
[docs/ownership-and-templates.md](docs/ownership-and-templates.md) (why a `.template` split
|
||||
exists, and why silent overwrite is the failure it guards against),
|
||||
[docs/language-boundaries.md](docs/language-boundaries.md) (why the control plane is English
|
||||
everywhere and the KB language is a value, and why the axis is the reader rather than the
|
||||
owner), [docs/why-gates-are-code.md](docs/why-gates-are-code.md) (why the four gates in
|
||||
[Gates](#gates) are code rather than instruction), and
|
||||
[Gates](#gates) are code rather than instruction),
|
||||
[docs/version-model.md](docs/version-model.md) (why a version number answers a compatibility
|
||||
question and a migration question separately). A sixth,
|
||||
`docs/model-and-effort-selection.md`, is deliberately not linked here but from `CLAUDE.md`: it
|
||||
decides something only that harness has to decide, and a link here would load it into the other
|
||||
three.
|
||||
question and a migration question separately), and
|
||||
[docs/knowledge-and-commitment.md](docs/knowledge-and-commitment.md) (why commitments live in a
|
||||
task tracker rather than in `kb/`, and why the two are joined at read time instead of synced). A
|
||||
seventh, `docs/model-and-effort-selection.md`, is deliberately not linked here but from
|
||||
`CLAUDE.md`: it decides something only that harness has to decide, and a link here would load it
|
||||
into the other three.
|
||||
|
||||
## Personalization
|
||||
|
||||
|
||||
+47
-1
@@ -59,7 +59,7 @@ concern - readable here, never shipped as something to parse.
|
||||
|
||||
---
|
||||
|
||||
## 7.0.0-beta.6 - 2026-09-20 - Skill weekly-review: turning wikitool review's findings into decisions
|
||||
## 7.0.0-beta.7 - 2026-09-20 - Doku-Nachzug zu #119: die Verpflichtungsschicht erreicht Installation, Setup und docs/
|
||||
|
||||
**Author:** Torben Nehmer
|
||||
|
||||
@@ -74,6 +74,7 @@ concern - readable here, never shipped as something to parse.
|
||||
- wikitool review: the weekly GTD review as a read-time join
|
||||
- wikitool new project: Seite und Tracker-Projekt unter einem Namen
|
||||
- Skill weekly-review: turning wikitool review's findings into decisions
|
||||
- Doku-Nachzug zu #119: die Verpflichtungsschicht erreicht Installation, Setup und docs/
|
||||
|
||||
**Low impact**
|
||||
- new project: Testabdeckung fuer die required-responsibility-Ablehnung
|
||||
@@ -222,6 +223,51 @@ zusammen). Die Kommandoflaeche bleibt bei `review`/`new project`; alles Aufgaben
|
||||
naechste Aktion anlegen, `follow_up_at` verschieben, einen Someday-Eintrag streichen - bleibt eine
|
||||
Handlung im Tracker selbst, weil dafuer kein `wikitool`-Kommando existiert (D31).
|
||||
|
||||
### Doku-Nachzug zu #119: die Verpflichtungsschicht erreicht Installation, Setup und docs/
|
||||
|
||||
Gitea #119, nach Abschluss von #122-#127: die sechs Umsetzungspakete haben ihre Vertragszeilen
|
||||
jeweils mitgebracht (`tools/CONTRACT.md`, `kb/CONTRACT.md`), aber drei Flaechen blieben zurueck,
|
||||
die kein Paket fuer sich allein besass - und keine davon faellt bei `docs verify` auf, weil dort
|
||||
keine Zeile fehlt, sondern Prosa.
|
||||
|
||||
- **`INSTALL.md` § Konfiguration kannte `.wikitool-tasks.json` nicht.** Die Datei stand in
|
||||
`tools/CONTRACT.md`s `doctor`-Zeile und in `review`s Fehlerkontrakt, also dort, wo ein Agent
|
||||
nachschlaegt - nur nicht dort, wo ein Mensch die Form nachschlaegt. Sie steht jetzt neben
|
||||
`.wikitool-telemetry.json` und `.wikitool-remotes.json`, mit vollstaendigem Beispiel, den drei
|
||||
Schwellwerten als Konfiguration statt Schema, und dem fuer Super Productivity getrennten
|
||||
Lese-/Schreibpfad. Die `doctor`-Beschreibung unter § Verifikation nennt den Tracker jetzt mit.
|
||||
- **`setup-instance.md` bot den Tracker nie an.** Eine neue Instanz bekam Typ und Collection ueber
|
||||
die generische Template-Adoption (Schritt 5), aber nichts fragte nach der anderen Haelfte des
|
||||
Rueckblicks. Neuer Entscheidungspunkt (Schritt 11, parallel zur Telemetrie): einmal fragen,
|
||||
`.wikitool-tasks.json` anlegen oder nichts tun - kein Tracker ist ein gueltiger Endzustand. Die
|
||||
Form steht nicht hier, sondern in `INSTALL.md` (Invariante 8). Folgenummern 12-16 nachgezogen,
|
||||
Skill-Liste um `weekly-review` ergaenzt.
|
||||
- **`upgrade-instance.md` hatte keinen Pfad fuer ein neu ausgeliefertes `.template`.** Genau der
|
||||
Fall, den 7.0.0 erzwingt: Schritt 5 sagte „`new` braucht keine Entscheidung", und die
|
||||
Schritt-6-Tabelle sagt, instanzeigene Dateien koennten dort gar nicht auftauchen - beides
|
||||
richtig und zusammen irrefuehrend, weil ein neues `types/<name>.md.template` fuer einen
|
||||
geforderten Typ sehr wohl eine Handlung braucht. Schritt 5 benennt diese eine Ausnahme jetzt,
|
||||
Schritt 9 traegt die Reparatur neben der TOC-Reparatur: die gewoehnliche Adoption, mit den zwei
|
||||
`cp`-Zeilen, ausdruecklich keine Datenmigration.
|
||||
|
||||
Dazu die Begruendung selbst: **`docs/knowledge-and-commitment.md`** ist neu und haelt fest, warum
|
||||
Wissen und Verpflichtung zwei Schichten sind (verschiedene Halbwertszeiten), warum nicht
|
||||
synchronisiert wird (Muster 4, mit den drei verworfenen Anordnungen), warum der Join zur Lesezeit
|
||||
passiert und nichts speichert, warum ein Name die Pflichten eines Identifiers erbt, warum eine
|
||||
Seite ihre Aufgabenliste nie zusammenfasst, warum Archivierung ein `state:`-Wert ist, und warum
|
||||
keine Instruction je den Provider nennt. Das stand bisher ausschliesslich in Gitea #119 - und ein
|
||||
Issue ist genau das, was `dist export` nicht mitliefert: eine ausgelieferte Instanz bekam den
|
||||
Mechanismus ohne das Warum. `AGENTS.md` § File naming zaehlt jetzt sechs statt fuenf von dort
|
||||
verlinkte `docs/`-Seiten.
|
||||
|
||||
`tools/README.md` § Layout fuehrt `review.py` und das Paket `tasks/`; und
|
||||
`instructions/dev/doc-pull-through.md` bekommt die zwei Zeilen, deren Fehlen dieser Nachzug ist:
|
||||
eine fuer eine instanzeigene Konfigurationsdatei (INSTALL.md § Konfiguration + der
|
||||
`setup-instance`-Entscheidungspunkt + `doctor`s Vertragszeile), eine fuer einen neuen geforderten
|
||||
Seitentyp oder eine neue Collection (Type-Spec/`COLLECTION.md` + `kb/CONTRACT.md` + **beide**
|
||||
Adoptionspfade). Die Zeile zur `docs/`-Begruendung sagt jetzt zusaetzlich, dass eine Entscheidung
|
||||
ohne Seite die eigentliche Luecke ist, weil Begruendungen aus einem Issue nie ausgeliefert werden.
|
||||
|
||||
---
|
||||
|
||||
## 6.2.0 - 2026-09-19 - Entity-Subtyp project nach codebase umbenannt
|
||||
|
||||
+36
-1
@@ -291,6 +291,39 @@ export WIKITOOL_UPDATE_TOKEN="<gitea-token>"
|
||||
tools/wikitool version check
|
||||
```
|
||||
|
||||
**Aufgaben-Tracker anbinden - optional.** Der Wochenrückblick (`tools/wikitool review`, Skill
|
||||
`weekly-review`) gleicht die Projektseiten unter `kb/gtd/` gegen einen Aufgaben-Tracker ab. Welcher
|
||||
das ist, steht in `.wikitool-tasks.json` im Repo-Root - der dritten Datei dieser Art neben
|
||||
`.wikitool-telemetry.json` und `.wikitool-remotes.json`: pro Checkout, ohne `.template`, und
|
||||
**gitignored, sobald ein Token darin liegt**. Fehlt sie, ist schlicht kein Tracker konfiguriert;
|
||||
das ist ein gültiger Endzustand, kein Fehler. Kaputt ist sie dagegen ein `FAIL` - eine
|
||||
unlesbare Konfiguration darf nicht als „kein Tracker" durchgehen.
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": 1,
|
||||
"provider": "superproductivity",
|
||||
"thresholds": {
|
||||
"stalled_waiting_days": 14,
|
||||
"unpaged_project_weeks": 3,
|
||||
"someday_stale_months": 5
|
||||
},
|
||||
"superproductivity": {
|
||||
"backups_dir": "~/.config/superProductivity/backups",
|
||||
"api_base_url": "http://127.0.0.1:3876",
|
||||
"api_token": "<token aus den SP-Einstellungen>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`provider` wählt den Adapter - ausgeliefert wird bislang `superproductivity`. Der `thresholds`-
|
||||
Block trägt die drei Schwellwerte des Rückblicks (Konfiguration, nicht Schema): ab wann ein
|
||||
Waiting-For überfällig ist, ab welchem Alter ein Tracker-Projekt ohne `kb/`-Seite gemeldet wird,
|
||||
und ab wann ein Someday-Eintrag als verstaubt gilt. Der gleichnamige Provider-Block trägt dessen
|
||||
Verbindungsangaben; bei Super Productivity sind Lese- und Schreibpfad verschieden - gelesen wird
|
||||
der jüngste Backup-Schnappschuss unter `backups_dir` (läuft auch ohne laufende App), geschrieben
|
||||
über die lokale REST-API, die nur antwortet, solange die App läuft.
|
||||
|
||||
## Verifikation
|
||||
|
||||
```bash
|
||||
@@ -300,7 +333,9 @@ tools/wikitool doctor
|
||||
Prüft in einem Aufruf: Abhängigkeiten, Autor-Auflösung, Git-Identität/Branch/Remote,
|
||||
publizierte Skills, Struktur (Collection-Contracts, generierte Dateien), Personalization
|
||||
(`USER.md`/`SOUL.md` vorhanden **und** ausgefüllt), die optionale Umgebungsnotiz
|
||||
(`ENVIRONMENT.md`) und die Session-ID.
|
||||
(`ENVIRONMENT.md`), den Aufgaben-Tracker (`.wikitool-tasks.json` - fehlt sie, ist das `OK`; ist
|
||||
ein Provider konfiguriert, zusätzlich ob sein Lesepfad bereitsteht und seine API gerade
|
||||
antwortet, beides nie ein `FAIL`) und die Session-ID.
|
||||
`OK`/`WARN` sind unbedenklich (ein fehlender Remote z. B. ist ein gültiger Endzustand); nur ein
|
||||
`FAIL` bricht mit exit 1 ab, und jede Zeile nennt ihr eigenes Fix-Kommando.
|
||||
|
||||
|
||||
@@ -223,6 +223,29 @@ The LLM will:
|
||||
See the [Maintenance](#maintenance) section below for the full schedule and
|
||||
command reference.
|
||||
|
||||
### Reviewing Commitments (Weekly Review)
|
||||
|
||||
Say: `Run the weekly review`
|
||||
|
||||
Knowledge and commitments keep different clocks, so they live in different
|
||||
places. A page under `kb/gtd/` is one committed initiative's durable memory -
|
||||
its goal, who is involved, where it stands, why it is worth doing - and it never
|
||||
summarizes the task list. The open items live in a task tracker that owns them,
|
||||
configured per checkout in `.wikitool-tasks.json` (see
|
||||
[INSTALL.md](INSTALL.md) § Konfiguration; no tracker configured is a valid
|
||||
state, and the pages work without one).
|
||||
|
||||
Nothing syncs between the two. `tools/wikitool review` joins them at read time
|
||||
over the project name and prints what needs a decision: initiatives with no next
|
||||
action, waiting-fors past their follow-up date, tracker projects with no page,
|
||||
active pages with no open loop, someday items gone stale. It stores nothing -
|
||||
not even a report file. The `weekly-review` skill then walks the findings with
|
||||
you and turns each one into a decision; `tools/wikitool new project` is what
|
||||
gives a new initiative its page and its tracker project under one name.
|
||||
|
||||
Why the split runs this way, rather than syncing the two:
|
||||
[docs/knowledge-and-commitment.md](docs/knowledge-and-commitment.md).
|
||||
|
||||
## Entity Types
|
||||
|
||||
Entities are subtyped as codebase, system, tool, technology, or person, and each subtype has
|
||||
|
||||
@@ -0,0 +1,123 @@
|
||||
# Why knowledge and commitments are two layers
|
||||
|
||||
Chemenu compiles knowledge into `kb/`, and it also tracks what its operator has committed to do.
|
||||
Those look like one subject - both are "things about my projects" - and the stack deliberately
|
||||
keeps them apart: `kb/gtd/` holds one page per initiative, an external task tracker holds the
|
||||
open items, and the only thing that crosses between them is a name. This page is about why that
|
||||
line was drawn there. The rules that follow from it live in [kb/CONTRACT.md](../kb/CONTRACT.md)
|
||||
and the `review` and `new project` rows of [tools/CONTRACT.md](../tools/CONTRACT.md).
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [Different half-lives want different machinery](#different-half-lives-want-different-machinery)
|
||||
- [Pattern 4: separate ownership, no synchronization](#pattern-4-separate-ownership-no-synchronization)
|
||||
- [The join happens at read time, and stores nothing](#the-join-happens-at-read-time-and-stores-nothing)
|
||||
- [One name, carrying the duties of an identifier](#one-name-carrying-the-duties-of-an-identifier)
|
||||
- [Status has exactly one home](#status-has-exactly-one-home)
|
||||
- [A finished initiative is a state, not a location](#a-finished-initiative-is-a-state-not-a-location)
|
||||
- [Which tracker is a decision the stack does not make](#which-tracker-is-a-decision-the-stack-does-not-make)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## Different half-lives want different machinery
|
||||
|
||||
`kb/` is a compiler for durable things, and every mechanism in it assumes durability: `raw/` is
|
||||
immutable, a claim has to trace back to a source, a page's title is its identity, the indexes are
|
||||
generated, and a large change stops at a gate so a human can look at it. All of that is the right
|
||||
amount of ceremony for something that will still be true next year.
|
||||
|
||||
A next action is the opposite kind of fact. It is unsourced - nobody cites a reason for "call the
|
||||
plumber". It changes several times a week. It is state, not knowledge: the interesting thing
|
||||
about it is whether it is still open. And it is only correct *now*.
|
||||
|
||||
Running both through one layer does not produce a richer wiki; it produces a worse one. Every
|
||||
task-shaped page carries `provenance: general` because there is no source to bind it to, which
|
||||
drains that field of meaning for the pages where it matters. `kb/log.md` fills with "task
|
||||
checked off" entries until the audit trail of what the *wiki* learned is unreadable. Lint findings
|
||||
about orphans and stale claims start firing on pages that are supposed to be short-lived. And a
|
||||
weekly pass over the task list trips the Mass-Update Gate every single time, which is how a gate
|
||||
stops being read and starts being cleared reflexively.
|
||||
|
||||
The GTD method this borrows from draws the same line for its own reasons: of its horizons, `kb/`
|
||||
covers the two slowest - project support material and reference - and nothing faster.
|
||||
|
||||
## Pattern 4: separate ownership, no synchronization
|
||||
|
||||
Four arrangements were on the table, and three of them fail in ways worth naming.
|
||||
|
||||
**One layer** is the case above. **Export** - the wiki writes a task list the tracker imports -
|
||||
means a checkbox ticked in the tracker is a tick in a view, while the truth sits in a file the
|
||||
operator was not editing; the two disagree immediately and silently. **Bidirectional sync** works,
|
||||
at the cost of an id mapping to maintain, a conflict-resolution rule to design, and a deletion
|
||||
semantics to decide - all of it machinery whose only job is to repair a split nobody needed.
|
||||
|
||||
What is left is **separate ownership with no sync at all**: the tracker owns the tasks, `kb/` owns
|
||||
the project memory, and the single point of contact is the project's name. Nothing is mirrored,
|
||||
so nothing can drift out of mirror.
|
||||
|
||||
## The join happens at read time, and stores nothing
|
||||
|
||||
Because there is no shared state, the connection between the two sides has to be made when
|
||||
somebody actually asks - which is what `wikitool review` does: it reads both sides, matches them on
|
||||
the case-normalized project name, prints what it found, and saves nothing. Not a cache, not a
|
||||
mapping file, not even a `reports/` artifact.
|
||||
|
||||
That is the same posture `search` takes, and for the same reason: anything it wrote down would be
|
||||
a third copy of a state the two sides already hold, stale the moment either side moved, and the
|
||||
first thing to distrust in a report. A read-time join can be wrong about the present, but it
|
||||
cannot be wrong about the past, because it does not remember one.
|
||||
|
||||
## One name, carrying the duties of an identifier
|
||||
|
||||
Reducing the coupling to a name is cheap, and it is not free. A name that joins two systems is an
|
||||
identifier, whether or not anything enforces it, so the design had to pick up an identifier's
|
||||
obligations explicitly: uniqueness is checked before a project is created rather than discovered
|
||||
later; a rename is a deliberate, infrequent operation that touches both sides in one pass; and
|
||||
nothing tries to re-match automatically behind the operator's back.
|
||||
|
||||
The last one is what makes the review's *both-directional* report matter. A tracker project with
|
||||
no page and a page with no tracker project are reported separately, as two findings. They are
|
||||
usually the two halves of one rename - and reporting them separately is exactly what turns a
|
||||
silent decoupling into a visible event, at the cost of the review occasionally saying the same
|
||||
thing twice.
|
||||
|
||||
## Status has exactly one home
|
||||
|
||||
The sharpest consequence of the split is a rule that feels like a restriction: a `kb/` page never
|
||||
summarizes its own task list. No "3 open items", no "next: call the supplier".
|
||||
|
||||
Two places claiming to know the current status is the failure mode the whole arrangement exists
|
||||
to avoid, and a summary is a copy with a slower clock. The page says what an initiative *is* -
|
||||
its goal, its participants, its durable state, why it is worth doing. The tracker says what is
|
||||
open right now. Anyone wanting the second reads the tracker, or runs the review.
|
||||
|
||||
This pays for itself somewhere unexpected: with the page carrying no task state, an agent has no
|
||||
reason to read the task list at all outside the weekly review. That is what keeps the command
|
||||
surface as small as it is - one read command and one creation command - rather than growing a
|
||||
full CRUD tree over somebody's todo list.
|
||||
|
||||
## A finished initiative is a state, not a location
|
||||
|
||||
Archiving moves nothing. A completed initiative's page stays where it is and changes its `state:`
|
||||
value, because the moment an initiative finishes is the moment its page is *most* valuable -
|
||||
what was decided, what it cost, who was involved - and filing it away is how that gets lost.
|
||||
|
||||
The state field carries the distinction the review actually needs, which is not "open vs. done"
|
||||
but "does silence here mean something is wrong". An initiative that is deliberately paused looks
|
||||
identical, from the outside, to one that quietly stalled; only the operator knows which. Without a
|
||||
value for "paused on purpose", the review reports the same untouched initiatives every week, and
|
||||
a report that is mostly noise stops being read by the third week - which would cost more than the
|
||||
findings are worth.
|
||||
|
||||
## Which tracker is a decision the stack does not make
|
||||
|
||||
The tracker is reached through a provider layer, and no instruction anywhere names which one it
|
||||
is. An instruction that said "open Super Productivity" would bake one instance's tool choice into
|
||||
the shared stack, and the next instance - a different context, a different employer, a different
|
||||
set of constraints - would have to edit prose to change a setting.
|
||||
|
||||
So the provider lives in configuration (`.wikitool-tasks.json`), the adapters live behind one
|
||||
protocol, and a capability the provider lacks surfaces as an ordinary tool error rather than as a
|
||||
paragraph of instruction explaining what this particular tracker cannot do. A provider that
|
||||
cannot create a project, for instance, stops and asks the operator to do it - the same posture the
|
||||
gates take, and for the same reason: better a visible stop than an invented workaround.
|
||||
@@ -37,8 +37,10 @@ touched; a row that does not apply needs no action.
|
||||
| A stage's authoring rules (`raw/`, `kb/`, `types/`, `reports/`, `work/`, `tools/`, `instructions/`) | The touched `<stage>/CONTRACT.md` |
|
||||
| A rule, gate, or invariant `AGENTS.md` itself states | The relevant `AGENTS.md` section (Invariants, Gates, File naming, Routing, ...) |
|
||||
| A workflow, stage, or command a human operates by hand | Whichever of `README.md`, `EVALS.md`, `tools/README.md`, `INSTALL.md`, `DEVELOPMENT.md` names it - AGENTS.md § File naming says which document is for which reader |
|
||||
| The reasoning behind a gate, boundary, or design decision | The `docs/` page that carries it, if one exists (AGENTS.md § File naming lists all five reached from AGENTS.md itself, plus a sixth reached only from CLAUDE.md) |
|
||||
| The reasoning behind a gate, boundary, or design decision | The `docs/` page that carries it, if one exists (AGENTS.md § File naming lists all six reached from AGENTS.md itself, plus a seventh reached only from CLAUDE.md). **A decision with no page yet is the gap worth closing**: reasoning that lives only in a Gitea issue never ships - `dist export` carries `docs/` and no issue tracker, so a distributed instance gets the mechanism without the why |
|
||||
| A skill's own step sequence or catalogue | The skill's `SKILL.md` source under `instructions/<name>/` or `instructions/dev/<name>/` |
|
||||
| A per-checkout configuration file an instance owns (`.wikitool-tasks.json`, `.wikitool-telemetry.json`, `.wikitool-remotes.json`, `.wikitool-upload.json`) | [INSTALL.md](../../INSTALL.md) § Konfiguration, where an operator looks the shape up; the [setup-instance.md](../setup-instance.md) decision point that offers it during setup; and `doctor`'s own row in [tools/CONTRACT.md](../../tools/CONTRACT.md), since `doctor` is what reports the file's state |
|
||||
| A new page type the stack requires, or a new collection | Its type-spec and `COLLECTION.md` (both as the `.template` an instance adopts), the collection table in [kb/CONTRACT.md](../../kb/CONTRACT.md), and **both adoption paths**: [setup-instance.md](../setup-instance.md) for a fresh instance and [upgrade-instance.md](../upgrade-instance.md) for an existing one, where an unadopted template is what `docs verify` refuses |
|
||||
|
||||
3. **A heading you changed means a table of contents to regenerate - by the tool, never by
|
||||
hand.** Every reference file over 100 lines carries one (`AGENTS.md`, the stage contracts,
|
||||
|
||||
@@ -239,25 +239,44 @@ and ready for its first ingest.
|
||||
off, and no file is created. `WIKI_TRACE` still overrides in both directions, should a
|
||||
single session need to differ.
|
||||
|
||||
`tools/wikitool doctor` reports the result in step 13 (`telemetry`): on/off, why
|
||||
`tools/wikitool doctor` reports the result in step 14 (`telemetry`): on/off, why
|
||||
(installation form, this file, or `WIKI_TRACE`), and the current volume against both caps -
|
||||
never a `FAIL`, since both directions are a valid state. More on this:
|
||||
[EVALS.md](../EVALS.md) § "Whether it runs at all".
|
||||
|
||||
11. **Scope the session budget** (details: [session-setup.md](session-setup.md)):
|
||||
11. **Decision point - task tracker.** The instance ships the `project` type and the collection
|
||||
its type-spec's `base_dir:` names (`kb/gtd/` here), so committed initiatives have a page from
|
||||
the start. What they do *not* have until this step is the other half of the weekly review:
|
||||
the tracker that owns the open items, which `tools/wikitool review` joins those pages against
|
||||
over the project name. No tracker configured is a legitimate end state - the pages work
|
||||
alone, `review` simply says so and refuses - so ask rather than assume.
|
||||
|
||||
Ask the user once: is there a task tracker to connect? If yes, create `.wikitool-tasks.json`
|
||||
in the repo root (per checkout, no `.template`, **gitignored once it holds a token** - like
|
||||
`.wikitool-telemetry.json` and `.wikitool-remotes.json`), with the provider's own section and
|
||||
the three thresholds the review reads as configuration rather than schema. The shape, the
|
||||
shipped providers, and what Super Productivity in particular needs are in
|
||||
[INSTALL.md](../INSTALL.md) § Konfiguration; do not restate them here. If no, do nothing - no
|
||||
file is created, and adding one later needs nothing from this procedure.
|
||||
|
||||
`doctor` reports the result in step 14 (`tasks`): absent is `OK`, a malformed file is the one
|
||||
`FAIL` here (a broken opt-in must not read as "no tracker configured"), and a configured
|
||||
provider that is simply not running is never a fault.
|
||||
|
||||
12. **Scope the session budget** (details: [session-setup.md](session-setup.md)):
|
||||
|
||||
```bash
|
||||
export WIKITOOL_SESSION_ID="wiki-$(date +%s)"
|
||||
```
|
||||
|
||||
12. **Build the generated indexes** - `dist export` deliberately does not ship them:
|
||||
13. **Build the generated indexes** - `dist export` deliberately does not ship them:
|
||||
|
||||
```bash
|
||||
tools/wikitool index rebuild
|
||||
tools/wikitool sources rebuild-index
|
||||
```
|
||||
|
||||
13. **Verify**, in this order:
|
||||
14. **Verify**, in this order:
|
||||
|
||||
```bash
|
||||
tools/wikitool doctor
|
||||
@@ -270,7 +289,7 @@ and ready for its first ingest.
|
||||
no `WIKITOOL_SESSION_ID`, say) is not a blocker. A `FAIL` names its own fix command; run it
|
||||
and call `doctor` again.
|
||||
|
||||
14. **Make the first commit:**
|
||||
15. **Make the first commit:**
|
||||
|
||||
```bash
|
||||
tools/wikitool publish --message "chore: initial instance setup"
|
||||
@@ -282,9 +301,9 @@ and ready for its first ingest.
|
||||
`--confirm <token>` line that publishes once they approve. Details on the gate:
|
||||
[gates.md](gates.md).
|
||||
|
||||
15. **Restart the agent session.** Harnesses read the skill directories at startup; only
|
||||
afterwards are `wiki-ingest`, `wiki-query`, `wiki-manage`, `wiki-lint` and `wiki-status`
|
||||
available.
|
||||
16. **Restart the agent session.** Harnesses read the skill directories at startup; only
|
||||
afterwards are `wiki-ingest`, `wiki-query`, `wiki-manage`, `wiki-lint`, `wiki-status` and
|
||||
`weekly-review` available.
|
||||
|
||||
## Scope
|
||||
|
||||
|
||||
@@ -91,9 +91,14 @@ fresh clone ([bootstrap.md](bootstrap.md)), and not for the clone-with-upstream
|
||||
tools/wikitool dist upgrade <tarball> --dry-run
|
||||
```
|
||||
|
||||
`unchanged` / `new` / `locally changed` / `removed from the release`. The first two need no
|
||||
decision. `locally changed` is step 6. `removed` matters only if `--prune` is wanted, which is
|
||||
optional and never required.
|
||||
`unchanged` / `new` / `locally changed` / `removed from the release`. `unchanged` needs no
|
||||
decision. `new` needs one only in a single shape: a `<name>.template` for a page type or
|
||||
collection this instance does not have yet. `dist upgrade` writes the template and stops there
|
||||
- adopting it (copying it to the unsuffixed name) is the instance's own act, and where the
|
||||
stack *requires* that type the omission is what step 9's `docs verify` refuses. Step 2's
|
||||
**Breaking Change:** line says when a release is in that shape; step 9 has the repair.
|
||||
`locally changed` is step 6. `removed` matters only if `--prune` is wanted, which is optional
|
||||
and never required.
|
||||
|
||||
6. **Only if a file is reported as locally changed: decide whose file it is, then reconcile it.**
|
||||
The classification is against the sha256 the *installed* release recorded, so "locally
|
||||
@@ -149,9 +154,24 @@ fresh clone ([bootstrap.md](bootstrap.md)), and not for the clone-with-upstream
|
||||
A `docs verify` failure naming a missing or stale table of contents is repaired with
|
||||
`tools/wikitool docs toc --apply`, never by hand - a release that widened the set of files
|
||||
carrying a region will produce exactly that on files this instance adopted before the
|
||||
widening. Any other failure is read against step 2's **Breaking Change:** line: if the release
|
||||
predicted it, the notes also say what fixes it; if it did not, stop and report it rather than
|
||||
improvising.
|
||||
widening.
|
||||
|
||||
A failure naming a page type the stack requires, or the collection that type's `base_dir:`
|
||||
points at, is the other repairable shape - the `new` template from step 5 that nobody adopted.
|
||||
The fix is the ordinary adoption every `root: kb` type already needs, not a data migration:
|
||||
copy the shipped templates to their unsuffixed names, then fill the instance-owned parts
|
||||
(language, template text, any extra fields) the way step 5 of
|
||||
[setup-instance.md](setup-instance.md) describes for a fresh instance.
|
||||
|
||||
```bash
|
||||
cp types/<name>.md.template types/<name>.md
|
||||
cp kb/<collection>/COLLECTION.md.template kb/<collection>/COLLECTION.md
|
||||
```
|
||||
|
||||
The `.template` files stay where they are - they are the source for the next upgrade's
|
||||
comparison. Any other failure is read against step 2's **Breaking Change:** line: if the
|
||||
release predicted it, the notes also say what fixes it; if it did not, stop and report it
|
||||
rather than improvising.
|
||||
|
||||
10. **Publish the machinery swap.** A release swap is far above the Mass-Update Gate's threshold,
|
||||
so expect exit 42. That is not an error and not yours to clear: reproduce the file breakdown
|
||||
|
||||
@@ -48,11 +48,13 @@ tools/
|
||||
catalog.py how the corpus groups into collections and areas, and the shard threshold - with no CLI attached
|
||||
lint_core.py the lint checks and the report, with no CLI attached
|
||||
types_core.py type-spec listing/description, with no CLI attached
|
||||
review.py the weekly review's five checks - the read-time join of kb/gtd/ against the tracker, with no CLI attached
|
||||
markdown_code.py masks code spans/fences so a page may show wiki notation, not only use it
|
||||
version.py the stack version: VERSION, the release stamp, the compatibility rule
|
||||
kb_state.py the KB version (.wikitool-kb.json) and the migration chain
|
||||
corpus_diff.py invariant comparison of kb/ between two revisions
|
||||
search/ pluggable search backends, plus service.py - the search core
|
||||
tasks/ the task-tracker provider layer: protocol.py (TaskReader/TaskWriter), config.py (.wikitool-tasks.json), one module per adapter - no instruction ever learns which provider it is
|
||||
commands/ one module per command or command group: the terminal adapters
|
||||
tests/ pytest suite
|
||||
```
|
||||
|
||||
Reference in new issue
Block a user