@plinth-music/cli 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,136 @@
+# Changelog
+
+Notable changes to `@plinth-music/cli`. Grouped by what a user notices, not by PR.
+
+## 0.5.0 — 2026-08-14
+
+Seven PRs since `0.4.0` (`v0.4.0..846b996`). Three new commands, and the generated
+context an agent reads at session start stops making claims that were not true.
+
+### Three new commands
+
+- **`plinth backlinks <entity>`** — answers "what points at this?" from the terminal,
+  and says what it left out rather than returning a confident partial answer. Resolves
+  by slug **and** display name: the corpus links artists as `[[Tors]]`, not
+  `[[tors]]`, so a slug-only resolver would have answered for the name nobody types.
+  An ambiguous query returns both candidates and says why the first is first.
+- **`plinth declare`** — lets an agent declare a work product, so the cockpit panel has
+  something to render instead of inferring it.
+- **`plinth review-tier`** — computes the code-review tier from the diff rather than
+  from whatever the operator remembered.
+
+### The generated workspace map stops lying
+
+The map is injected into every agent session in a workspace, so a false line there
+produces confident wrong answers rather than a visible failure. It now **names
+`files/`** — contract lookups had been routed to `documents/`, which holds 31 notes,
+while `files/` holds 193 documents including every executed agreement. The three
+**render-only regions** (`## Contacts`, `## Recent activity`, `## Tasks`) now say so
+at render time, having silently discarded edits across 182 mirror files. And the
+`claude plugin add plinth-ai` line is gone; it pointed at a package that exists in no
+registry and no repo.
+
+### Over-cap files fail loudly instead of vanishing
+
+A file too large to sync was dropped while `plinth status` reported "No writes
+rejected". Over-cap now routes into `rejected` in `state.json`, so `status` reports it.
+
+⚠️ **Behaviour change, worth reading before upgrading.** The client size ceiling drops
+from 25 MiB to the largest size measured to succeed against the platform. **Files
+between roughly 4 MB and 25 MiB that previously appeared to sync are now refused,
+loudly.** They were not arriving before either — the platform rejected them ahead of
+the route, and the log printed the client's own constant as though it had caused the
+rejection. The number is now the measured platform ceiling, labelled as the platform's
+rather than Plinth's. **This path has not been exercised against production; the
+measurement is inherited from 12 August.**
+
+### Also
+
+- Memory indexes state their own age, so silence stops reading like settledness.
+- The grounding block tells an agent that other MCP servers may exist, and how to find
+  out.
+
+## 0.4.0 — 2026-08-06
+
+56 commits of product work since `0.3.0` (`v0.3.0..8c921e4`). `0.3.0` shipped four
+commands — `login`, `sync`, `start`, `version` — and synced a single entity type,
+documents. This release is most of a working daemon.
+
+### Five new commands
+
+- **`plinth status`** — daemon liveness, last sync and per-type counts, and how many
+  destructive batches are being held. Also warns when `dist/` is behind the checkout,
+  so a stale bundle can't be mistaken for the merged code (source-install only; a
+  registry install has no checkout to compare against and stays silent).
+- **`plinth confirm`** — review and release the destructive batches the daemon
+  quarantines. Apply, or `--discard`. `--all` is gated behind rendering every batch
+  first and a final default-No.
+- **`plinth refresh-context`** — regenerate the workspace-root `CLAUDE.md` from the
+  current schema and workspace. Your block between the `<!-- BEGIN: user-customisable -->`
+  markers is preserved verbatim; `CLAUDE.local.md` is never touched.
+- **`plinth grounding`** — print the session-start grounding block (current date,
+  entity resolution, write confirmation, workspace rules, workspace memory, user
+  memory). Invoked by the generated Claude Code SessionStart hook.
+- **`plinth voice-gate`** — gate agent-originated copy against the workspace voice
+  rubric. `--hook` runs it as a Claude Code PreToolUse hook that blocks
+  non-compliant Gmail drafts; direct mode gates a file or stdin and can print the
+  raw verdict as JSON.
+
+### Sync covers the workspace, not just documents
+
+`0.3.0` synced documents only — `plinth sync` was a one-shot pull, and `plinth start`
+carried a watcher that pushed local edits for that one type. `0.4.0` syncs
+**documents, projects, tasks, artists, meetings and threads**, each on its own entity
+strategy, in both directions. Alongside that:
+
+- **Ambient pull** — `plinth start` now pulls continuously rather than once at boot.
+- **A user-writable `files/` subtree** — drop any file into the mirror and it syncs.
+- **Rendered read-only blocks** in the mirror: artist contacts in `_artist.md`, a
+  bounded "Recent activity" comment tail on tasks and projects, and project-as-rollup
+  task lists in `projects/<slug>.md`.
+- **Documents round-trip raw markdown** — the HTML conversion layer is gone. Frontmatter
+  (`category`, `is_context_doc`) round-trips faithfully.
+- **`~/.plinth/daemon.log`** — live push/pull is visible instead of silent.
+
+### Your local edits are harder to lose
+
+Most of this release's fixes are one shape: the daemon must never silently discard
+work you did on disk.
+
+- Diverged local edits are reconciled at boot instead of being overwritten.
+- A singleton pull no longer clobbers un-pushed local edits.
+- Bulk deletes and gutting overwrites are quarantined for `plinth confirm` rather
+  than pushed.
+- Task-mirror conflicts are field-typed, and validation failures are written back
+  into the file as a `# sync-error` block instead of vanishing.
+- Rate-limit bursts (429) are throttled and retried, and anything still unsynced is
+  recorded rather than dropped.
+- Renames are classified against a refreshed inode at boot, so a stale one can't turn
+  a rename into a delete-plus-create.
+- Push failures surface the server's own error message instead of a bare 400.
+- Untracked files already on disk at daemon boot are discovered rather than ignored,
+  and the `files/` subtree is scaffolded at boot instead of deadlocking on its own
+  absence.
+
+### Context and grounding for agents
+
+- A workspace-root `CLAUDE.md` and per-artist `CLAUDE.md` / `memory.md` /
+  `daily-log.md` are generated on sync.
+- The workspace and per-artist maps are a content index, not just a folder structure.
+- `workspace-rules.md`, `workspace-memory.md` and a member-private user-memory lane
+  sync bidirectionally.
+- Dates ground to the mapped calendar rather than the retired `key_dates` table.
+
+### Notes
+
+- Requires Node >= 20. The keychain integration (`@napi-rs/keyring`) installs a
+  native prebuild for your platform: macOS Keychain, Windows Credential Manager, or
+  Linux Secret Service.
+- `dist/build-stamp.json` ships in the tarball and records the git SHA the bundle was
+  built from.
+
+## 0.3.0 — 2026-05-20
+
+First published release. `plinth login` with OS-keychain PAT storage, `plinth sync`
+(documents, one-shot pull), an early `plinth start` with a push watcher, and
+`plinth version`.

package/README.md

@@ -2,35 +2,44 @@
 
 Plinth capstone sync daemon and CLI. Mirrors your Plinth workspace to `~/Plinth/<workspace>/` and keeps it bidirectionally synced. AI-native: pair with Claude Code or any LLM agent for context-aware artist management.
 
-**Status: early access. `login` and `sync` (pull-only, documents) are implemented; the watcher and other entity types land in subsequent PRs. See V1_SPEC §5 M3 in the plinth monorepo for the full milestone plan.**
+**Status: early access.** Two-way sync runs as a daemon across documents, projects, tasks, artists, meetings, threads and a user-writable `files/` subtree. See `V1_SPEC` §5 M3 in the plinth monorepo for the full milestone plan, and [`CHANGELOG.md`](CHANGELOG.md) for what landed when.
 
-## Commands
+## Install
 
-Implemented today:
+```sh
+npm i -g @plinth-music/cli
+```
 
-- `plinth login --workspace <slug>` — issue a PAT in the browser, paste it back, store in the OS keychain (macOS Keychain / Linux Secret Service / Windows Credential Manager).
-- `plinth sync [--workspace <slug>]` — one-shot pull of documents into `~/Plinth/<workspace>/`. Defaults to the active workspace if `--workspace` is omitted.
+Requires Node >= 20. A Homebrew tap (signed + notarised) is planned; npm is the only install path today.
 
-Planned (not yet implemented):
+## Getting started
 
-- `plinth start` — run the sync daemon (file watcher + cloud subscription).
-- `plinth status` — print last-synced-at per entity type and pending changes.
-- `plinth refresh-context` — regenerate `CLAUDE.md` from the current Plinth schema + workspace.
-- `plinth export workspace` — generate an export bundle.
-- `plinth update` — detect install method (brew vs npm-global) and upgrade in place.
-- `plinth logout --workspace <slug>` — revoke local PAT reference, retain mirror files.
+```sh
+plinth login --workspace <slug>   # issue a PAT in the browser, paste it back
+plinth sync                       # one-shot pull into ~/Plinth/<slug>/
+plinth start                      # run the daemon: continuous pull + watch + push
+```
 
-## Install (once published)
+## Commands
 
-Neither path is published yet.
+- `plinth login --workspace <slug>` — issue a personal access token in the browser, paste it back, store it in the OS keychain (macOS Keychain / Linux Secret Service / Windows Credential Manager).
+- `plinth sync [--workspace <slug>]` — one-shot pull into `~/Plinth/<workspace>/`. Also generates the workspace-root `CLAUDE.md` (a thin TOC + entity model + skill pointers) and an empty `CLAUDE.local.md` stub on first sync, and silently refreshes `CLAUDE.md` on a schema-version change. Defaults to the active workspace if `--workspace` is omitted.
+- `plinth start` — run the long-running sync daemon: pull the latest, then watch the mirror for local edits and push them. Logs to `~/.plinth/daemon.log`.
+- `plinth status` — local sync state: daemon liveness, last sync and per-type counts, and any destructive batches being held. Warns when a source install's `dist/` is behind its checkout.
+- `plinth confirm` — review and release destructive batches the daemon has quarantined (apply, or `--discard`).
+- `plinth refresh-context [--workspace <slug>]` — force-regenerate the workspace-root `CLAUDE.md` from the current Plinth schema + workspace. The user-customisable block between the `<!-- BEGIN: user-customisable -->` / `<!-- END -->` markers is always preserved verbatim; `CLAUDE.local.md` is never touched.
+- `plinth grounding` — print the session-start grounding block (current date, entity resolution, write confirmation, workspace rules, workspace memory, user memory). Invoked by the generated Claude Code SessionStart hook.
+- `plinth voice-gate` — gate agent-originated copy against the workspace voice rubric. `--hook` runs it as a Claude Code PreToolUse hook that blocks non-compliant Gmail drafts; direct mode takes `--file <path>` or stdin and prints the verdict (`--json` for the raw response).
+- `plinth backlinks <target>` — report what points at a target, by reading the local mirror rather than making a network call. `<target>` can be a mirror path (`projects/breadcrumb-trail.md` — including a mirror-root file like `CLAUDE.md`), a bare name (`breadcrumb-trail`), or a wikilink target as written (`Aligned Timeline - 4 June 2026`). Output is file paths with line numbers and the link as written; `--paths-only` emits deduped paths for piping, and stdout carries the answer ALONE — withheld rows never reach the pipe, whatever the display flags say. **Every narrowing is disclosed, and the counts print even when they are zero**, because a filter the caller cannot see is indistinguishable from an empty corpus, and a disclosure that only appears when it bites gives a reader no baseline to judge it against. Two footers carry them: links withheld from the answer (daemon-rendered marker blocks, code spans / HTML comments, and links to a bare name several files answer to), and the corpus line — which workspace was searched, how much of the mirror was read against its full size, and what went unread: `this-fiction · 859 of 880 files scanned (21 non-markdown, 0 unreadable) in 34ms`. `--unfiltered` shows the withheld rows, each tagged with the narrowing that hid it. Non-markdown files are not scanned for links but **do** count as existing, so asking about a PDF in `files/` answers rather than denying it. Exit codes: `0` results found or the target file exists, `1` no such target and nothing links to that name, `2` a bare name several files answer to (it lists them rather than guessing — and every candidate it prints resolves when pasted back), `3` no active workspace, an unknown or malformed workspace slug, or a mirror with nothing to search.
+- `plinth declare <path> --scratchpad <dir> [--label <text>]` — declare a file in the session scratchpad as a work product, so it appears in the cockpit's work-products panel instead of being lost with the session. Appends one line to an append-only `.plinth-deliverables.jsonl` manifest inside `<dir>`; the manifest records the **path, never the content**, so the panel always points at the live file rather than a snapshot that can go stale. Grounding primitive (j) instructs the agent to run this the moment it writes a deliverable whose only home is the scratchpad. **The scratchpad directory is required and never inferred** (`--scratchpad`, or `PLINTH_SCRATCHPAD_DIR`): this repo learns it from neither the app that spawns the terminal nor the harness that told the agent, so a guessed root would silently widen the containment check every refusal rests on. Refuses, with exit 1, anything outside that directory — including a symlink whose target is outside it — plus a directory, a file that does not exist yet, and a missing root.
+- `plinth review-tier [--repo <path>] [--base <ref>]` — print the code-review tier the current diff earns, `low` or `high`, for use as `/code-review $(plinth review-tier)`. Reads the diff against the merge base — committed, uncommitted **and untracked**, since a brand-new never-added file is invisible to `git diff` and would otherwise be classified as absent — and routes `high` on the risk classes the review rubric names: auth/RLS, optimistic concurrency/CAS, financial math, data-moving migrations, and large **and** multi-subsystem together. **It is a router, not a ceiling**: size alone never escalates, because a blanket cap would kill the concurrency reviews that earn their keep. **The output contract is the safety story.** It is invoked inside `$( )`, where an empty stdout or a non-zero exit would collapse the caller to an unqualified `/code-review` that silently inherits whatever global effort is configured — safe by accident, and indistinguishable from this working. So stdout carries **exactly one token and nothing else**, the exit code is **always 0**, and the reasoning goes **unconditionally to stderr** on both tiers. Anything it cannot classify — not a git repo, no merge base, no default branch, an empty diff — prints `high` and says why on stderr.
+- `plinth version` — print the installed version.
 
-```sh
-# npm (cross-platform)
-npm i -g @plinth-music/cli
+Planned (not yet implemented):
 
-# Homebrew (macOS, signed + notarised)
-brew install plinth-music/tap/plinth-cli
-```
+- `plinth export workspace` — generate an export bundle.
+- `plinth update` — detect install method (brew vs npm-global) and upgrade in place.
+- `plinth logout --workspace <slug>` — revoke the local PAT reference, retain mirror files.
 
 ## Develop
 
@@ -39,7 +48,7 @@ Requires [Bun](https://bun.sh/) (latest).
 ```sh
 bun install
 bun run build      # produces dist/cli.js
-bun test           # builds, then runs the smoke test
+bun test           # builds, then runs the suite
 bun run typecheck  # strict tsc, no emit
 ```
 
@@ -50,6 +59,8 @@ The built CLI is a standard Node-compatible ESM bundle with a `#!/usr/bin/env no
 ./dist/cli.js --help
 ```
 
+Releasing is documented in [`docs/RELEASING.md`](docs/RELEASING.md).
+
 ## License
 
 MIT — see `LICENSE`.

package/dist/build-stamp.json

@@ -0,0 +1,5 @@
+{
+  "sha": "aa7af2b93debdba13e6abbbc8689c54d66a2c8d5",
+  "dirty": false,
+  "built_at": "2026-08-14T14:09:40.708Z"
+}