Skip to content

Commit fe291ed

Browse files
NetDevAutomateNetDevAutomate
committed
Merge integration/2026-09-second-brain: the optional second-brain layer (0.2.0)
Fifty commits across three lanes (m7 core, m8 xTiles stage 1, m9 spec/ADR). Merged with --no-ff on purpose: the campaign's shape -- which lane decided what, and which commits the P2 council changed -- is the part worth being able to read back, and a fast-forward would flatten it into main's linear history. What lands: - `studyloop brain` (status/publish/pull/enable/template) and an Obsidian backend that writes plain files: only inside the configured vault folder, only over files carrying StudyLoop's own frontmatter marker, never through a symlink, and never at all when the rendered projection matches what is already there. - xTiles stage 1: three documented prompts and one opt-in wind-down skill, installed once into ~/.agents/skills/ and symlinked into each harness that documents a skills directory. - The plan document stays the only source of truth. No backend, command or agent path writes back to it; `pull` reads a sibling `.notes.md` the learner owns. - Off unless configured: no `second_brain:` section means no provider module is imported, no file is written, and wind-down says nothing. Gates at this merge: `just preflight` green (4670 passed, 3 skipped), `just release-check` green, `just e2e` 503 passed / 20 skipped, `ci-standards check` 0 blocking, `ci-standards run-job lint` in-container pass, and a live round trip against a real throwaway Obsidian vault plus a live xTiles create/validate/delete recorded under reviews/2026-09-03-second-brain/evidence/. Two three-family model councils ran against this branch. The first cut the Obsidian CLI adapter (it resolved its target by vault name, and passed note text through argv); the second corrected the website's privacy claims. Both records, with the arbitration, are in reviews/2026-09-03-second-brain/.
2 parents 2a0d22f + 3c512f8 commit fe291ed

91 files changed

Lines changed: 9643 additions & 123 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -511,6 +511,9 @@ docs/architecture/*
511511
# Un-ignored 2026-09-02 — session-authority contract (M2 remediation lane),
512512
# linked from ADR-0009 and tested against by tests/test_session_authority_matrix.py.
513513
!docs/architecture/session-authority.md
514+
# Un-ignored 2026-09 — second-brain projection contract (R-84), linked from ADR-0010
515+
# and docs/second-brain.md; tested against by tests/test_second_brain_*.py.
516+
!docs/architecture/second-brain.md
514517

515518
# Demo recordings (large, local-only)
516519
demos/

‎CHANGELOG.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,55 @@ experience may change before `1.0.0`.
77

88
## [Unreleased]
99

10+
## [0.2.0] - 2026-09-04
11+
12+
### Added
13+
14+
- An optional second-brain layer: `studyloop brain status` reports whether a
15+
provider is configured, and `studyloop brain publish --plan <id>` publishes a
16+
projection of that plan. Nothing is written anywhere until you opt in with a
17+
`second_brain:` section in `config.yaml`, and nothing ever writes back to the
18+
plan document.
19+
- Publish your study plans, today's next action and due reviews into an Obsidian
20+
vault as safe, idempotent notes StudyLoop owns. Your own notes are never
21+
overwritten: StudyLoop writes only files carrying its own marker, only inside
22+
the folder you name, never through a symbolic link, and it reads your personal
23+
notes for a plan only when you ask it to with `studyloop brain pull`.
24+
Republishing an unchanged plan writes nothing at all. Nothing in this feature
25+
runs an external program or stores a credential.
26+
- An Obsidian study-plan template ships with StudyLoop
27+
(`studyloop brain template --install`); it mirrors the plan document's sections,
28+
so a plan you write by hand in your vault and one StudyLoop published look the
29+
same. Templates carry no ownership marker, so a note you make from one is yours.
30+
- `studyloop brain` publishes plans and today's study to a configured second brain,
31+
pulls your notes back on request, and `studyloop config init` can enable it when
32+
you point StudyLoop at a vault. `studyloop doctor` reports the provider, the vault
33+
and whether that vault is writable — but only if you have configured one.
34+
- The project website, [www.studyloop.dev](https://www.studyloop.dev/), is linked
35+
from the README and the documentation home.
36+
- xTiles users can move today's study and their whole plan into xTiles through
37+
their assistant's MCP connector: the Second Brain guide ships the three prompts,
38+
and `studyloop install agents` installs an opt-in wind-down skill into every
39+
harness it detects. The skill is silent unless your provider is `xtiles` and an
40+
`xtiles` server is connected, and StudyLoop stores no xTiles credential.
41+
42+
### Changed
43+
44+
- The wind-down protocol offers, once, to publish the session to your second brain
45+
when one is configured that can be published to. It says nothing otherwise.
46+
47+
### Notes for anyone who ran a pre-release build
48+
49+
- An optional Obsidian CLI adapter existed during development and was **withdrawn
50+
before release**, after a multi-model review found that it could write into a vault
51+
other than the one you configured, and that it passed your plan text as a
52+
command-line argument where other users on the machine could read it. StudyLoop
53+
writes notes directly instead, which is all this feature ever needed.
54+
- The keys `use_cli`, `vault_name`, `template` and `daily_note` are gone. If any of
55+
them is still in your `config.yaml`, StudyLoop now says so and stops rather than
56+
ignoring it — `daily_note` used to append a line to your own daily note, and you
57+
should know that it no longer does.
58+
1059
## [0.1.0] - 2026-09-03
1160

1261
### Added

‎README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,9 @@ explaining, and being asked the next useful question. It pairs a browser workspa
99
with AI mentors such as Kiro, keeps track of where you left off, and turns real
1010
practice into evidence you can revisit.
1111

12+
**[www.studyloop.dev](https://www.studyloop.dev/)** — what StudyLoop is, who it is
13+
for, and what it honestly cannot do yet.
14+
1215
![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)
1316
![License MIT](https://img.shields.io/badge/license-MIT-green)
1417
![CI](https://github.com/NetDevAutomate/StudyLoop/actions/workflows/ci.yml/badge.svg)
@@ -120,6 +123,10 @@ pull request process.
120123

121124
## Guides
122125

126+
The project website, [www.studyloop.dev](https://www.studyloop.dev/), is the
127+
shortest way to decide whether StudyLoop suits you. The guides below are the
128+
detail.
129+
123130
- [Setup Guide](docs/setup-guide.md) — install and configure the current release
124131
- [Your First Week](docs/first-week.md) — reach a useful first routine gradually
125132
- [Web UI Guide](docs/web-ui-guide.md) — Study Session, Body Double, review, and access

‎agents/claude/socratic-mentor.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,8 @@ Follow `agents/shared/wind-down-protocol.md`. Summary:
118118
**Phase 1 — Session Wrap:**
119119
1. Record progress: `studyloop progress "<concept>" -t <topic> -c <confidence>`
120120
2. End session: `studyloop session end --notes "<summary>"` — flushes parking lot to DB, exports to Obsidian
121-
3. Summarise key concepts and teaching moments
121+
3. Second brain: If `studyloop brain status --json` reports both `configured` and `supports_publish` as true, offer ONCE to publish (`studyloop brain publish --today --plan <plan-id>`); otherwise say nothing about second brains.
122+
4. Summarise key concepts and teaching moments
122123
3. Surface parking lot topics
123124
4. Suggest next review based on spaced repetition intervals
124125
5. Suggest a concrete next study block in prose (no calendar CLI exists yet)

‎agents/codex/AGENTS.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,9 @@ Follow `wind-down-protocol.md`:
8989
1. Record progress: `studyloop progress "<concept>" -t <topic> -c <confidence>`
9090
2. End session: `studyloop session end --notes "<summary>"` — flushes parking lot to DB, exports to Obsidian
9191
3. Export the real Codex conversation: `session-export --codex-only`
92-
4. Suggest next review based on spaced repetition intervals
92+
4. Second brain: If `studyloop brain status --json` reports both `configured` and `supports_publish` as true, offer ONCE to publish (`studyloop brain publish --today --plan <plan-id>`); otherwise say nothing about second brains.
93+
- xTiles: if that same status reports `provider: xtiles` and an `xtiles` MCP server is connected in this session, follow the `studyloop-xtiles-wind-down` skill instead; otherwise skip this step silently and say nothing about xTiles.
94+
5. Suggest next review based on spaced repetition intervals
9395
5. Suggest a concrete next study block in prose (no calendar CLI exists yet)
9496
6. If session exceeds the energy-adaptive threshold (see `agents/shared/break-science.md`), remind to take a break
9597
7. Parking lot: note tangential topics worth revisiting

‎agents/manifest.json‎

Lines changed: 27 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -2,56 +2,64 @@
22
"version": 1,
33
"agents": {
44
"claude/socratic-mentor.md": {
5-
"hash": "93f844100b6ba0b9",
6-
"updated": "2026-08-27"
5+
"hash": "42880ffa80484ec9",
6+
"updated": "2026-09-03"
77
},
88
"codex/AGENTS.md": {
9-
"hash": "1604a3ebdf014205",
10-
"updated": "2026-08-27"
9+
"hash": "23dc3d4fbdea89c3",
10+
"updated": "2026-09-03"
1111
},
1212
"kiro/study-mentor.json": {
1313
"hash": "c9f2302ebc8d3c39",
14-
"updated": "2026-08-27"
14+
"updated": "2026-09-03"
1515
},
1616
"opencode/study-mentor.md": {
17-
"hash": "aa2e849e351ec55c",
18-
"updated": "2026-08-27"
17+
"hash": "0ff72c058de9f7d2",
18+
"updated": "2026-09-03"
1919
},
2020
"pi/AGENTS.md": {
21-
"hash": "cf02d2854a27d5b8",
22-
"updated": "2026-08-27"
21+
"hash": "8706855f619c71b5",
22+
"updated": "2026-09-03"
2323
},
2424
"shared/audhd-framework.md": {
2525
"hash": "8b694064b100741f",
26-
"updated": "2026-08-27"
26+
"updated": "2026-09-03"
2727
},
2828
"shared/break-science.md": {
2929
"hash": "74541a44431f7f6a",
30-
"updated": "2026-08-27"
30+
"updated": "2026-09-03"
3131
},
3232
"shared/knowledge-bridging.md": {
3333
"hash": "adb4221cda83498f",
34-
"updated": "2026-08-27"
34+
"updated": "2026-09-03"
3535
},
3636
"shared/network-bridges.md": {
3737
"hash": "8af4732b77cc15ae",
38-
"updated": "2026-08-27"
38+
"updated": "2026-09-03"
3939
},
4040
"shared/session-protocol.md": {
41-
"hash": "fc88049adb1badc4",
42-
"updated": "2026-08-27"
41+
"hash": "b58178df20cb9008",
42+
"updated": "2026-09-03"
4343
},
4444
"shared/socratic-engine.md": {
4545
"hash": "42738fba9479ec14",
46-
"updated": "2026-08-27"
46+
"updated": "2026-09-03"
4747
},
4848
"shared/teach-back-protocol.md": {
4949
"hash": "9bbe8831f1c74837",
50-
"updated": "2026-08-27"
50+
"updated": "2026-09-03"
5151
},
5252
"shared/wind-down-protocol.md": {
53-
"hash": "065bef2cc196fe9b",
54-
"updated": "2026-08-27"
53+
"hash": "d9d0dde390e03b4c",
54+
"updated": "2026-09-03"
55+
},
56+
"skills/studyloop-xtiles-wind-down/SKILL.md": {
57+
"hash": "aa31c59092ffe929",
58+
"updated": "2026-09-03"
59+
},
60+
"skills/studyloop-xtiles-wind-down/references/harnesses.md": {
61+
"hash": "e3f0ebc00ee792a8",
62+
"updated": "2026-09-03"
5563
}
5664
}
5765
}

‎agents/opencode/study-mentor.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,8 @@ Follow `wind-down-protocol.md`:
9292
6. If session exceeds the energy-adaptive threshold (see `agents/shared/break-science.md`), remind to take a break
9393
7. Parking lot: note tangential topics worth revisiting
9494

95+
xTiles second brain: if `studyloop brain status --json` reports `provider: xtiles` and an `xtiles` MCP server is connected in this session, follow the `studyloop-xtiles-wind-down` skill while wrapping up; otherwise skip it silently and say nothing about xTiles.
96+
9597
## Break Reminders
9698

9799
Follow the energy-adaptive schedule in `agents/shared/break-science.md`:

‎agents/pi/AGENTS.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,13 @@ session-export --pi-only
3939
If `session-export` is unavailable, note the failure but do not block the
4040
session close.
4141

42+
## Second Brain (xTiles)
43+
44+
At wind-down, if `studyloop brain status --json` reports `provider: xtiles` and an
45+
`xtiles` MCP server is connected in this session, follow
46+
the `studyloop-xtiles-wind-down` skill. Otherwise skip it silently and say nothing
47+
about xTiles — the learner has not asked for it.
48+
4249
## Identity
4350

4451
You are a strict Socratic mentor, not a code assistant. Teach through guided

‎agents/shared/session-protocol.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -290,6 +290,8 @@ Follow the full wind-down protocol in `wind-down-protocol.md`. Summary of the th
290290
studyloop progress "<concept>" -t <topic> -c <confidence>
291291
studyloop session end --notes "<summary>" # Flush parking lot to DB, export to Obsidian
292292
```
293+
294+
**Second brain (only if one is configured)** — If `studyloop brain status --json` reports both `configured` and `supports_publish` as true, offer ONCE to publish (`studyloop brain publish --today --plan <plan-id>`); otherwise say nothing about second brains.
293295
Confidence levels: `struggling`, `learning`, `confident`, `mastered`
294296

295297
Ask the learner: "How confident do you feel about [concept]? (struggling/learning/confident/mastered)"

‎agents/shared/wind-down-protocol.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,33 @@ Standard end-of-session tasks from session-protocol.md:
4848

4949
4. Set next review dates via spaced repetition schedule.
5050

51+
5. Offer the second brain — **only if one is configured, and only once**:
52+
53+
```bash
54+
studyloop brain status --json
55+
```
56+
57+
If **both** `configured` and `supports_publish` are `true`, offer exactly once,
58+
in one sentence:
59+
60+
<!-- wind-down-offer -->
61+
Want me to publish today's study record and this plan to your Obsidian vault (Study/Today.md and Study/Plans/<plan-id>.md)? Yes or no — I'll only ask once.
62+
<!-- /wind-down-offer -->
63+
64+
On **yes**:
65+
66+
```bash
67+
studyloop brain publish --today --plan <plan-id>
68+
```
69+
70+
On **no**, or in any other case, **say nothing about second brains at all** and
71+
continue the wind-down. Do not repeat the offer later in the session.
72+
73+
Both flags are required, not just `configured`. A learner on xTiles *is*
74+
configured but has no programmatic backend (`supports_publish: false`), so
75+
offering the publish command would name something that cannot work — and would
76+
do it at the end of every session.
77+
5178
### Phase 2: Consolidation Guidance (spoken if voice mode is active)
5279

5380
After the session wrap, the agent delivers consolidation guidance. This is the novel part — most study tools skip this entirely.

0 commit comments

Comments
 (0)