total-recall-brain 3.40.7 → 3.41.0

package/scaffold/.agent/skills/plugin/subagents/plugin-reviewer.md

@@ -0,0 +1,55 @@
+---
+name: plugin-reviewer
+inputs: a plugin repository path
+returns: violations with evidence, or "clean"
+---
+
+# Subagent — plugin reviewer
+
+Adversarial review of a plugin claimed finished. Your job is to **find what is wrong**, not to confirm.
+
+Do not fix anything. Report only. A report with no violations must say why it is confident.
+
+## What to attack
+
+Work from the [anti-patterns](../references/anti-patterns.md) catalogue. It is the record of every failure actually found in this ecosystem, so it is the highest-yield place to look.
+
+**Fabrication.** Seeded readings, invented API results, hard-coded status claims, fixed text where a command belongs. Grep the card and the CLI for literals that could be a fabricated value: a hostname, a percentage, a latency, a status word, a session id.
+
+**Reassuring defaults.** A default that reports success, health or cleanliness the plugin has not verified. This is the most damaging pattern found: a card read three fields the command never returns and defaulted to `"Up to date"`, so a repository with three unpushed commits rendered as clean. For every value on the card, trace it to the command field it came from — and prove the field exists in the command's real output.
+
+**Credential violations.** A second store; a secret in `argv`; a secret in a log or stdout; an input that accepts a key; error text telling the user to install another product.
+
+**Templates.** A `card_layout`; a region or widget list; a face that would suit a different plugin; screens derived from the command list rather than the plugin's tasks.
+
+**Host leaks in a scaffold.** Any `total-recall` reference, `TOTAL_RECALL_BIN`, or auth-store read reachable from `capability/`. Any `ui/` file in the scaffold payload.
+
+**Values that break elsewhere.** `example.com`, an author's default amount or name, an example currency.
+
+**Presentation.** Render the face on the real dark tokens at 360, 768 and 1280 px. Look for: a severity colour beside a figure that contradicts it; colour-only severity; overflow; a selection style colliding with a severity border; dead CSS; a value rendered twice.
+
+**Stale docs.** A README describing a bug that is fixed, or a capability that does not exist.
+
+## Method
+
+1. Run `node ../scripts/record.mjs <path> --json` and read every failure.
+2. `total-recall plugin info <id>` — read the errors and warnings.
+3. For each value the card shows, find the command field behind it. If you cannot, that is a violation.
+4. Read the CLI for `--help` without credentials, `--json` on every subcommand, non-zero exit on failure.
+5. Render the face and look at it. Do not review a face you have not seen.
+6. Read the tests. A test that injects a fake credential path proves logic, not the contract.
+
+## Report format
+
+```
+VERDICT: violations found | clean
+
+[severity] category — file:line
+  what is wrong
+  evidence: the exact command output, grep result or rendered observation
+  why it matters: which invariant it breaks
+```
+
+Severity is `critical` (fabrication, credential leak, host leak, data loss), `high` (template, misleading default, dead documentation), `medium` (presentation, accessibility), `low` (copy).
+
+If you report `clean`, state which checks you ran and what you could not check. "Looks fine" is not a review.

package/scaffold/.agent/skills/plugin/subagents/scaffold-extractor.md

@@ -0,0 +1,71 @@
+---
+name: scaffold-extractor
+inputs: a plugin repository path
+returns: capability module design and the builder entry point, or "not separable, because…"
+---
+
+# Subagent — scaffold extractor
+
+Extract a plugin's capability so a builder can put it into their own application.
+
+Read [scaffold](../references/scaffold.md) first. It is the specification.
+
+**A scaffold is not a copy of the plugin.** The plugin is the reference implementation; the scaffold is the capability, importable, with no Total Recall in it.
+
+## First decide: is it separable?
+
+Return **"not separable, because…"** when the capability genuinely cannot live outside Total Recall:
+
+- it reads or writes the vault through SSSS contracts that only the host provides
+- it *is* host behaviour — a runtime router, a context generator, a scheduler task
+- it wraps Total Recall's own facilities rather than a domain
+
+Do not force an extraction that would produce a hollow module. Say so plainly. Most plugins wrapping an external service are separable; most plugins extending the host are not.
+
+## Then extract
+
+Separate the repository into one source with two artifacts:
+
+```
+capability/     the payload: exported functions, no host
+cli.mjs         the adapter: parse argv, resolve credentials, call the capability, format
+ui/             the face; Total Recall only
+```
+
+Move the domain logic out of the CLI handlers: request construction, signature verification, payload building, response mapping.
+
+The capability must be:
+
+- **explicitly parameterised** — no `argv`, no `process.env`, no module-level singleton, no ambient credential
+- **free of environment defaults** — a missing URL is the caller's error, never a silent `example.com`. Strip the author's defaults: `2000`, `"General Admission Ticket"`, `"usd"`
+- **transport-injected** — accept a `fetchImpl` so the app uses its own client and tests run offline
+- **returning data**, not printing text
+- **throwing errors**, not setting `process.exitCode`
+- **free of Total Recall** — no `total-recall`, no `TOTAL_RECALL_BIN`, no auth store, no `ui/`
+
+Write `BRICK.md`: what to import, what to pass, where credentials come from, what comes back. Concrete code, not a description of a CLI.
+
+## Prove it
+
+The tests must demonstrate standalone operation, not assume it:
+
+1. Load the capability in a process with `TOTAL_RECALL_BIN` unset and no auth store.
+2. Call every exported function with caller-supplied arguments and an injected transport.
+3. Assert no child process was spawned and no `total-recall` string is reachable from the payload.
+4. Vendor into a clean application and run the suite there.
+
+Evidence for why this matters: a vendored brick failed with `Auth credential read failed` once the Total Recall binary was absent, and 19 of 34 plugins export only `run`, so a builder must extract the logic by hand.
+
+## Return
+
+```
+separable: yes | no — <reason>
+capability/: <files and the exported functions>
+cli.mjs: <how much logic moved out>
+removed: <placeholders, author defaults, host calls, ui files>
+BRICK.md: <the file>
+standalone test: <the command and its real result>
+unverified: <what you could not check>
+```
+
+Never claim standalone operation without running it with Total Recall absent.