@plinth-music/cli 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 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

package/README.md

@@ -30,6 +30,9 @@ plinth start                      # run the daemon: continuous pull + watch + pu
 - `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.
 
 Planned (not yet implemented):

package/dist/build-stamp.json

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