settings: the four per-feature files .wikitool-remotes/-telemetry/-upload/-tasks.json move into the three tiers and disappear; new command config migrate; 10.0.0-beta.1 (#208)
Files changed: - .gitignore - AGENTS.md - CHANGES.md - INSTALL.md - VERSION - docs/explanation/knowledge-and-commitment.md - docs/explanation/telemetry-and-evaluation.md - docs/explanation/why-gates-are-code.md - docs/how-to/run-the-weekly-review.md - docs/how-to/set-up-the-mcp-server.md - docs/how-to/trace-and-score-sessions.md - docs/how-to/troubleshoot.md - docs/reference/commands/README.md - docs/reference/commands/configuration.md - docs/reference/commands/finding-and-checking.md - docs/reference/commands/git.md - docs/reference/commands/instance-health.md - docs/reference/commands/pages.md - docs/reference/commands/raw-material-and-uploads.md - docs/reference/configuration.md - docs/reference/exit-codes.md - instructions/dev/doc-pull-through.md - instructions/dev/tracker-testing.md - instructions/gates.md - instructions/ingest-queue.md - instructions/mcp-read-server.md - instructions/migrate-corpus.md - instructions/migrations/10.0.0-settings-tiers.md - instructions/setup-instance.md - raw/CONTRACT.md - reports/CONTRACT.md - tools/CONTRACT.md - tools/README.md - tools/bugreport.py - tools/chemenu/cli_contract.py - tools/chemenu/commands/_util.py - tools/chemenu/commands/config_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/doctor.py - tools/chemenu/commands/export_cmd.py - tools/chemenu/commands/git_publish.py - tools/chemenu/commands/new_page.py - tools/chemenu/commands/review_cmd.py - tools/chemenu/commands/task_cmd.py - tools/chemenu/commands/upload_cmd.py - tools/chemenu/config.py - tools/chemenu/config_shapes.py - tools/chemenu/legacy_settings.py - tools/chemenu/mcp/__main__.py - tools/chemenu/mcp/server.py - tools/chemenu/reference_doc.py - tools/chemenu/review.py - tools/chemenu/settings.py - tools/chemenu/tasks/__init__.py - tools/chemenu/tasks/caldav.py - tools/chemenu/tasks/config.py - tools/chemenu/tasks/superproductivity.py - tools/chemenu/telemetry/policy.py - tools/chemenu/tests/conftest.py - tools/chemenu/tests/record_sp_fixtures.py - tools/chemenu/tests/test_bugreport.py - tools/chemenu/tests/test_caldav.py - tools/chemenu/tests/test_config_shapes.py - tools/chemenu/tests/test_doctor.py - tools/chemenu/tests/test_git_publish.py - tools/chemenu/tests/test_legacy_settings.py - tools/chemenu/tests/test_mcp_server.py - tools/chemenu/tests/test_new_page.py - tools/chemenu/tests/test_review.py - tools/chemenu/tests/test_settings.py - tools/chemenu/tests/test_sp_recorded.py - tools/chemenu/tests/test_superproductivity.py - tools/chemenu/tests/test_task_cmd.py - tools/chemenu/tests/test_tasks_config.py - tools/chemenu/tests/test_telemetry_policy.py - tools/chemenu/tests/test_tracker_live.py - tools/chemenu/tests/test_upload.py - tools/chemenu/tests/tracker_live.py - tools/chemenu/upload.py Co-Authored-By: Claude Code <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
This commit is contained in:
torbenandClaude Code committed
1 parent
e085a8b6c1
commit
db8f90c229
79 files changed
+2784
-1793
No files matched your search
+105
-42
@@ -100,9 +100,9 @@ cause of its own falls back to a bare `see: wikitool <cmd> -h` pointer.
|
||||
<!-- wikitool:commands -->
|
||||
```
|
||||
new write non-idempotent budget:counted exit:0,1,42 Scaffold a new wiki page of any type.
|
||||
task new write non-idempotent budget:counted exit:0,1 Create one open item in the configured task tracker - never a kb/ page.
|
||||
task list read idempotent budget:counted exit:0,1 List a project's open items - id, title, and whether each carries the WAITING status.
|
||||
task close write idempotent budget:counted exit:0,1 Mark one tracker item done - never delete it.
|
||||
task new write non-idempotent budget:counted exit:0,1,42 Create one open item in the configured task tracker - never a kb/ page.
|
||||
task list read idempotent budget:counted exit:0,1,42 List a project's open items - id, title, and whether each carries the WAITING status.
|
||||
task close write idempotent budget:counted exit:0,1,42 Mark one tracker item done - never delete it.
|
||||
touch write idempotent budget:counted exit:0,1 Bump a page's `modified:` date and optionally rewrite its other frontmatter fields.
|
||||
rename write idempotent budget:counted exit:0,1 Rename a page, or repoint references that name a page that never existed.
|
||||
rm write non-idempotent budget:counted exit:0,1 Delete a page and mechanically de-link it from the rest of the wiki.
|
||||
@@ -119,7 +119,7 @@ log append write non-idempotent budget:counted exit:0,1
|
||||
log status read idempotent budget:counted exit:0 Read-only: count `ingest` entries logged since the last `lint` entry.
|
||||
lint write idempotent budget:counted exit:0,1 Run structural lint checks against kb/.
|
||||
search read idempotent budget:exempt exit:0,1 Find pages in `kb/` by text and/or frontmatter.
|
||||
review read idempotent budget:exempt exit:0,1 The GTD weekly review.
|
||||
review read idempotent budget:exempt exit:0,1,42 The GTD weekly review.
|
||||
sources coverage read idempotent budget:counted exit:0 List raw files with no source page, broken `raw_files:` references, and legacy directory/URL-only source pages.
|
||||
sources trace read idempotent budget:counted exit:0,1 Trace provenance in either direction: raw file, or page.
|
||||
sources rebuild-index write idempotent budget:counted exit:0,1 Regenerate the `kb/provenance.md` reverse index.
|
||||
@@ -167,6 +167,7 @@ migrate verify read idempotent budget:exempt exit:0,1
|
||||
migrate done write non-idempotent budget:counted exit:0,1 Record one migration as applied, advancing `kb_version` in `.wikitool-kb.json`.
|
||||
migrate baseline write idempotent budget:counted exit:0,1 Declare `kb_version` once, for an instance predating `.wikitool-kb.json`.
|
||||
config set write idempotent budget:counted exit:0,1,42 Set one value of the tiered settings, in the file its tier names.
|
||||
config migrate write idempotent budget:counted exit:0,1 Move the settings out of the per-feature files of earlier versions into the tiered settings.
|
||||
doctor read idempotent budget:exempt exit:0,1 Check that this instance is correctly configured.
|
||||
```
|
||||
|
||||
@@ -239,7 +240,7 @@ Scaffold a new wiki page of any type.
|
||||
- `--set` is repeatable, and comma-separated values fill array fields. An element that itself contains a comma is written `\,`, or passed as its own repeated `--set` for that field - repeating an array field appends.
|
||||
- A capture field the type-spec requires (a source's `fidelity`/`authority`) must be passed with `--set`; `new` never guesses it and refuses `unknown` for it.
|
||||
- Produces structurally correct frontmatter and a body skeleton only - the prose (Description, Summary, judgment calls about relationships) is written afterwards.
|
||||
- `new project`: with `.wikitool-tasks.json` configuring a task tracker, also makes sure a same-named tracker project exists - one name, one identity. No tracker configured is a legitimate, explicitly announced state: page only.
|
||||
- `new project`: with the `tasks` section of the settings configuring a task tracker, also makes sure a same-named tracker project exists - one name, one identity. No tracker configured is a legitimate, explicitly announced state: page only.
|
||||
- `new project`: tracker before page. The tracker side is settled first, so a failure past that point leaves a tracker project with no page - a state `review`'s check 3 reports - never a page with no tracker project.
|
||||
- `new project`: a name already taken, case-insensitively, in `kb/` or the tracker is refused outright, naming where it was found, and creates nothing. For `caldav` the tracker check covers every list in the account, not only the ones counted as projects.
|
||||
- `new project`: a provider whose configured access path has no write path (Super Productivity's `access: "snapshot"`) refuses entirely with exit 1, naming the `access: "api"` instance to use instead - neither the tracker project nor the page is created, and `--resume` behaves the same.
|
||||
@@ -278,21 +279,23 @@ Create one open item in the configured task tracker - never a kb/ page.
|
||||
**EXIT STATUS**
|
||||
|
||||
- 0 success
|
||||
- 1 No `.wikitool-tasks.json` - no tracker configured
|
||||
- 1 `WIKITOOL_TASKS_CONFIG` names a file that does not exist or is broken
|
||||
- 1 No `tasks` section in the settings - no tracker configured
|
||||
- 1 `WIKITOOL_TASKS_CONFIG` names a profile that does not exist or is broken
|
||||
- 1 Neither or both of `--project`/`--inbox`, or a `--follow-up-at` without `--waiting` or not `YYYY-MM-DD`
|
||||
- 1 A `--project` name matching no tracker project
|
||||
- 1 `--waiting` against a provider with no way to represent it right now (Super Productivity: the `waiting` tag does not exist)
|
||||
- 1 A read-only access path (Super Productivity's `access: "snapshot"`)
|
||||
- 42 The tracker settings file of an earlier version is still there, or a secret source (1Password) needs unlocking
|
||||
|
||||
**ON FAILURE**
|
||||
|
||||
- No `.wikitool-tasks.json` - no tracker configured -> Not transient - configure a tracker first
|
||||
- `WIKITOOL_TASKS_CONFIG` names a file that does not exist or is broken -> Not transient - fix the path or unset the variable
|
||||
- No `tasks` section in the settings - no tracker configured -> Not transient - configure a tracker first
|
||||
- `WIKITOOL_TASKS_CONFIG` names a profile that does not exist or is broken -> Not transient - fix the path or unset the variable
|
||||
- Neither or both of `--project`/`--inbox`, or a `--follow-up-at` without `--waiting` or not `YYYY-MM-DD` -> Fix the argument and retry once
|
||||
- A `--project` name matching no tracker project -> Create the tracker project first, or fix the name, then retry once
|
||||
- `--waiting` against a provider with no way to represent it right now (Super Productivity: the `waiting` tag does not exist) -> Create the tag in the tracker first, then retry once
|
||||
- A read-only access path (Super Productivity's `access: "snapshot"`) -> Point at the `access: "api"` instance the error names, then retry once
|
||||
- The tracker settings file of an earlier version is still there, or a secret source (1Password) needs unlocking -> Show the output to the user verbatim and stop - `tools/wikitool config migrate` or the unlock is theirs to run
|
||||
|
||||
**NEVER**
|
||||
|
||||
@@ -306,10 +309,10 @@ Create one open item in the configured task tracker - never a kb/ page.
|
||||
- `--inbox` files into the tracker's own inbox. An item filed there never appears in `review`, since every one of its checks reaches items through a project name.
|
||||
- `--waiting` sets the WAITING status `review`'s waiting-overdue check reads. `--follow-up-at` is refused without `--waiting` - it is never a due date on its own.
|
||||
- `--notes` carries a freetext backref (e.g. to the `kb/` source page the item came from), stored verbatim, never parsed.
|
||||
- The tracker configuration is read from `.wikitool-tasks.json`, or from the file `WIKITOOL_TASKS_CONFIG` names when that variable is set (so one checkout can be run against several trackers in turn). A set variable that names no file is an error, never "no tracker configured".
|
||||
- No `.wikitool-tasks.json` fails immediately with a "no tracker configured" message.
|
||||
- The tracker configuration is read from the `tasks`, `superproductivity` and `caldav` sections of the settings, or from the profile `WIKITOOL_TASKS_CONFIG` names when that variable is set (so one checkout can be run against several trackers in turn). A set variable that names no file is an error, never "no tracker configured".
|
||||
- No `tasks` section fails immediately with a "no tracker configured" message.
|
||||
- A provider whose configured access path has no write path (Super Productivity's `access: "snapshot"`) refuses entirely with exit 1, naming the `access: "api"` instance to use instead.
|
||||
- **Never exits 42.** A `--project` matching no tracker project, or `--waiting` against a provider that cannot represent it right now (Super Productivity: the `waiting` tag does not exist yet, and its API cannot create tags), are ordinary exit-1 refusals that create nothing.
|
||||
- **Exits 42 only for the settings** (the tracker settings file of an earlier version, a locked secret source). A `--project` matching no tracker project, or `--waiting` against a provider that cannot represent it right now (Super Productivity: the `waiting` tag does not exist yet, and its API cannot create tags), are ordinary exit-1 refusals that create nothing.
|
||||
- Not idempotent: every successful run creates another item.
|
||||
|
||||
**SEE ALSO**
|
||||
@@ -343,13 +346,15 @@ List a project's open items - id, title, and whether each carries the WAITING st
|
||||
|
||||
- 0 success
|
||||
- 0 A `--project` matching no tracker project - prints "No open items", not an error
|
||||
- 1 No `.wikitool-tasks.json` - no tracker configured
|
||||
- 1 `WIKITOOL_TASKS_CONFIG` names a file that does not exist or is broken
|
||||
- 1 No `tasks` section in the settings - no tracker configured
|
||||
- 1 `WIKITOOL_TASKS_CONFIG` names a profile that does not exist or is broken
|
||||
- 42 The tracker settings file of an earlier version is still there, or a secret source (1Password) needs unlocking
|
||||
|
||||
**ON FAILURE**
|
||||
|
||||
- No `.wikitool-tasks.json` - no tracker configured -> Not transient - configure a tracker first, then retry once
|
||||
- `WIKITOOL_TASKS_CONFIG` names a file that does not exist or is broken -> Not transient - fix the path or unset the variable
|
||||
- No `tasks` section in the settings - no tracker configured -> Not transient - configure a tracker first, then retry once
|
||||
- `WIKITOOL_TASKS_CONFIG` names a profile that does not exist or is broken -> Not transient - fix the path or unset the variable
|
||||
- The tracker settings file of an earlier version is still there, or a secret source (1Password) needs unlocking -> Show the output to the user verbatim and stop - `tools/wikitool config migrate` or the unlock is theirs to run
|
||||
|
||||
**NOTES**
|
||||
|
||||
@@ -387,17 +392,19 @@ Mark one tracker item done - never delete it.
|
||||
**EXIT STATUS**
|
||||
|
||||
- 0 success
|
||||
- 1 No `.wikitool-tasks.json` - no tracker configured
|
||||
- 1 `WIKITOOL_TASKS_CONFIG` names a file that does not exist or is broken
|
||||
- 1 No `tasks` section in the settings - no tracker configured
|
||||
- 1 `WIKITOOL_TASKS_CONFIG` names a profile that does not exist or is broken
|
||||
- 1 An `--id` matching no tracker item right now
|
||||
- 1 A read-only access path (Super Productivity's `access: "snapshot"`)
|
||||
- 42 The tracker settings file of an earlier version is still there, or a secret source (1Password) needs unlocking
|
||||
|
||||
**ON FAILURE**
|
||||
|
||||
- No `.wikitool-tasks.json` - no tracker configured -> Not transient - configure a tracker first
|
||||
- `WIKITOOL_TASKS_CONFIG` names a file that does not exist or is broken -> Not transient - fix the path or unset the variable
|
||||
- No `tasks` section in the settings - no tracker configured -> Not transient - configure a tracker first
|
||||
- `WIKITOOL_TASKS_CONFIG` names a profile that does not exist or is broken -> Not transient - fix the path or unset the variable
|
||||
- An `--id` matching no tracker item right now -> Get a current id from `task list` or `review`, then retry once
|
||||
- A read-only access path (Super Productivity's `access: "snapshot"`) -> Point at the `access: "api"` instance the error names, then retry once
|
||||
- The tracker settings file of an earlier version is still there, or a secret source (1Password) needs unlocking -> Show the output to the user verbatim and stop - `tools/wikitool config migrate` or the unlock is theirs to run
|
||||
|
||||
**NEVER**
|
||||
|
||||
@@ -407,10 +414,10 @@ Mark one tracker item done - never delete it.
|
||||
|
||||
- Marks one tracker item done. It never deletes or moves an item - the only closing write this stack makes.
|
||||
- `--id` is the provider's own item id, from `task list` or a `review` finding - never a title.
|
||||
- The tracker configuration is read from `.wikitool-tasks.json`, or from the file `WIKITOOL_TASKS_CONFIG` names when that variable is set (so one checkout can be run against several trackers in turn). A set variable that names no file is an error, never "no tracker configured".
|
||||
- No `.wikitool-tasks.json` fails with a "no tracker configured" message.
|
||||
- The tracker configuration is read from the `tasks`, `superproductivity` and `caldav` sections of the settings, or from the profile `WIKITOOL_TASKS_CONFIG` names when that variable is set (so one checkout can be run against several trackers in turn). A set variable that names no file is an error, never "no tracker configured".
|
||||
- No `tasks` section fails with a "no tracker configured" message.
|
||||
- A provider whose configured access path has no write path (Super Productivity's `access: "snapshot"`) refuses entirely with exit 1, naming the `access: "api"` instance to use instead.
|
||||
- **Never exits 42.**
|
||||
- **Exits 42 only for the settings** (the tracker settings file of an earlier version, a locked secret source).
|
||||
|
||||
**SEE ALSO**
|
||||
|
||||
@@ -1245,15 +1252,17 @@ The GTD weekly review.
|
||||
**EXIT STATUS**
|
||||
|
||||
- 0 success
|
||||
- 1 No `.wikitool-tasks.json`, or a malformed one - a clear "no tracker configured" message
|
||||
- 1 `WIKITOOL_TASKS_CONFIG` names a file that does not exist or is broken
|
||||
- 1 No `tasks` section in the settings, or a malformed one - a clear "no tracker configured" message
|
||||
- 1 `WIKITOOL_TASKS_CONFIG` names a profile that does not exist or is broken
|
||||
- 1 The provider was reachable at config-parse time but a read call failed mid-run; the full report (findings plus which checks ran) was printed first
|
||||
- 42 The tracker settings file of an earlier version is still there, or a secret source (1Password) needs unlocking
|
||||
|
||||
**ON FAILURE**
|
||||
|
||||
- No `.wikitool-tasks.json`, or a malformed one - a clear "no tracker configured" message -> Not fixed by retrying unchanged - configure or repair `.wikitool-tasks.json` first
|
||||
- `WIKITOOL_TASKS_CONFIG` names a file that does not exist or is broken -> Not transient - fix the path or unset the variable
|
||||
- No `tasks` section in the settings, or a malformed one - a clear "no tracker configured" message -> Not fixed by retrying unchanged - configure or repair the `tasks`, `superproductivity` and `caldav` sections first
|
||||
- `WIKITOOL_TASKS_CONFIG` names a profile that does not exist or is broken -> Not transient - fix the path or unset the variable
|
||||
- The provider was reachable at config-parse time but a read call failed mid-run; the full report (findings plus which checks ran) was printed first -> Start the unreachable provider (e.g. the tracker app), then retry plainly
|
||||
- The tracker settings file of an earlier version is still there, or a secret source (1Password) needs unlocking -> Show the output to the user verbatim and stop - `tools/wikitool config migrate` or the unlock is theirs to run
|
||||
|
||||
**NEVER**
|
||||
|
||||
@@ -1269,7 +1278,8 @@ The GTD weekly review.
|
||||
- **someday-stale**: a someday/maybe item untouched for longer than `thresholds.someday_stale_months`.
|
||||
- A value a provider genuinely cannot supply - a `WAITING` item with no `follow_up_at`, a tracker project with no determinable creation date - is its own finding (`waiting_no_follow_up`/`project_age_unknown`) rather than a silent skip.
|
||||
- Thresholds come from the tracker configuration, never from the schema.
|
||||
- The tracker configuration is read from `.wikitool-tasks.json`, or from the file `WIKITOOL_TASKS_CONFIG` names when that variable is set (so one checkout can be run against several trackers in turn). A set variable that names no file is an error, never "no tracker configured".
|
||||
- The tracker configuration is read from the `tasks`, `superproductivity` and `caldav` sections of the settings, or from the profile `WIKITOOL_TASKS_CONFIG` names when that variable is set (so one checkout can be run against several trackers in turn). A set variable that names no file is an error, never "no tracker configured".
|
||||
- The tracker settings file of an earlier version exits 42 and names `tools/wikitool config migrate`; so does a secret source that needs unlocking.
|
||||
- Text output is one `[check] project: message` line per finding, preceded by a `Source:` line naming which access path answered and, for `superproductivity`'s `access: "snapshot"`, the snapshot's age. `--json` carries the same findings plus `checks_run`/`checks_skipped`/`kb_project_count`/`complete`/`source` (`{"kind": ..., "detail": ...}` or `null`).
|
||||
- A provider that cannot be reached mid-run degrades only the checks that needed the failing call; the report is printed in full, then exit 1 follows - never rendered as if it were complete.
|
||||
- Re-reads everything fresh on every call, so nothing is ever stale to re-fetch.
|
||||
@@ -1805,7 +1815,7 @@ List every MCP submission currently waiting in the quarantine (`mcp-upload/`).
|
||||
**NOTES**
|
||||
|
||||
- Lists every submission waiting in `mcp-upload/`, oldest id first: id, filename, size, submitter.
|
||||
- Only ever non-empty when `.wikitool-upload.json` opts the checkout into the MCP server's `submit` tool.
|
||||
- Only ever non-empty when the `upload` section of `.wikitool-local.json` opts the checkout into the MCP server's `submit` tool.
|
||||
- A submission directory with a corrupt manifest is silently skipped.
|
||||
- Never fails; read-only and safe to retry freely.
|
||||
|
||||
@@ -2038,10 +2048,11 @@ Reconcile with `<remote>/<branch>`, then stage all changes, commit, and push.
|
||||
- 1 The push target (`--branch`) is not the checked-out branch, or HEAD is detached; the unborn branch of a fresh `git init` is not this case
|
||||
- 1 No `--no-push`, and the remote is not configured or cannot be reached; nothing was committed
|
||||
- 1 `--yes`/`-y` was passed - the flag does not exist and fails with an explicit error
|
||||
- 1 `.wikitool-remotes.json` is unreadable or has no usable `allowed_push_urls` list
|
||||
- 1 The settings files do not pass their check, or `remotes.allowed_push_urls` is not a list of strings
|
||||
- 42 The remotes settings file of an earlier version is still there
|
||||
- 42 Mass-Update Gate: `--threshold` (default 10) or more counted files would be committed, or the `--confirm` token does not match this changeset
|
||||
- 42 Rebase-Review Gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff
|
||||
- 42 Publish-Remote Gate: `.wikitool-remotes.json` exists and the push URL of `--remote` is not listed in it, or `--remote` resolves to no push URL
|
||||
- 42 Publish-Remote Gate: `remotes.allowed_push_urls` is set and the push URL of `--remote` is not listed in it, or `--remote` resolves to no push URL
|
||||
|
||||
**ON FAILURE**
|
||||
|
||||
@@ -2049,16 +2060,17 @@ Reconcile with `<remote>/<branch>`, then stage all changes, commit, and push.
|
||||
- The push target (`--branch`) is not the checked-out branch, or HEAD is detached; the unborn branch of a fresh `git init` is not this case -> Check out the branch you mean to publish, or pass `--branch <checked-out branch>`, then retry once
|
||||
- No `--no-push`, and the remote is not configured or cannot be reached; nothing was committed -> Show the message to the user and ask whether to commit locally with `--no-push`. Never push by hand - the next `publish` that reaches the remote sends that commit
|
||||
- `--yes`/`-y` was passed - the flag does not exist and fails with an explicit error -> Drop it. The Mass-Update Gate is cleared only with `--confirm <token>` from the gate's own refusal output
|
||||
- `.wikitool-remotes.json` is unreadable or has no usable `allowed_push_urls` list -> Show the error to the user and stop - a malformed file is not permission, and fixing or deleting it is theirs to do
|
||||
- The settings files do not pass their check, or `remotes.allowed_push_urls` is not a list of strings -> Show the error to the user and stop - a malformed section is not permission, and fixing it is theirs to do
|
||||
- The remotes settings file of an earlier version is still there -> Show the output to the user verbatim and stop; `tools/wikitool config migrate` moves it, and the user decides when
|
||||
- Mass-Update Gate: `--threshold` (default 10) or more counted files would be committed, or the `--confirm` token does not match this changeset -> Show the user the command's full output verbatim and stop. Once they have approved it, run the re-run line the output prints, which carries `--confirm <token>`. Without that token, or with a wrong, invented or superseded one, it exits 42 again with the current state
|
||||
- Rebase-Review Gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff -> Show the user the command's full output verbatim and stop. Once they have approved it, run the re-run line the output prints, which carries `--confirm-rebase <token>`. Without that token, or with a wrong, invented or superseded one, it exits 42 again with the current state
|
||||
- Publish-Remote Gate: `.wikitool-remotes.json` exists and the push URL of `--remote` is not listed in it, or `--remote` resolves to no push URL -> Show the user the push URL it names and the allowed ones, and stop. This gate has no token and no flag: only the user resolves it, by adding the URL to that file
|
||||
- Publish-Remote Gate: `remotes.allowed_push_urls` is set and the push URL of `--remote` is not listed in it, or `--remote` resolves to no push URL -> Show the user the push URL it names and the allowed ones, and stop. This gate has no token and no flag: only the user resolves it, by adding the URL to `.wikitool-local.json`
|
||||
|
||||
**NEVER**
|
||||
|
||||
- Never retry a failed git step unchanged, and never force (`--force`, `--force-with-lease`).
|
||||
- Never pass a `--confirm` or `--confirm-rebase` token the user has not seen and approved.
|
||||
- Never edit `.wikitool-remotes.json` to get past a Publish-Remote refusal - that is opening a gate on your own initiative.
|
||||
- Never edit `remotes.allowed_push_urls` to get past a Publish-Remote refusal - that is opening a gate on your own initiative.
|
||||
|
||||
**NOTES**
|
||||
|
||||
@@ -2073,7 +2085,8 @@ Reconcile with `<remote>/<branch>`, then stage all changes, commit, and push.
|
||||
- Mass-Update Gate: counts the files that would be committed, refuses with exit 42 at `--threshold` (default 10) or more, and prints a review report - a scale line (file count, total lines added/removed, status breakdown), attention notes where they apply (deletions by name, control-plane and harness-config touches, published pages, the largest single change, binaries), and every counted path grouped by area with its status and churn. The list is what the commit will hold: it is computed from a scratch copy of the index after `git add -A`, so a path that is staged as deleted and back in the working tree is not counted twice, and a rename counts as its old path deleted plus its new path added. The real index and the working tree are not touched, so a refused publish leaves both byte-identical.
|
||||
- Never counted and never shown for approval, but committed like everything else: anything under `work/`, and the files `wikitool` generates itself (`kb/index.md`, `kb/log.md`, `kb/provenance.md`, every `INDEX.md` under `kb/`). The refusal line accounts for both, by reason.
|
||||
- The `--confirm` token covers each counted path, the blob id of its contents and the publish target: a different file list or edited contents need a new clearance.
|
||||
- Publish-Remote Gate: when the checkout carries `.wikitool-remotes.json` and the push URL of `--remote` is not listed in it, exits 42 before the reconcile fetches anything. The URL is read with `git remote get-url --push`, so a repointed remote does not pass on its name. An absent file means unrestricted; a malformed one is an error, not permission.
|
||||
- Publish-Remote Gate: when `.wikitool-local.json` carries `remotes.allowed_push_urls` and the push URL of `--remote` is not listed in it, exits 42 before the reconcile fetches anything. The URL is read with `git remote get-url --push`, so a repointed remote does not pass on its name. An absent section means unrestricted; a malformed one is an error, not permission.
|
||||
- The remotes settings file of an earlier version is not read: while it exists this exits 42 and names `tools/wikitool config migrate`, so a restriction is never lost silently.
|
||||
- `--path` (repeatable) scopes the whole operation - gate count, staging and commit - to that subtree, with one exception: uncommitted generated files outside `--path` (`kb/index.md`, `kb/log.md`, `kb/provenance.md`, every `INDEX.md` under `kb/`) are staged and committed too, and a line names them - whether a reconcile or the change itself wrote them. They stay out of the gate count, and the `--confirm` token and the re-run line cover the `--path` given. Every other file outside `--path` is left as it is.
|
||||
- Commit message: `--message`, then a `Files changed:` paragraph listing every committed path. When `--message` ends in a paragraph git reads as a trailer block (`Co-Authored-By:` and the like), that block stays the last paragraph and the list goes in front of it, since git reads trailers from the last paragraph only. `git interpret-trailers` decides whether there is such a block, and the list moves only when git reads the same trailers from the result; otherwise it is appended at the end. `--message` is not part of any gate token.
|
||||
- After a successful commit or push whose changed files include `tools/`, `types/`, `instructions/`, `AGENTS.md` or a path ending in `CONTRACT.md`, prints one reminder line: the phase past this point (an issue-body rewrite, `docs/` staleness, a changelog entry's accuracy) is not covered by `docs verify`, `instructions verify` or `pytest`. It is not a gate: no exit code change, nothing to clear, and silent for an ordinary content publish.
|
||||
@@ -3684,9 +3697,9 @@ Set one value of the tiered settings, in the file its tier names.
|
||||
|
||||
**EXAMPLES**
|
||||
|
||||
- `tools/wikitool config set tracker.stale_days 14`
|
||||
- `tools/wikitool config set tracker.token --ref tracker_token`
|
||||
- `tools/wikitool config set tracker.url --ref op://Chemenu/tracker/url`
|
||||
- `tools/wikitool config set tasks.stalled_waiting_days 14`
|
||||
- `tools/wikitool config set caldav.app_password --ref caldav_app_password`
|
||||
- `tools/wikitool config set caldav.username --ref op://Chemenu/caldav/username`
|
||||
|
||||
**EXIT STATUS**
|
||||
|
||||
@@ -3725,6 +3738,55 @@ Set one value of the tiered settings, in the file its tier names.
|
||||
- `docs/reference/configuration.md` - the files, the tiers and the references
|
||||
- `docs/how-to/use-1password-for-settings.md` - setting 1Password up as the source
|
||||
|
||||
#### `config migrate`
|
||||
|
||||
Move the settings out of the per-feature files of earlier versions into the tiered settings.
|
||||
|
||||
**SYNOPSIS**
|
||||
|
||||
- `wikitool config migrate`
|
||||
|
||||
**PROPERTIES**
|
||||
|
||||
- effect: write
|
||||
- idempotent: yes
|
||||
- atomic: Everything is computed and checked in memory first; the secrets file, `wikitool.json` and `.wikitool-local.json` are each replaced in one rename, read back and checked, and only then are the old files removed. Any failure before that puts every target back to the bytes it had and leaves the old files as they were
|
||||
- budget: counted
|
||||
- network: no
|
||||
|
||||
**EXAMPLES**
|
||||
|
||||
- `tools/wikitool config migrate`
|
||||
|
||||
**EXIT STATUS**
|
||||
|
||||
- 0 success
|
||||
- 1 An old file does not pass the check the new section applies, a target key holds a different value, or the files would not pass their check afterwards
|
||||
|
||||
**ON FAILURE**
|
||||
|
||||
- An old file does not pass the check the new section applies, a target key holds a different value, or the files would not pass their check afterwards -> Nothing was changed. Fix the problem the message names, then re-run once
|
||||
|
||||
**NEVER**
|
||||
|
||||
- Never read the secrets file or an old file yourself to see a value.
|
||||
- Never delete an old file by hand to make a leftover message go away - the move is what carries its settings over.
|
||||
|
||||
**NOTES**
|
||||
|
||||
- Moves the four per-feature settings files of earlier versions - telemetry, remotes, upload and the task tracker, each named in the migration document - into the sections `telemetry`, `remotes`, `upload`, and `tasks`, `superproductivity` and `caldav`: each value into the file its field's tier names, a secret's value into the secrets file with only a reference in `wikitool.json`.
|
||||
- Every setting keeps its effective value, defaults included: the old content is read with the same checks the new sections use, and a field the old file did not set is not written.
|
||||
- Run once per checkout, since the old files and `.wikitool-local.json` belong to one checkout. `.wikitool-tools.json` stays as it is.
|
||||
- Prints each key and the file it went to, plus anything the old file held that was not read before and is not carried over - never a value.
|
||||
- A second run, or a run with no old file, prints that there is nothing to move and changes no file.
|
||||
- A key the target files already hold with a different value stops the move before anything is written: decide which one stands, remove the other, run again.
|
||||
|
||||
**SEE ALSO**
|
||||
|
||||
- `wikitool doctor` - reports every leftover old file as a `FAIL`
|
||||
- `docs/reference/configuration.md` - the sections the files became
|
||||
- `instructions/migrations/10.0.0-settings-tiers.md` - the migration this command belongs to
|
||||
|
||||
### Instance health
|
||||
|
||||
#### `doctor`
|
||||
@@ -3767,13 +3829,14 @@ Check that this instance is correctly configured.
|
||||
- Personalization: `USER.md`/`SOUL.md` present **and** filled - a file still carrying the template's sentinel is a `FAIL`.
|
||||
- KB conventions: `kb/CONVENTIONS.md` present, unsentinelled, and naming all three tool-owned section headings - a `FAIL` on any of the three.
|
||||
- Environment note: `ENVIRONMENT.md` is optional, so absent is `OK`; a still-templated one is a `WARN`.
|
||||
- MCP `submit` tool: whether `.wikitool-upload.json` is present, absent or malformed, its limits, and how many submissions wait in `mcp-upload/`. Absent is `OK` and means the write path does not exist at all; malformed is a `FAIL`.
|
||||
- Task tracker: `.wikitool-tasks.json` present, absent or malformed - absent is `OK` (no tracker configured), malformed is a `FAIL`. When `WIKITOOL_TASKS_CONFIG` is set, that file is read instead and the finding names it; a set variable that names no file is a `FAIL`, never `OK`.
|
||||
- Legacy settings (`legacy-settings`): one `FAIL` for each per-feature settings file of an earlier version (telemetry, remotes, upload, task tracker) that is still there. Nothing reads them any more, so the settings they hold are not in effect; the fix is `tools/wikitool config migrate`.
|
||||
- MCP `submit` tool: whether the `upload` section of the settings is present, absent or malformed, its limits, and how many submissions wait in `mcp-upload/`. Absent is `OK` and means the write path does not exist at all; malformed is a `FAIL`.
|
||||
- Task tracker: the `tasks` section present, absent or malformed - absent is `OK` (no tracker configured), malformed is a `FAIL`. When `WIKITOOL_TASKS_CONFIG` is set, the profile it names is read instead of the `tasks`, `superproductivity` and `caldav` sections and the finding names it; a set variable that names no file is a `FAIL`, never `OK`.
|
||||
- For a configured `superproductivity` provider, the configured `access` path's own state: `access: "api"` reports whether its local REST API answers `GET /health` with a ready renderer right now, `access: "snapshot"` whether a backup file is ready. The other access path is never attempted, and neither state is ever a `FAIL`.
|
||||
- For a configured `caldav` provider, whether the server is reachable and Basic auth succeeds - never a `FAIL`; only a broken config block is.
|
||||
- Settings (`settings-instance`, `settings-checkout`, `settings-secrets`): one line per tier. `wikitool.json` and `.wikitool-local.json` each present or absent - absent is `OK` - and a `FAIL` naming file, key and the right tier when a value sits in the wrong file, a secret or a committed private field holds a plain value, or a value fails its field; a section this version does not read is a `WARN`. For the references: how many resolve, never a value - an unresolvable one is a `FAIL`, one 1Password will not hand out until a human unlocks it a `WARN`.
|
||||
- Session id source: `OK` for `WIKITOOL_SESSION_ID` or a registered harness variable, `WARN` only for the bare parent-pid fallback.
|
||||
- Telemetry: on or off and why - installation-form default, `.wikitool-telemetry.json`, or `WIKI_TRACE` - and the current session's count and byte total against both caps; never a `FAIL`. A `WARN` when `.wikitool-telemetry.json` is not read as written - unreadable JSON, not an object, `enabled` not a JSON boolean, a cap not a positive integer, or an unknown key - naming the field; telemetry itself drops or reinterprets such a value without a word, so this is where it shows.
|
||||
- Telemetry: on or off and why - installation-form default, the `telemetry` section of `.wikitool-local.json`, or `WIKI_TRACE` - and the current session's count and byte total against both caps; never a `FAIL`. A `WARN` when that section is not read as written - unreadable JSON, not an object, `enabled` not a JSON boolean, a cap not a positive integer, or an unknown key - naming the field; telemetry itself drops or reinterprets such a value without a word, so this is where it shows.
|
||||
- Exits 1 only on a `FAIL`; a missing remote, session id or `VERSION` is a `WARN`, not a fault.
|
||||
- Read-only and exempt from the Iteration Budget Gate.
|
||||
|
||||
@@ -3812,7 +3875,7 @@ Check that this instance is correctly configured.
|
||||
`commands/` is importable from the server, so `new`/`touch`/`xref`/`cite`/
|
||||
`publish`/`migrate` are unreachable rather than filtered - and every
|
||||
response carries the commit it was computed from. The one exception is
|
||||
`submit` (opt-in via `.wikitool-upload.json` - absent means the
|
||||
`submit` (opt-in via the `upload` section of `.wikitool-local.json` - absent means the
|
||||
tool is not registered at all): the server may write, but by a **positive
|
||||
list** rather than an absence - `chemenu.upload._write_atomic_within`
|
||||
resolves every target and refuses anything outside `mcp-upload/`, the one
|
||||
|
||||
Reference in new issue
Block a user