.windsurfrules

185 lines 6.4 KB

sha256:38dd0b4dc48e9ccb0207b5d79d0b39b5824230ff2768f41b0fec365ff55b8a4e remove files Human minor ⚠ breaking 14 days ago

1	# Workspace — Shared Agent Configuration
2
3	This file contains shared rules for all repositories in this workspace.
4	Each member repository may have its own ``.muse/agent.md`` with repo-specific
5	additions.
6
7	Managed by `muse agent-config` — regenerate adapters with `muse agent-config sync`.
8
9	---
10
11	## Workspace Members
12
13	\| Repo \| Path \| Branch \|
14	\|------\|------\|--------\|
15	\| muse \| `muse` \| `dev` \|
16	\| musehub \| `musehub` \| `dev` \|
17	\| agentception \| `agentception` \| `dev` \|
18	\| contracts \| `contracts` \| `dev` \|
19	\| Stori \| `Stori` \| `dev` \|
20	\| maestro \| `maestro` \| `dev` \|
21	\| muse-zsh \| `muse-zsh` \| `dev` \|
22
23	---
24
25	## Version Control
26
27	This workspace uses Muse for version control — not git, not GitHub.
28
29	- Never run `git`, `gh`, or any git subcommand.
30	- Never reference GitHub, GitHub Actions, or GitHub URLs.
31	- Use `muse -C ~/path/to/repo <command>` when CWD differs from the target repo.
32
33	If you find a `git` or `gh` call anywhere — delete it in the same commit.
34
35	---
36
37	## Commit Convention — Agent-First
38
39	This workspace is agent-first: agents do the work, humans provision agents.
40	Every commit made by an agent must carry full provenance. Human commits (direct
41	manual changes without an agent) are the exception, not the norm.
42
43	### Agent commit — always use this
44
45	```bash
46	muse commit -m "feat: ..." \
47	--agent-id claude-code \
48	--model-id claude-sonnet-4-6 \
49	--sign
50	```
51
52	- `--agent-id` — identifies the agent type (`claude-code`, `codex`, `agentception/worker`, …)
53	- `--model-id` — the specific model that produced the change (`claude-sonnet-4-6`, …)
54	- `--sign` — embeds Ed25519 public key + signature; traces back to gabriel's root mnemonic in `~/.muse/identity.toml`
55
56	Use the model you are actually running. For Claude Code the current model is `claude-sonnet-4-6`.
57
58	### Human commit — manual actions only
59
60	```bash
61	muse commit -m "chore: manual config change"
62	```
63
64	No provenance flags. Their absence is itself a signal that a human acted directly.
65
66	### Provenance chain
67
68	```
69	~/.muse/identity.toml ← root mnemonic (HD wallet seed, gabriel's root identity)
70	↓ HD derivation
71	Ed25519 key pair ← signer_public_key embedded in every --sign commit
72	↓ signs
73	CommitRecord ← agent_id + model_id + signature stored per-commit
74	↓ content-addressed
75	sha256:<commit_id> ← tamper-evident, auditable forever
76	```
77
78	Agents spawned by agentception receive a derived key via `MUSE_AGENT_KEY` env var —
79	their commits sign with that key, which itself traces back to gabriel's root identity.
80
81	---
82
83	## Branch Flow
84
85	Always work on a feature branch — never commit directly to `main` or `dev`.
86
87	```bash
88	muse -C ~/path/to/repo checkout dev
89	muse -C ~/path/to/repo checkout -b task/my-thing
90
91	muse rm <file> # delete from disk + stage deletion (mirrors git rm)
92	muse code add . # stage additions + modifications + already-deleted files
93	muse commit -m "feat: ..." --agent-id claude-code --model-id claude-sonnet-4-6 --sign
94
95	muse -C ~/path/to/repo checkout dev
96	muse -C ~/path/to/repo merge task/my-thing
97	muse -C ~/path/to/repo branch -d task/my-thing
98	muse -C ~/path/to/repo push local dev
99	```
100
101	---
102
103	## Code Intelligence
104
105	\| Task \| Command \|
106	\|------\|---------\|
107	\| Find symbol declaration \| `muse code grep "Name" --json` \|
108	\| Read one symbol \| `muse code cat "file.py::Symbol" --json` \|
109	\| File structure \| `muse code symbols --file file.py --json` \|
110	\| Blast radius \| `muse code impact "file.py::Symbol" --json` \|
111	\| Dependencies \| `muse code deps "file.py" --json` \|
112	\| Tests for changed code \| `muse code test --json` \|
113
114	---
115
116	## Testing Rules
117
118	Never run the full test suite. It is slow and gabriel runs it when he's ready.
119
120	1. Start with `muse code test --json` — runs only tests relevant to changed files.
121	2. Run one file at a time when fixing a specific failure:
122	```bash
123	python3 -m pytest tests/test_foo.py -q --tb=short
124	```
125	3. Run one test by name to verify a fix:
126	```bash
127	python3 -m pytest tests/test_foo.py::test_bar -q --tb=short
128	```
129
130	### Forbidden
131
132	- `python3 -m pytest tests/` — runs everything, never do this
133	- `python3 -m pytest` with no path — same as above
134	- `pytest -x tests/` or any whole-suite invocation
135	- Looping retries on the same command after a failure — diagnose first
136
137	# muse — Agent Configuration
138
139	This repository is a member of a workspace.
140	Shared workspace rules live in the parent ``.muse/agent.md``.
141	This file contains only muse-specific additions.
142
143	Managed by `muse agent-config` — regenerate adapters with `muse agent-config sync`.
144
145	---
146
147	## Repo-Specific Notes
148
149	### Snapshot Design Intent — Flat Manifest is Intentional
150
151	Muse snapshots are flat `path → object_id` dicts covering the entire repo in one
152	structure. This is a deliberate architectural choice, not an oversight.
153
154	Why not git's recursive tree model?
155
156	Git's tree objects provide subtree sharing: two commits that differ only in `src/`
157	reuse the same tree object for every other directory. This saves storage at the cost
158	of requiring recursive tree traversal to reconstruct a file's path.
159
160	Muse does not use this model because the primary unit of meaning in Muse is not a
161	directory — it is a snapshot of the entire system state. A music arrangement,
162	its samples, its metadata, and its MIDI files are one coherent atomic thing. A
163	genomics dataset, a 3D scene, a financial model — all of these are captured as a
164	single indivisible state, not a hierarchy of independently meaningful subtrees.
165
166	The flat manifest reflects that: state is atomic, not hierarchical.
167
168	Storage tradeoff
169
170	Each snapshot materializes the full path list on disk. For small-to-medium repos
171	(up to ~100k files) this is not a meaningful constraint — snapshot files are just
172	path strings and SHA-256 IDs, not blob bytes. On the wire, delta encoding
173	(`delta_upsert`/`delta_remove`) means only changes are transmitted regardless.
174
175	If very large file counts become a real constraint, the natural evolution is a
176	tiered manifest: flat below a threshold, chunked or tree-structured above it.
177	The content-addressing model and delta format would not change.
178
179	Domain agnosticism
180
181	At the storage layer, a MIDI file and a Python file are identical — both are just
182	bytes with a path. Domain semantics live in the content of those bytes, not in how
183	they are stored. Muse is multi-domain (code, music, genomics, 3D, financial
184	modeling) but the object store, snapshot, and commit model are the same for all of
185	them. Do not introduce domain-specific logic into the core storage layer.

File History 4 commits

sha256:38dd0b4dc48e9ccb0207b5d79d0b39b5824230ff2768f41b0fec365ff55b8a4e remove files Human minor ⚠ 14 days ago

sha256:8860dea10c653956b613a814cc752a6d34cb3986cdf16749a49172affdabf045 fix tests Human minor ⚠ 14 days ago

sha256:fe844c2411edd1cec3d4c847f36a96c6ccd4e3d7d1a715106d2ecd64216bf94f fix: bare object detection and read recovery; rm adapter files Sonnet 4.6 minor ⚠ 14 days ago

sha256:99f8eb388d9a9c353e68b9a4e5bebe1b4240a8f511e6f0928e58c0e95153e103 feat: branch --prune-config, fix hub repo delete docstrings… Sonnet 4.6 minor ⚠ 15 days ago