cxs is a local-first CLI for searching Codex session logs. It is designed for progressive retrieval: find the right session first, then read
mainline: init
+635
+38
.cursor/rules/mainline.md
+38
.cursor/rules/mainline.md
···
1
+
<!-- mainline:agents:start version=12 checksum=sha256:bb93a86dcc1512ce1f81dfd84c14e6714261d252997e36eda3e1041a515273ba -->
2
+
## Mainline
3
+
4
+
<!-- mainline-agents-md-version: 8 -->
5
+
6
+
This project uses **Mainline** for AI-driven intent tracking and
7
+
conflict detection. The full agent workflow lives in `AGENTS.md` at
8
+
the repo root — read that file for the complete contract.
9
+
10
+
Quick reference:
11
+
12
+
```
13
+
mainline status # see your state
14
+
15
+
# Read team intents for context (do this aggressively):
16
+
mainline log --json --limit 30 # recent intents
17
+
mainline show <intent_id> --json # full why/decisions/risks
18
+
mainline list-proposals --json # what's in flight
19
+
20
+
# Write your own intent:
21
+
mainline start "<goal>" # claim work
22
+
mainline append "<what changed>" # after each turn
23
+
git add ... && git commit -m ... # commit code
24
+
mainline seal --prepare > .ml-cache/seal.json # patch the starter
25
+
mainline seal --submit < .ml-cache/seal.json # auto syncs + checks
26
+
```
27
+
28
+
Sync, pin, merge are automatic — do not invoke them.
29
+
30
+
### If `mainline hooks` is installed for your agent
31
+
32
+
When hooks are active, the only thing that changes is sessionStart:
33
+
the hook runs `mainline sync` + `mainline status` for you and injects
34
+
the snapshot into your system context. Every other workflow step
35
+
(start / append / commit / seal --prepare / seal --submit / check)
36
+
remains agent-driven exactly as `AGENTS.md` describes. Hooks are a
37
+
context provider, not a workflow driver.
38
+
<!-- mainline:agents:end -->
+14
.github/PULL_REQUEST_TEMPLATE.md
+14
.github/PULL_REQUEST_TEMPLATE.md
+38
.github/copilot-instructions.md
+38
.github/copilot-instructions.md
···
1
+
<!-- mainline:agents:start version=12 checksum=sha256:bb93a86dcc1512ce1f81dfd84c14e6714261d252997e36eda3e1041a515273ba -->
2
+
## Mainline
3
+
4
+
<!-- mainline-agents-md-version: 8 -->
5
+
6
+
This project uses **Mainline** for AI-driven intent tracking and
7
+
conflict detection. The full agent workflow lives in `AGENTS.md` at
8
+
the repo root — read that file for the complete contract.
9
+
10
+
Quick reference:
11
+
12
+
```
13
+
mainline status # see your state
14
+
15
+
# Read team intents for context (do this aggressively):
16
+
mainline log --json --limit 30 # recent intents
17
+
mainline show <intent_id> --json # full why/decisions/risks
18
+
mainline list-proposals --json # what's in flight
19
+
20
+
# Write your own intent:
21
+
mainline start "<goal>" # claim work
22
+
mainline append "<what changed>" # after each turn
23
+
git add ... && git commit -m ... # commit code
24
+
mainline seal --prepare > .ml-cache/seal.json # patch the starter
25
+
mainline seal --submit < .ml-cache/seal.json # auto syncs + checks
26
+
```
27
+
28
+
Sync, pin, merge are automatic — do not invoke them.
29
+
30
+
### If `mainline hooks` is installed for your agent
31
+
32
+
When hooks are active, the only thing that changes is sessionStart:
33
+
the hook runs `mainline sync` + `mainline status` for you and injects
34
+
the snapshot into your system context. Every other workflow step
35
+
(start / append / commit / seal --prepare / seal --submit / check)
36
+
remains agent-driven exactly as `AGENTS.md` describes. Hooks are a
37
+
context provider, not a workflow driver.
38
+
<!-- mainline:agents:end -->
+35
.mainline/config.toml
+35
.mainline/config.toml
···
1
+
[mainline]
2
+
schema_version = 1
3
+
main_branch = "main"
4
+
actor_log_prefix = "_mainline/actor"
5
+
require_seal_before = "push"
6
+
remote = "origin"
7
+
[mainline.skip]
8
+
patterns = ["^Merge pull request ", "^Merge branch ", "^chore: bump version", "^mainline: init"]
9
+
10
+
[sync]
11
+
auto_sync = true
12
+
interval = "30s"
13
+
freshness_seconds = 300
14
+
stale_threshold_seconds = 86400
15
+
auto_check_after_sync = true
16
+
auto_pin_after_sync = true
17
+
18
+
[check]
19
+
auto_check = true
20
+
lookback = 50
21
+
phase1_threshold = 0.1
22
+
require_before_merge = false
23
+
24
+
[publish]
25
+
auto_publish = false
26
+
27
+
[merge]
28
+
strategy = "squash"
29
+
30
+
[log]
31
+
default_limit = 20
32
+
33
+
[hooks]
34
+
enabled = false
35
+
auto_sync_on_session_start = false
+38
.windsurfrules
+38
.windsurfrules
···
1
+
<!-- mainline:agents:start version=12 checksum=sha256:bb93a86dcc1512ce1f81dfd84c14e6714261d252997e36eda3e1041a515273ba -->
2
+
## Mainline
3
+
4
+
<!-- mainline-agents-md-version: 8 -->
5
+
6
+
This project uses **Mainline** for AI-driven intent tracking and
7
+
conflict detection. The full agent workflow lives in `AGENTS.md` at
8
+
the repo root — read that file for the complete contract.
9
+
10
+
Quick reference:
11
+
12
+
```
13
+
mainline status # see your state
14
+
15
+
# Read team intents for context (do this aggressively):
16
+
mainline log --json --limit 30 # recent intents
17
+
mainline show <intent_id> --json # full why/decisions/risks
18
+
mainline list-proposals --json # what's in flight
19
+
20
+
# Write your own intent:
21
+
mainline start "<goal>" # claim work
22
+
mainline append "<what changed>" # after each turn
23
+
git add ... && git commit -m ... # commit code
24
+
mainline seal --prepare > .ml-cache/seal.json # patch the starter
25
+
mainline seal --submit < .ml-cache/seal.json # auto syncs + checks
26
+
```
27
+
28
+
Sync, pin, merge are automatic — do not invoke them.
29
+
30
+
### If `mainline hooks` is installed for your agent
31
+
32
+
When hooks are active, the only thing that changes is sessionStart:
33
+
the hook runs `mainline sync` + `mainline status` for you and injects
34
+
the snapshot into your system context. Every other workflow step
35
+
(start / append / commit / seal --prepare / seal --submit / check)
36
+
remains agent-driven exactly as `AGENTS.md` describes. Hooks are a
37
+
context provider, not a workflow driver.
38
+
<!-- mainline:agents:end -->
+432
AGENTS.md
+432
AGENTS.md
···
112
112
3. 更重的 reranker / projection / diversity 控制放后面
113
113
114
114
具体 roadmap 见 [docs/ROADMAP.md](/Users/envvar/work/repos/cxs/docs/ROADMAP.md)。
115
+
116
+
<!-- mainline:agents:start version=12 checksum=sha256:62ee66d15a420f45eb3c1403cffe332072b56e14044597a18ddcc71fa14a0d83 -->
117
+
## Mainline
118
+
119
+
<!-- mainline-agents-md-version: 12 -->
120
+
121
+
**Mainline is a git-native intent memory layer for AI-assisted engineering.**
122
+
It gives coding agents the historical *why* before they inspect the
123
+
current *what*.
124
+
125
+
This project uses Mainline to record the intent behind every AI-driven
126
+
change and to surface conflicts between intents before they reach a PR
127
+
review. The agent is expected to both **read** team intents (for context)
128
+
and **write** its own intent (for the work it's doing). Both halves
129
+
matter — intents capture *why* changes were made, which is information
130
+
the diff alone cannot give you.
131
+
132
+
> **v0.3 invariant**: every commit on `main` is in exactly one of three
133
+
> states — `covered` (sealed intent claims it), `skipped` (`Mainline-Skip:`
134
+
> trailer or matched config pattern), or `uncovered` (neither). Run
135
+
> `mainline status` to see the rollup; `mainline gaps` to see uncovered
136
+
> commits with rescue suggestions.
137
+
138
+
### At the start of a task
139
+
140
+
```
141
+
mainline status --json
142
+
```
143
+
144
+
If there is no `active_intent`, start one (use the user's goal verbatim
145
+
when possible — it becomes the headline in `mainline log`):
146
+
147
+
```
148
+
mainline start "<short description of the user's goal>" --json
149
+
```
150
+
151
+
### Intent-first workflow (the load-bearing rule)
152
+
153
+
Before making any non-trivial code change, retrieve relevant intent
154
+
context **before** searching the codebase directly.
155
+
156
+
The default agent order is:
157
+
158
+
1. `mainline status` — overall state, identity, sync staleness, suggestions.
159
+
2. `mainline context --current --json` — historical intents relevant to
160
+
your current branch + active draft + diff vs main.
161
+
3. If the task names files: `mainline context --files <path>... --json`.
162
+
4. If the task is semantic: `mainline context --query "<task summary>" --json`.
163
+
5. Read the returned intents' `summary`, `decisions`, `risks`,
164
+
`anti_patterns`, and `fingerprint`.
165
+
6. **Only then** grep / read code to verify against the current
166
+
implementation.
167
+
7. Edit.
168
+
8. When sealing, reference relevant prior intent IDs in your
169
+
decisions, and record any new `anti_patterns` future agents must
170
+
avoid in this area.
171
+
172
+
Do not lead with `grep`, `rg`, or broad file reads for non-trivial
173
+
changes unless Mainline is unavailable or the task is purely mechanical.
174
+
175
+
`mainline context` does NOT replace code inspection. It provides the
176
+
historical *why* before the agent inspects the current *what*.
177
+
178
+
**Reading the retrieval output** — every returned intent carries a
179
+
`status` field that tells you how to use it RIGHT NOW (distinct from
180
+
its lifecycle status):
181
+
182
+
| status | how to read it |
183
+
|---|---|
184
+
| `current` | the current effective decision; verify against current code, then apply |
185
+
| `superseded` | replaced — read `superseded_by` instead and use this only for context |
186
+
| `abandoned` | this approach was tried and abandoned; do not repeat without understanding why |
187
+
| `stale` | files have churned or the intent is old; verify decisions still hold |
188
+
189
+
Each intent also carries:
190
+
191
+
- `risks` — soft warnings to weigh.
192
+
- `anti_patterns` — **hard constraints**. Each one carries a `what`,
193
+
a `why`, and a `severity`. Do not violate them. The retrieval API
194
+
never truncates `anti_patterns`, so if you see one, it is in scope.
195
+
- `guidance` — a single-line reminder derived from `status`.
196
+
197
+
### Pre-edit checklist for agents
198
+
199
+
Before editing code, answer:
200
+
201
+
- Did I run `mainline status`?
202
+
- Did I run `mainline context --current --json`?
203
+
- If files are involved, did I run `mainline context --files ... --json`?
204
+
- Did I read the relevant prior decisions and risks?
205
+
- Did I verify those intents against the current code?
206
+
- Am I about to repeat an abandoned or superseded approach?
207
+
208
+
### Task priority — when intent-first matters most
209
+
210
+
| Always mainline-first | Mainline-first preferred | Direct code OK |
211
+
|---|---|---|
212
+
| architecture changes / refactors | bug fixes | typo / formatting fixes |
213
+
| migrations / deletions | new feature additions | one-line obvious syntax fixes |
214
+
| auth / billing / data-model / permissions | API behaviour changes | mechanical rename, scoped |
215
+
| test-strategy changes | config / CI / release tweaks | user explicitly asks to view ONE file |
216
+
| any cross-file change | | |
217
+
| user asks "why is this here?" | | |
218
+
| user asks "can we delete this?" | | |
219
+
| user asks "did we try this before?" | | |
220
+
221
+
### Read team intents for context (do this aggressively)
222
+
223
+
Before working on anything non-trivial, scan recent intents for prior
224
+
work in the area you're about to touch. Each intent's `summary`
225
+
(what / why / decisions / risks / followups) plus `fingerprint`
226
+
(subsystems, files_touched, tags) is **strictly richer than the diff** —
227
+
it tells you *why* the code looks the way it does, which decisions
228
+
were considered and rejected, and what the author flagged as a risk
229
+
or follow-up.
230
+
231
+
```
232
+
mainline log --json --limit 30
233
+
```
234
+
235
+
Filter by goal/title keywords matching the user's task. For each
236
+
relevant hit, pull the full record:
237
+
238
+
```
239
+
mainline show <intent_id> --json # decisions / risks / fingerprint
240
+
mainline trace <intent_id> --json # turn timeline (when each turn
241
+
# was added, how long it took)
242
+
```
243
+
244
+
`show` answers *what* the intent decided. `trace` answers *how* it
245
+
unfolded over time — useful when you're trying to understand why a
246
+
PR looks the way it does, or whether the agent got stuck and looped.
247
+
248
+
Before designing a change, also see what is currently in flight so
249
+
your work does not collide with someone else's proposed intent:
250
+
251
+
```
252
+
mainline list-proposals --json
253
+
```
254
+
255
+
`mainline context --json` is a quick agent-consumption snapshot of
256
+
the same data (current actor, active intent, recent merged) — useful
257
+
for orientation but does not replace the targeted log/show calls.
258
+
259
+
Use this aggressively. The cost is one or two CLI calls; the payoff
260
+
is correct architectural decisions and not duplicating someone's
261
+
just-finished work.
262
+
263
+
### Turns and intent history
264
+
265
+
Turns are a lightweight thinking scaffold used to prepare a good
266
+
seal. They are **not** expected to be a real-time activity log.
267
+
268
+
It is normal for several turns to be recorded together near seal
269
+
time, especially when an agent summarizes its work before sealing.
270
+
`mainline trace` will surface this honestly via the
271
+
`append_turns_recorded_together` flag — that is informational, not a
272
+
warning.
273
+
274
+
Use:
275
+
276
+
```
277
+
mainline show <intent_id> --json
278
+
```
279
+
280
+
to inspect the structured conclusion of an intent: summary,
281
+
decisions, risks, and fingerprint.
282
+
283
+
Use:
284
+
285
+
```
286
+
mainline trace <intent_id> --json
287
+
```
288
+
289
+
to inspect how an intent unfolded over time: start, append, seal,
290
+
abandon, or supersede events.
291
+
292
+
`show` answers: *"What did this intent decide?"*
293
+
`trace` answers: *"How did this intent unfold?"*
294
+
295
+
### While working
296
+
297
+
Record turns at points that will help you write a good seal — when
298
+
a meaningful subtask completes, when you pivot, when a discovery
299
+
changes the plan. Many short turns or a few long turns are both
300
+
fine; what matters is that the seal author (you, later) has the
301
+
material to compose a faithful summary:
302
+
303
+
```
304
+
mainline append "<what changed and why>" --json
305
+
```
306
+
307
+
Turns are append-only. Don't try to amend or delete them — describe
308
+
the next state in a new turn.
309
+
310
+
### When the task is complete
311
+
312
+
1. Commit your code changes the normal way:
313
+
314
+
```
315
+
git add <files> && git commit -m "<message>"
316
+
```
317
+
318
+
2. Ask Mainline to prepare a seal package:
319
+
320
+
```
321
+
mainline seal --prepare --json > .ml-cache/seal.json
322
+
```
323
+
324
+
The package includes a `seal_result_starter` field — a partially-
325
+
filled `SealResult` with the deterministic bits (intent_id,
326
+
fingerprint.files_touched, fingerprint.subsystems) pre-populated.
327
+
Patch in the agent-judgment fields rather than typing the JSON
328
+
from scratch.
329
+
330
+
Why `.ml-cache/`? Init writes that directory to `.gitignore`, so
331
+
the temporary seal file stays out of git and does not trip the
332
+
v0.3 worktree-clean snapshot contract on submit.
333
+
334
+
3. Generate a `SealResult` JSON matching the schema returned by
335
+
`--prepare`. Populate the fingerprint generously — primary subsystem,
336
+
synonyms, parent concepts, related technologies — so phase-1
337
+
conflict detection has signal:
338
+
339
+
```
340
+
"tags": ["auth", "authentication", "security", "jwt", "session"]
341
+
```
342
+
343
+
When the work establishes constraints future agents must respect,
344
+
record them as `anti_patterns` (NOT as `risks`). Each entry MUST
345
+
carry both `what` and `why`; empty `why` is rejected at seal time.
346
+
347
+
```json
348
+
"anti_patterns": [
349
+
{
350
+
"what": "Removing legacy session middleware on /oauth path",
351
+
"why": "OAuth callback handler still requires session state",
352
+
"severity": "high"
353
+
}
354
+
]
355
+
```
356
+
357
+
Use `risks` for soft warnings the reviewer should weigh; use
358
+
`anti_patterns` for hard constraints the next agent must not
359
+
violate. Anti-patterns are surfaced uncapped in `mainline context`,
360
+
so future agents will always see them.
361
+
362
+
4. Submit it:
363
+
364
+
```
365
+
mainline seal --submit --json < .ml-cache/seal.json
366
+
```
367
+
368
+
Submit auto-syncs with the team and runs phase-1 conflict detection
369
+
against every other proposed/merged intent. If the JSON response
370
+
carries a `conflicts` array, **surface those conflicts to the user
371
+
verbatim** before continuing. Do not silently move on.
372
+
373
+
5. (Optional but encouraged) Quality-check the seal:
374
+
375
+
```
376
+
mainline lint <intent_id> --json
377
+
```
378
+
379
+
`lint` runs deterministic checks against the sealed payload —
380
+
empty / boilerplate `what`, missing decisions, decision without
381
+
rationale, missing risks/anti_patterns, broken supersedes refs.
382
+
Errors mean the seal will be hard for future retrieval to use;
383
+
warnings are advisory. Lint is **not** wired into submit, so a
384
+
bad seal still goes through — but a low-quality seal pollutes
385
+
future `mainline context` results, which is the whole loop this
386
+
workflow exists to keep healthy.
387
+
388
+
### When the user asks you to phase-2 check an intent
389
+
390
+
Phase 1 is automatic; phase 2 is invoked deliberately when phase 1
391
+
flags an overlap (`[check:~]` in `mainline log`) and the user wants a
392
+
real semantic judgment.
393
+
394
+
```
395
+
mainline check --prepare --intent <id> --json
396
+
```
397
+
398
+
Read each `judgment_task` in the package, judge whether it is a real
399
+
semantic conflict, and submit a `CheckJudgmentResult`:
400
+
401
+
```
402
+
mainline check --submit --json < judgment.json
403
+
```
404
+
405
+
The verdict surfaces in `mainline log`'s `[check:X]` column.
406
+
407
+
### Optional: agent hooks (opt-in context provider)
408
+
409
+
If `mainline hooks install <agent>` has been run for your agent
410
+
runtime (Cursor today; Codex / Claude Code reserved), the hook layer
411
+
runs **two mechanical operations** at session start and injects a
412
+
**status snapshot** into your system context — nothing more:
413
+
414
+
- At `sessionStart` the hook runs `mainline sync` (refreshes the team
415
+
view) and `mainline status` (active intent, proposed count, synced
416
+
head). It feeds that snapshot back to you as system-prompt context
417
+
along with a pointer to this document. You no longer need to run
418
+
`mainline status` as the very first call of a session — it has
419
+
already run.
420
+
- At every other lifecycle event (turn start, turn end, subagent
421
+
end, session end) the hook is a **no-op** for your reasoning. It
422
+
fires webhook notifications for external observers (CI dashboards,
423
+
pager integrations) and exits. It does NOT call `mainline start`,
424
+
`mainline append`, `mainline seal --prepare`, or any other command
425
+
that requires deciding what counts as a goal / a meaningful change /
426
+
a fingerprint — those are LLM judgments and you remain the only
427
+
party qualified to make them.
428
+
429
+
Concretely: every step described above (start when there is real
430
+
work, append after each meaningful logical change, commit, seal
431
+
--prepare, fill SealResult, seal --submit, surface conflicts) you do
432
+
yourself, hooks installed or not. The hook layer is a **context
433
+
provider**, not a workflow driver.
434
+
435
+
Run `mainline hooks status` to confirm whether hooks are wired and
436
+
whether `auto_sync_on_session_start` is on (the only mechanical
437
+
toggle). Disable it with `mainline hooks disable` if your network
438
+
makes the session-start sync painful — you can still drive the rest
439
+
of the workflow by hand.
440
+
441
+
### Hub: human reader surface (you don't run this; you suggest it)
442
+
443
+
`mainline hub export <dir>` and `mainline hub open` build a static
444
+
HTML site over the local synced intent view. It is for **humans**, not
445
+
agents — agents use `context` / `show` / `trace` / `gaps`.
446
+
447
+
You should suggest the hub when the user asks one of:
448
+
449
+
- *"What's the history of `<file>`?"* → hub's per-file page lists
450
+
every intent that touched it.
451
+
- *"Who's been working on what lately?"* → hub's index shows the
452
+
recent intents table; the actor pages give per-author rollups.
453
+
- *"Are there any conflicts or risky changes I should review?"* →
454
+
hub's risks page and graph (supersessions, conflicts_with,
455
+
shares_file edges) put the answer one click away.
456
+
457
+
Concretely:
458
+
459
+
```
460
+
mainline hub open # build + open in the default browser
461
+
mainline hub export ./hub-snapshot # write a portable copy elsewhere
462
+
```
463
+
464
+
Both commands default the output to `<os-temp>/mainline-hub/<repo>`
465
+
so the static site never enters git.
466
+
467
+
Hub is read-only and rebuildable from the synced view; it never
468
+
modifies repo files outside the user-chosen output directory.
469
+
470
+
### What you do NOT need to run
471
+
472
+
- `mainline sync` — runs automatically inside `seal --submit` and
473
+
whenever a fresh-data command (`check`, `pin`) needs it.
474
+
- `mainline pin` — runs automatically after every sync; the strategy
475
+
cascade (tree_hash → commit_hash → goal_text) catches GitHub
476
+
squash-merges with near-100 % reliability.
477
+
- `mainline merge` — humans merge via the GitHub PR UI; the next
478
+
`mainline sync` auto-pins the squash commit.
479
+
480
+
### Do not run unless the user explicitly asks
481
+
482
+
```
483
+
mainline pin <intent> <commit> # manual fallback
484
+
mainline merge --intent <id> # non-PR pipeline only
485
+
mainline init --rewire # repo setup repair
486
+
mainline doctor --setup --fix # repo setup repair
487
+
```
488
+
489
+
### Encountering an uncovered commit (v0.3 rescue)
490
+
491
+
If `mainline status` or `mainline gaps` flags an uncovered commit (one
492
+
that landed on main with no intent), pick the **best** path you still
493
+
can — ordered by reversibility, cheapest first:
494
+
495
+
1. **Unpushed** — undo and redo via the proper flow:
496
+
497
+
```
498
+
git reset --soft HEAD^ # un-commit, keep changes
499
+
mainline start "<goal>"
500
+
<continue normal flow>
501
+
```
502
+
503
+
2. **Pushed** — backfill an intent that retroactively claims the commit:
504
+
505
+
```
506
+
mainline start "<why this commit was made>" --commits <sha>
507
+
mainline append "<turn-by-turn description, post-hoc>"
508
+
mainline seal --prepare > .ml-cache/seal.json
509
+
<fill .ml-cache/seal.json>
510
+
mainline seal --submit < .ml-cache/seal.json
511
+
```
512
+
513
+
The seal flow auto-pins the new intent to the listed commit on next
514
+
`mainline sync`.
515
+
516
+
3. **Routine** (chore / format / version bump) — mark as deliberately
517
+
skipped:
518
+
519
+
```
520
+
git commit --amend # add `Mainline-Skip: <reason>` trailer
521
+
```
522
+
523
+
Or add a pattern in `.mainline/config.toml` under `[mainline.skip]`
524
+
so future similar commits classify automatically:
525
+
526
+
```toml
527
+
[mainline.skip]
528
+
patterns = ["^chore: format", "^bump:"]
529
+
```
530
+
531
+
4. **Already distributed, regrettably** — accept uncovered. The
532
+
mainline log is a record of reality, not aspiration.
533
+
534
+
### Seal snapshot contract (v0.3)
535
+
536
+
`mainline seal --prepare` snapshots the worktree state (HEAD, branch,
537
+
clean/dirty/untracked) and persists it. `mainline seal --submit`
538
+
validates the live repo against that snapshot — HEAD drift, branch
539
+
drift, or dirty worktree all fail by default with a typed error. The
540
+
escape hatch is the explicit CLI flag `--allow-dirty`; even then, the
541
+
sealed event permanently records `worktree_status` so reviewers see
542
+
the audit trail.
543
+
544
+
Always commit your code BEFORE `mainline seal --prepare`. Untracked
545
+
files (planning docs, scratch notes) do **not** enter sealed evidence.
546
+
<!-- mainline:agents:end -->
+38
CLAUDE.md
+38
CLAUDE.md
···
1
+
<!-- mainline:agents:start version=12 checksum=sha256:bb93a86dcc1512ce1f81dfd84c14e6714261d252997e36eda3e1041a515273ba -->
2
+
## Mainline
3
+
4
+
<!-- mainline-agents-md-version: 8 -->
5
+
6
+
This project uses **Mainline** for AI-driven intent tracking and
7
+
conflict detection. The full agent workflow lives in `AGENTS.md` at
8
+
the repo root — read that file for the complete contract.
9
+
10
+
Quick reference:
11
+
12
+
```
13
+
mainline status # see your state
14
+
15
+
# Read team intents for context (do this aggressively):
16
+
mainline log --json --limit 30 # recent intents
17
+
mainline show <intent_id> --json # full why/decisions/risks
18
+
mainline list-proposals --json # what's in flight
19
+
20
+
# Write your own intent:
21
+
mainline start "<goal>" # claim work
22
+
mainline append "<what changed>" # after each turn
23
+
git add ... && git commit -m ... # commit code
24
+
mainline seal --prepare > .ml-cache/seal.json # patch the starter
25
+
mainline seal --submit < .ml-cache/seal.json # auto syncs + checks
26
+
```
27
+
28
+
Sync, pin, merge are automatic — do not invoke them.
29
+
30
+
### If `mainline hooks` is installed for your agent
31
+
32
+
When hooks are active, the only thing that changes is sessionStart:
33
+
the hook runs `mainline sync` + `mainline status` for you and injects
34
+
the snapshot into your system context. Every other workflow step
35
+
(start / append / commit / seal --prepare / seal --submit / check)
36
+
remains agent-driven exactly as `AGENTS.md` describes. Hooks are a
37
+
context provider, not a workflow driver.
38
+
<!-- mainline:agents:end -->