feat: workspace review — skill publish waits for the owner, review status, decision notices, served-version skill sync

docs/docs/configure/learn.md

@@ -205,7 +205,7 @@ The card never blocks the input: keep typing, and answer it when you are ready.
 
 **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.
 
-**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").
+**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. Your own proposals still waiting for review are delivered to you, and only you, from the same pull: a new rule under a "Your rules pending review" heading after the team rules, and a proposed edit in place of the rule it would replace (a proposed retirement changes nothing until it is approved). They follow the team rules' conditions (learning on, workspaces on, signed in as the account that pulled them, the same workspace and repository), and once a proposal is approved or rejected the next pull delivers what the workspace holds then. Proposals still queued on this machine and not yet sent are not delivered; they arrive with the pull after they are sent, usually the same sync. 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").
 
 **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.
 
@@ -657,7 +657,7 @@ Full setup, arms, and caveats are in the research notes in the repository under
 - **Conflict detection sees backticked identifiers.** Two rules that contradict each other in prose, with no shared identifier in backticks, depend on the reflector and the replacement step.
 - **Reflection quality depends on the model.** In our test a weaker reflector needed the replacement step to reach the same result as a stronger one. You still review every candidate.
 - **Review import is GitHub only.** GitLab, Bitbucket, and other hosts are not supported. It reads merged PRs, not open ones.
-- **Local rules are shared by hand.** In a project linked to a workspace, team rules are proposed and reviewed per rule (see [Workspace rules](#workspace-rules)). Rules in the project's local stores under `.altimate-code/learn/` are not: `promote --publish` exports them as a single-file workspace skill. Publishing a name that another checkout already published is refused unless you pass `--replace`, which only updates a skill you own. You can also commit the rules: learn creates `.altimate-code/learn/.gitignore`, which ignores everything except each store's `approved.json`, and delivery reads a committed `approved.json` in any checkout.
+- **Local rules are shared by hand.** In a project linked to a workspace, team rules are proposed and reviewed per rule (see [Workspace rules](#workspace-rules)). Rules in the project's local stores under `.altimate-code/learn/` are not: `promote --publish` exports them as a single-file workspace skill. Publishing a name that another checkout already published is refused unless you pass `--replace`, which only updates a skill you own: it is looked up among your own skills, so it also finds one that is attached to no workspace (for example after its first review request was rejected), but not one attached only to other workspaces. You can also commit the rules: learn creates `.altimate-code/learn/.gitignore`, which ignores everything except each store's `approved.json`, and delivery reads a committed `approved.json` in any checkout.
 - **One rule set per `--name`.** Delivery reads every store in the project that has an `approved.json`.
 - **Keyword retrieval can over-apply a rule.** A rule scoped to one kind of file can be retrieved for a request elsewhere that uses the same words, and the agent sometimes follows it there. In our benchmark a staging-model money rule was applied to an analysis that had to keep integer cents in 1 of 6 runs, in three of the retrieval arms. Showing the rule's scope did not remove it. Write the scope into the rule's path triggers.
 - **Benchmarks are on dbt tasks, with small samples.** The results show direction, not exact lift for your repository.

docs/docs/configure/skills.md

@@ -195,8 +195,22 @@ altimate-code skill remove my-tool          # remove skill + paired tool
 
 # Publish to the linked workspace
 altimate-code skill publish my-tool         # upload every file in the skill directory; re-run to update
+altimate-code skill publish my-tool --json  # the same, with the result (and the server's review status) as JSON
+
+# Your review requests on the linked workspace
+altimate-code workspace review status       # changes nothing on the server; --json for scripts
 ```
 
+**Workspace review.** When the workspace service supports review, `skill publish` uploads the skill to your own skills and then submits it to the linked workspace, and what it prints comes from the service's answer:
+
+- `Published "<name>" to "<workspace>"`: you own the workspace, so the skill is attached directly.
+- `Sent "<name>" for review to <owner>`: you are a member of a workspace whose owner turned review on. The team gets the skill once the owner approves it in the Altimate web app; until then only you get your pending version. Approving and rejecting happen only in the web app.
+- `Already waiting for review` or `Already approved`: the same content was already submitted or approved, so nothing new was sent.
+
+Requests sent from the CLI are recorded as such in the request's history. What the team gets is the exact version that was approved: editing the skill afterwards changes nothing for them until you run `skill publish` again, which submits the new version as an update. A member publishing to a workspace whose owner has review off is refused before anything is uploaded. If the skill uploads but cannot be sent (offline, an expired sign-in, too many open requests), the command says so and exits non-zero; running it again updates the uploaded skill and submits it. Against a workspace service without review, `skill publish` attaches the skill directly as before, which only the workspace owner can do. With `--json`, the output carries `ok`, the upload (`action`, `public_id`, `files`, `bytes`, `workspace_id`, `workspace_name`) and `review` with the service's `status`, `attached_directly`, `duplicate`, `owner_name` and `contribution` (`null` without review); every failure exits non-zero with `{"ok": false, "error": ...}`.
+
+When the owner approves or rejects one of your requests that this client has seen pending (submitted from it, or listed by an earlier check), the TUI of that project shows a notice once (with the reason for a rejection). The session server checks every 5 minutes and keeps the 50 most recent decisions in your own state directory, so a decision that arrives while the TUI is closed or disconnected is shown when it next starts (as rule review notices are). The first time a TUI opens a project, decisions already kept are recorded without a notice; `workspace review status` lists them. `altimate-code workspace review status` lists your requests on the linked workspace (skills and knowledge bases): kind, name, status, whether it is new or an update, the reviewer and their reason, and `expired` for a request waiting longer than 14 days (it can still be approved).
+
 `skill publish` sends the whole skill directory, not just `SKILL.md`, so keep secrets out of it. A built-in filter skips known file and directory names — `.env*`, `.git`, `id_rsa`, `*.pem`, `*.key`, `*.p12`, `.npmrc`/`.netrc`, `credentials.json`, `secrets.*`, `.ssh`/`.aws`, editor swap files — but it matches names only and never scans file contents, so a token inside `config.yaml` or a key named `server.crt` would still be uploaded. Built-in skills, global skills and skills the workspace itself sent you cannot be published — including the copies the VS Code / Cursor extension delivers into `.claude/skills/` and `.agents/skills/`, which carry an `.altimate-managed.json` marker.
 
 ### TUI

docs/docs/usage/cli.md

@@ -60,12 +60,15 @@ With workspaces on:
     - `altimate-code link --workspace <name|id>` links to an existing workspace (an id is matched before a name), and `altimate-code link --create [name]` creates one (named after the repo by default) and links to it. Neither prompts. If the project is already linked to a different workspace they refuse unless `--yes` is passed. Running `--create` again when the project is already linked to a workspace of that name creates nothing, so it is safe in a devcontainer's setup command; if another workspace already has that name it refuses and names its id, unless `--allow-duplicate` is passed. Linking to the workspace the project is already linked to confirms that link on this machine, which a fresh clone needs before `workspace sync` sends its memory.
     - `altimate-code workspace list [--json]` lists the workspaces your account can link to, with their ids, for `link --workspace`.
     - `altimate-code workspace status [--json]` shows the linked workspace and, when known, how many saved memories have not reached it and when skills last synced.
+    - `altimate-code workspace review status [--json]` lists your own review requests on the linked workspace (skills from `skill publish`, and knowledge bases you submitted in the web app): kind, name, status, new or update, the reviewer and their reason, and whether a pending request has waited past 14 days (`expired`; it can still be approved). It changes nothing on the server: it does not open the project, so it starts no sync (checking the link may refresh this machine's record of it, as `workspace status` does). Approving and rejecting happen in the Altimate web app.
     - `altimate-code workspace refresh` pulls the workspace's skills (memory is loaded by the next session started in the project); `altimate-code workspace sync` sends memory the workspace has not received; `altimate-code workspace unlink [--yes]` detaches the project (`--yes` is required without a terminal).
     - These commands accept `--directory`. Exit codes: `0` done, `1` failed (including when the workspace service could not be reached), `2` a request to change (not signed in, a re-link or unlink without `--yes` and no terminal to confirm on, or a `sync` to a link not yet confirmed on this machine), `3` the project is not linked. With `--json`, `ok` is `true` exactly when the exit code is `0`.
 - `/workspace` in the TUI opens a menu: **Get started** shows what the workspace provides and prompts to try (choosing one puts it in the prompt without sending it; after you link from the TUI, the confirmation shows the same summary and prompts), **Refresh** pulls the workspace's skills and memory into this project, **Sync** re-sends local memory the workspace never received, **Open in browser** (when a web URL is available) shows the workspace on the web, **Switch workspace** relinks the project, **Unlink** detaches it. In a project that is not linked yet, it offers **Link to a workspace** instead.
 - `/integrations` in the TUI opens the workspace's integration status directly (the same view as `/workspace` → Status). In a project that is not linked it offers the link, and when the workspace engine is missing or too old it offers the install and says which.
 - In a project linked to a workspace, integrations come only from the workspace's engine, so the `datamate_manager` tool is not offered there and refuses to run. `datamate-*` MCP servers already in the config still load, and a one-time notice names the file they are in; the config is not edited.
-- `altimate-code skill publish <name>` uploads a project skill to the linked workspace; see [Skills](../configure/skills.md#cli-commands).
+- `altimate-code skill publish <name>` uploads a project skill to the linked workspace, attached directly for the workspace owner and sent for the owner's review for a member when the owner has turned review on; see [Skills](../configure/skills.md#cli-commands).
+- When the owner approves or rejects one of your skill or knowledge base requests that altimate-code has seen pending (submitted from it, or listed by an earlier check), the TUI shows a notice once, with the reason for a rejection; only the TUI of that project shows it. The session server checks every 5 minutes while workspaces are on and you are signed in, and keeps the decision per account and workspace in your own state directory (`$XDG_STATE_HOME/altimate-code/workspace-reviews/`, the 50 most recent), so a TUI that was closed or disconnected when it arrived shows it when it next starts. The first time a TUI opens a project, decisions already kept are recorded without a notice; `altimate-code workspace review status` lists them.
+- Workspace skills are synced at the version the workspace serves you: the approved version, or your own pending version of a skill you submitted. The next sync follows what the workspace serves: a skill whose first submission is rejected, or that is detached from the workspace, is removed from the project; when an update to an approved skill is rejected or replaced, the skill stays at its approved version. Each skill is downloaded as one version: if it is approved or rejected while its files are being read, nothing of it is installed from that sync and it is fetched again on the next one. When a download fails, the copy already in the project is kept only if it is still the version the workspace serves, as far as the server has said (its list, or a read refused because the version just changed), or if neither the copy nor the list names a version (a copy synced before revisions, or an older server), in which case it is kept until the server says otherwise; a copy of a version it no longer serves (for example your rejected pending version), or of a skill it no longer lists, is removed until the download succeeds, even when no other skill could be downloaded. Two processes syncing the same project take turns: a sync never replaces or removes a snapshot another process installed after it started, and the next sync starts from the newer one.
 - When the linked workspace has knowledge, the agent is told to check it for best practices and team conventions before answering, without you having to mention the knowledge base.
 - In an ordinary session the agent is told every turn which workspace the project is linked to — or that none is, or that the link could not be verified just now. In an extension-pinned session it is told the pinned workspace instead, and that it differs from the project's own link. Either way "which workspace am I in?" has an answer, and the agent is told not to confuse it with a Databricks workspace or an IDE workspace folder.
 - When `altimate-code serve` is launched by the VS Code / Cursor extension, the workspace selected in the extension's panel governs that session's skills, memory and (unless `--integrations local` is set) warehouse tool routing, taking priority over whatever the project is linked to on the backend, and is scoped to the folder it was launched for. A pin is fixed for the life of the `serve` process, so the extension relaunches `serve` when the selection changes; nothing updates a running one.

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

@@ -227,6 +227,17 @@ export class Delivery {
         log.info("learn session snapshot rebuilt without team rules", { session })
         return undefined
       }
+      // A rule shown as the person's pending proposal stays only while it is still that proposal, with that wording and
+      // those paths: approved, rejected or proposed again, the session is given what the state holds now.
+      if (name === Store.WORKSPACE_RULES_STORE) {
+        const now = (await vouched!).get(lesson.id)!
+        const changed =
+          now.text !== lesson.text || JSON.stringify(now.trigger ?? null) !== JSON.stringify(lesson.trigger ?? null)
+        if (now.review !== lesson.review || (lesson.review === "pending" && changed)) {
+          log.info("learn session snapshot rebuilt: a pending team rule changed", { session })
+          return undefined
+        }
+      }
       // altimate_change end
       if (lesson.text.length > MAX_TEXT && !grandfathered.has(name))
         grandfathered.set(name, await Store.grandfathered(this.root, name, { migrate: false }).catch(() => []))

packages/opencode/src/altimate/learn/lesson.ts

@@ -17,6 +17,9 @@ export const Lesson = z.object({
   created: z.string(),
   updated: z.string(),
   provenance: z.string().optional(),
+  /** A workspace rule the person proposed that is still waiting for review: delivered to them only, under its own heading
+   * (`renderSection`). Set only by the workspace rules state (`RulesStore.vouched`). */
+  review: z.literal("pending").optional(),
 }).strict()
 export type Lesson = z.infer<typeof Lesson>
 export const RetiredLesson = Lesson.extend({ supersededBy: id.optional(), reason: z.string() })