From 592586d16a4dbcebe5256943283d40dd0c7a180f Mon Sep 17 00:00:00 2001 From: karitham Date: Sat, 3 Oct 2026 17:51:44 +0200 Subject: [PATCH] opencode/knowledge-base: sync, commit, and push the wiki --- modules/opencode/agents/knowledge-worker.md | 8 +- .../opencode/skills/knowledge-base/SKILL.md | 115 ++++++++++++++++-- modules/opencode/skills/vcs/SKILL.md | 8 +- 3 files changed, 116 insertions(+), 15 deletions(-) diff --git a/modules/opencode/agents/knowledge-worker.md b/modules/opencode/agents/knowledge-worker.md index 4f95ace..747b2df 100644 --- a/modules/opencode/agents/knowledge-worker.md +++ b/modules/opencode/agents/knowledge-worker.md @@ -28,11 +28,13 @@ You are the bulk executor for the knowledge base at `~/notes/wiki`. exactly — it defines the layout, scope resolution, page types, and write constraints. Nothing in this file overrides it. 2. Execute the dispatched task within those rules. -3. Report back: pages created or updated, log entries appended, gaps - found, and any judgment calls that need a human decision. +3. Report back: pages created or updated, log entries appended, commits + made and pushed, gaps found, and any judgment calls that need a human + decision. ## Constraints - MUST NOT act without loading the skill first — without it you lack the layout, scope map, and authorship boundary. -- MUST NOT write outside `~/notes/wiki/`. +- MUST NOT write outside `~/notes/wiki/`; the knowledge-base skill's + sync/publish protocol is the sanctioned exception. diff --git a/modules/opencode/skills/knowledge-base/SKILL.md b/modules/opencode/skills/knowledge-base/SKILL.md index b2fe80f..4ecde2c 100644 --- a/modules/opencode/skills/knowledge-base/SKILL.md +++ b/modules/opencode/skills/knowledge-base/SKILL.md @@ -1,9 +1,10 @@ --- name: knowledge-base description: > - Conventions for the wiki at ~/notes/wiki: record outcomes, ingest sources, - and lint. Use when the user wants something saved to or changed in their - notes; use knowledge-query for read-only questions. + Conventions for the wiki at ~/notes/wiki: sync with origin, record + outcomes, ingest sources, lint, and publish. Use when the user wants + something saved to or changed in their notes; use knowledge-query for + read-only questions. license: MIT metadata: author: kar @@ -56,7 +57,64 @@ If `wiki/` does not exist yet, scaffold the layout above. scope hints, which topic dirs cover the domain. A match proposes it. - Still unclear → write nothing; ask which scope to use. -### 3. Record / Ingest +### 3. Sync + +Run this before the first write of a run. The vault is a colocated +jj + git repo; reconcile with origin so the later commit fast-forwards +cleanly. + +1. `jj st` to see the working copy, then `jj git fetch`. + + Do not rebase with `-b @`. When local wiki commits are ahead of + origin, jj anchors that revset at the empty working-copy commit and + re-parents origin's commit above the local one, silently taking + origin's content. Use the local chain root instead. + +2. Rebase the local chain onto upstream. The chain root is the oldest + commit that is not already on `main@origin`: + + jj bookmark set main -r @- # only if `main` is conflicted after fetch + jj log -r 'roots(::@ & ~::main@origin)' --no-graph -T change_id + jj rebase -s -o main@origin + + `jj git fetch` leaves `main` conflicted (`main??`) when local and + origin diverged; point it at the local commit then. If `main` is not + conflicted it is already correct and `jj bookmark set` can fail with + "Refusing to move bookmark backwards or sideways" — skip it. + When the vault has no unpushed commits, `roots(...)` is the empty + working-copy commit `@`, so the rebase is a no-op. +3. Resolve conflicts. `jj log -r 'conflicts()'` lists them. + - Working copy: edit the file to the intended content and delete every + conflict marker (their form follows `ui.conflict-marker-style`); jj + snapshots the fix. + - Committed revision C: the conflict is materialized in the working + copy too. Edit the file there to the intended content, then squash + only that path into C: `jj squash --into C `. Restrict it to + the conflicted path (`wiki/index.md`, `wiki//...`) so + untracked or out-of-scope files in the working copy are not swept + into C. Repeat until `jj log -r 'conflicts()'` is empty. + - Never `jj new C` or `jj edit C`: moving the working copy onto the + conflicted revision deletes uncommitted files outside `wiki/`. + - A conflict outside `wiki/` is never guessed at: stop and report. +4. Verify the rebase kept the local work: `jj log -r 'conflicts()'` must be + empty and `jj diff -r 'main@origin..@'` must show the local wiki + changes. If a local edit is missing, stop and report before writing + anything. +5. Commit pre-existing work in this operation's paths so it does not mix + with the new work: + + jj commit -m "wiki: " \ + wiki/ wiki/index.md wiki/log.md + + Prefix the subject with the scope when it is not `common`: + `wiki/: `, matching recent commits (`wiki/upf: ...`). + Run it only when `jj diff wiki/ wiki/index.md wiki/log.md` is + non-empty; a `jj commit` whose paths match nothing still creates an + empty commit. Read the diff and name what changed, never `wip`. + Changes outside those paths stay in the working copy; never move or + discard them. + +### 4. Record / Ingest For each unit of knowledge (session outcome, source, decision): @@ -77,20 +135,20 @@ For each unit of knowledge (session outcome, source, decision): what changed and why — never silently overwritten, never left standing unflagged next to its successor. -### 4. Query +### 5. Query Answer from wiki pages and human notes (read-only), citing a path for every claim. Search all scopes. Answers worth keeping get filed into the scope they belong to so explorations compound. -### 5. Lint +### 6. Lint On request, or after bulk ingest: orphan pages, broken links, stale index entries, recurring terms lacking a page, contradictions between pages — requested scope unless told otherwise. Fix mechanical breakage directly; report judgment calls. -### 6. Log +### 7. Log After every operation append to `log.md`: @@ -99,10 +157,51 @@ After every operation append to `log.md`: and update `index.md` in the same pass. Gaps and open questions go into `log.md`, never into speculative prose. +### 8. Publish + +Run this after a run that wrote to `wiki/`, or that committed pre-existing +work in §3. A question answered without filing anything writes nothing +and publishes nothing. + +1. `jj st`. If `jj diff wiki/ wiki/index.md wiki/log.md` is + non-empty, commit the operation's paths the same way as §3 step 5 + (`wiki: `, or `wiki/: ` for a named scope): + + jj commit -m "wiki: " \ + wiki/ wiki/index.md wiki/log.md + +2. Point `main` at the newest commit and push: + + jj bookmark set main -r @- + jj git push -b main + + `@-` is the commit just made; `@` keeps any human or other-scope + changes uncommitted, and those stay local, so the push carries only + the wiki commits. +3. If the push is rejected because origin moved, run Sync §3 again: + `jj git fetch`, rebase the local chain root onto `main@origin`, + resolve conflicts, verify, then push again. +4. Report the commits pushed. + ## Constraints - MUST NOT create, edit, or delete anything under `~/notes` except within - `wiki/` — everything else belongs to the human. + `wiki/` — everything else belongs to the human. The jj sync/publish + commands are the sanctioned exception: they touch VCS metadata and + remote state, never file content outside `wiki/`. +- MUST NOT commit or push paths outside `wiki/`, `wiki/index.md`, + and `wiki/log.md` — other scopes and human notes stay uncommitted in + the working copy. +- MUST stop and report a rebase conflict outside `wiki/` — never guess at + human prose. +- MUST leave pre-existing out-of-scope changes untouched; never reset, + move, or discard them. In particular, never run `jj new` or `jj edit` + onto a revision while the working copy holds uncommitted human or + other-scope files — it deletes them. Squash conflict resolutions into + a committed revision with `jj squash --into C `, path-limited to + the conflicted `wiki/` file. +- MUST run Sync and Publish only around a run that writes to `wiki/`; a + question answered without filing anything must not touch VCS state. - MUST NOT delete wiki pages — mark superseded/archived instead so history and inbound links survive. - MUST NOT state facts without a citation — if the corpus cannot answer, diff --git a/modules/opencode/skills/vcs/SKILL.md b/modules/opencode/skills/vcs/SKILL.md index 5bb2e07..43a5c1d 100644 --- a/modules/opencode/skills/vcs/SKILL.md +++ b/modules/opencode/skills/vcs/SKILL.md @@ -17,7 +17,7 @@ You use jj, not git. Command syntax comes from `jj help `; query syntax ## Workflows -These are local-only workflows. Fetch is fine, push is not. +These are local-only workflows in this repository. Fetch is fine, push is not. ### 1. Stack & Commit @@ -71,7 +71,7 @@ jj rebase -b my-feature -o main # or a specific bookmark jj always succeeds — conflicts are stored in the commit, not errors. Never undo to escape a conflict; resolve in place. ``` -jj log -r 'conflict()' # find conflicted commits +jj log -r 'conflicts()' # find conflicted commits jj new ABC1234 # sit on the first conflicted commit # ...edit conflicted files... jj squash # move the resolution in; descendants auto-rebase @@ -103,7 +103,7 @@ One line per command; `jj help ` for flags and details. - `jj bookmark list --all-remotes` — bookmarks; `jj bookmark create|set|move|delete|track` to manage - `jj op log -p` — operation history with changes - `jj undo [--operation ID]` — undo an operation, itself reversible -- `jj git fetch` — the only allowed remote operation +- `jj git fetch` — the only allowed remote operation in this repository ## Rules @@ -112,7 +112,7 @@ One line per command; `jj help ` for flags and details. - **MUST** run `jj st` before any commit operation. - **MUST** use `jj log --limit N` to limit output (NOT `@-5..@` — that revset syntax is invalid). - **MUST** use `jj file show -r REV PATH` to view file contents at a revision. The `REV:PATH` fileset syntax is NOT accepted. -- **MUST NOT** run `jj git push` under any circumstances — that's the user's responsibility. +- **MUST NOT** run `jj git push` in this repository — that's the user's responsibility. A repo-specific skill may authorize pushing another repository (the `knowledge-base` skill pushes `~/notes`). - **MUST NOT** use git commands directly — this repo uses jj as the primary VCS. - **SHOULD** use `jj absorb` instead of `jj squash` when fixups belong in earlier commits — it's automatic and less error-prone. - **SHOULD** use `jj undo` on mistakes — it's safe, reversible, and works on almost any operation. -- 2.51.2