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
@@ -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
|
||||
|
||||
Reference in new issue
Block a user