mini-trellis 0.3.8 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,268 +1,131 @@
1
- <h1 align="center">mini-trellis</h1>
2
-
3
- <p align="center"><strong>Cross-session memory for AI coding agents — without the heavy workflow tax.</strong></p>
1
+ <h1 align="center">
2
+ <a href="https://mini-trellis.github.io/">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Tiger-zzZ/mini-trellis/main/docs/assets/wordmark-dark.svg" />
5
+ <img src="https://raw.githubusercontent.com/Tiger-zzZ/mini-trellis/main/docs/assets/wordmark-light.svg" alt="mini-trellis" width="460" />
6
+ </picture>
7
+ </a>
8
+ </h1>
4
9
 
5
10
  <p align="center">
6
- Keep architectural conventions, research conclusions, and verified fixes in plain Markdown, and search local agent conversations in place.<br/>
7
- <strong>38.4% less wall time (1.62×)</strong> and <strong>40.1% fewer processed tokens</strong> in Claude Code benchmarks; <strong>86.9% fewer injected context characters</strong> across a 10-turn task fixture.
11
+ <a href="https://www.npmjs.com/package/mini-trellis"><img src="https://img.shields.io/npm/v/mini-trellis?style=flat-square&amp;logo=npm&amp;logoColor=white&amp;labelColor=173f35&amp;color=28785e" alt="npm version" /></a>
12
+ <a href="https://www.npmjs.com/package/mini-trellis"><img src="https://img.shields.io/npm/dm/mini-trellis?style=flat-square&amp;logo=npm&amp;logoColor=white&amp;label=downloads&amp;labelColor=173f35&amp;color=28785e" alt="npm downloads per month" /></a>
13
+ <a href="https://mini-trellis.github.io/"><img src="https://img.shields.io/badge/docs-website-28785e?style=flat-square&amp;logo=readthedocs&amp;logoColor=white&amp;labelColor=173f35" alt="Documentation website" /></a>
14
+ <a href="https://github.com/Tiger-zzZ/mini-trellis/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-64766f?style=flat-square&amp;labelColor=173f35" alt="AGPL-3.0 license" /></a>
8
15
  </p>
9
16
 
10
- <p align="center">Local Markdown · Zero Vector DB · On-Demand Recall &amp; Recording · One-Command Migration from Trellis</p>
17
+ <p align="center"><strong>Project knowledge, ready for the next session.</strong></p>
11
18
 
12
- <p align="center">
13
- <a href="#measured-performance--context-overhead">Benchmarks</a> ·
14
- <a href="#why-mini-trellis">Comparison</a> ·
15
- <a href="#quick-start">Quick start</a> ·
16
- <a href="#working-with-project-memory">How it works</a> ·
17
- <a href="./docs/using.md">During a change</a> ·
18
- <a href="#supported-tools">Supported agents</a> ·
19
- <a href="#migrating-from-trellis--upgrading">Migration</a> ·
20
- <a href="./README_CN.md">简体中文</a>
21
- </p>
19
+ <p align="center">Keep conventions, research, and development notes in project Markdown.<br/>Find the source in your docs and local agent conversations, and update it as the code evolves.</p>
22
20
 
23
21
  <p align="center">
24
- <a href="https://www.npmjs.com/package/mini-trellis"><img src="https://img.shields.io/npm/v/mini-trellis?style=flat-square&amp;color=28785e" alt="npm version" /></a>
25
- <a href="./LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-64766f?style=flat-square" alt="AGPL-3.0 license" /></a>
22
+ <a href="https://mini-trellis.github.io/docs/">Documentation</a> ·
23
+ <a href="https://mini-trellis.github.io/install/">Quick start</a> ·
24
+ <a href="https://mini-trellis.github.io/agents/">Supported agents</a> ·
25
+ <a href="https://mini-trellis.github.io/faq/">FAQ</a> ·
26
+ <a href="https://github.com/Tiger-zzZ/mini-trellis/blob/main/README_CN.md">简体中文</a>
26
27
  </p>
27
28
 
28
- > **v0.3.8:** Adds Kiro and OMP support, fixes Pi recording command arguments, and refreshes the current project after `upgrade`. See [Pi / OMP setup](./docs/using.md#pi-and-omp), [Kiro setup](./docs/using.md#kiro) and [release notes](./docs/releases/v0.3.8.md).
29
-
30
- ![Conventions, research and verified fixes accumulate in project Markdown, inform later work, and are updated with new evidence.](./docs/assets/knowledge-en.svg)
31
-
32
- AI coding workflows often fall into one of two traps: **starting every session with amnesia**—re-explaining the same API boundaries and past bugs—or **strapping on a heavy phase-gated workflow** that injects thousands of characters at startup, re-injects state on every prompt, and spawns cold-start sub-agents for routine edits.
33
-
34
- **mini-trellis keeps the project memory layer and leaves your workflow alone:**
35
-
36
- - **Carry decisions across sessions.** Interface contracts (`spec`), technical investigations (`research`), and session journals (`workspace`) live in versioned project Markdown—ready to consult and update as your codebase evolves.
37
- - **Unified lookup over docs and past chats.** When prior context matters, `mini-trellis mem recall` searches project Markdown and local agent conversation history together, returning short excerpts first and expanding full text via `ref` only when needed.
38
- - **Local-first, zero external services.** No vector database, no embedding API keys, and no background daemon. Planning, coding, and review stay completely with you and your agent.
39
-
40
- ---
41
-
42
- ## Why mini-trellis
43
-
44
- | Dimension | Hand-maintained `CLAUDE.md` | Vector DB / RAG Memory MCP | Phase-Gated Workflow (Trellis) | **mini-trellis** |
45
- | --- | --- | --- | --- | --- |
46
- | **Startup & per-turn injection** | Grows unbounded; loaded into every session | Plugin-dependent; extra indexing & network latency | ~8.6k chars at startup + per-turn state + sub-agent re-injection | **~1.1k-char memory entry; no per-turn workflow payload** |
47
- | **How specs & notes are loaded** | Always in context, even when irrelevant | Opaque similarity chunks; easy to miss exact contracts | Cold-start sub-agents re-read specs repeatedly | **On-demand `mem recall` excerpts; `mem read` only when needed** |
48
- | **Past conversation lookup** | None—lost when the chat closes | Requires syncing chats into an external store | Relies on manual task directory artifacts | **Searches local Claude / Codex / OpenCode V1 / Pi sessions in place** |
49
- | **Knowledge evolution** | Manual pruning; stale rules linger | Old and updated decisions collide in vector space | Scattered across archived task folders | **Built-in `superseded` lineage lifts current rules above old ones** |
50
- | **Infrastructure & ceremony** | Plain file, no search | Database, embeddings, and service config | Mandatory phase gates and sub-agent templates | **Plain Git-friendly Markdown + lightweight CLI; no forced workflow** |
51
-
52
- ---
53
-
54
- ## Measured performance & context overhead
55
-
56
- We report two distinct measurements below: **1) end-to-end wall time and processed tokens on Claude Code (`-38.4%` time, `-40.1%` processed tokens)**, and **2) static injected character counts across a 10-turn task fixture (`-86.9%` injected characters)**. They measure different layers and are kept separate.
57
-
58
- ### 1. End-to-end Claude Code benchmark (38.4% less wall time, 40.1% fewer processed tokens)
29
+ ## Carry the useful parts forward
59
30
 
60
- Under identical conditions—**same project code, same `.trellis` knowledge base, same Claude Code (`v2.1.306`), and same model (`deepseek-v4-flash`, `effort = max`)**—we compared `mini-trellis v0.3.1` against `Trellis v0.7.0-beta.4` across 6 task groups × 3 independent runs (27 sessions per tool):
31
+ **New in [v0.4.0](docs/releases/v0.4.0.md):** confirmed decisions flow through topic updates, verification, and journal recording. Recording retries resume saved work, corrected topics get a new record, and recall follows the current project's boundary.
61
32
 
62
- ![mini-trellis vs Trellis on Claude Code: Measured Wall Time and Processed Tokens](./docs/assets/v0.3.1-benchmark-en.svg)
33
+ | Capability | How you use it |
34
+ | --- | --- |
35
+ | **Keep project knowledge** | Maintain conventions and conclusions in existing README, docs, spec, and research files; link the session from a journal. |
36
+ | **Find the source** | `mem recall` searches documents and supported local conversations, returning excerpts, paths, and references. |
37
+ | **Organize past discussions** | `session-insight` turns selected conversations or text exports into existing project documents. |
38
+ | **Update decisions** | Edit the current topic, retain the reasoning, and link old notes to their replacements. |
39
+ | **Work across agents** | Different coding tools use the same project Markdown; the platform matrix lists native history support. |
63
40
 
64
- | Evaluation Task | Scenario | Median Time (mini / Trellis) | Time Saved | Median Processed Tokens (mini / Trellis) | Tokens Saved | Automated Check |
65
- | --- | --- | :---: | :---: | :---: | :---: | :---: |
66
- | **Cold Startup Overhead** (`O00`) | Reply `pong` without reading files; measures startup hook | **1.8s** / 2.9s | `-39.3%` | **11.6k** / 13.6k | `-14.8%` | Startup only (3/3 done) |
67
- | **Focused Function Coding** (`N01`) | Implement `normalize_label` + `unittest` from docstring | **16.9s** / 18.6s | `-9.2%` | **84.9k** / 131.4k | `-35.4%` | Unit tests 3/3 pass |
68
- | **Spec Lookup: Formulas** (`R01`) | Find capacity vs. flow impact formulas & edge policies | **14.5s** / 20.4s | `-28.8%` | **57.3k** / 79.3k | `-27.8%` | Formula & policy 3/3 pass |
69
- | **Spec Lookup: Permissions** (`R02`) | Verify 5 read-only tool service permission boundaries | **7.2s** / 16.3s | `-55.9%` | **38.8k** / 70.4k | `-44.9%` | Booleans & quote 3/3 pass |
70
- | **Spec-Driven Implementation** (`I01`) | Locate business spec & implement `assess_notice` + tests | **49.8s** / 57.1s | `-12.7%` | **192.6k** / 248.7k | `-22.6%` | 27 test cases 3/3 pass |
71
- | **4-Session Rule Evolution** (`M01`) | 4 fresh sessions: Save rule → Code → Update rule → Re-code | **68.1s** / 132.9s | `-48.8%` | **426.0k** / 713.6k | `-40.3%` | Both code stages 3/3 pass |
72
- | **All Recorded Runs Cumulative** | **Actual sum across all 6 tasks × 3 repeats (27 sessions/side)** | **472.2s** / 766.5s | **`-38.4%` (1.62×)** | **2.43M** / 4.05M | **`-40.1%` (-1.63M)** | **All automated checks pass** |
73
-
74
- - **Metric definitions**: Wall time is measured from command start to exit (including tool execution). **Processed tokens** = uncached input + output + cache reads (measuring total context volume processed across turns, not billed USD cost). Automated checks cover external unit test suites for coding tasks and numeric formula probes, boolean checks, and quotation matching for read tasks.
75
- - Full experimental setup, task designs, per-session numbers across all 54 sessions, and the 4-stage continuity breakdown are in the [Detailed Benchmark Report](./docs/releases/benchmark-detail.md) (release overview in the [v0.3.1 Release Notes](./docs/releases/v0.3.1.md)).
76
-
77
- ### 2. Injected character breakdown: why is the context lighter? (86.9% fewer injected characters)
78
-
79
- The chart below measures **hook and sub-agent injected text length in characters** on the v0.2.2 fixture (static and repeated prompt injection volume, distinct from the runtime token totals above). A phase-gated workflow injects state or specs at session start, on every user prompt, and whenever a sub-agent starts; `mini-trellis` keeps only a short startup entry and reads specs once in the main session when needed:
80
-
81
- ![Context Breakdown and Cumulative Overhead Across a 10-Turn Task](./docs/assets/context-overhead-en.svg)
82
-
83
- Measured on the same repository fixture across a 10-turn backend task, where both runs load the same three backend spec files (`2,690 chars`) and the same research note (`474 chars`):
84
-
85
- | Stage | Phase-Gated Workflow | mini-trellis | What changed |
86
- | --- | ---: | ---: | --- |
87
- | Session start (`SessionStart`) | 7,883 chars | **1,167 chars** | Drops the workflow manual and full directory tree; keeps current state and lookup commands |
88
- | Every turn (`UserPromptSubmit` ×10) | 9,530 chars | **0 chars** | No per-turn state hook |
89
- | Prior decision lookup (`recall` + `read`) | 1,621 chars | **1,053 chars** | Finds the topic via a 579-char excerpt, then reads the 474-char note |
90
- | Project specs (3 backend spec files) | 18,585 chars | **2,690 chars** | Reads the 3 spec files once in the main session instead of re-injecting into two cold-start sub-agents |
91
- | **10-turn cumulative injected chars** | **37,619 chars** | **4,910 chars** | **Identical spec and note text loaded; 86.9% fewer injected characters (7.7×)** |
92
-
93
- On a production repository with 19 domain spec files (`137k chars`) and 262 migrated research notes (`2.37M chars`), `mini-trellis` startup stays at **1,171 chars**, while phase-gated `implement` + `check` sub-agent injections reach **127k–512k chars** per task.
94
-
95
- ---
41
+ ![How project conventions, research, and verification records are reused in later sessions](https://raw.githubusercontent.com/Tiger-zzZ/mini-trellis/main/docs/assets/knowledge-en.svg)
96
42
 
97
43
  ## Quick start
98
44
 
99
- Requires **Node.js ≥ 18.17**, **Python ≥ 3.9**, and Git.
100
-
101
- ### 1. Install and initialize
102
-
103
- Run in your project root:
45
+ Requires Node.js ≥ 18.17, Python ≥ 3.9, and Git. In the project root:
104
46
 
105
47
  ```bash
106
48
  npm install -g mini-trellis
107
49
  mini-trellis init -u your-name --claude
50
+ mini-trellis doctor
108
51
  ```
109
52
 
110
- Choose or combine flags for the agents you use (`--claude`, `--cursor`, `--codex`, `--opencode`, `--pi`, `--omp`, `--dsh`, `--codebuddy`, `--zcode`, `--kiro`). You can also hand this prompt directly to your agent to install or migrate from Trellis:
53
+ Open a new agent session and save a confirmed decision:
111
54
 
112
55
  ```text
113
- Install or migrate mini-trellis in this project. If the command is missing, run npm install -g mini-trellis first.
114
- If this project has legacy workflow files (for example .trellis/workflow.md, .trellis/scripts/task.py, or inject-*.py), run mini-trellis migrate --dry-run, show me the plan, and run mini-trellis migrate -y after I confirm.
115
- If this is a new project, run mini-trellis init -u <name> -y with only the tools I actually use (--claude, --codex, --opencode, --pi, --omp, --dsh, --cursor, --codebuddy, --zcode, --kiro). For OpenCode, new projects default to V2; existing entries are preserved. Use --opencode-version 1 only for a V1 host.
116
- Then run mini-trellis doctor and report the result. Do not delete .trellis/spec, .trellis/research, or .trellis/workspace.
56
+ Confirmed: transient callback failures allow at most 2 total attempts,
57
+ including the first, only when upstream idempotency is guaranteed.
58
+ Otherwise, and for permanent failures, allow 1 attempt and never retry.
59
+ Save this agreed future policy in the existing project document and use
60
+ mini-trellis-remember to record its link. It is not implemented yet.
117
61
  ```
118
62
 
119
- ### 2. Record a decision worth keeping
120
-
121
- Start a new agent session. For routine edits, just write code. Once you reach a decision or root-cause fix that a future session should know about, ask the agent to save it and run its `remember` command (for example `/mini-trellis:remember` in Claude Code):
63
+ Follow the agent's links to the updated topic and journal. In a new session,
64
+ give it a normal development request:
122
65
 
123
66
  ```text
124
- Confirmed: every callback must carry an idempotency key, and transient failures retry up to 4 attempts total (upstream confirmed idempotency).
125
- Update the existing topic file, or create a spec or research note if none exists, then run remember for this session.
67
+ Implement attempt_limit(failure_kind, upstream_idempotent) in policy.py,
68
+ returning the total number of callback attempts. Add basic tests.
126
69
  ```
127
70
 
128
- The agent updates the existing topic file, which can also be a root `README*.md` or Markdown under `docs/` or `doc/`, and writes a short entry in `.trellis/workspace/<you>/` linking to that file.
129
-
130
- ### Already have chats but no project docs?
131
-
132
- Since 0.3.6, ask the `mini-trellis-session-insight` skill to organize selected sessions or a supplied Markdown/text export. It updates the existing README/docs/spec/research, preserves sources and corrections, and records a verified topic link. Repeating unchanged material adds no journal entry. In your next chat, use `mem recall` to apply that knowledge. See [selected history → project docs → next session](docs/using.md#organize-selected-history-into-project-knowledge).
133
-
134
- ### 3. Recall it in a later session
71
+ Check the generated behavior against the saved conditions. Later, confirm a
72
+ change to 4 attempts for idempotent transient failures, update the same topic,
73
+ and repeat the development request. Keep permanent failures at 1 attempt.
74
+ The [day-to-day guide](docs/using.md) covers starting with existing documents,
75
+ selected history, or a migrated project.
135
76
 
136
- When a later session touches that area—or when you want to check prior reasoning from the terminal—run `recall` to search project Markdown and local conversation history together:
77
+ For a manual lookup, expand a returned `ref` only if its excerpt lacks context:
137
78
 
138
79
  ```bash
139
- mini-trellis mem recall "callback retries"
80
+ mini-trellis mem recall "callback idempotency"
81
+ mini-trellis mem read "<ref-from-recall>"
140
82
  ```
141
83
 
142
- `recall` returns short excerpts, source paths, and `<ref>` handles generated for your project:
84
+ The [installation guide](https://mini-trellis.github.io/install/) covers requirements, trust settings, and verifying your first use.
143
85
 
144
- ```text
145
- [doc] .trellis/spec/backend/callback-retries.md:1 § Callback retries strong
146
- ref: <ref-from-recall>
147
- Transient failures retry up to 4 attempts total (including the initial attempt) after upstream confirmed idempotency; permanent failures run once.
148
-
149
- [session] claude:a8f2c104 strong
150
- ref: <ref-from-recall>
151
- Updated transient callback max_attempts from 2 to 4 after upstream confirmed idempotency guarantees.
152
- ```
153
-
154
- **Usually the short excerpt is enough to proceed.** Only when you need the full section or original conversation turns, copy the `<ref>` printed by `recall` into `read`:
155
-
156
- ```bash
157
- mini-trellis mem read "<ref>"
158
- ```
159
-
160
- ---
161
-
162
- ## Working with project memory
163
-
164
- Consider a billing service where repeated callbacks caused duplicate charges. Once fixed, the rule and its rationale stay in the project for future sessions:
165
-
166
- | What to keep | Location | Example | When a future session uses it |
167
- | --- | --- | --- | --- |
168
- | **Project conventions (`spec`)** | `.trellis/spec/` | Every callback must carry an idempotency key (read `index.md` first) | Before changing the callback handler or boundary contract |
169
- | **Research & evidence (`research`)** | `.trellis/research/` | Retry conditions, alternatives considered, and provider docs (archive old topics under `archive/`) | When the provider changes its API and you need the original rationale |
170
- | **Development notes (`workspace`)** | `.trellis/workspace/<you>/` | Root cause of the duplicate charge, files changed, and verifying tests | When a similar bug report arrives and you want the prior investigation |
171
- | **Local chat history (`mem`)** | Agent's local session store | Original discussion turns, searched in place with `mini-trellis mem` | When distinguishing a rejected proposal from the final agreed decision |
172
-
173
- ### On-demand, not a mandatory ceremony
174
-
175
- - **Just code for routine changes.** You do not create a task before editing, and you do not have to run `remember` at the end of every chat.
176
- - **Look up only when context is missing.** Run `mem recall` when touching unfamiliar rules or prior decisions; stop at the excerpt if it answers your question, and run `mem read "<ref>"` only when you need the full text. For conversation-only search, use `mem search` and `mem context <session-id>`.
177
- - **Record only what future sessions need.** Update an existing topic note when rules evolve, promote lasting boundaries with `mini-trellis-update-spec`, and run `remember` when a session produced a reusable conclusion. New installations write files without auto-committing to Git.
178
-
179
- Keep one current project description in the existing README, docs page, or spec; create a short spec only when none exists. Verify implemented capabilities against code or tests, keep agreed but unimplemented behavior separate, and preserve the document's language. Update stale symbol and path references after a rename. A rename or formatting change alone does not add a journal entry. See [Keep the project description current](./docs/using.md#keep-the-project-description-current).
86
+ ## Supported agents
180
87
 
181
- > Walk through a concrete change in [During a change](./docs/using.md).
88
+ Claude Code · Codex · Cursor · OpenCode V1/V2 · Pi · OMP · Kiro · DeepSeek Harness · CodeBuddy · ZCode
182
89
 
183
- ---
90
+ Combine init flags, such as `--claude --codex`. Native transcript readers support Claude Code, Codex, OpenCode V1, and Pi. See [Agent setup](https://mini-trellis.github.io/agents/) for the knowledge entry, recording command, and setup steps for each tool.
184
91
 
185
- ## Supported tools
92
+ ## Documentation
186
93
 
187
- Combine flags as needed (for example, `mini-trellis init -u your-name --claude --cursor`):
94
+ | What you want to do | Guide |
95
+ | --- | --- |
96
+ | Find and record decisions during development | [Day-to-day use](https://mini-trellis.github.io/using/) |
97
+ | Organize existing conversations | [History](https://mini-trellis.github.io/history/) |
98
+ | Write conventions, research, and journals | [Writing knowledge](https://mini-trellis.github.io/writing-notes/) |
99
+ | Look up options and project settings | [Commands and skills](https://mini-trellis.github.io/commands/) · [Configuration](https://mini-trellis.github.io/configuration/) |
100
+ | Move from Trellis or maintain an installation | [Migration](https://mini-trellis.github.io/migration/) · [Upgrades](https://mini-trellis.github.io/upgrade/) |
101
+ | Diagnose installation or search issues | [Troubleshooting](https://mini-trellis.github.io/troubleshooting/) |
188
102
 
189
- | Agent | Init flag | Record a session | Knowledge & history support |
190
- | --- | --- | --- | --- |
191
- | **Claude Code** | `--claude` | `/mini-trellis:remember` | `SessionStart` injects the short entry; searches project docs and `~/.claude/projects` history |
192
- | **Cursor** | `--cursor` | `mini-trellis-remember` | Installs `.cursor/skills/` and a local `sessionStart` entry, verified on Cursor 3.27.22. Uses `AGENTS.md` and `mem recall` for project knowledge. Cursor-managed cloud agents do not run `sessionStart`. Conversation history is not parsed |
193
- | **Codex** | `--codex` | `$mini-trellis-remember` | Project hook injection and local session history search |
194
- | **OpenCode V1/V2** | `--opencode` | `/mini-trellis:remember` | New projects default to V2; existing V1 entries are preserved. `--opencode-version 1` explicitly selects legacy compatibility. V1 local history is searchable; V2 history is not parsed and produces a warning |
195
- | **CodeBuddy CLI / IDE** | `--codebuddy` | `mini-trellis-remember` skill; CLI also `/mini-trellis:remember` | Shared project settings, skills and SessionStart entry. Project knowledge is searchable; CodeBuddy conversation history is not parsed |
196
- | **Kiro CLI V3 / IDE 1.x** | `--kiro` | `/mini-trellis-remember` | Project skills, SessionStart entry, recording and cross-session recall |
197
- | **ZCode (Z.ai)** | `--zcode` | `$mini-trellis-remember` or the skill | Project startup entry, recording and cross-session recall; shared skills with Codex. Organizes supplied Markdown/text |
198
- | **Pi** | `--pi` | `/mini-trellis-remember [decision]` | Startup entry, project knowledge and local session search |
199
- | **Oh My Pi (OMP)** | `--omp` | `/mini-trellis-remember [decision]` | Native `.omp` extension, prompts and skills; project knowledge recall |
200
- | **DeepSeek Harness** | `--dsh` | `mini-trellis-remember` | Installs `.dsh/skills/`; no project `SessionStart` hook—the model calls `mem recall` / `mem read` when needed |
103
+ The complete guides are also available in the repository's [docs](https://github.com/Tiger-zzZ/mini-trellis/blob/main/docs/index.md).
201
104
 
202
- See [Pi and OMP setup](./docs/using.md#pi-and-omp) for initialization, existing-project refresh and recording examples.
105
+ ## Frequently asked questions
203
106
 
204
- <details>
205
- <summary><strong>Codex trust setup &amp; host-specific boundaries</strong></summary>
107
+ **How does this work with AGENTS.md / CLAUDE.md?** Keep those files as project entry points and maintain detailed knowledge in the existing documents. mini-trellis provides recording skills and unified retrieval.
206
108
 
207
- - **Codex first-time setup**:
208
- 1. Run `codex` in the project and review the project trust prompt. If project-local configuration is disabled, trust the resolved project path in `~/.codex/config.toml`.
209
- 2. Open `/hooks` to review and approve the project hook (`untrusted` hooks stay inactive).
210
- 3. If required by your Codex version, set `hooks = true` under `[features]` in the user config.
211
- 4. Run `mini-trellis doctor`, then start a new session.
212
- - **Host boundaries**:
213
- - DeepSeek Harness has no project-level `SessionStart` hook and does not parse compressed transcripts in `~/.dsh/sessions`;
214
- - Cursor's generated local `sessionStart` entry is verified on Cursor 3.27.22. A successful hook log alone does not prove model delivery or use. Use `AGENTS.md`, the `mini-trellis-remember` skill, and `mini-trellis mem recall`. Cursor-managed cloud agents do not run `sessionStart`; self-hosted machines remain unverified. Cursor conversation history is not parsed;
215
- - OpenCode V2 (tested on 2.2.0) is the default development target. V1 (tested on 1.18.29) remains a legacy compatibility option with a separate plugin protocol. Ordinary refresh preserves the installed protocol. V2 rebuilds a bounded entry in each outgoing request without saving it to conversation history. Only V1 history is parsed; neither protocol provides precise compact recovery.
216
- - In ZCode Desktop, review and trust the project hook in **Settings → Hooks**, then start a new session. After compact, follow `AGENTS.md` to read saved knowledge. See [setup](./docs/using.md#zcode-zai).
217
- - CodeBuddy CLI and IDE share `.codebuddy/settings.json` and `.codebuddy/skills/`. See [setup](./docs/using.md#codebuddy-cli-and-ide).
218
- - Pi supports session listing and search without precise compact boundary recovery.
109
+ **What should I save explicitly?** Decisions, investigations, and fixes that will help a later change. Routine edits follow your own development process.
219
110
 
220
- </details>
111
+ **Where does the data live?** The CLI reads local document and conversation files. Project knowledge can be shared through Git; an agent may send retrieved text to its configured model provider.
221
112
 
222
- ---
113
+ [Read the full FAQ](https://mini-trellis.github.io/faq/).
223
114
 
224
- ## Migrating from Trellis & upgrading
115
+ ## Measured results
225
116
 
226
- Existing `Trellis` projects can be converted in place with `migrate` (both tools share `.trellis/`, so migrate rather than installing both side by side):
117
+ In the published Claude Code comparison, mini-trellis v0.3.1 versus Trellis v0.7.0-beta.4 across six task groups with three runs each used **38.4% less total wall time** and **40.1% fewer processed tokens**. These are historical measurements for the tested versions and configuration. Processed tokens include cache reads and are not a direct measure of cost.
227
118
 
228
- ```bash
229
- mini-trellis migrate --dry-run # Preview the migration plan
230
- mini-trellis migrate # Apply after confirmation
231
- ```
232
-
233
- - **Retains existing knowledge**: Keeps `.trellis/spec/`, `.trellis/research/`, and `.trellis/workspace/` journals intact.
234
- - **Folds task directories cleanly**: Moves task research into `.trellis/research/`, archives other task artifacts under `legacy/` by default, and replaces Trellis workflow files and scripts with `mini-trellis`.
235
- - **Keeps local state private**: Adds a missing `.trellis/.gitignore` during migration or when adding a host; existing user ignore rules are kept. This does not untrack files already in Git.
236
-
237
- <details>
238
- <summary><strong>Upgrading (`upgrade` / `refresh`) &amp; uninstalling</strong></summary>
239
-
240
- Run from the project root:
241
-
242
- ```bash
243
- mini-trellis upgrade # Update the global CLI and refresh this initialized project
244
- mini-trellis doctor # Check installation status
245
- ```
246
-
247
- From 0.3.8 onward, `upgrade` runs the new CLI to refresh the current project after npm succeeds. Other projects can be refreshed separately. Normal managed updates run directly. When file replacements need confirmation, refresh lists the files and asks once `[y/N]`. Enter `Y` to replace them and finish the update; `N` or Enter keeps all project files. Outside an initialized project, `upgrade` updates the CLI only.
248
-
249
- When updating with `npm install -g mini-trellis@latest`, or running `upgrade` from 0.3.7 or earlier, refresh the project once afterward:
250
-
251
- ```bash
252
- mini-trellis refresh --dry-run # Preview managed asset updates
253
- mini-trellis refresh # Update managed files while preserving knowledge
254
- mini-trellis doctor # Check installation status
255
- ```
119
+ See [Benchmarks](https://mini-trellis.github.io/benchmarks/) for the environment, per-task results, and separate injected-character experiment.
256
120
 
257
- - Inspect configured tools with `mini-trellis platforms`.
258
- - Before running `mini-trellis uninstall`, check `mini-trellis uninstall --help`: uninstall removes `.trellis/`, including knowledge files. See the [migration guide](./docs/migration.md) for path mappings and conflict handling.
121
+ ## Contributing and license
259
122
 
260
- </details>
123
+ Share feedback through [Issues](https://github.com/Tiger-zzZ/mini-trellis/issues), or follow the [contribution guide](https://github.com/Tiger-zzZ/mini-trellis/blob/main/CONTRIBUTING.md).
261
124
 
262
- ---
125
+ Licensed under [AGPL-3.0](https://github.com/Tiger-zzZ/mini-trellis/blob/main/LICENSE).
263
126
 
264
- ## Contributing & license
127
+ ## Star History
265
128
 
266
- Bug reports and practical examples are welcome in [Issues](https://github.com/Tiger-zzZ/mini-trellis/issues). For local development, see [CONTRIBUTING](./CONTRIBUTING.md). For releases, follow the [maintenance workflow](./docs/maintenance-workflow.md). Community: [Linux.do](https://linux.do/).
129
+ [![Star History](https://img.shields.io/badge/Star_History-view_chart-28785e?style=for-the-badge&logo=github&logoColor=white&labelColor=173f35)](https://www.star-history.com/?repos=Tiger-zzZ%2Fmini-trellis&type=date&legend=top-left)
267
130
 
268
- mini-trellis evolved from the open-source [Trellis](https://github.com/mindfold-ai/Trellis) project. Thanks to the early contributors for the foundation. Released under [AGPL-3.0](./LICENSE). Original copyright Mindfold LLC; modification notices and contributor attribution are retained in [COPYRIGHT](./COPYRIGHT).
131
+ [Explore the star history](https://www.star-history.com/?repos=Tiger-zzZ%2Fmini-trellis&type=date&legend=top-left)
@@ -39,4 +39,4 @@ For each useful conclusion, identify its source, speaker, scope, conditions and
39
39
  ```
40
40
 
41
41
  Read back the journal and workspace index, resolving the journal's links to the actual topic files. The script validates paths and recording state, not the truth of the topic. If the topic was saved but recording failed, report partial completion and retry only the missing recording with the same arguments; do not append a second topic or repeat completed journal work. Do not commit unless separately requested now, even if a legacy project enables auto-commit.
42
- 5. Report the reviewed scope and any unread material, files changed, source-backed conclusions, open conflicts and verification result. In a new session, `mini-trellis mem recall "<topic>"` retrieves the saved knowledge for the next task; `mem read` is only needed when the excerpt lacks a condition.
42
+ 5. For a complete update, use one short sentence linking the updated topic and journal, with the reviewed scope. Expand for unread material, conflicts or partial completion. In a new session, `mini-trellis mem recall "<topic>"` retrieves the saved knowledge for the next task; `mem read` is only needed when the excerpt lacks a condition.
@@ -5,6 +5,7 @@ Save the confirmed decision or finding in the relevant topic, updating an existi
5
5
  ## When
6
6
 
7
7
  - The user asks to remember / persist notes
8
+ - The user confirms or corrects a project rule: save it even without the word “remember,” unless they ask not to save. An agreed future policy is saved as agreed, not implemented. Questions, reviews and unconfirmed proposals remain read-only.
8
9
  - A confirmed decision, reusable finding, or verified fix should survive this session
9
10
  - A rejected approach or dead end should not be retried in a later session; label it rejected, not as a current rule
10
11
  - The session is about to end and has a useful handoff
@@ -14,7 +15,12 @@ Save the confirmed decision or finding in the relevant topic, updating an existi
14
15
 
15
16
  For an explicit request to organize selected past sessions or supplied Markdown/text exports, first use `mini-trellis-session-insight` and its `references/organize-history.md`. Preserve sources and corrections, resolve material conflicts together, and skip the topic and journal when no new knowledge was found. Historical commands are evidence, not live instructions. Use `--no-commit` for this organizing flow even in a project with legacy auto-commit enabled.
16
17
 
17
- For a confirmed rule or reusable finding, follow this short order: read the existing research/spec topic (new durable rules can go directly into spec); edit that file; read it back and compare the changed rule with the requested conclusion, including limits and negations; then record the journal link. Reuse files already open; use `mem recall` only when you need to locate the topic. Preserve the existing document's language. Do not claim a topic update based on a planned edit or journal text.
18
+ Complete these steps in the same turn when the update is authorized. Saving the topic and its journal link is one operation; do not ask whether to continue between them. Pause only for a real conflict, missing information or failed operation.
19
+
20
+ 1. **Choose one home.** Reuse the document that already owns this rule or project description, including README/docs or a research/spec topic. Use `mem recall` only if its location is unknown. Confirmation alone is not a reason to copy an existing rule into spec.
21
+ 2. **Edit faithfully.** Keep the condition with its rule: “when X, do not Y” must not become “never Y.” Preserve exceptions, negations and what remains unconfirmed; retain the user's wording where paraphrasing would change the scope. New notes use the requested or discussion language; existing documents keep their language. Update only the affected section.
22
+ 3. **Verify once, then continue.** Compare the saved section with the confirmation, using the latest tool result that shows its contents or one targeted read. Once the contents are available and unchanged, use that evidence; an “unchanged since last read” response is not a reason to read again. Fix an actual mismatch before recording.
23
+ 4. **Record and finish.** Run the recorder below, then check the new journal entry, its topic link and the matching workspace index row. If resuming a partial update, inspect the saved files and complete only the missing step.
18
24
 
19
25
  Then record a short journal entry using the existing script; no CLI `spec` or `update-spec` subcommand is needed:
20
26
 
@@ -26,11 +32,13 @@ python3 ./.trellis/scripts/add_session.py \
26
32
  --topic .trellis/research/example.md
27
33
  ```
28
34
 
29
- Replace `--topic` with the actual file just verified, or omit it for a handoff without a topic. It validates the file and adds its path to the journal; it does not write the topic or check its meaning. Do not pass an invented path. Read back the resulting journal entry to verify its link before reporting completion. If only the topic or journal was saved, name the completed part and the missing part; retry only the missing work.
35
+ Replace `--topic` with the actual file just verified, or omit it for a handoff without a topic. The script validates the path and recording state; the content comparison above checks the meaning. If recording fails, retain the verified topic and retry only the missing work with the same arguments.
30
36
 
31
37
  `--commit` already defaults to `-` (no git evidence). Add `--change`, `--test`, `--next-step` when they help a future session. Use `--stdin` for longer notes.
32
38
 
33
- If this session produced reusable research, write `.trellis/research/<topic>.md` and mention that path in the summary. Promote durable boundaries into `.trellis/spec/` with `mini-trellis-update-spec` (short markdown).
39
+ If the user forbids commits, pass `--no-commit`: it still writes journal/index and skips staging/committing, regardless of project auto-commit. Use `add_session.py --help` for option details.
40
+
41
+ Use `.trellis/research/<topic>.md` for reusable research with no existing home. When promoting a topic with `mini-trellis-update-spec`, keep one current rule body and link to it from the old location.
34
42
 
35
43
  ## Project status
36
44
 
@@ -38,7 +46,7 @@ When the user asks what the project is today, or a confirmed capability or archi
38
46
 
39
47
  - Update the README, docs page, or spec section that already states it. Create a short `.trellis/spec/` note only when no such file exists. Do not copy the same description into a second file.
40
48
  - Write the purpose, implemented capabilities, main modules, and constraints. Check capability claims against current code or tests; a confirmed decision alone does not prove implementation. A constant or configuration value does not prove the behavior that would use it. Keep planned or agreed behavior separate from implemented capabilities. A suggestion stays a suggestion, or is labeled unverified.
41
- - Edit only the affected section. An ordinary rename or formatting change does not trigger a full rewrite or get a journal entry. Still update any symbol or path references made stale by that change.
49
+ - When implementation changes an existing description, update the affected README/docs/spec/research section in the same development turn, including stale “planned” or “not implemented” statements. This maintenance is part of the implementation; it does not require a separate remember request or a new journal entry. A confirmed future rule stays labeled as a plan until implemented.
42
50
  - Keep the file's language. A Chinese discussion updates an English description in English, with the same meaning, limits, and negations.
43
51
  - Link that verified file from the journal with `--topic`. A root `README*.md` or a Markdown file under `docs/` or `doc/` is accepted, as are spec and research notes. The journal does not replace the description.
44
52
 
@@ -47,3 +55,7 @@ When the user asks what the project is today, or a confirmed capability or archi
47
55
  Before writing a topic, use `mini-trellis mem recall "<topic>"` if the relevant notes are not already open. Expand needed evidence with `mini-trellis mem read "<ref>"`. Update the existing research/spec section; record the scope and sources, distinguish user confirmation from measured facts and inference, and keep a link when replacing an earlier decision. Journal should briefly describe the work and link to the topic, not repeat its body.
48
56
 
49
57
  Skip ordinary turns and changes that add no reusable knowledge. Write new notes in the user's requested language, otherwise the discussion language; preserve the language of an existing document. Do not translate paths or identifiers. Check the writer's result and report failures; never claim notes were saved after an error. Closing a window or a crash does not guarantee a final write.
58
+
59
+ ## Reply
60
+
61
+ For a memory-only request, the complete reply is one short sentence with Markdown links to the actual topic and journal, in the discussion language: `Updated [topic](<actual-topic-path>) and recorded [session](<actual-journal-path>).` Substitute real paths; a path in backticks is not a link. Do not repeat the rule or list routine checks. For a larger development request, report the requested development result and include the links briefly. Explain a conflict or partial completion when one remains. Ordinary edits without new reusable knowledge need no memory report.
@@ -11,15 +11,19 @@ Capture durable contracts and conventions into `.trellis/spec/` as short markdow
11
11
  ## Write
12
12
 
13
13
  - Check the existing topic first (`mini-trellis mem recall "<topic or path>"` when needed); update the relevant section instead of duplicating it.
14
- - If a README or docs page already states the project description, update that section when the confirmed boundary belongs there. Add a spec file only for a durable rule that has no home. Do not keep two copies.
14
+ - If a README, docs or research topic already owns the rule or project description, update it there. Confirmation alone does not require a new spec. When promoting a topic into spec, keep the current rule in spec and replace the old current-rule body with a short status/source link; preserve distinct research and history.
15
15
  - Record confirmed rules, scope, and sources. Check implemented-capability claims against current code or tests; a confirmed decision, constant, or configuration value alone does not prove implementation. Keep agreed behavior separate from implemented capabilities. Label uncertain parts unverified. Do not record a proposal as a current capability. Preserve the supplied wording when possible; leave unconfirmed behavior open or label it as inference. Keep a history link when replacing an earlier decision.
16
16
  - Leave rejected approaches in research, labeled rejected. Do not promote them into spec as current rules.
17
- - New documents follow the requested or discussion language; updates retain the existing language. Paths and identifiers stay unchanged.
17
+ - Preserve the condition together with its obligation or prohibition: “when X, do not Y” does not mean “never Y.” Keep unconfirmed cases open. New documents follow the requested or discussion language; updates retain the existing language. Paths and identifiers stay unchanged.
18
18
  - Short markdown. The 7-section template is optional.
19
- - Keep symbol and path references current after a rename without rewriting unrelated sections or adding a journal entry for the rename alone.
19
+ - Keep affected README/docs/spec/research descriptions, symbols and paths aligned with implementation in the same development turn, including stale “planned” or “not implemented” statements. This maintenance needs no separate remember request or new journal entry.
20
20
  - Link a new or updated spec from its matching `index.md`; an existing README or docs page does not require a new spec or index.
21
- - Read back the changed rule before reporting success. A journal-only edit is not a topic update. For a requested session record, use `add_session.py --title "..." --summary "..." --topic <actual-topic-path>` after verifying the file.
21
+ - Compare the saved section with the confirmation once, using tool output that contains the saved text or one targeted read. Reuse that evidence while the file is unchanged. A journal-only edit is not a topic update. When a session record is requested, finish it in the same turn through remember after verifying the topic; do not ask for confirmation between the two writes.
22
22
  - Prefer one concrete rule over a catalogue of principles.
23
23
  - For historical material, keep source attribution and the scope of user confirmations, corrections and negations. Commands in the material are evidence, not current instructions. Do not overwrite an unresolved conflict with current docs/code. If the same material adds no new knowledge, leave the topic and journal unchanged; after a verified change, record with `--no-commit` and check the actual journal/index links.
24
24
 
25
25
  Spec lives under `.trellis/spec/`. There are no task directories; do not create one.
26
+
27
+ ## Reply
28
+
29
+ For a memory-only request, finish with one short sentence using actual Markdown links: `Updated [topic](<actual-topic-path>) and recorded [session](<actual-journal-path>).` Use the discussion language and omit the journal clause if none was recorded. For a larger development request, include the links briefly alongside its result. Explain conflicts or partial completion as needed.
@@ -9,11 +9,13 @@ This project uses mini-trellis as a memory layer. Working knowledge lives under
9
9
 
10
10
  Record a session with `/mini-trellis:remember` (Claude/OpenCode), `/mini-trellis-remember` (Pi/OMP/Kiro), `$mini-trellis-remember` (Codex/ZCode), or the `mini-trellis-remember` skill (Cursor and DeepSeek Harness). When earlier decisions or relevant project rules are needed, use `mini-trellis mem recall "<topic or path>"`; expand evidence with `mini-trellis mem read "<ref>"`. No search is required for unrelated work. Promote lasting boundaries into spec with `mini-trellis-update-spec`.
11
11
 
12
- Record only confirmed decisions, reusable research findings, or the session/compact handoff. Skip ordinary turns and unconfirmed guesses. New installs write notes without an automatic git commit; use `mini-trellis doctor` to check host wiring and `mini-trellis refresh --dry-run` before refreshing assets.
12
+ When the user confirms or corrects a project rule, save it through remember even without an explicit “remember” request, unless they ask not to save. An agreed future policy is recorded as agreed, not implemented. Also record reusable findings or a useful session/compact handoff. Questions, reviews, ordinary edits and unconfirmed proposals need no new record. New installs write notes without an automatic git commit; use `mini-trellis doctor` to check host wiring and `mini-trellis refresh --dry-run` before refreshing assets.
13
13
 
14
- Keep confirmed rules short and faithful. Unconfirmed scope, exceptions, and implementation choices stay open or are labeled as inference, not added to the contract.
14
+ Keep one current rule in the document that already owns it. Preserve conditions with their rules: “when X, do not Y” must not become “never Y.” Unconfirmed scope, exceptions, and implementation choices stay open or are labeled as inference, not added to the contract.
15
15
 
16
- For a confirmed update, follow this short order: read the existing topic; edit that file; read it back and check the new rule, limits, and negations; run `python3 ./.trellis/scripts/add_session.py --title "..." --summary "..." --topic <actual-topic-path>`; read the journal and check its topic link. Journal-only success is not topic success; report partial writes accurately. New notes follow the requested or discussion language; updates preserve the document language.
16
+ For a confirmed update, use remember to edit the existing topic, verify the saved section once, record the journal link, and check the new entry/index row. Complete these authorized steps in the same turn without asking again between writes. Reuse returned file contents while unchanged instead of repeating reads. Journal-only success is not topic success; report partial writes accurately. New notes follow the requested or discussion language; updates preserve the document language.
17
+
18
+ For a memory-only update, reply with one short sentence using actual topic and journal Markdown links; expand for conflicts or partial writes. In a development task, include the links briefly with the requested result. Update affected README/docs/spec/research descriptions, including stale implementation status, in the same turn as the code. This maintenance needs no separate remember request or new journal entry.
17
19
 
18
20
  When recall excerpts already answer the question with source and qualifiers, cite them and stop. Expand only missing context; do not repeat a lookup or fall back to dialogue-only `search` merely to reconfirm sufficient evidence.
19
21
 
@@ -21,9 +21,9 @@
21
21
 
22
22
  ## Remember
23
23
 
24
- Save confirmed decisions and reusable findings in the relevant spec/research topic, updating an existing topic when possible. If a README or docs page already states the project description, update that file instead of copying it into a new note. Check the saved content, then record a short journal entry linking to it:
24
+ When the user confirms or corrects a project rule, use remember even without an explicit “remember” request, unless they ask not to save. Record future policy as agreed, not implemented. Finish the authorized update in one turn: update the document that already owns the rule, compare the saved section once, then record and verify its journal link. Reuse returned contents while unchanged. Existing README/docs/research/spec topics are valid homes; confirmation alone does not require a second copy in spec.
25
25
 
26
- Keep confirmed rules short and faithful. Unconfirmed scope, exceptions, and implementation choices stay open or are labeled as inference, not added to the contract.
26
+ Keep conditions with their rules: “when X, do not Y” must not become “never Y.” Unconfirmed scope, exceptions, and implementation choices stay open or are labeled as inference, not added to the contract.
27
27
 
28
28
  ```bash
29
29
  python3 ./.trellis/scripts/add_session.py \
@@ -35,7 +35,11 @@ python3 ./.trellis/scripts/add_session.py \
35
35
 
36
36
  Use the actual topic path; omit `--topic` for a handoff without a topic. The script writes journal/index and a relative topic link; it does not edit the topic. Verify the files before reporting completion. Skip ordinary changes and unconfirmed ideas. New notes follow the discussion language; updates keep the original document's language.
37
37
 
38
- Promote durable boundaries into `.trellis/spec/` and link them from the matching `index.md`. Cold research can move into `.trellis/research/archive/`. When a whole note is replaced, leave a superseded mark on the old note pointing at the new path instead of deleting history:
38
+ For a verified memory-only update, use one short sentence with actual topic and journal Markdown links; include them briefly with the result of a larger development request. Expand for a conflict or partial completion. A saved record does not establish that development or tests succeeded. A failed index update keeps the journal: repair the reported structure and retry the same command. Same-checkout recording is serialized; separate worktrees and direct topic edits still need conflict review.
39
+
40
+ When implementation changes make an existing README/docs/spec/research description stale, update the affected section and implementation status in the same development turn. This maintenance needs no separate remember request or new journal entry. Questions, reviews, ordinary edits and unconfirmed proposals need no memory report.
41
+
42
+ When promoting a boundary into `.trellis/spec/`, link it from the matching `index.md` and replace the old current-rule body with a short source/status link. Keep distinct research and history. Cold research can move into `.trellis/research/archive/`. When a whole note is replaced, leave a superseded mark on the old note pointing at the new path instead of deleting history:
39
43
 
40
44
  ```markdown
41
45
  ---
@@ -75,6 +75,20 @@ MAX_CONTEXT_CHARS = 4000
75
75
  RUNTIME_STATUS_VERSION = 1
76
76
  _LAST_PROJECT_DIR: Path | None = None
77
77
 
78
+
79
+ def _resolve_project_dir(start: Path) -> Path:
80
+ """Use the same nearest-project/Git boundary as recording and recall."""
81
+ current = start.resolve()
82
+ while True:
83
+ trellis = current / ".trellis"
84
+ if trellis.is_dir() and not trellis.is_symlink():
85
+ return current
86
+ if (current / ".git").exists():
87
+ return current
88
+ if current == current.parent:
89
+ return start.resolve()
90
+ current = current.parent
91
+
78
92
  # Force UTF-8 on stdin/stdout/stderr on Windows. Default codepage there is
79
93
  # cp936 / cp1252 / etc. — non-ASCII content (Chinese task names, prd snippets)
80
94
  # both in stdin (hook payload from host CLI) and stdout (our emitted blocks)
@@ -538,6 +552,8 @@ def _write_runtime_status(trellis_dir: Path, platform: str | None, status: str,
538
552
  try:
539
553
  host = {"claude": "claude-code", "droid": "factory"}.get(platform or "", platform or "unknown")
540
554
  target = trellis_dir / ".runtime" / "hooks" / f"{host}.json"
555
+ if not target.resolve().is_relative_to(trellis_dir.parent.resolve()):
556
+ raise OSError("hook diagnostics escape the project")
541
557
  target.parent.mkdir(parents=True, exist_ok=True)
542
558
  payload = {"schema": 1, "platform": host, "last_hook_at": datetime.now(timezone.utc).isoformat(), "last_status": status, "last_output_chars": max(0, int(output_chars))}
543
559
  if error_category: payload["last_error_category"] = error_category
@@ -588,8 +604,13 @@ def _main_impl():
588
604
  break
589
605
  if project_dir is None:
590
606
  project_dir = Path(_normalize_windows_shell_path(hook_input.get("cwd", "."))).resolve()
607
+ project_dir = _resolve_project_dir(project_dir)
591
608
 
592
609
  trellis_dir = project_dir / ".trellis"
610
+ if not trellis_dir.is_dir() or trellis_dir.is_symlink():
611
+ # An independent, uninitialized project must not borrow parent state
612
+ # or become initialized merely because an inherited hook ran here.
613
+ return
593
614
  global _LAST_PROJECT_DIR
594
615
  _LAST_PROJECT_DIR = project_dir
595
616
  context_key = _resolve_context_key(trellis_dir, hook_input)
@@ -637,11 +658,15 @@ mini-trellis SessionStart context. Orient from journal, spec, and research.
637
658
  "approaches, and project rules. If the excerpt answers the question with its "
638
659
  "source and conditions, cite it and stop; use `mini-trellis mem read <ref>` "
639
660
  "only for missing context. Do not repeat a sufficient lookup.\n"
640
- "Research lives in `.trellis/research/`; durable rules belong in `.trellis/spec/`.\n"
641
- "Record a confirmed decision, a rejected approach worth not retrying, or a useful "
642
- f"handoff with `{remember_command}` or "
643
- "`python3 ./.trellis/scripts/add_session.py`. The remember command has the write "
644
- "steps. Do not record every turn, and do not create a git commit unless the user asks.\n"
661
+ "Keep one current rule in its existing document. On a confirmed or corrected rule, "
662
+ f"run `{remember_command}` even without an explicit remember request, unless told "
663
+ "not to save. Future policy is agreed, not implemented. Finish topic, verification "
664
+ "and journal together; reuse unchanged file contents. Preserve conditions and "
665
+ "negations. New notes follow the discussion language; updates keep theirs.\n"
666
+ "Memory-only reply: one short sentence with topic/journal Markdown links; explain "
667
+ "conflicts or partial writes. With implementation, update stale README/docs/spec/research "
668
+ "descriptions and status; no separate remember request or journal is needed. Questions, "
669
+ "reviews and unconfirmed proposals need no recording. Commit only when asked.\n"
645
670
  )
646
671
 
647
672
  if source == "compact" and platform in {"cursor", "codebuddy", "zcode"}: