Skip to content

Commit cc12329

Browse files
fix: workspace rules state lives outside the project (#1669)
Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 265d89c commit cc12329

9 files changed

Lines changed: 276 additions & 45 deletions

File tree

‎docs/docs/configure/learn.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -197,17 +197,17 @@ In a project linked to an Altimate workspace (`altimate-code link`), what you te
197197
- you correct a team rule the session was shown (the card proposes changing it, with the current text struck through);
198198
- you ask the agent to remember something as a rule (the card appears as soon as the agent saves it, always as a new rule: changing a team rule comes from correcting it).
199199

200-
Cards are shown by the TUI and by the VS Code extension from its release with workspace rules, for the project they have open and in its top-level sessions. Where no attached client shows cards (`altimate-code run`, ACP, the Claude Code and Codex plugins, a subagent's session), the save tools work as they did before cards: a rule is saved for this project only, a memory to memory, and nothing goes to review; corrections are kept, and proposed the next time that session runs with a client that shows cards. A card you asked for ("remember …") that closes without an answer (after a day, or when the session server stops) is saved the same way. Requests are kept in the project's rules state while their card is open: if the server exits unexpectedly, or a save fails for a passing reason (a busy disk, a lock), the next session server that opens the project saves them. A request is dropped, with a log line, only when it can never be saved as asked (the project's memory or training is full, or the text is too long for a memory block). While 50 requested cards are open, a new request is saved right away instead of raising a card.
200+
Cards are shown by the TUI and by the VS Code extension from its release with workspace rules, for the project they have open and in its top-level sessions. Where no attached client shows cards (`altimate-code run`, ACP, the Claude Code and Codex plugins, a subagent's session), the save tools work as they did before cards: a rule is saved for this project only, a memory to memory, and nothing goes to review; corrections are kept, and proposed the next time that session runs with a client that shows cards. A card you asked for ("remember …") that closes without an answer (after a day, or when the session server stops) is saved the same way. Requests are kept in your rules state for the project while their card is open: if the server exits unexpectedly, or a save fails for a passing reason (a busy disk, a lock), the next session server that opens the project saves them. A request is dropped, with a log line, only when it can never be saved as asked (the project's memory or training is full, or the text is too long for a memory block). While 50 requested cards are open, a new request is saved right away instead of raising a card.
201201

202202
The card never blocks the input: keep typing, and answer it when you are ready. **ctrl+x p** (or a click) moves to the card; **←/→** choose an action, **Enter** confirms, **Esc** goes back to typing. The card shows the proposed wording, what it applies to, why it was proposed and your correction. **Enter** on the first action sends it to the owner's review queue (the workspace's **Rules** tab); for the workspace owner, it approves it at once instead. **e** edits the wording, and **n** ("Not a rule") stops a correction's topic from being proposed for 30 days (on a card you asked for, it just closes it). A rule that tells the agent to skip or disable verification (tests, CI, hooks, `--no-verify`) is flagged: the owner approves it with "Approve anyway", which takes a second Enter (a client answers it with the `approve_anyway` action; a plain `approve` is refused). Nothing reaches a teammate until it is approved. A card nobody answers is dropped when the session server stops, and after a day (an answer after that closes it instead). A card is answered for the account and workspace it was shown for: after signing in as someone else or relinking, it closes without sending anything.
203203

204204
**Rule or memory.** A personal preference ("I prefer CTEs") or a fact ("our warehouse is Snowflake") is saved to memory without review. When the agent saved it with `training_save`, a preference goes to your own memory (all your projects) and a fact to this project's memory (outside a linked project, `training_save` saves project training as before). When it saved it with the memory tool, it stays in that tool's project memory. When the wording does not say which, the card asks: Memory, Team rule, or Skip.
205205

206-
**Where they live.** Approved team rules are mirrored into the `workspace-rules` store (`.altimate-code/learn/workspace-rules/`), which is git-ignored and written only by sync: the name is reserved for it, and a store you create needs another `--name`. Your other stores, including one named `team`, are not touched. Team rules stop being delivered when the project is unlinked, when you sign out, when the workspace refuses access, and while workspaces are turned off (`ALTIMATE_DISABLE_WORKSPACE`); they come back with the next sync.
206+
**Where they live.** Approved team rules are mirrored into the `workspace-rules` store (`.altimate-code/learn/workspace-rules/`), which is git-ignored and written only by sync: the name is reserved for it, and a store you create needs another `--name`. Everything else sync keeps (proposals waiting to be sent, your review notices, dismissed topics, your learning choice) is your rules state for the project, kept outside it in your own state directory (`$XDG_STATE_HOME/altimate-code/workspace-rules/`, usually `~/.local/state/altimate-code/workspace-rules/`, one file per project folder). Team rules are delivered from your rules state, and only while you are signed in as the account that pulled them: the project's `workspace-rules` copy is never trusted on its own, so a copy that came with a branch or a merge is not delivered. Your other stores, including one named `team`, are not touched. Team rules stop being delivered when you sign out or sign in as someone else (at once), when the project is unlinked, when the workspace refuses access, and while workspaces are turned off (`ALTIMATE_DISABLE_WORKSPACE`); they come back with the next sync.
207207

208208
**After review.** Approved rules reach new sessions, and new requests and files in running ones, within a few minutes (a pull at session start and every 5 minutes; `/rules` → Sync now, or `altimate-code learn sync`). A session keeps the wording it was already shown. You see a notice when the owner approves or rejects your rule, with the reason. Usage is reported back to the workspace: how many sessions a rule was applied in, and how often you corrected the agent on its topic after it was shown ("corrected again").
209209

210-
**Learning on or off.** In order: the learning kill switch (`learn.enabled`, `ALTIMATE_LEARN`), `ALTIMATE_LEARN_CAPTURE`, a `learn.capture` your organization sets (managed config, MDM, the account's config, `OPENCODE_CONFIG_CONTENT`, `OPENCODE_CONFIG_DIR` or the home `~/.altimate-code` config; shown as "organization policy"), your `/rules` → "Turn learning on/off for me" choice, `learn.capture` (`learn enable` / `learn disable`), then the workspace's "Learn from sessions". The `/rules` choice is yours alone: it is kept in the project's git-ignored rules state, not in the project config, so it never reaches a teammate through a commit ("Follow the workspace setting again" clears it). It takes effect right away. Approved rules are delivered either way.
210+
**Learning on or off.** In order: the learning kill switch (`learn.enabled`, `ALTIMATE_LEARN`), `ALTIMATE_LEARN_CAPTURE`, a `learn.capture` your organization sets (managed config, MDM, the account's config, `OPENCODE_CONFIG_CONTENT`, `OPENCODE_CONFIG_DIR` or the home `~/.altimate-code` config; shown as "organization policy"), your `/rules` → "Turn learning on/off for me" choice, `learn.capture` (`learn enable` / `learn disable`), then the workspace's "Learn from sessions". The `/rules` choice is yours alone: it is kept in your own rules state for the project, outside it, not in the project config, so it never reaches a teammate through a commit ("Follow the workspace setting again" clears it). It takes effect right away. Approved rules are delivered either way.
211211

212212
**Commands.** `/rules` in the TUI lists team rules and your proposals with their status. `altimate-code learn sync` syncs now; `learn status` shows the workspace rules line, your learning setting and the last proposal check. In a linked project, `learn bootstrap` and `learn import-reviews` list the rules they staged from history and ask before sending them to the owner's review in the named workspace (default no). Without a terminal, `--send-for-review` sends them; `--yes` only confirms the model step. Declined rules stay local candidates (`learn show`, `learn promote`).
213213

‎packages/opencode/src/altimate/learn/delivery.ts‎

Lines changed: 18 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -217,13 +217,13 @@ export class Delivery {
217217
// Older versions froze unchecked content. Rebuild unsafe snapshots on the next prepare;
218218
// valid snapshots retain their byte-identical prefix across resume and approved edits.
219219
const grandfathered = new Map<string, Pick<Lesson, "id" | "text">[]>()
220-
// Read once per check, an unreadable mirror (null) included.
221-
let mirrored: Promise<Set<string> | null> | undefined
220+
// Read once per check.
221+
let vouched: Promise<Map<string, Lesson>> | undefined
222222
for (const { name, lesson } of state.shown) {
223223
// altimate_change start — workspace rules: a session's cached section and notes keep a team rule only while sync
224-
// still vouches for it: workspaces on, and the rule still in the mirror (an edit keeps its id, so its frozen
225-
// wording stays). Otherwise (workspaces off, signed out, unlinked, another workspace, retired) it is rebuilt.
226-
if (name === Store.WORKSPACE_RULES_STORE && (!workspacesOn() || (await (mirrored ??= this.mirroredIds()))?.has(lesson.id) === false)) {
224+
// still vouches for it: workspaces on, and the rule still in the person's rules state (an edit keeps its id, so its
225+
// frozen wording stays). Otherwise (workspaces off, signed out, unlinked, another workspace, retired) it is rebuilt.
226+
if (name === Store.WORKSPACE_RULES_STORE && (!workspacesOn() || !(await (vouched ??= this.vouched())).has(lesson.id))) {
227227
log.info("learn session snapshot rebuilt without team rules", { session })
228228
return undefined
229229
}
@@ -239,16 +239,16 @@ export class Delivery {
239239
return state
240240
}
241241

242-
// altimate_change start — workspace rules: the ids the team-rules mirror holds now; a missing mirror holds none, and
243-
// one that cannot be read is unknown (null): the snapshot is kept rather than rebuilt on a passing read error
244-
private async mirroredIds(): Promise<Set<string> | null> {
245-
const raw = await read(this.root, Store.paths(this.root, Store.WORKSPACE_RULES_STORE).approved).catch(() => null)
246-
if (raw === null) return null
247-
if (raw === undefined) return new Set()
242+
// altimate_change start — workspace rules: the team rules the person's own rules state holds now, by lesson id,
243+
// outside the project. They are delivered from that state, never from the `workspace-rules` copy in the project: a file
244+
// in the working tree can come from anyone (a branch, a merge). Unreadable, it vouches for none.
245+
private async vouched(): Promise<Map<string, Lesson>> {
248246
try {
249-
return new Set(parse(raw).map((lesson) => lesson.id))
250-
} catch {
251-
return null
247+
const { RulesStore } = await import("../rules/store")
248+
return await RulesStore.vouched(this.root)
249+
} catch (error) {
250+
log.warn("workspace rules state unreadable; team rules not delivered", { error })
251+
return new Map<string, Lesson>()
252252
}
253253
}
254254
// altimate_change end
@@ -273,7 +273,10 @@ export class Delivery {
273273
if (raw === undefined) continue
274274
await SafeFS.assertSafePath(this.root, Store.paths(this.root, name).usage)
275275
await SafeFS.assertSafePath(this.root, path.join(Store.paths(this.root, name).learnDir, "shown.jsonl"))
276-
const lessons = await Store.mergeUsage(this.root, name, parse(raw))
276+
// altimate_change start — workspace rules: the team rules come from the person's rules state, not the project's copy
277+
const parsed = name === Store.WORKSPACE_RULES_STORE ? [...(await this.vouched()).values()] : parse(raw)
278+
// altimate_change end
279+
const lessons = await Store.mergeUsage(this.root, name, parsed)
277280
const grandfathered = lessons.some((lesson) => lesson.text.length > MAX_TEXT)
278281
? await Store.grandfathered(this.root, name, { migrate: false }) : []
279282
for (const lesson of lessons) {
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
// altimate_change - new file
2+
//
3+
// Where a project's workspace rules state lives: in the person's own state directory, keyed by the project's real path,
4+
// never in the project (`RulesStore`). Its own module so the prompt path can find it without loading the rules store.
5+
import { createHash } from "node:crypto"
6+
import path from "node:path"
7+
import { Global } from "@/global"
8+
9+
/** The rules state file of the project whose real path is `realRoot`. */
10+
export function stateFileOf(realRoot: string): string {
11+
return path.join(Global.Path.state, "workspace-rules", createHash("sha256").update(realRoot).digest("hex") + ".json")
12+
}

0 commit comments

Comments
 (0)