Skip to content

Commit bdb7dcc

Browse files
feat: workspace rules — proposal card, owner review, approved rules in every session (#1605)
Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 6c2d548 commit bdb7dcc

55 files changed

Lines changed: 7906 additions & 342 deletions

Some content is hidden

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

‎docs/docs/configure/learn.md‎

Lines changed: 165 additions & 141 deletions
Large diffs are not rendered by default.

‎docs/docs/reference/telemetry.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,15 @@ We collect the following categories of events:
7474
| `onboarding_abandoned` | The CLI exited during a first run without connecting. `last_stage` is the furthest point reached: `started`, `model_picker`, `provider_setup`, `altimate_base_confirm`, or `gateway_auth`. (`connected` is a funnel position but never a `last_stage` — reaching it means the run completed, which is not an abandonment.) Only emitted for a genuine first run — opening `/connect` as an existing user does not enter the funnel, and abandonment after setup completes is out of scope by definition. Emitted on the exit path under a bounded flush, so the measured rate is a lower bound — see [Delivery & Reliability](#delivery--reliability). |
7575
| `review_run` | A dbt/SQL review completed or failed — `invocation` (`cli` for `altimate-code review`, `tool` for the `dbt_pr_review` tool), status, duration, and on success the verdict, the pre-gating verdict, mode, risk tier, and finding counts by severity and by category. No file paths, model or column names, finding titles or bodies, SQL, diff content, or repository/branch/PR names. |
7676
| `review_post_outcome` | Whether a review was published to GitHub — `not_requested`, `not_attempted`, `target_unresolved`, `full`, `partial`, or `summary_failed`, plus duration. Emitted on the **CLI path only** — the `dbt_pr_review` tool completes reviews but never publishes, so a `review_run` with `invocation: tool` has no post event and that is not a failure. Within the CLI path there is exactly one per **completed** review: a review that failed emits `review_run: failed` and no post event, so absence there means the review failed rather than that an event was lost. `not_attempted` is publication requested but never reached (a bad `--output` path, a stdout write error). No repository, PR, or comment content. |
77+
| `rule_proposal_shown` | A proposed-rule card was shown (or shown again for the same wording, `repeat`) — what raised it (`remember`, `shown_rule`, `recurrence`), the kind of change, whether it is a "Save as" choice, linked/owner, the buttons offered, whether it weakens verification, evidence session count, whether it came from a correction, how many paths it applies to, and its length. The card id is random. No rule text, quotes, paths or globs. |
78+
| `rule_proposal_answered` | A card was answered or closed (`send`, `approve`, `approve_anyway`, `edit`, `dismiss`, `save_local`, `save_memory`, `expired`, `closed`) — `ok` or why it did not go through (`busy`, `not_available`, `verification_flagged`, `invalid_text`, `refused` by the workspace, `failed`), what happened (`sent`, `queued`, `approved`, `approve_failed`, `approve_retry`, `target_changed`, `exists`, `dismissed`, `saved_memory_project`, `saved_memory_global`, `saved_local`, or `saved_unanswered` when a card the person asked for closed unanswered and was saved as before cards), wording edits so far, and time since the card was shown. No rule text. |
79+
| `rule_drafted` | One model call that drafted a proposal after a turn (it runs in the background) — the path (`shown_rule` or `recurrence`), `ok` or `failed`, input and output tokens, estimated cost and duration. No wording or correction text. |
80+
| `rule_proposal_skipped` | Corrections were checked after a turn and no card was shown — `card_open`, `no_renderer` (no attached client shows cards; the corrections are kept for a later check), `covered`, `no_draft`, `topic_dismissed`, `no_topic` or `failed`. The path checked (`shown_rule` or `recurrence`) is omitted when the check stopped before choosing one. |
81+
| `rule_remember_routed` | Where a "remember …" save went — through `training_save` or the memory tool, to a card, a "Save as" card, memory, refused as not a one-line rule, or saved as before cards because learning/workspaces are off, the project is not linked, or no attached client shows cards for this project (or the session is a subagent's), or its request could not be kept on disk: too many requested cards are already open, or the write failed (`requests_full`). No text. |
82+
| `rules_sync` | One rules sync — what started it (`refresh`, `session_start`, `manual`, `card`, `cli`, `import`), `ok` (the pull worked and no proposal this run tried to send was kept queued; proposals beyond one push's batch can still be waiting, and proposals the workspace refused still count as `ok`, under `refused`), `failed` (a failed pull, attempted proposals kept queued, or a run that threw: reason `error`), `off` or `skipped` with a fixed reason code, duration, counts of rules, pending reviews, proposals sent, refused and still queued, review notices and usage items, and whether a retried "Approve now" failed (`approval_failed`). No rule text, error text, URLs or workspace names. |
83+
| `rules_delivered` | Rules added to a session's context — at the start, for a request, or for a file the agent touched — with the number of rules (and how many are team rules), their total length, the session's running total, and the token budget. No rule text or file paths. |
84+
| `rules_learning_changed` | The person turned learning from sessions on or off for a project, or back to the workspace's setting, with the resulting state and who decides it (`organization`, `you`, `workspace` or `default`). |
85+
| `rules_command` | `/rules` opened in a client (`view`), or a `learn` subcommand run (its name only, never its arguments). |
7786

7887
Each event includes a timestamp, session ID, a per-launch correlation ID (`launch_id` — a random value regenerated every process start, not persisted and not derived from your machine or identity; it exists only to group events from the same run), CLI version, and a machine ID (a random UUID stored in `~/.altimate/machine-id`, generated once and not derived from your hardware or identity). When the machine is signed in to Altimate, each event also carries `user_id` and `tenant`, described under [User Identification](#new-user-identification).
7988

‎packages/core/src/flag/flag.ts‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,15 @@ export function truthy(key: string) {
2525
return value === "true" || value === "1"
2626
}
2727

28+
// altimate_change start — the one fail-closed kill-switch parse, shared with readers that take an explicit environment
29+
/** A kill switch fails closed: any value but empty, `0` or `false` turns the feature off, so `yes` or `on` cannot leave
30+
* it running while the operator believes it is off. */
31+
export function killSwitchSet(value: string | undefined): boolean {
32+
const normalized = value?.trim().toLowerCase()
33+
return normalized !== undefined && normalized !== "" && normalized !== "0" && normalized !== "false"
34+
}
35+
// altimate_change end
36+
2837
/** An Effect `Config` boolean with the same documented-name-first rule, for the flags
2938
* that are resolved through the ambient ConfigProvider rather than `process.env`. The
3039
* documented value is read as a string and judged by `truthy`'s rule, so a set-but-invalid
@@ -122,10 +131,7 @@ export const Flag = {
122131
// runtime `--` middleware can flip it between plugin activation and command execution.
123132
// Unrelated to OPENCODE_EXPERIMENTAL_WORKSPACES (multi-instance control plane).
124133
get ALTIMATE_DISABLE_WORKSPACE() {
125-
// A kill switch fails closed: any value but empty, `0` or `false` turns workspaces off, so `yes`
126-
// or `on` cannot leave them running while the operator believes they are off.
127-
const value = env("ALTIMATE_DISABLE_WORKSPACE")?.trim().toLowerCase()
128-
return value !== undefined && value !== "" && value !== "0" && value !== "false"
134+
return killSwitchSet(env("ALTIMATE_DISABLE_WORKSPACE"))
129135
},
130136
/**
131137
* Workspace precedence escape hatch, set by `--integrations=local`. When on, the

‎packages/opencode/src/altimate/learn/auto-promote.ts‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -109,15 +109,15 @@ export async function voidAutoOwnership(root: string, name: string): Promise<voi
109109
state = await readAutoPromoteState(root, name)
110110
} catch (error) {
111111
// Its marks could become readable again later, so a person action must not go ahead without voiding them.
112-
throw new Error(`Cannot read ${autoPromoteStateFile(root, name)} to record that lessons are no longer automatic ` +
112+
throw new Error(`Cannot read ${autoPromoteStateFile(root, name)} to record that rules are no longer automatic ` +
113113
`(${redactSecrets(errText(error))}); nothing was changed. Fix the file's permissions or delete it, then retry.`)
114114
}
115115
if (Object.keys(state.auto).length === 0 && state.approvedHash === undefined) return
116116
const { approvedHash: _voided, ...rest } = state
117117
try {
118118
await writeState(root, name, { ...rest, auto: {} })
119119
} catch (error) {
120-
throw new Error(`Cannot record that lessons are no longer automatic in ${autoPromoteStateFile(root, name)} ` +
120+
throw new Error(`Cannot record that rules are no longer automatic in ${autoPromoteStateFile(root, name)} ` +
121121
`(${redactSecrets(errText(error))}); nothing was changed. Fix the file's permissions or delete it, then retry.`)
122122
}
123123
}
@@ -244,22 +244,22 @@ export async function autoPromote(input: AutoPromoteInput): Promise<AutoPromoteR
244244
if (input.previousCandidate) {
245245
const earlier = lessonChanges(approved, input.previousCandidate)
246246
if (earlier.added.length + earlier.edited.length + earlier.removed.length)
247-
return held("the candidate already had lesson changes waiting for review")
247+
return held("the candidate already had rule changes waiting for review")
248248
}
249249
const { added, edited, removed } = lessonChanges(approved, candidate)
250250
const changed = [...added, ...edited]
251-
if (changed.length + removed.length === 0) return held("no lesson text changed (counter updates only)")
251+
if (changed.length + removed.length === 0) return held("no rule text changed (counter updates only)")
252252
// Gate: verification-weakening lessons always need a person. Unchanged flagged lessons were already approved.
253253
const flagged = changed.filter((lesson) => verificationWarning(lesson.text))
254-
if (flagged.length) return held(`flagged lesson ${ids(flagged)} mentions skipping or weakening verification`)
254+
if (flagged.length) return held(`flagged rule ${ids(flagged)} mentions skipping or weakening verification`)
255255
// Gate: a person's approval is never undone automatically.
256256
const auto = autoPromotedIds(state, approved)
257257
const person = [...edited, ...removed].filter((lesson) => !auto.has(lesson.id))
258-
if (person.length) return held(`it would edit or remove person-approved lesson ${ids(person)}`)
258+
if (person.length) return held(`it would edit or remove person-approved rule ${ids(person)}`)
259259
// Gate: size.
260260
const count = changed.length + removed.length
261261
if (count > input.limits.auto_promote_max_changes)
262-
return held(`${count} lesson changes exceed learn.auto_promote_max_changes (${input.limits.auto_promote_max_changes})`)
262+
return held(`${count} rule changes exceed learn.auto_promote_max_changes (${input.limits.auto_promote_max_changes})`)
263263
// Gate: rate. Reservations count; timestamps in the future count, so a clock change cannot reopen the window.
264264
const recent = state.promotions.filter((promotion) => Date.parse(promotion.at) > now - DAY_MS)
265265
if (recent.length >= input.limits.auto_promote_daily)

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ export function describeOutcome(
5656
): string {
5757
const head = `learn: ${signals} signal${signals === 1 ? "" : "s"} -> ${summary}`
5858
if (promotion?.status === "promoted")
59-
return `${head}; auto-promoted${promotion.archived ? ` (previous lessons archived as v${promotion.archived})` : ""}. Undo with \`altimate-code learn rollback\`` +
59+
return `${head}; auto-promoted${promotion.archived ? ` (previous rules archived as v${promotion.archived})` : ""}. Undo with \`altimate-code learn rollback\`` +
6060
(promotion.warning ? ` (warning: ${promotion.warning})` : "")
6161
if (!candidate) return head
6262
if (promotion?.status === "held")

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -225,7 +225,7 @@ export async function bootstrap(options: BootstrapOptions, deps: BootstrapDeps):
225225
deps.out(`Signals found: ${all.length} (${all.filter((s) => s.kind === "user_correction").length} corrections, ${all.filter((s) => s.kind === "tool_retry").length} tool failures; ${all.length - plans.reduce((n, p) => n + p.signals.length, 0)} pending).`)
226226
deps.out(`Model/provider: ${label}. Estimated input tokens: ${estimatedInput} for up to ${estimatedReflections} reflection(s), excluding candidate growth.`)
227227
deps.out(`Limits: ${limit} sessions, ${maxReflections} reflections, ${maxSeconds}s total after confirmation.`)
228-
deps.out(model ? "Bootstrap sends redacted excerpts of past sessions to this model and stages candidate lessons only."
228+
deps.out(model ? "Bootstrap sends redacted excerpts of past sessions to this model and stages candidate rules only."
229229
: "Bootstrap imports signals locally without model calls.")
230230
if (options.dryRun) {
231231
for (const signal of all) deps.out(`[${signal.sessionID}] [${signal.kind}] ${Signals.clipSignalText(signal.text)}`)
@@ -338,7 +338,7 @@ export async function bootstrap(options: BootstrapOptions, deps: BootstrapDeps):
338338
}
339339
}
340340
}
341-
deps.out(`Bootstrap summary: ${summary.signalsFound} signals found, ${summary.signalsAdded} added; ${summary.reflectionsRun} reflections run; candidate lessons: ${summary.candidatesAdded} added, ${summary.candidatesEdited} edited.`)
341+
deps.out(`Bootstrap summary: ${summary.signalsFound} signals found, ${summary.signalsAdded} added; ${summary.reflectionsRun} reflections run; candidate rules: ${summary.candidatesAdded} added, ${summary.candidatesEdited} edited.`)
342342
deps.out(`Tokens${summary.tokensEstimated ? " (estimated)" : ""}: ${summary.inputTokens} input, ${summary.outputTokens} output. Estimated cost: $${summary.estimatedCost.toFixed(6)}.`)
343343
if (!ready() || stop || (await Signals.readSignalsSnapshot(options.root, name)).some((s) => s.source === "bootstrap" && s.status === "open"))
344344
deps.out("Unfinished signals remain queued; re-run `learn bootstrap` to continue.")

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

Lines changed: 58 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -247,6 +247,24 @@ export class Capture {
247247

248248
// Keep every active capture drainable when more than one instance is open.
249249
const active = new Set<Capture>()
250+
/** Instance directories whose capture runs, whoever started it. */
251+
const running = new Set<string>()
252+
253+
/** Whether capture runs for the instance at `directory`. */
254+
export function captureRunning(directory: string): boolean {
255+
return running.has(directory)
256+
}
257+
258+
// altimate_change start — workspace rules: a per-project gate the rules service sets from the full learning decision
259+
// (the person's /rules choice can turn learning off while config still has learn.capture on). No gate: record.
260+
const gates = new Map<string, () => Promise<boolean>>()
261+
262+
/** Set (or clear, with undefined) whether corrections are recorded for the project at `directory`. */
263+
export function setCaptureGate(directory: string, gate: (() => Promise<boolean>) | undefined) {
264+
if (gate) gates.set(directory, gate)
265+
else gates.delete(directory)
266+
}
267+
// altimate_change end
250268

251269
export async function flushCapture() {
252270
await Promise.all([...active].map((capture) => capture.flush()))
@@ -272,17 +290,36 @@ async function subscribeWhenReady<T>(subscribe: () => T): Promise<T> {
272290
* Starts capture for one instance when enabled. Called once from instance bootstrap inside the instance
273291
* context. Never throws.
274292
*/
275-
export async function startCapture(ctx: { directory: string; worktree: string }): Promise<void> {
293+
// altimate_change start — returns a stop function once capture runs (workspace rules stop it when learning turns off)
294+
export async function startCapture(
295+
ctx: { directory: string; worktree: string },
296+
options: { force?: boolean } = {},
297+
): Promise<(() => Promise<void>) | undefined> {
298+
// altimate_change end
276299
try {
277300
const root = ctx.worktree !== "/" ? ctx.worktree : ctx.directory
278301
const { Config } = await import("@/config/config")
279-
if (!captureEnabled((await Config.get()).learn)) return
302+
// altimate_change start — `force`: workspace rules turned learning on for this project (the person set nothing)
303+
if (!options.force && !captureEnabled((await Config.get()).learn)) return
304+
// altimate_change end
280305
const { Bus } = await import("@/bus")
281306
const { MessageV2 } = await import("../../session/message-v2")
282307
const { Session } = await import("../../session")
283308
const { SessionID } = await import("../../session/schema")
284309
const capture = new Capture({
285-
record: (signal) => appendSignal(root, signal),
310+
record: async (signal) => {
311+
// Fails closed: a gate that cannot decide (unreadable rules state) must not record a correction the person
312+
// may have turned off. It throws rather than returns, so the correction is not marked recorded and a later
313+
// update of the message can try again; `track` logs it.
314+
const gate = gates.get(ctx.directory)
315+
if (gate) {
316+
const on = await gate().catch((error: unknown) => {
317+
throw new Error(`learning decision unavailable, correction not recorded: ${error instanceof Error ? error.message : String(error)}`)
318+
})
319+
if (!on) return
320+
}
321+
return appendSignal(root, signal)
322+
},
286323
turnStart: async (sessionID, messageID) => {
287324
const messages = await Session.messages({ sessionID: SessionID.make(sessionID) })
288325
return correctedTurnStart(turnMessages(messages), messageID)
@@ -294,15 +331,25 @@ export async function startCapture(ctx: { directory: string; worktree: string })
294331
},
295332
})
296333
active.add(capture)
334+
running.add(ctx.directory)
297335
const subscriptions: Array<() => void> = []
336+
// altimate_change start — one stop path for disposal and for workspace rules
337+
// One stop, shared: a second caller (the instance disposer overlapping a settings change) waits for the
338+
// same flush instead of returning before the pending signal writes land.
339+
let stopping: Promise<void> | undefined
340+
const stopCapture = () =>
341+
(stopping ??= (async () => {
342+
for (const stop of subscriptions) stop()
343+
await capture.flush()
344+
await flushWrites()
345+
active.delete(capture)
346+
running.delete(ctx.directory)
347+
unregister()
348+
})())
298349
const unregister = registerDisposer(async (directory) => {
299-
if (directory !== ctx.directory) return
300-
for (const stop of subscriptions) stop()
301-
await capture.flush()
302-
await flushWrites()
303-
active.delete(capture)
304-
unregister()
350+
if (directory === ctx.directory) await stopCapture()
305351
})
352+
// altimate_change end
306353
subscriptions.push(
307354
await subscribeWhenReady(() => Bus.subscribe(MessageV2.Event.Updated, (evt) => capture.onMessage(evt.properties.info))),
308355
)
@@ -312,7 +359,9 @@ export async function startCapture(ctx: { directory: string; worktree: string })
312359
),
313360
)
314361
log.info("learn capture started", { root })
362+
return stopCapture
315363
} catch (e) {
316364
log.warn("learn capture not started", { error: e instanceof Error ? e.message : String(e) })
365+
return undefined
317366
}
318367
}

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

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
// altimate_change - new file
2+
import { killSwitchSet } from "@opencode-ai/core/flag/flag"
23

34
interface LearnConfig {
45
enabled?: boolean
@@ -8,12 +9,17 @@ interface LearnConfig {
89
model?: string
910
}
1011

11-
function booleanFlag(value: string | undefined): boolean | undefined {
12+
export function booleanFlag(value: string | undefined): boolean | undefined {
1213
if (value === "1" || value?.toLowerCase() === "true") return true
1314
if (value === "0" || value?.toLowerCase() === "false") return false
1415
return undefined
1516
}
1617

18+
/** Workspaces are on unless the `ALTIMATE_DISABLE_WORKSPACE` kill switch is set (`Flag`'s parse, with `env` explicit). */
19+
export function workspacesOn(env: NodeJS.ProcessEnv = process.env): boolean {
20+
return !killSwitchSet(env["ALTIMATE_DISABLE_WORKSPACE"])
21+
}
22+
1723
/** The global switch defaults on; env overrides config in both directions. */
1824
export function learnEnabled(cfg?: { enabled?: boolean }, env: NodeJS.ProcessEnv = process.env): boolean {
1925
return booleanFlag(env["ALTIMATE_LEARN"]) ?? cfg?.enabled ?? true

0 commit comments

Comments
 (0)