agent-trellis 0.1.0

package/docs/roadmap.md

@@ -0,0 +1,484 @@
+# Roadmap
+
+Each phase must ship with a `trellis doctor` check that verifies its own
+claim — no phase is "done" on the strength of a config file existing, only
+on the strength of a passing verification against the real running agent.
+
+See [`implementation-plan.md`](implementation-plan.md) for P1–P4 broken down
+to file/function level.
+
+**P0 is done and archived** (`openspec/changes/archive/2026-09-12-trellis-doctor-p0/`;
+living spec at `openspec/specs/agent-state-probing/` and
+`openspec/specs/capability-drift-detection/`). Verified against this real
+machine, not just fixtures: independently rediscovered the already-fixed
+Codex `openspec-*` duplication as clean, found a real, previously-unknown
+MCP name collision (`sentry` statically configured on Claude Code and Kiro
+while also being a `known_host_injected` name), and found a real wrong-case
+skill file (`e2e-test`). `trellis doctor` (no flags) does none of this by
+spawning anything — MCP handshake probing is opt-in via `--probe-mcp`
+(see `docs/architecture.md`), added after a real run showed the default
+had a much larger blast radius than "read-only" should mean.
+
+This is the format every later phase uses: one `openspec/changes/<phase>/`
+directory per phase, `openspec new change <name>` → tasks implemented →
+`openspec archive <name>`. `implementation-plan.md`'s P0/P1 sections are
+kept only as historical notes; don't edit them further.
+
+**P1 is done and archived** (`openspec/changes/archive/2026-09-12-trellis-sync-p1/`;
+living spec at `openspec/specs/canonical-source-loading/` and
+`openspec/specs/skill-instructions-sync/`). Covers all four agents,
+including pi — a corrected assumption found while starting this change
+(pi previously assumed to need "no adapter"; it needs the same symlink
+treatment as the other three once its real global directory,
+`~/.pi/agent/skills`, was confirmed in P0). Verified against a scratch
+`$HOME` and `scripts/sandbox.sh`'s real container, never this developer's
+actual dotfiles. The acceptance pass itself caught two real bugs before
+they'd have shipped: a removal check that used `realpathSync` and
+silently never fired on a symlink whose canonical target had just been
+deleted (exactly the case it existed to catch — broken symlinks throw on
+realpath), and a plural/singular string mismatch between the CLI's
+`target` option and `AdapterPlanItem.kind` that made `trellis sync skills`
+silently apply nothing while reporting "already in sync." Both were only
+found because the sandbox was actually run end-to-end, not just unit
+tests of the pieces — see docs/architecture.md's testing philosophy.
+
+**P2 is done and archived** (`openspec/changes/archive/2026-09-12-trellis-mcp-sync-p2/`;
+living spec at `openspec/specs/mcp-server-sync/`). `trellis mcp sync`
+covers create/repair only — automatic removal is deliberately deferred: a
+symlink's realpath proves Trellis ownership for skills, but a bare TOML/
+JSON key has no equivalent marker, so "gone from canonical" and "the user
+configured this directly" are indistinguishable without a `trellis.lock.json`
+ownership-tracking mechanism that doesn't exist yet. Two write mechanisms
+were chosen only after empirically ruling out the obvious ones first: both
+`@iarna/toml` and `smol-toml` silently drop comments and reformat arrays on
+a bare parse→stringify round-trip (so Codex's `config.toml` is patched by a
+hand-rolled, purpose-built line-based section locator/splicer,
+`src/lib/tomlSection.ts`, never a general parser), and `codex mcp add
+--env` only accepts literal `KEY=VALUE` with no bare-name form (so it's
+never shelled out to for the general write path — writing a real secret
+value into a config file is the exact thing the secrets policy forbids).
+Claude Code and Kiro use a plain JSON parse/merge/stringify, safe because
+JSON has no comments to lose. The sandbox acceptance pass caught a real
+bug unit tests alone hadn't: a comment block immediately introducing the
+*next* `[header]` was being swallowed into the *previous* section's range,
+so updating that previous section would have silently deleted an
+unrelated comment — see docs/architecture.md's testing philosophy for why
+this project always runs the real container, not just fixtures in memory.
+
+**P3 is done and archived** (`openspec/changes/archive/2026-09-12-trellis-secrets-audit-p3/`;
+living spec at `openspec/specs/secrets-audit/`). `trellis secrets audit`
+reads each present MCP-capable agent's real, on-disk config (never
+canonical) and runs two independent checks: a whole-file scan against
+`secrets.policy.yaml`'s `reject_patterns`, and a check of every declared
+environment-variable *name* against `allowed_vars`. The second check
+exists because a value-only scan structurally cannot catch the first real
+incident on record — a GitLab PAT stored under the *wrong variable name*
+was still a well-formed `${VAR}` reference, just the wrong name. Env-var-
+name extraction stays dependency-free and format-narrow (real `JSON.parse`
+for Claude Code/Kiro; a five-line regex over the one `env_vars = [...]`
+line shape for Codex) rather than reusing P2's write-path
+`tomlSection.ts` or adding a TOML library for reads — a deliberate,
+separately-reasoned choice, not an oversight (P2's D2 rejected TOML
+libraries specifically for round-trip fidelity on *writes*; that concern
+doesn't apply to a read-only linter, but a full parser is still more than
+this one narrow extraction needs). Both real incidents on record were
+reproduced and caught live in the sandbox, not just in unit tests.
+
+**P4 is done and archived** (`openspec/changes/archive/2026-09-12-trellis-pi-mcp-bridge-p4/`;
+living spec at `openspec/specs/pi-mcp-bridge/`). pi's MCP access is a
+single symlinked extension (`~/.pi/agent/extensions/trellis-mcp-bridge.js`),
+not a settings.json entry — found by reading pi's own extension-loader
+source directly (same technique as P0's D5): `~/.pi/agent/extensions/`
+is auto-discovered on every startup, including symlinks, with zero
+configuration. The genuinely hard problem, found only by actually running
+the real `pi` binary against the real symlink in a dedicated sandbox
+(`docker/pi-sandbox.Dockerfile`) rather than trusting the design on paper:
+a symlinked file's own bare-specifier imports (`@modelcontextprotocol/sdk`,
+`typebox`) resolve relative to the *symlink's own path*, not its
+target — the reverse of the initial assumption — so no dependency
+declared in Trellis's own `package.json` could ever make an unbundled
+bridge file resolve once placed in an arbitrary user's home directory.
+Fixed by bundling the whole bridge into one dependency-free
+`dist/pi-bridge/bundle.js` via `esbuild`, confirmed by re-running the
+same sandbox check: the bridge loaded cleanly (no more "Failed to load
+extension"), reaching pi's own unrelated "no API key configured" failure
+instead — proof positive without ever spending a real model call.
+
+**P5 is done and archived** (`openspec/changes/archive/2026-09-12-trellis-sdk-p5/`;
+living spec at `openspec/specs/trellis-sdk/`). `agent-trellis` now has a
+real `"exports"` map: `import { loadCanonicalSource } from "agent-trellis"`
+resolves without touching the CLI at all. Deliberately narrow (a curated
+`src/sdk.ts` barrel — canonical-source loading and its types only, never
+`src/adapters/*`/`src/commands/*`) and deliberately one package, not a
+separately-published `@trellis/sdk` — the roadmap's naming was a working
+label, not a monorepo commitment, and there is no second consumer yet to
+justify that cost. Verified with a real package-resolution check
+(`scripts/verify-sdk-export.sh`: pack the actual tarball, install it into
+a throwaway scratch project, import via the bare `"agent-trellis"`
+specifier), not just a source-relative `tsx` import — the two use
+different resolution algorithms, and only the former would have caught an
+`"exports"` map that looked right but didn't actually resolve for a real
+consumer.
+
+**P6 is done and archived** (`openspec/changes/archive/2026-09-12-trellis-memory-p6/`;
+living spec at `openspec/specs/memory-defaults/`). `@modelcontextprotocol/server-memory`
+is the documented default (`schema/servers.example.yaml`), confirmed by
+the user over `totalrecallai` — a real, third-party memory server found
+statically configured on this machine's Kiro install only (Claude
+Code/Codex had none at all). No new adapter code: an unscoped `memory`
+entry reaches all three native-config agents via P2's existing pipeline
+and pi via P4's bridge, verified end-to-end in the real sandbox with the
+actual `@modelcontextprotocol/server-memory` package name (never
+spawned — `mcp sync` only writes config). One real wrinkle corrected
+along the way: the schema example already lists `memory` under
+`known_host_injected` (a genuine, empirically-grounded P0 finding about
+mirasim's own runtime injection, not a stale guess), so the new default
+entry ships commented out with guidance on which of the two situations
+applies, rather than shipping an example that self-collides with
+Trellis's own guard. Deliberately out of scope: auto-ingesting
+`~/.trellis/memories/*.md` content into the running memory server's
+store — a real, separate problem left as an open question, not silently
+resolved.
+
+**P7 is done and archived** (`openspec/changes/archive/2026-09-12-trellis-secrets-env-management-p7/`;
+living specs at `openspec/specs/secret-env-resolution/`, plus
+modifications to `pi-mcp-bridge` and `secrets-audit`). Two real gaps
+found testing the pi bridge against this real machine, not assumed: (1)
+`secrets audit` only ever checked declared env var *names* against an
+allow-list, never whether a name actually resolves to a value — a
+machine migration could carry every name across while every value stayed
+unset, silently, until some agent's tool call 401'd; (2) the pi bridge's
+`connectStdio` already read real secret values (unavoidable — it's
+Trellis's own code spawning the MCP subprocess, unlike Claude Code/
+Codex/Kiro's own native clients resolving `${VAR}` in their own process),
+but did so unconditionally from ambient `process.env` — every credential
+the parent `pi` process's shell exported, not just the one or two names
+the active server declared. Fixed with one shared, dependency-free
+resolver (`src/lib/secretEnv.ts`) both the bridge and the audit call, and
+one new optional `secrets.policy.yaml` field, `env_file`: when set, it's
+the *sole* source for a declared name (no fallback to ambient — a silent
+fallback would defeat the isolation this exists to offer), read via a
+narrow hand-rolled `KEY=VALUE` parser, same "no new dependency" reasoning
+as P3's `envVarNames.ts`. Verified with a real spawned MCP subprocess
+(not a mock) reading back its own env by name
+(`test/unit/piBridge.test.ts`), proving `env_file`'s value wins even when
+ambient holds a different one — and separately in the real (non-pi)
+Docker sandbox, `trellis secrets audit` correctly reporting
+`missing-env-value` and exiting non-zero. Deliberately scoped down from
+the original plan: no second `pi`-sandbox rebuild, since the bridge's own
+unit test already exercises the exact changed code path with the same
+rigor, and P4's own sandbox pass already covers the pi-extension-loading
+surface this change never touches (tasks.md 5.1 records the reasoning,
+not a silent skip). Honestly scoped non-goal, stated rather than
+discovered later: `missing-env-value` is authoritative for pi, but only a
+best-effort proxy for Claude Code/Codex/Kiro — those three resolve
+`${VAR}` in their own process, which this audit cannot observe directly.
+
+**P8 is done and archived** (`openspec/changes/archive/2026-09-12-trellis-kiro-approved-env-vars/`;
+living spec at `openspec/specs/kiro-env-var-approval/`). A real,
+already-shipped correctness gap, found by reading Kiro's own installed
+extension source directly
+(`kiro.kiro-agent/dist/extension.js`'s `expandEnvironmentVariables`):
+Kiro's `${VAR}` substitution is gated by a workspace/user setting,
+`kiroAgent.mcpApprovedEnvVars` — a name absent from that list is
+silently left as the literal, unresolved string, no error. On this real
+machine that list was entirely empty, which is exactly why the one real
+Kiro server needing a secret (`mcp-router`) held a literal token instead
+of a `${VAR}` reference. Every Kiro MCP server Trellis had ever
+generated with a `${VAR}` reference was, by default, silently broken —
+P2 never knew this second gate existed. Fixed: the Kiro adapter now
+also ensures every env name it references is present in
+`kiroAgent.mcpApprovedEnvVars`, in Kiro's own global, VS-Code-style
+`settings.json` (a different file from `~/.kiro/settings/mcp.json`,
+shared with hundreds of unrelated editor preferences) — additive only,
+parses the whole file and preserves every other key, refuses to touch a
+file it can't parse. Verified in the real sandbox twice: a clean machine
+gets the file created with exactly the needed name; an already-correct,
+pre-seeded machine (including an unrelated key) produces zero writes and
+comes out byte-identical. Deliberately narrow: only covers `env` names
+(not the not-yet-built `headers` field), and only macOS's settings path
+(Linux/Windows equivalents are the well-known convention but unverified
+against a real install, stated as an open question).
+
+**P9 is done and archived** (`openspec/changes/archive/2026-09-12-trellis-mcp-transport-auth/`;
+living specs at modifications to `mcp-server-sync`, `pi-mcp-bridge`,
+`secrets-audit`, and `kiro-env-var-approval`). `McpServerDef` gains
+`headers?: Record<string,string>` (`${VAR}` references, same discipline
+as `env`) and `Transport` gains `"sse"`; the dead `auth?: "oauth" |
+"bearer-env"` field — never read anywhere in the codebase — is removed.
+Four real, verified per-agent schemas (CLI `--help` output, Kiro's own
+installed extension source, the MCP SDK's real `.d.ts`) converged on:
+Claude Code and Kiro accept the identical plain headers map, rendered
+verbatim; Codex has no generic headers concept at all, only a single
+purpose-built `bearer_token_env_var` field (matching what its own `mcp
+add --bearer-token-env-var` generates) — a server needing more than one
+header is refused for Codex specifically (a real conflict, not a silent
+drop or lossy approximation) while still reaching every other agent; the
+pi bridge passes resolved headers into both `connectHttp` and a new
+`connectSse` via the SDK's `requestInit.headers`. Real OAuth (browser
+redirect, token refresh) is explicitly not built anywhere — all three
+native-config agents already have their own working flow (`claude mcp
+add --client-id`, `codex mcp login`, Kiro's own `oauth` schema fields);
+pi has none and gains none here, a stated limitation. A cross-cutting
+fix shipped alongside the feature rather than after: both P7's
+`missing-env-value` check and P8's Kiro approved-env-vars list now see
+names embedded in `headers` values too, via one shared
+`declaredEnvNames` helper — shipping `headers` without teaching both of
+them about it would have reproduced P8's own root cause for a new
+field. Verified with a real, unmocked network test (a plain `node:http`
+server capturing the bridge's actual outbound request headers) and in
+the real Docker sandbox: both a bearer-token-shaped and a
+two-header-shaped fixture server, confirming Claude Code/Kiro render
+`headers` verbatim, Codex renders `bearer_token_env_var` or refuses with
+the exact expected conflict message, and `secrets audit` catches a
+headers-embedded name both on the canonical side and in a real,
+already-written agent config file.
+
+**Post-P9 hardening, done and archived**
+(`openspec/changes/archive/2026-09-12-trellis-mcp-connect-timeout/`;
+modifies `pi-mcp-bridge`). Found live, not hypothesized: a real, still-
+published MCP server CLI (`@harness-fe/cli mcp`) that exits in under a
+second with `stdio: "ignore"` but, spawned exactly the way a real stdio
+MCP client must (a readable stdin pipe attached), never writes a byte
+and never exits — indistinguishable from "still starting up" without a
+bound. The pi bridge's `Promise.all` over every configured server had
+no timeout on `client.connect()`, so one such server stalled the entire
+extension load, plus every other configured server's tool registration
+with it. Each of `connectStdio`/`connectHttp`/`connectSse` (and
+`listTools()` after a successful connect) now races against a fixed
+10-second timeout — the same constant `doctor --probe-mcp`'s
+`mcpProbe.ts` already used independently, confirmed by reading it, not
+assumed. Fixing this surfaced a second, real bug beyond the plan: a
+timed-out `connectStdio` was leaking its spawned child process forever
+(discovered when a test run took 12-19s instead of the expected ~300ms,
+and confirmed by a live orphaned process still in `ps` after the test
+exited) — every connect function now calls `transport.close()` on any
+failure, timeout or otherwise, which for a stdio transport kills the
+underlying process. Verified three ways: a dedicated hanging-server
+fixture (two modes — silent from the first byte, and silent only after
+a real `initialize` reply) proves the isolation and the process-leak
+fix in the unit suite; the real Docker pi sandbox re-ran end to end
+with the fix in place, hitting the exact timeout path for real (a
+`memory` server's `npx` cold-start exceeding 10s), while two other,
+differently-broken servers failed fast and pi still reached its own
+unrelated "no API key" stage — proof nothing stalled. A pre-existing,
+unrelated gap was found (not fixed here, out of this change's scope):
+none of `sync skills`/`sync instructions`/`mcp sync`'s target filters
+cover the bridge extension symlink's `kind: "extension"` — only bare
+`trellis sync` delivers it.
+
+**`pi-bridge-lifecycle`, done and archived**
+(`openspec/changes/archive/2026-09-12-pi-bridge-lifecycle/`; modifies
+`pi-mcp-bridge`). The bridge now owns the full lifecycle of every MCP
+client it connects — a `clients: Set<Client>` tracked from a successful
+`connectStdio`/`connectHttp`/`connectSse`, closed (idempotently, best-
+effort) on pi's `session_shutdown` event or when `tools/list` fails
+after connecting. Started as an open proposal carried forward from
+earlier work with only 1 of 3 declared scenarios under test; closed out
+here by adding the two missing ones — multiple connected servers are
+*all* released on shutdown (not just the first), and calling shutdown
+twice is a no-op on the second call, not an error or a double-close —
+both verified against real spawned subprocesses, not mocks. The fourth
+declared scenario ("a server that never connects is not cleaned
+twice") needed no dedicated test: it's enforced by control flow, not a
+runtime check — a failed connect never reaches `clients.add(client)`,
+so it was never a candidate for cleanup in the first place, and
+`trellis-mcp-connect-timeout`'s own tests already exercise that exact
+failure path. Real pi-sandbox verification was judged already covered
+by `trellis-mcp-connect-timeout`'s own Docker run, which exercised this
+same session_shutdown/`closeAllClients` code path with no dedicated
+second real-CLI run needed.
+
+**`trellis-cli-init`, done and archived**
+(`openspec/changes/archive/2026-09-12-trellis-cli-init/`; adds
+`canonical-source-bootstrap`, modifies `capability-drift-detection`).
+New `trellis init` command: creates `~/.trellis/agents.md`,
+`mcp/servers.yaml` (`servers: {}`, `known_host_injected: []`), and
+`secrets.policy.yaml` (`reject_patterns` read live from
+`schema/secrets.policy.example.yaml`, not retyped) whenever they don't
+already exist — per file, never overwriting real content — then prints
+which of the four agents are present, each pointing at `trellis migrate
+--from <agent>` (next). Turns `sync`/`mcp sync`/`secrets audit`'s
+existing "no canonical source, create it" refusal into something an
+actual command satisfies, closing a gap this session's own real pi
+onboarding had to route around entirely by hand (`mkdir`, hand-copied
+skills, hand-written `scope.yaml`). Found and fixed alongside it, not
+separately: `doctor`'s collision check had been permanently stuck on a
+hardcoded `DEFAULT_KNOWN_HOST_INJECTED` list since before canonical
+source loading existed — `collectDoctorReport` already accepted an
+override, but `src/cli.ts` never passed one, so `doctor` and `mcp
+sync`'s own collision refusal (which does read canonical) could
+disagree about what counts as a collision on any machine whose real
+host-injected connectors differ from this project's own development
+machine. `doctor` now resolves `known_host_injected` from canonical
+when it exists, falling back to the hardcoded default only when it
+doesn't (unchanged P0 behavior). Verified in the real Docker sandbox —
+and that run caught a second real, unrelated bug of its own: neither
+`docker/sandbox.Dockerfile` nor `docker/pi-sandbox.Dockerfile` copied
+`schema/` into the image, so `init` crashed on `ENOENT` reading
+`schema/secrets.policy.example.yaml` the first time it ran inside a
+container — both Dockerfiles fixed, `package.json`'s own `files` array
+also gained `schema` for the same underlying reason (the published npm
+package didn't ship it either, and README already told users to read
+it).
+
+**`trellis-cli-migrate`, done and archived**
+(`openspec/changes/archive/2026-09-12-trellis-cli-migrate/`; adds
+`canonical-source-migration`). `trellis migrate --from <agent>`: probes
+the named agent, then per real (non-symlinked, case-correct) skill and
+per real instructions file, plans one of `create` (no canonical entry
+yet), `already-migrated` (byte-identical to what's already in
+canonical — `src/lib/dirEquals.ts`, a real recursive directory-content
+comparison, not a name/mtime/hash shortcut), or `conflict` (differs —
+reported, never overwritten). A symlinked or case-broken skill is
+skipped and reported rather than migrated, since there's nothing real
+of that agent's own to import. Canonical `agents.md` still at `trellis
+init`'s placeholder is treated the same as "doesn't exist yet" so a
+first real migrate always lands. No `scope.yaml` entry is ever written
+— a migrated skill stays unscoped (visible to all agents), matching
+`sync`'s own default. `--dry-run` computes and prints the same plan
+with zero writes. This closes `trellis init`'s own per-agent pointer
+message (`trellis migrate --from <agent>` — next), completing the
+init → migrate → sync → mcp sync → secrets audit onboarding path for a
+user who already has real content in one of the four agents. Verified
+in the real Docker sandbox in the sequence a real user would actually
+run it: `migrate --from claude-code` against the fixture home correctly
+created a new canonical skill from claude-code's real content and
+correctly conflicted on instructions (fixture's canonical `agents.md`
+already has real content); a subsequent `trellis sync` in the same
+container then correctly symlinked the newly migrated skill out to
+kiro and pi (byte-identical content confirmed via `diff`), while
+correctly reporting conflicts — not overwriting — on claude-code and
+codex, since both already have their own real, non-canonical
+`sample-skill` at that exact path.
+
+**Agent auto-install scope decision, addendum to `trellis-cli-migrate`:**
+`trellis init` prints each undetected agent's real, currently-correct
+install command/URL (`npm install -g @anthropic-ai/claude-code`,
+`npm install -g @openai/codex`, `npm install -g
+@earendil-works/pi-coding-agent`, and `https://kiro.dev/downloads/`
+for Kiro — a desktop IDE with no CLI package) — never spawns an
+installer itself. A global package install or IDE download is exactly
+the kind of system-wide, hard-to-reverse action this project's own
+safety discipline requires an explicit human "yes" for, not a silent
+side effect of running `trellis init`; a detect-and-print pointer
+delivers "help me install the agents you support" without that risk.
+
+**`trellis-cli-onboard`, done and archived**
+(`openspec/changes/archive/2026-09-12-trellis-cli-onboard/`; adds
+`onboarding-flow`). `trellis onboard` chains `init` → detect all four
+agents (skill names/count, real-instructions presence — the exact
+subset `migrate` can act on, nothing about MCP) → resolve a single base
+agent → `migrate --from <base>` → `sync`, purely by calling each
+command's own already-tested plan/apply functions — no new skill-copy,
+symlink, or conflict-detection judgment exists in `onboard.ts` itself.
+Base-agent resolution: zero present prints every agent's install
+hint and stops (exit 0 — not a failure, a correct stopping point);
+exactly one present auto-selects with no prompt; two or more resolve
+via `--agent <id>` (the scriptable/sandbox/`--json` path) or an
+interactive `node:readline/promises` prompt when stdin is a real
+terminal, refusing cleanly with the present-agent list rather than
+guessing when neither is available. `--json` never prompts even if
+stdin happens to be a TTY, matching the same principle
+`scripts/sandbox.sh` already uses for its own `-it`/`-i` branching.
+Found and fixed alongside it: `trellis sync` itself had no dry-run
+mode at all before this change (`collectSyncReport` always called
+`adapter.apply()` unconditionally) — added as `RunSyncOptions.dryRun`,
+independently useful on its own (`trellis sync --dry-run`) and a
+prerequisite for `onboard --dry-run`'s own true-no-writes guarantee
+across the whole chain. Verified in the real Docker sandbox: `trellis
+onboard --agent claude-code` against the fixture home (which has
+multiple present agents) produced the identical real result to running
+`migrate --from claude-code` then `sync` by hand — same canonical
+`sample-skill` created, same instructions conflict correctly reported
+and left untouched, same real distribution of the migrated skill out
+to kiro and pi.
+
+**Merge mode — named future work, not a silent gap:** today, two or
+more present agents with genuinely *different* real content still
+resolves to "pick one as the base"; the others' own differing content
+stays exactly as `migrate`/`sync` already report it (conflict,
+untouched — never silently dropped or overwritten). Actually merging
+differing skills/instructions from more than one agent into one
+canonical result is real, separate design work (whose content wins per
+file? per skill? does the user review a diff before it's written?) —
+deliberately out of scope for `trellis-cli-onboard`, tracked here as an
+explicit next step rather than something a user has to discover is
+missing.
+
+**Pre-release closed-loop audit, before first publish.** A full,
+skeptical review of the whole new-user path — every command's usage
+text against its real implementation, every doc claim against the
+actual code, `package.json`'s shipped files against everything read at
+runtime — found and fixed five real issues, none caught by the
+existing test suite because each lived in code path or a doc claim
+nothing exercised directly:
+- `trellis sync --dry-run` was broken as a flags-first invocation:
+  `src/cli.ts`'s target parsing only ever checked `rest[0]`, so a flag
+  placed before a target (or with no target at all) was misread as an
+  unknown target named e.g. `"--dry-run"`. Fixed by parsing the whole
+  `rest` array for a recognized target instead of assuming position,
+  and the parsing logic (`parseSyncArgs`) was pulled out into its own
+  small, directly unit-tested function (`test/unit/cli.test.ts`) —
+  `src/cli.ts` previously had zero direct test coverage of its own argv
+  dispatch, which is exactly why a pure-parsing bug like this shipped
+  unnoticed. Adding that test surfaced a second real issue: importing
+  `cli.ts` for the pure function ran the whole CLI against the test
+  runner's own argv as an unguarded side effect (`main(...)` had no
+  entrypoint check) — fixed with the standard `import.meta.url ===
+  file://${process.argv[1]}` guard.
+- `sync --dry-run` was undocumented in `printUsage()`, `README.md`, and
+  `docs/getting-started.md` despite being real and (once fixed) working
+  — all three now document it.
+- `onboard.ts` had its own, second copy of `migrate`'s and `sync`'s
+  report-printing logic, and that copy was missing `migrate.ts`'s own
+  "nothing to migrate" empty-plan case — a real gap for exactly the
+  fresh-Claude-Code-install scenario this project's own new-user
+  persona represents (config present, zero skills, no instructions
+  file). Fixed by exporting and reusing `migrate.ts`'s `printPlan` and
+  `sync.ts`'s `printReport` directly instead of a second copy that
+  could silently drift.
+- `package.json`'s `files` shipped `dist` and `schema` but not `docs` —
+  every globally-installed user's local `README.md` (which *is*
+  shipped) links to `docs/getting-started.md`, `docs/architecture.md`,
+  and `docs/roadmap.md`, none of which existed on their machine. Same
+  root cause `trellis-cli-init`'s own entry already fixed once for
+  `schema/` — the fix pattern (add it to `files`) applied again here.
+- `docs/architecture.md`'s canonical-schema diagram listed
+  `trellis.lock.json` with no "not built yet" annotation, unlike every
+  other not-yet-built thing described in the same document — annotated.
+
+**A near-miss caught by re-running the real installed-tarball check, not
+by the test suite:** the first fix for `parseSyncArgs`'s test coverage
+gap put the pure function in `src/cli.ts` itself and guarded that
+file's top-level `main()` call with `import.meta.url ===
+file://${process.argv[1]}` so importing the function for a test
+wouldn't run the whole CLI as a side effect. That guard is not
+symlink-safe: npm's `bin` entry is a symlink, and a symlink's
+`import.meta.url` (resolved) never equals its own symlink path
+(`process.argv[1]`, unresolved) — so the real, installed `trellis`
+binary silently did nothing and exited 0 on every invocation. `npm
+test` stayed green throughout, because nothing in the unit suite runs
+through an actual symlinked bin — only `scripts/verify-cli-install.sh`
+does, and it caught this immediately on the very next run. Fixed
+properly by moving `parseSyncArgs` to its own zero-side-effect module
+(`src/lib/syncArgs.ts`) instead of trying to make the entrypoint guard
+symlink-safe — the reminder here: a real installed-package check is
+not a redundant formality alongside the unit suite, it's the only
+thing in this project that exercises the actual `bin` symlink at all.
+
+| Phase | Deliverable | Depends on |
+|---|---|---|
+| P0 | ✅ `trellis doctor` — read-only, opt-in-for-handshakes scan of all four agents' current skills/MCP/instructions state, reports drift and duplicates | nothing |
+| P1 | ✅ `trellis sync skills` / `trellis sync instructions` — symlink-based distribution to Claude Code, Codex, Kiro, and pi | P0 |
+| P2 | ✅ `trellis mcp sync` — incremental, in-place adapters for Claude Code (JSON merge), Codex (TOML section patch), Kiro (JSON merge); collision check against known host-injected server names | P1 |
+| P3 | ✅ `trellis secrets audit` — scans every adapter's output for literal credential patterns and unexpected env var names, fails non-zero on any hit | P2 |
+| P4 | ✅ pi bridge extension — MCP tool registration via `registerTool`, sourced from the same `mcp/servers.yaml` | P2 |
+| P5 | ✅ `@trellis/sdk` — read-only API over the canonical source, for third-party agents to consume without depending on the CLI | P1–P4 stable |
+| P6 | ✅ Memory: document and wire the `server-memory` default; write the mem0/OpenMemory upgrade guide | P2 |
+| P7 | ✅ Secrets/env management: shared `resolveSecretEnv` + `secrets.policy.yaml`'s `env_file`, pi bridge stops reading raw ambient env, `secrets audit` gains a `missing-env-value` check | P3, P4 |
+| P8 | ✅ Kiro `${VAR}` fix: adapter also manages `kiroAgent.mcpApprovedEnvVars`, without which Kiro silently never substitutes any env reference Trellis writes | P2 |
+| P9 | ✅ MCP transport/auth expansion: `headers` field for static bearer/API-key remote auth (Claude Code/Codex/Kiro/pi bridge, each via its own real schema), `sse` transport; real OAuth flows explicitly delegated to each agent's own native support, not reimplemented | P2, P4, P8 |
+| P10 | GUI: evaluate embedding into mcp-router's or skills-hub's existing interface before building anything new | P3–P9 |
+
+No dates. This is scoped by verification milestones, not calendar time.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "agent-trellis",
+  "version": "0.1.0",
+  "description": "A single source of capability for every coding agent — skills, MCP, subagents, memory, and secret policy, adapted natively into Claude Code, Codex, Kiro, and pi.",
+  "license": "MIT",
+  "author": "Paul Leo",
+  "type": "module",
+  "bin": {
+    "trellis": "./dist/cli.js"
+  },
+  "main": "./dist/sdk.js",
+  "types": "./dist/sdk.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/sdk.d.ts",
+      "import": "./dist/sdk.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "schema",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/build-pi-bridge.mjs",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/unit/**/*.test.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paul-leo/Trellis.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "codex",
+    "kiro",
+    "agent-skills",
+    "agents.md"
+  ],
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.28.2",
+    "tsx": "^4.19.0",
+    "typebox": "^1.3.0",
+    "typescript": "^5.6.0"
+  },
+  "dependencies": {
+    "yaml": "^2.9.1"
+  }
+}

package/schema/scope.example.yaml

@@ -0,0 +1,33 @@
+# .trellis/scope.yaml — exceptions only. Anything NOT listed here is
+# shared with all four agents — that's the default Trellis exists for.
+# Only write an entry when a capability should NOT go everywhere.
+#
+# Why this lives in its own file instead of inside each SKILL.md/agent.md:
+# Codex validates SKILL.md frontmatter against an allow-list of known keys
+# and rejects unrecognized ones (see docs/research.md). A Trellis-only
+# `scope:` field embedded in SKILL.md's own frontmatter would break that
+# skill specifically on Codex. Scope declarations stay outside every file
+# an agent itself parses.
+#
+# MCP servers are the one exception: `mcp/servers.yaml` is Trellis's own
+# format, never handed to an agent directly (always translated by an
+# adapter), so its per-server `agents:` field is declared inline there
+# instead of here — see schema/servers.example.yaml.
+
+skills:
+  # This skill only makes sense for Claude Code's tool surface (e.g. it
+  # references the Task tool for subagent delegation, which the other
+  # three agents don't have an equivalent of).
+  claude-subagent-dispatch: [claude-code]
+
+agents:
+  # Subagent profiles are implicitly Claude-Code-only today — Codex has no
+  # persistent subagent concept, Kiro/pi unconfirmed (see docs/research.md).
+  # No entries needed here until another agent gains an equivalent
+  # mechanism and a specific profile should NOT go to all of them.
+
+memories:
+  # A memory entry that only makes sense in the context of one agent's
+  # own quirks (e.g. a note about Codex's TOML in-place-patch behavior)
+  # rather than something every agent's context should carry.
+  codex-toml-patch-gotcha: [codex]

package/schema/secrets.policy.example.yaml

@@ -0,0 +1,43 @@
+# .trellis/secrets.policy.yaml — allow-list of variable names an adapter
+# output is permitted to reference. `trellis secrets audit` uses this to
+# tell "a legitimate ${VAR} reference" apart from "a name that shouldn't be
+# here" — it does NOT store or see the actual secret values, only names.
+#
+# The real values live wherever your environment already resolves them from
+# (a local .env-style file sourced by your shell, 1Password's `op run`,
+# anything that populates process env before an adapter's generated command
+# runs). Trellis never reads, writes, or transports the values themselves —
+# with one narrow, unavoidable exception: pi's MCP bridge is Trellis's own
+# code spawning the MCP server subprocess (unlike Claude Code/Codex/Kiro,
+# whose own native MCP client resolves `${VAR}` in its own process), so it
+# already has to read a value into memory to hand to that subprocess.
+#
+# env_file (optional) narrows *where* the bridge reads those values from —
+# a dotenv-format file (KEY=VALUE per line, no quoting/interpolation), never
+# merged with ambient process env once set: a name absent from it resolves
+# to missing, it does NOT fall back to the shell's own exported value. This
+# also lets `trellis secrets audit` check that every name your canonical
+# mcp/servers.yaml declares actually resolves to something, agent-agnostic.
+#
+# WARNING: whatever file you point this at holds plaintext secrets. Never
+# point it at a path inside a git-tracked directory (this file's own
+# directory, ~/.trellis/, included) — a `git add .` there would commit them.
+# env_file: ~/.config/agent-env/secrets.env
+
+allowed_vars:
+  - TANKA_EMAIL
+  - TANKA_ENV
+  - GITLAB_PERSONAL_ACCESS_TOKEN
+  - GITLAB_API_URL
+  - MCPR_TOKEN
+  - NOTION_OPENAPI_MCP_HEADERS
+
+# Patterns `trellis secrets audit` treats as "this looks like a literal
+# credential, not a reference" and fails the build on sight. Extend this
+# list as new credential shapes turn up — it grows from real incidents,
+# not speculative coverage.
+reject_patterns:
+  - 'glpat-[A-Za-z0-9_-]{20,}'   # GitLab personal access token
+  - 'mcpr_[A-Za-z0-9_-]{20,}'    # mcp-router token
+  - 'sk-[A-Za-z0-9]{20,}'        # OpenAI-style API key
+  - 'ghp_[A-Za-z0-9]{30,}'       # GitHub personal access token