@wardby/cli 0.5.3 → 0.7.0

package/docs/knowledge/transactional-agent-authorization.md

@@ -0,0 +1,52 @@
+---
+type: invariant
+title: Agent authorization must share the mutation transaction
+description: Using the default access client inside a transaction disconnects grant reads from mutation isolation.
+tags: [access, transactions]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-15T10:20:14.397Z }
+sources:
+  - id: access
+    url: https://github.com/wardby/wardby/blob/9c0f910f919dec4f1a2149bae78612cda41f6007/src/mcp/auth/access.ts#L47-L70
+  - id: mutation
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/mcp/tools/agents.ts#L847-L857
+  - id: isolation
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/mcp/tools/agents.ts#L975-L985
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/mcp/auth/**", "src/mcp/tools/**"]
+  citations:
+    - id: access
+      repo: github:wardby/wardby
+      path: src/mcp/auth/access.ts
+      lines: [47, 70]
+      symbol: assertAgentAccess
+      sha: 9c0f910f919dec4f1a2149bae78612cda41f6007
+      spanHash: sha256:04c8d3accf60339956706f501fbf628ae620e8f368bd93c20825f6ef4f915cbb
+    - id: mutation
+      repo: github:wardby/wardby
+      path: src/mcp/tools/agents.ts
+      lines: [847, 857]
+      symbol: update_agent
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:f6b5789fc562f8de5ad3e905513cd239c4ac447229ee1ee6bf4378cadffaeaa6
+    - id: isolation
+      repo: github:wardby/wardby
+      path: src/mcp/tools/agents.ts
+      lines: [975, 985]
+      symbol: update_agent
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:d3c25b8684e11ec56311649d617f6e933d380d4d063257e2f21804f502b2b832
+  confidence: high
+---
+
+The access helpers default to `ctx.db`; callers inside a mutation transaction must explicitly pass `tx` so grant reads participate in the same isolation boundary.[^access] Agent updates re-check write access through `tx` and commit under Serializable isolation.[^mutation][^isolation]
+
+**Why:** checking access only before a mutation, or using the default client within it, lets a concurrent grant revocation escape the transaction’s conflict detection. The operator-facing revocation behavior is described in [Security deployment, Sharing agents](../security-deployment.md); this concept records the transaction contract behind that behavior.
+
+[^access]: src/mcp/auth/access.ts, lines 47-70.
+
+[^mutation]: src/mcp/tools/agents.ts, lines 847-857.
+
+[^isolation]: src/mcp/tools/agents.ts, lines 975-985.

package/docs/knowledge/viewer-notify-write-isolation.md

@@ -0,0 +1,30 @@
+---
+type: invariant
+title: Viewer notifications must not abort authoritative writes
+description: The viewer trigger contains notification errors so event delivery cannot fail run persistence.
+tags: [database, viewer, observability]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-16T18:34:00.557Z }
+sources:
+  - id: notify
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/prisma/migrations/20261003030000_viewer_notify_fixes/migration.sql#L1-L47
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["prisma/migrations/**", "src/viewer/**"]
+  citations:
+    - id: notify
+      repo: github:wardby/wardby
+      path: prisma/migrations/20261003030000_viewer_notify_fixes/migration.sql
+      lines: [1, 47]
+      symbol: wardby_viewer_notify
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:8c16b83ca66d420cd0ccc5824e496625baa8ebc6b1010a0721e4ac36d6419b93
+  confidence: high
+---
+
+The trigger formats the already-UTC timestamp without time-zone conversion and catches errors around pg_notify, including oversized payload failures. Its notification is a projection of the write, not a prerequisite for it.[^notify]
+
+**What to do:** preserve the exception boundary when changing event payloads. [Viewer API](../viewer-api.md) already documents resynchronizing after stream gaps; this concept records the database consequence: viewer delivery must never roll back the write it observes.
+
+[^notify]: prisma/migrations/20261003030000_viewer_notify_fixes/migration.sql, lines 1-47.

package/docs/knowledge/warm-input-publication.md

@@ -0,0 +1,30 @@
+---
+type: invariant
+title: Warm input publication must refuse replacement
+description: Atomic visibility alone is insufficient when one warm worker may receive its capability only once.
+tags: [native, isolation, workers]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-16T18:34:00.557Z }
+sources:
+  - id: publish
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/native-worker/warm-delivery.ts#L19-L36
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/native-worker/warm-delivery.ts", "src/native-worker/main.ts"]
+  citations:
+    - id: publish
+      repo: github:wardby/wardby
+      path: src/native-worker/warm-delivery.ts
+      lines: [19, 36]
+      symbol: warmDeliveryCommand
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:cfb11a192eec28b8296f9e7d56d79dd9b70c2aae4f57ef888c7e4173e1f1219b
+  confidence: high
+---
+
+Warm delivery writes stdin to an exclusive temporary file, then hard-links it to the input filename. Unlike rename, the link cannot replace an input already published by another delivery.[^publish]
+
+**What to do:** retain both complete-file visibility and no-replacement semantics. [Native sandbox, claim isolation](../native-sandbox.md#how-claims-keep-the-isolation-guarantees) already documents single-use workers and capability delivery over stdin; this is the file-publication consequence of that contract.
+
+[^publish]: src/native-worker/warm-delivery.ts, lines 19-36.

package/docs/knowledge/workspace-staging-failure.md

@@ -0,0 +1,54 @@
+---
+type: invariant
+title: Failed workspace fills must remain untrusted
+description: Collection failure must not expose a partially materialized worker tree to validation or trusted replacement.
+tags: [coding, collection, isolation]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:24:27.356Z }
+sources:
+  - id: swap
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/jobs/workspace-swap.ts#L16-L51
+  - id: docker
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/jobs/docker.ts#L385-L400
+  - id: kubernetes
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/jobs/kubernetes.ts#L738-L750
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["src/providers/jobs/workspace-swap.ts", "src/providers/jobs/docker.ts", "src/providers/jobs/kubernetes.ts"]
+  citations:
+    - id: swap
+      repo: github:wardby/wardby
+      path: src/providers/jobs/workspace-swap.ts
+      lines: [16, 51]
+      symbol: replaceDirectoryFromStaging
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:0d7e951e15553a190b064604ec72c49998f79ebff84b8983aae37b212cc56069
+    - id: docker
+      repo: github:wardby/wardby
+      path: src/providers/jobs/docker.ts
+      lines: [385, 400]
+      symbol: DockerJobLauncher.materializeWorkspace
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:3e9525156cbd3c0791e79ff7ce86b16c92b0d62d8acc92a104b604fc6f54c08f
+    - id: kubernetes
+      repo: github:wardby/wardby
+      path: src/providers/jobs/kubernetes.ts
+      lines: [738, 750]
+      symbol: KubernetesJobLauncher.materializeWorkspace
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:44a85cadf23fdb1d77c0f4e1738873327756c029ce114c4efb47276d18abac84
+  confidence: high
+---
+
+Both job launchers materialize collected worker content through a sibling staging directory. Only a successful fill proceeds to validation and replacement of the trusted workspace; a rejected fill can leave escaping symlinks and must go straight to removal without walking that tree.[^swap][^docker][^kubernetes]
+
+The swap keeps the original workspace until filling and validation succeed, then uses a backup during renames. Failure after moving the original attempts to restore it before cleanup; restoration is best effort, so this is not a crash-safe transaction.[^swap]
+
+**What to do:** keep fill, validation and replacement in that order. Never catch a collection error and continue validating or publishing the partial tree. Preserve cleanup that unlinks symlinks rather than traversing them. This complements [descriptor-bound reads](bounded-file-descriptor.md) at the directory boundary; see [coding execution](overview-coding.md).
+
+[^swap]: src/providers/jobs/workspace-swap.ts, lines 16-51.
+
+[^docker]: src/providers/jobs/docker.ts, lines 385-400.
+
+[^kubernetes]: src/providers/jobs/kubernetes.ts, lines 738-750.

package/docs/knowledge.md

@@ -21,7 +21,43 @@ docs/knowledge/
 ```
 
 `index.md` and `log.md` are reserved names and are never concepts. The default
-bundle path is `docs/knowledge`.
+bundle path is `docs/knowledge`; a repository can choose another folder (see
+[Where the bundle lives](#where-the-bundle-lives)).
+
+## Where the bundle lives
+
+Wardby itself reads the bundle in three places: the knowledge note it adds to
+every coding run, the merge watcher's drift scoping, and `wardby knowledge
+check`. For those, it uses the first of these that applies:
+
+1. **`.wardby/knowledge.yaml` on the branch names a folder.** The file has one
+   key:
+
+   ```yaml
+   path: .okf
+   ```
+
+   `path` is a folder relative to the repository root (a leading `./` and a
+   trailing `/` are ignored). It may not be absolute, contain `..`, or point
+   into `.wardby/` or `.git/`.
+
+2. **Otherwise, `docs/knowledge/`.** This is also used when
+   `.wardby/knowledge.yaml` cannot be used (invalid YAML, an unknown key, or a
+   path that breaks the rules above): Wardby logs a warning and falls back to
+   `docs/knowledge/`, and `wardby knowledge check` reports
+   `knowledge_config_invalid`. A bad file never fails a run or a dispatch.
+
+3. **No bundle at either place.** Wardby adds no knowledge note and the merge
+   watcher finds no concepts. Your agents can still keep knowledge in any folder
+   you like: say where in their system prompts or in `AGENTS.md`, and they read
+   and write it there. You give up only the automatic note and drift scoping on
+   merge; a scheduled architecture agent still re-verifies every citation on
+   its next run.
+
+Coding runs cannot change `.wardby/knowledge.yaml` (everything under `.wardby/`
+except `.wardby/services.yaml` is protected), so a person sets it, in a normal
+commit. Prompts that name the bundle folder, such as the architecture agent's
+below, should use the folder you chose.
 
 ## Concept format
 
@@ -108,7 +144,9 @@ The `spanHash` above is a placeholder; compute the real one from the cited lines
 
 ## How coding runs use the bundle
 
-When `docs/knowledge/index.md` exists on the run's base branch, Wardby adds a
+When the bundle's `index.md` (in `docs/knowledge/`, or the folder
+[`.wardby/knowledge.yaml`](#where-the-bundle-lives) names) exists on the run's
+base branch, Wardby adds a
 knowledge note to the coding run's task automatically. The note tells the agent
 that the knowledge is recalled context rather than authority (the repository's
 own instructions, such as `AGENTS.md`, win on conflict), includes the index, and
@@ -116,8 +154,8 @@ asks the agent to read the concepts covering files it will touch and to update a
 concept's prose if its change alters the behavior the concept describes.
 
 - The note is capped at 8 KiB. When the index does not fit it is cut at a line
-  boundary and a `[index truncated — list docs/knowledge/ for the rest]` marker
-  is added. The note always ends with an `[end of architecture knowledge]` line.
+  boundary and an `[index truncated — list <bundle folder>/ for the rest]`
+  marker is added. The note always ends with an `[end of architecture knowledge]` line.
 - It is dropped when the task leaves no room for it.
 - It never fails or changes a dispatch: an unreadable or oversized index, or any
   problem reading the branch, simply means no note.
@@ -138,21 +176,23 @@ Anything that writes citations must take the `sha` value from this line.
 wardby knowledge check [dir] [--root <repo root>] [--strict] [--json]
 ```
 
-`dir` defaults to `docs/knowledge` and `--root` to the current directory;
+`dir` defaults to the folder `.wardby/knowledge.yaml` under `--root` names, else
+`docs/knowledge`, and `--root` to the current directory;
 citation paths resolve against `--root`. The command prints one line per issue
 (`<severity> <code> <file>: <message>`) and a summary. It exits 1 when there is
 any error, or, with `--strict`, any warning. `--json` prints
 `{ "issues": [...] }` instead.
 
-| Code                    | Severity | Meaning                                                         | Fix                                                |
-| ----------------------- | -------- | --------------------------------------------------------------- | -------------------------------------------------- |
-| `concept_invalid`       | error    | Front-matter is missing, is not valid YAML, or fails the schema | Fix the field the message names                    |
-| `concept_secret`        | error    | The file contains a secret-shaped value                         | Remove it and rotate the credential                |
-| `index_missing`         | error    | The bundle has no root `index.md`                               | Create it                                          |
-| `index_link_broken`     | error    | An index links to a file that does not exist                    | Fix or remove the link                             |
-| `concept_not_indexed`   | warning  | A concept is not linked from any `index.md`                     | Add its line to the index                          |
-| `citation_unverifiable` | warning  | The cited file is missing or the lines are out of range         | Re-anchor the citation, or deprecate the concept   |
-| `citation_stale`        | warning  | The cited span no longer matches `spanHash`                     | Re-read the code, update the claim, then re-anchor |
+| Code                       | Severity | Meaning                                                                           | Fix                                                |
+| -------------------------- | -------- | --------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `concept_invalid`          | error    | Front-matter is missing, is not valid YAML, or fails the schema                   | Fix the field the message names                    |
+| `concept_secret`           | error    | The file contains a secret-shaped value                                           | Remove it and rotate the credential                |
+| `index_missing`            | error    | The bundle has no root `index.md`                                                 | Create it                                          |
+| `index_link_broken`        | error    | An index links to a file that does not exist                                      | Fix or remove the link                             |
+| `concept_not_indexed`      | warning  | A concept is not linked from any `index.md`                                       | Add its line to the index                          |
+| `citation_unverifiable`    | warning  | The cited file is missing or the lines are out of range                           | Re-anchor the citation, or deprecate the concept   |
+| `citation_stale`           | warning  | The cited span no longer matches `spanHash`                                       | Re-read the code, update the claim, then re-anchor |
+| `knowledge_config_invalid` | error    | `.wardby/knowledge.yaml` cannot be used, so `docs/knowledge/` was checked instead | Fix the file as the message says                   |
 
 Use plain `wardby knowledge check` while editing and `--strict` for the agent or
 CI job that maintains the bundle.