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 +77 -214
- package/dist/templates/common/bundled-skills/mini-trellis-session-insight/references/organize-history.md +1 -1
- package/dist/templates/common/commands/remember.md +16 -4
- package/dist/templates/common/skills/update-spec.md +8 -4
- package/dist/templates/markdown/agents.md +5 -3
- package/dist/templates/markdown/spec/guides/mini-memory.md.txt +7 -3
- package/dist/templates/shared-hooks/session-start.py +30 -5
- package/dist/templates/trellis/gitattributes.txt +5 -6
- package/dist/templates/trellis/scripts/add_session.py +241 -175
- package/dist/templates/trellis/scripts/common/paths.py +12 -5
- package/dist/templates/trellis/scripts/common/recording_lock.py +71 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,268 +1,131 @@
|
|
|
1
|
-
<h1 align="center">
|
|
2
|
-
|
|
3
|
-
<
|
|
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
|
-
|
|
7
|
-
<
|
|
11
|
+
<a href="https://www.npmjs.com/package/mini-trellis"><img src="https://img.shields.io/npm/v/mini-trellis?style=flat-square&logo=npm&logoColor=white&labelColor=173f35&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&logo=npm&logoColor=white&label=downloads&labelColor=173f35&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&logo=readthedocs&logoColor=white&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&labelColor=173f35" alt="AGPL-3.0 license" /></a>
|
|
8
15
|
</p>
|
|
9
16
|
|
|
10
|
-
<p align="center">
|
|
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://
|
|
25
|
-
<a href="
|
|
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
|
-
|
|
29
|
-
|
|
30
|
-

|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-

|
|
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
|
+

|
|
96
42
|
|
|
97
43
|
## Quick start
|
|
98
44
|
|
|
99
|
-
Requires
|
|
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
|
-
|
|
53
|
+
Open a new agent session and save a confirmed decision:
|
|
111
54
|
|
|
112
55
|
```text
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
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
|
-
|
|
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
|
-
|
|
125
|
-
|
|
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
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
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
|
-
|
|
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
|
|
80
|
+
mini-trellis mem recall "callback idempotency"
|
|
81
|
+
mini-trellis mem read "<ref-from-recall>"
|
|
140
82
|
```
|
|
141
83
|
|
|
142
|
-
|
|
84
|
+
The [installation guide](https://mini-trellis.github.io/install/) covers requirements, trust settings, and verifying your first use.
|
|
143
85
|
|
|
144
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
92
|
+
## Documentation
|
|
186
93
|
|
|
187
|
-
|
|
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
|
-
|
|
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
|
-
|
|
105
|
+
## Frequently asked questions
|
|
203
106
|
|
|
204
|
-
|
|
205
|
-
<summary><strong>Codex trust setup & 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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
115
|
+
## Measured results
|
|
225
116
|
|
|
226
|
-
|
|
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
|
-
|
|
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`) & 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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
127
|
+
## Star History
|
|
265
128
|
|
|
266
|
-
|
|
129
|
+
[](https://www.star-history.com/?repos=Tiger-zzZ%2Fmini-trellis&type=date&legend=top-left)
|
|
267
130
|
|
|
268
|
-
|
|
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.
|
|
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
|
-
|
|
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.
|
|
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
|
|
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
|
-
-
|
|
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
|
|
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
|
|
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
|
-
-
|
|
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
|
-
|
|
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
|
|
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,
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
"
|
|
641
|
-
"
|
|
642
|
-
|
|
643
|
-
"
|
|
644
|
-
"
|
|
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"}:
|