@journeykit/canon 0.38.0 → 0.39.0

package/man/canon-subject-unadopt.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-subject-unadopt 1  "unadopt 0.38.0" 
+.TH canon-subject-unadopt 1  "unadopt 0.39.0" 
 .SH NAME
 canon\-subject\-unadopt \- Take a change back out of a subject (the mirror of adopt; refused for a change whose brief is approved)
 .SH SYNOPSIS
@@ -60,4 +60,4 @@ change whose brief carries an `Approved:` line: it is the subject\*(Aqs approved
 scope, and for a change a scenario the subject owns is tagged
 `@flow:<change>.*` for (remove or retag it first). A pair that is not linked writes nothing and exits 0.
 .SH VERSION
-v0.38.0
+v0.39.0

package/man/canon-subject.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-subject 1  "subject 0.38.0" 
+.TH canon-subject 1  "subject 0.39.0" 
 .SH NAME
 canon\-subject \- Create and manage subjects (durable product units)
 .SH SYNOPSIS
@@ -48,4 +48,4 @@ Show a subject (read\-only)
 canon\-subject\-move(1)
 Move a subject to another lifecycle state (shipping is evidence\-gated; with spec_coverage.require_review, entering its scope is review\-gated; shipped → verifying reopens with \-\-reason)
 .SH VERSION
-v0.38.0
+v0.39.0

package/man/canon-task-done.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-task-done 1  "done 0.38.0" 
+.TH canon-task-done 1  "done 0.39.0" 
 .SH NAME
 canon\-task\-done \- Flip one task checkbox, gated on real evidence (fails closed)
 .SH SYNOPSIS
@@ -44,4 +44,4 @@ Print version
 <\fITASK_ID\fR>
 The task id (<change_id>#<n>)
 .SH VERSION
-v0.38.0
+v0.39.0

package/man/canon-task.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-task 1  "task 0.38.0" 
+.TH canon-task 1  "task 0.39.0" 
 .SH NAME
 canon\-task \- Flip a plan task\*(Aqs checkbox once committed evidence supports it
 .SH SYNOPSIS
@@ -39,4 +39,4 @@ Flip one task checkbox, gated on real evidence (fails closed)
 Examples:
   canon task done my\-change#3
 .SH VERSION
-v0.38.0
+v0.39.0

package/man/canon-tier-age.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-tier-age 1  "age 0.38.0" 
+.TH canon-tier-age 1  "age 0.39.0" 
 .SH NAME
 canon\-tier\-age \- Apply canon.yaml aging rules, moving old records to their destination tier
 .SH SYNOPSIS
@@ -47,4 +47,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.38.0
+v0.39.0

package/man/canon-tier.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-tier 1  "tier 0.38.0" 
+.TH canon-tier 1  "tier 0.39.0" 
 .SH NAME
 canon\-tier \- Age records between storage tiers
 .SH SYNOPSIS
@@ -36,4 +36,4 @@ Print version
 canon\-tier\-age(1)
 Apply canon.yaml aging rules, moving old records to their destination tier
 .SH VERSION
-v0.38.0
+v0.39.0

package/man/canon-trace.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-trace 1  "trace 0.38.0" 
+.TH canon-trace 1  "trace 0.39.0" 
 .SH NAME
 canon\-trace \- Follow a finding\*(Aqs review loop in time order: review, finding, fix, re\-review, evidence
 .SH SYNOPSIS
@@ -53,4 +53,4 @@ the ledger archive\*(Aqs old versions included, oldest first. Reads the same der
 `canon search`. Exit 2 for an id no record says, an ambiguous sha prefix or an operand of none
 of the three shapes.
 .SH VERSION
-v0.38.0
+v0.39.0

package/man/canon.1

@@ -1,12 +1,12 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon 1  "canon 0.38.0" 
+.TH canon 1  "canon 0.39.0" 
 .SH NAME
 canon \- Specs, evidence gates, and agent memory for your repo
 .SH SYNOPSIS
 \fBcanon\fR [\fB\-\-as\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fIsubcommands\fR>
 .SH DESCRIPTION
-canon keeps a repo\*(Aqs specs, review evidence, and agent strategy memory in one place: author .feature specs, task done completion on real evidence, ingest agent sessions, and retrieve role\-scoped guidance.
+canon keeps a repo\*(Aqs specs, review evidence, and agent strategy memory in one place: author .feature specs, task done completion on real evidence, ingest plans and records, and retrieve role\-scoped guidance.
 .SH OPTIONS
 .TP
 \fB\-\-as\fR \fI<ROLE>\fR
@@ -103,7 +103,7 @@ canon\-divergence(1)
 Stage, promote, resolve, and inspect spec divergences
 .TP
 canon\-ingest(1)
-Import agent sessions, records, and plans into canon\*(Aqs store
+Import records and plans into canon\*(Aqs store
 .TP
 canon\-retrieve(1)
 Fetch role\-scoped strategy guidance
@@ -172,4 +172,4 @@ Learn more:
   plus the script sidecar; `skills check` and `skills doctor` inspect the
   target without deleting user files.
 .SH VERSION
-v0.38.0
+v0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@journeykit/canon",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "canon — harness knowledge substrate. JS launcher: platform detection + native binary resolution.",
   "license": "MIT",
   "type": "module",
@@ -34,9 +34,9 @@
   },
   "dependencies": {},
   "optionalDependencies": {
-    "@journeykit/canon-core-darwin-arm64": "0.38.0",
-    "@journeykit/canon-core-linux-x64": "0.38.0",
-    "@journeykit/canon-core-win32-x64": "0.38.0"
+    "@journeykit/canon-core-darwin-arm64": "0.39.0",
+    "@journeykit/canon-core-linux-x64": "0.39.0",
+    "@journeykit/canon-core-win32-x64": "0.39.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/dist/skills/reference/canon-session-ingest.md

@@ -1,224 +0,0 @@
-# canon-session-ingest
-
-`canon ingest sessions` turns every agent CLI's on-disk transcript store
-into `Session`/`Run`/`Event` records on canon's join spine, scanning four
-adapters, normalizing, and persisting through the same tier resolution
-`canon query` / `canon tier age` use. The default corpus is scoped to the
-current PROJECT; the watermark gate is per-file; user directives are
-metadata-only unless explicitly opted in by bounded privacy config.
-
-**Quick start needs zero docker/services.** `canon init` scaffolds `hot`
-as a local sqlite file (`.canon/hot.db`) with `session`/`run`/`event`
-already routed to it — a fresh repo's FIRST `canon ingest sessions`
-persists real records with no `docker compose` stack, no `CANON_PG_DSN`,
-no live database. Swap `hot` to postgres (the commented stanza `canon
-init` ships beside the sqlite one) once team-scale multi-agent
-concurrency outgrows sqlite's single-writer mode.
-
-## `canon ingest sessions [--watch] [--interval-secs N] [--home <dir>] [--full] [--all-workspaces]`
-
-```bash
-# one pass over this project's sources
-canon ingest sessions
-# poll every 30s (see --interval-secs)
-canon ingest sessions --watch
-# ignore the watermark; re-parse every in-scope file
-canon ingest sessions --full
-# machine-wide scan
-canon ingest sessions --all-workspaces
-# override the scan-root home ($HOME)
-canon ingest sessions --home /custom
-```
-
-**Done when:** the run summary (below) ends with `malformed records … : 0`
-and `canon query --kind session` lists the sessions; a rerun reports the
-files as `skipped unchanged (watermark)` and writes nothing.
-
-## The four adapters
-
-Registered in order: **`omp`** (omp/pi sessions), **`hermes`**,
-**`claude`** (`~/.claude/projects/**/*.jsonl`), **`codex`**
-(`${CODEX_HOME:-~/.codex}/sessions/` unioned with `archived_sessions/`).
-Each resolves its default root and honors an env override
-(`CANON_INGEST_OMP_SESSIONS_DIR`, `CANON_INGEST_CLAUDE_SESSIONS_DIR`,
-`CODEX_HOME`, `HERMES_HOME`). An absent source root is a zero-record,
-non-fatal skip.
-
-### Per-source root overrides (`canon.yaml`)
-
-```yaml
-ingest:
-  sources:
-    omp:
-      roots: [/data/omp-sessions]   # relative paths resolve against the canon.yaml dir
-    codex:
-      roots: []                      # explicit empty = scan ZERO (not the default)
-```
-
-A source with a **present** `roots` scans exactly those (explicit
-`roots: []` scans nothing); a source whose key or `roots` is **absent**
-keeps its env-override + default resolution. Unlike artifacts (where
-unconfigured = no scan), sessions default to their home roots when
-unconfigured. A PRESENT but broken `ingest:` section fails **loud** (a
-typo like `root:` for `roots:`, an unknown source id, or a non-YAML
-canon.yaml) rather than silently scanning the wrong corpus; a
-missing/unreadable canon.yaml stays a soft no-config.
-
-## Project scope — the default corpus
-
-`canon ingest sessions` defaults to THIS PROJECT's sessions, never the
-whole machine: the repo's main `git worktree` root plus every linked
-worktree (`git worktree list --porcelain`). Outside a git repo, the scope
-fails soft to the repo root alone.
-
-- **omp/pi and Claude Code are cwd-partitioned on disk** — one
-  subdirectory per project. Out-of-scope subdirectories are pruned at
-  enumerate time — never read or counted.
-- **Codex and Hermes are not partitioned** — rows are filtered
-  post-parse by workspace membership; a row with no captured workspace is
-  kept, fail-soft.
-- **`--all-workspaces`** restores the machine-wide scan. Scope is still
-  resolved (so `project_key` stamping stays correct); only the
-  pruning/filtering are disabled.
-- Every ingested session whose workspace resolves into the active project
-  gets `project_key` stamped to the MAIN worktree's key, so `canon query
-  --kind session` aggregates a whole project's sessions regardless of
-  which worktree recorded them.
-- The run summary's first line always names the active scope:
-  `scope: project /repo/root (2 roots)` or `scope: all workspaces`.
-
-### Provenance, digests, and parser generations
-
-The parser semantics are compared against Tokscale upstream at
-https://github.com/junhoyeo/tokscale (revision
-`fe72e1f9b5a2b1a927108b353a9730a5c631a196`); the cache-accounting comparison
-reference is commit
-[`2cd6c648df026fb43d37e492efa9c344e2d681ee`](https://github.com/junhoyeo/tokscale/commit/2cd6c648df026fb43d37e492efa9c344e2d681ee).
-Canon ports the selected parser semantics, including Claude's nested
-cache-write buckets, but does **not** vendor Tokscale's pricing or cache
-service.
-
-Three identities are intentionally distinct:
-
-* the raw file SHA-256 watermark identifies unchanged transcript bytes;
-* the normalized content digest is canonical JSON over the complete
-  normalized event and changes when normalized token detail changes; and
-* the parse-generation cursor identity combines adapter id and parse version,
-  forcing a re-read when parser semantics change even if raw bytes do not.
-
-## The watermark — per-file, incremental `--watch`
-
-Each pass content-digests every present (post-pruning) file and diffs it
-against its source's persisted cursor (under
-`<repo>/.canon/ingest/cursors/`, gitignored), written after a durable
-pass. A file whose digest matches its cursor is SKIPPED — never parsed; a
-new or changed file is (re-)parsed. One session derives from exactly one
-file, so a single growing transcript re-parses alone instead of dragging
-the whole source back through parse/persist.
-
-- The gate is sound: a file is skipped only when its digest matches the
-  cursor, so a new, changed, copied, or restored file is always
-  re-scanned.
-- Correctness never depends on the cursor: a missing/corrupt cursor
-  treats every present file as new, and the digest-idempotent write path
-  keeps any rescan from double-writing.
-- A cursor's identity carries its adapter's PARSE VERSION as well as its
-  files, so changing an adapter's normalization re-reads that adapter's
-  transcripts instead of reporting them unchanged — no `--full`, no
-  cursor deletion. Version `1` IS the bare `client_id` (`omp.json`), so a
-  cursor already on disk is never invalidated just by installing the
-  mechanism; a bump appends the suffix (`claude-code-v3.json`) and that
-  `omp` is at `2` because the logical adapter now deduplicates forks
-  across files; `hermes` remains at `1`; `codex` is at `2` because its
-  reasoning-token accounting is split; and `claude-code` is at `3` because
-  cache accounting now recognizes `cache_write_1h` buckets. Each changed
-  adapter re-reads once to backfill the normalization change that the old
-  watermark would otherwise hide.
-
-**`--full`** ignores the cursors and re-parses every present in-scope
-file (a full rescan / cursor reset) — safe because a byte-identical
-resubmission is a no-op; cursors re-advance afterward.
-
-## User directives
-
-Every adapter (except Hermes, whose format carries no user-turn text)
-emits one parsed `DirectiveRow` per USER-role message. Parsing retains
-source text only in memory; the shared post-adapter privacy boundary
-controls whether it becomes a durable event. The default when
-`ingest.sessions.privacy` is absent is metadata-only: no
-`user_directive` event reaches normalized output.
-
-Repositories that explicitly opt in MUST set a positive bound:
-
-```yaml
-ingest:
-  sessions:
-    privacy:
-      capture_user_directives: true
-      max_directive_chars: 4096
-```
-
-Captured text is classified and redacted BEFORE the Unicode-scalar capture
-bound is applied. The conservative classifier replaces known API
-key/token/password assignments, bearer credentials, PEM private keys, and
-email addresses with deterministic `[REDACTED_SECRET_N]` /
-`[REDACTED_PII_N]` placeholders and includes `redaction_counts`. The
-detail's `redacted` is true only when a known value was replaced;
-`truncated` is independent and may be true for otherwise unredacted text.
-This classifier is not a guarantee against every kind of secret or PII.
-`workspace_key`/`workspace_label` remain metadata. The source transcript
-remains the source of truth and is not rewritten, purged, or replaced by
-Canon's normalized event.
-
-The source cursor identity includes the privacy mode and positive bound, so
-toggling capture or changing its bound re-scans unchanged source bytes.
-Re-scans retain stable event sequence/key ordinals; they do not purge
-previously stored normalized records. Operators owning pre-existing raw
-data MUST handle purge/migration separately.
-
-These events interleave with `token_usage` events in one deterministic
-order (directive-before-token on a timestamp tie). Query them with:
-
-```bash
-# filter detail.label == "user_directive"
-canon query --kind event
-```
-
-## Reading the run summary
-
-Each pass prints the active scope, one line per adapter, then totals:
-
-```
-scope: project /path/to/repo (2 roots)
-omp: 3 file(s) scanned, 1 reparsed, 2 skipped unchanged (watermark), 4 row(s) parsed, 0 malformed record(s)
-claude-code: 1 file(s) scanned, 0 reparsed, 1 skipped unchanged (watermark), 0 row(s) parsed, 0 malformed record(s)
-sessions normalized: 4
-malformed records (corrupt line/db, counted as violations): 0
-rows skipped (malformed session_id): 0
-runs written: 4
-events written: 37
-```
-
-- **scope** — the active project scope (`--all-workspaces` names it).
-- **file(s) scanned** — every present file this source matched, after
-  pruning, before the per-file gate.
-- **reparsed** — the subset actually (re-)parsed this pass (`0` on a
-  steady-state pass).
-- **skipped unchanged (watermark)** — files skipped because that file's
-  digest was byte-identical to its cursor entry.
-- **malformed records** — corrupt lines / dbs an adapter hit but could
-  not extract a row from (counted as a violation, never crashing).
-- **store tiers unreachable** — if `canon.yaml`'s tiers aren't reachable
-  (e.g. `tiers.pg` set but `CANON_PG_DSN` unset) or `session`/`run`/
-  `event` aren't routed, the pass prints a metadata-only JSON fallback
-  instead of persisting — never a partial write. The fallback contains
-  scope, adapter counts, record counts, IDs/digests, and a stable
-  routing/tier failure class/reason; it never contains directive text,
-  task/context prose, or raw event detail.
-
-## What this skill does NOT cover
-
-- Artifact/verdict ingestion (`canon ingest records`) — a different
-  pipeline; see the `canon-artifact-ingest` skill.
-- Cost-parity computation — omp/pi's own cost is `0.0`/`Unknown` per the
-  ported behavior.

package/man/canon-ingest-sessions.1

@@ -1,62 +0,0 @@
-.ie \n(.g .ds Aq \(aq
-.el .ds Aq '
-.TH canon-ingest-sessions 1  "sessions 0.38.0" 
-.SH NAME
-canon\-ingest\-sessions \- Import agent CLI session transcripts (omp/pi, Claude Code, Codex, Hermes)
-.SH SYNOPSIS
-\fBcanon ingest sessions\fR [\fB\-\-as\fR] [\fB\-\-watch\fR] [\fB\-\-interval\-secs\fR] [\fB\-\-home\fR] [\fB\-\-repo\fR] [\fB\-\-full\fR] [\fB\-\-all\-workspaces\fR] [\fB\-\-dry\-run\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
-.SH DESCRIPTION
-Import agent CLI session transcripts (omp/pi, Claude Code, Codex, Hermes)
-.SH OPTIONS
-.TP
-\fB\-\-as\fR \fI<ROLE>\fR
-The role you act as: planner, implementer, reviewer or orchestrator. Overrides `CANON_ROLE`. `schema` and `context` list only the role\*(Aqs commands, `status` keeps its steps, and `\-\-role` on `evidence add` / `evidence audit` / `review scenario` / `review change` is this role unless given
-.br
-
-.br
-\fIPossible values:\fR
-.RS 14
-.IP \(bu 2
-planner
-.IP \(bu 2
-implementer
-.IP \(bu 2
-reviewer
-.IP \(bu 2
-orchestrator
-.RE
-.TP
-\fB\-\-watch\fR
-Keep polling instead of exiting after one pass
-.TP
-\fB\-\-interval\-secs\fR \fI<N>\fR [default: 30]
-Seconds between polls
-.TP
-\fB\-\-home\fR \fI<DIR>\fR
-The scan root\*(Aqs home directory (defaults to $HOME)
-.TP
-\fB\-\-repo\fR \fI<DIR>\fR
-The repo to act on (default: the nearest ancestor directory holding a canon.yaml)
-.TP
-\fB\-\-full\fR
-Ignore watermark cursors and re\-parse every in\-scope file
-.TP
-\fB\-\-all\-workspaces\fR
-Scan every workspace on this machine, not just this project
-.TP
-\fB\-\-dry\-run\fR
-Validate fully and report what would be written, without writing anything
-.TP
-\fB\-\-json\fR
-Output JSON instead of the human\-readable form
-.TP
-\fB\-\-input\fR \fI<JSON|FILE|\->\fR
-The arguments as JSON: an object (one run) or an array / NDJSON file or `\-` (a batch); keys are the option names in camelCase, `operands` an array
-.TP
-\fB\-h\fR, \fB\-\-help\fR
-Print help
-.TP
-\fB\-V\fR, \fB\-\-version\fR
-Print version
-.SH VERSION
-v0.38.0