Compare commits
2 Commits
67516adef4
...
feat/769-k
| Author | SHA1 | Date | |
|---|---|---|---|
|
12b58c3eaa | ||
| 2e2280070a |
@@ -52,20 +52,20 @@ Active workstream is **W1 — Federation v1**. Workers should:
|
||||
> the repository quality gates, independent code and security review, terminal-green CI, and
|
||||
> the applicable acceptance evidence before merge. Issue #758 remains open until M5 closes.
|
||||
|
||||
| id | status | description | issue | agent | repo | branch | depends_on | estimate | notes |
|
||||
| ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------------- | ----------------- | --------------------------------------- | ---------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
|
||||
| FCM-M0-001 | done | Publish normative PRD requirements/acceptance criteria, this M0–M5 DAG, docs-IA checklist, and legacy example/profile disposition inventory; no implementation changes | #758 | sonnet | mosaicstack/stack | `docs/758-fleet-config-management` | — | 18K | Merged via #760 (`c32d85a`); parent #758 intentionally remains open through M5 |
|
||||
| FCM-M1-001 | done | Implement narrow local-tmux v2 roster structural contract/compiler with YAML/JSON canonicalization and schema/parser parity tests | #758 | coder0 | mosaicstack/stack | `feat/758-roster-v2-compiler` | FCM-M0-001 | 30K | #764 squash `aa5b43b`; exact-head RoR and PR/main terminal-green CI; no lifecycle or live mutation |
|
||||
| FCM-M1-002 | in-progress | Reuse existing profile/persona/provision resolver for roster semantics; add canonical class/authority validation and approved aliases | #758 | native-sonnet | mosaicstack/stack | `feat/758-shared-role-resolution` | FCM-M0-001 | 25K | Started 2026-07-14 from `aa5b43b`; one shared resolver only; validator certificate-only; merge-gate sole merge authority |
|
||||
| FCM-M1-003 | not-started | Convert the M0 legacy inventory into executable example/profile/service-preset validation and explicit v1-version/retirement checks | #758 | codex | mosaicstack/stack | `test/758-example-profile-dispositions` | FCM-M1-001, FCM-M1-002 | 20K | Every shipped artifact must validate, be versioned v1, or be retired with replacement |
|
||||
| FCM-M2-001 | not-started | Migrate generic launch chain to deterministic `.env.generated` plus strict data-only `.env.local`; quarantine forbidden legacy keys | #758 | codex | mosaicstack/stack | `feat/758-generated-env-boundary` | FCM-M1-001, FCM-M1-002 | 30K | No arbitrary command compatibility path; diagnostics expose key names/hashes only |
|
||||
| FCM-M2-002 | not-started | Add generation-guarded local fleet agent create/get/update/delete mutations with plan/dry-run, atomic roster writes, and recovery output | #758 | codex | mosaicstack/stack | `feat/758-fleet-agent-crud` | FCM-M1-001, FCM-M2-001 | 30K | Fresh create persists stopped unless explicit persisted start |
|
||||
| FCM-M3-001 | not-started | Implement local roster-owned reconcile/apply plus lifecycle/status/verify/doctor contracts and stable JSON/exit codes | #758 | codex | mosaicstack/stack | `feat/758-local-reconciler` | FCM-M2-001, FCM-M2-002 | 35K | Exact systemd/tmux ownership; remote/schema-only entries are inventory only |
|
||||
| FCM-M3-002 | not-started | Add isolated systemd/tmux lifecycle, drift, socket, unmanaged-session, crash, and rollback acceptance coverage | #758 | sonnet | mosaicstack/stack | `test/758-reconciler-lifecycle-gates` | FCM-M3-001 | 25K | Proves stopped-state preservation and zero fuzzy destructive targeting |
|
||||
| FCM-M4-001 | not-started | Implement field-complete v1-to-v2 inventory/preview/migrator with alias, lifecycle, env-quarantine, and remote/connector disposition evidence | #758 | codex | mosaicstack/stack | `feat/758-v1-v2-migrator` | FCM-M1-003, FCM-M3-001 | 35K | Preview first; no unreviewed lifecycle inference |
|
||||
| FCM-M4-002 | not-started | Add reversible canary migration, rollback, stale-projection/orphan classification, and current-host 9-managed/3-unmanaged fixture coverage | #758 | sonnet | mosaicstack/stack | `test/758-migration-rollback-gates` | FCM-M4-001, FCM-M3-002 | 25K | Never starts a previously stopped agent or kills an unproven unmanaged session |
|
||||
| FCM-M5-001 | not-started | Deliver the accepted fleet documentation IA, how-to/operations/migration references, and link/example validation | #758 | haiku | mosaicstack/stack | `docs/758-fleet-config-operator-docs` | FCM-M1-003, FCM-M2-002, FCM-M3-001, FCM-M4-001 | 24K | Must close every checklist item or record an approved deferral |
|
||||
| FCM-M5-002 | not-started | Package/update asset-drift checks, rolling local canary, independent validation certificate, and release evidence | #758 | sonnet | mosaicstack/stack | `feat/758-fleet-config-release-gate` | FCM-M3-002, FCM-M4-002, FCM-M5-001 | 30K | Final #758 gate: quality, independent code/security review, validator certificate, merge-gate approval, green CI |
|
||||
| id | status | description | issue | agent | repo | branch | depends_on | estimate | notes |
|
||||
| ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ | ----------------- | --------------------------------------- | ---------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
|
||||
| FCM-M0-001 | in-progress | Publish normative PRD requirements/acceptance criteria, this M0–M5 DAG, docs-IA checklist, and legacy example/profile disposition inventory; no implementation changes | #758 | sonnet | mosaicstack/stack | `docs/758-fleet-config-management` | — | 18K | M0 exit: approved docs; every shipped example/profile/service preset classified; docs-only PR |
|
||||
| FCM-M1-001 | not-started | Implement narrow local-tmux v2 roster structural contract/compiler with YAML/JSON canonicalization and schema/parser parity tests | #758 | codex | mosaicstack/stack | `feat/758-roster-v2-compiler` | FCM-M0-001 | 30K | No lifecycle, remote, connector, secret, channel, or gateway work |
|
||||
| FCM-M1-002 | not-started | Reuse existing profile/persona/provision resolver for roster semantics; add canonical class/authority validation and approved aliases | #758 | codex | mosaicstack/stack | `feat/758-shared-role-resolution` | FCM-M0-001 | 25K | Validator is certificate-only; merge-gate remains sole merge authority |
|
||||
| FCM-M1-003 | not-started | Convert the M0 legacy inventory into executable example/profile/service-preset validation and explicit v1-version/retirement checks | #758 | codex | mosaicstack/stack | `test/758-example-profile-dispositions` | FCM-M1-001, FCM-M1-002 | 20K | Every shipped artifact must validate, be versioned v1, or be retired with replacement |
|
||||
| FCM-M2-001 | not-started | Migrate generic launch chain to deterministic `.env.generated` plus strict data-only `.env.local`; quarantine forbidden legacy keys | #758 | codex | mosaicstack/stack | `feat/758-generated-env-boundary` | FCM-M1-001, FCM-M1-002 | 30K | No arbitrary command compatibility path; diagnostics expose key names/hashes only |
|
||||
| FCM-M2-002 | not-started | Add generation-guarded local fleet agent create/get/update/delete mutations with plan/dry-run, atomic roster writes, and recovery output | #758 | codex | mosaicstack/stack | `feat/758-fleet-agent-crud` | FCM-M1-001, FCM-M2-001 | 30K | Fresh create persists stopped unless explicit persisted start |
|
||||
| FCM-M3-001 | not-started | Implement local roster-owned reconcile/apply plus lifecycle/status/verify/doctor contracts and stable JSON/exit codes | #758 | codex | mosaicstack/stack | `feat/758-local-reconciler` | FCM-M2-001, FCM-M2-002 | 35K | Exact systemd/tmux ownership; remote/schema-only entries are inventory only |
|
||||
| FCM-M3-002 | not-started | Add isolated systemd/tmux lifecycle, drift, socket, unmanaged-session, crash, and rollback acceptance coverage | #758 | sonnet | mosaicstack/stack | `test/758-reconciler-lifecycle-gates` | FCM-M3-001 | 25K | Proves stopped-state preservation and zero fuzzy destructive targeting |
|
||||
| FCM-M4-001 | not-started | Implement field-complete v1-to-v2 inventory/preview/migrator with alias, lifecycle, env-quarantine, and remote/connector disposition evidence | #758 | codex | mosaicstack/stack | `feat/758-v1-v2-migrator` | FCM-M1-003, FCM-M3-001 | 35K | Preview first; no unreviewed lifecycle inference |
|
||||
| FCM-M4-002 | not-started | Add reversible canary migration, rollback, stale-projection/orphan classification, and current-host 9-managed/3-unmanaged fixture coverage | #758 | sonnet | mosaicstack/stack | `test/758-migration-rollback-gates` | FCM-M4-001, FCM-M3-002 | 25K | Never starts a previously stopped agent or kills an unproven unmanaged session |
|
||||
| FCM-M5-001 | not-started | Deliver the accepted fleet documentation IA, how-to/operations/migration references, and link/example validation | #758 | haiku | mosaicstack/stack | `docs/758-fleet-config-operator-docs` | FCM-M1-003, FCM-M2-002, FCM-M3-001, FCM-M4-001 | 24K | Must close every checklist item or record an approved deferral |
|
||||
| FCM-M5-002 | not-started | Package/update asset-drift checks, rolling local canary, independent validation certificate, and release evidence | #758 | sonnet | mosaicstack/stack | `feat/758-fleet-config-release-gate` | FCM-M3-002, FCM-M4-002, FCM-M5-001 | 30K | Final #758 gate: quality, independent code/security review, validator certificate, merge-gate approval, green CI |
|
||||
|
||||
## Thin-core prompt diet (#528) — feat/contract-thin-core
|
||||
|
||||
|
||||
@@ -1,54 +0,0 @@
|
||||
# Customize Fleet Roles
|
||||
|
||||
Mosaic resolves persona contracts through two layers:
|
||||
|
||||
1. `fleet/roles/<canonical-class>.md` — seeded baseline contract.
|
||||
2. `fleet/roles.local/<canonical-class>.md` — operator override or custom role; this layer wins.
|
||||
|
||||
The same shared resolver is used by profile validation, provisioning, roster-v2 semantic validation,
|
||||
and launch-time persona injection.
|
||||
|
||||
## Override a baseline role
|
||||
|
||||
Create a readable Markdown contract under `roles.local` with the canonical filename and class marker:
|
||||
|
||||
```markdown
|
||||
# Code — local role definition
|
||||
|
||||
The local code role (`class: code`) follows the operator's repository conventions.
|
||||
```
|
||||
|
||||
Save it as `fleet/roles.local/code.md`. Do not edit generated or seeded baseline assets when the goal
|
||||
is a durable local customization.
|
||||
|
||||
Legacy aliases canonicalize before lookup. Therefore `roles.local/implementer.md` does not override
|
||||
`code`; use `roles.local/code.md`. See [Legacy Fleet Class Aliases](../migration/legacy-class-aliases.md).
|
||||
|
||||
## Add a custom class
|
||||
|
||||
A custom class remains supported when a readable contract exists for the exact identifier:
|
||||
|
||||
```markdown
|
||||
# Release notes — local role definition
|
||||
|
||||
The release-notes role (`class: release-notes`) prepares operator-reviewed release copy.
|
||||
```
|
||||
|
||||
Save it as `fleet/roles.local/release-notes.md`, then reference `class: release-notes` and a matching
|
||||
`tool_policy: release-notes` in roster v2. Adding only a `LIBRARY.md` row is insufficient.
|
||||
|
||||
Names such as `worker`, `analyst`, and `canary` are not built-in aliases; they need genuine custom
|
||||
contracts. `agents[].alias`, Tess, and Ultron are display names and cannot select a class.
|
||||
|
||||
## Validation and authority boundaries
|
||||
|
||||
Semantic validation reads the winning contract and rejects missing, unreadable, or empty files.
|
||||
Protected authority is derived from canonical class metadata in code, never from role prose. A custom
|
||||
contract cannot claim merge, validation-certificate, orchestration, lease, or interaction authority.
|
||||
|
||||
Roster v2 also fails closed when a protected class and tool policy do not match after canonicalization,
|
||||
or when an unprotected class claims a protected tool policy. The legacy `operator-interaction` policy
|
||||
canonicalizes to `interaction`.
|
||||
|
||||
Role customization does not issue leases, store validation certificates, mutate credentials, or
|
||||
change lifecycle state.
|
||||
@@ -1,40 +0,0 @@
|
||||
# Legacy Fleet Class Aliases
|
||||
|
||||
Fleet class compatibility is intentionally narrow. The shared resolver accepts exactly three legacy
|
||||
class names and converts them to canonical classes before persona lookup:
|
||||
|
||||
| Legacy value | Canonical value | Migration action |
|
||||
| ---------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
||||
| `implementer` | `code` | Replace class and tool-policy references with `code`. |
|
||||
| `reviewer` | `review` | Replace class and tool-policy references with `review`. |
|
||||
| `operator-interaction` | `interaction` | Replace class and roster-v2 tool-policy references with `interaction`. The legacy service artifact remains compatible. |
|
||||
|
||||
Alias support preserves existing inputs while provisioning and typed semantic output use canonical
|
||||
identities. Requested and canonical class values remain separately observable during semantic
|
||||
validation.
|
||||
|
||||
## Lookup and override behavior
|
||||
|
||||
Canonicalization precedes baseline and `roles.local` lookup. A legacy-named override such as
|
||||
`roles.local/implementer.md` is not a separate authority and is not selected for an `implementer`
|
||||
request. Customize the canonical role instead, for example `roles.local/code.md`.
|
||||
|
||||
The compatibility file `operator-interaction.md` remains shipped, but `interaction` is the canonical
|
||||
role class. Tess is an example display name only.
|
||||
|
||||
## Unresolved and custom classes
|
||||
|
||||
No names are inferred from historical usage, instance names, or similar wording. `worker`, `analyst`,
|
||||
`canary`, Tess, and Ultron are not aliases. An otherwise unknown class is accepted only if the shared
|
||||
resolver can read an actual baseline or `roles.local` contract for that exact class. A `LIBRARY.md`
|
||||
row without a readable contract fails semantic validation.
|
||||
|
||||
Custom classes receive no protected authority implicitly. Protected class/tool-policy mismatches
|
||||
fail closed.
|
||||
|
||||
## Retirement guidance
|
||||
|
||||
New configuration should emit canonical values. Existing inputs may use the three aliases during the
|
||||
compatibility period, but operators should migrate class and tool-policy fields together. Do not
|
||||
create new legacy-named role overrides; move their intended content to the canonical filename and
|
||||
validate the roster/profile before removing the old artifact.
|
||||
@@ -1,45 +0,0 @@
|
||||
# Fleet Role Classes and Authority
|
||||
|
||||
A fleet role class is a machine identity resolved from the persona library. Resolution uses the
|
||||
canonical class before consulting the baseline `fleet/roles/` and operator `fleet/roles.local/`
|
||||
layers. A readable role contract is required; an index entry alone is not semantic success.
|
||||
|
||||
## Canonicalization
|
||||
|
||||
Only these legacy class aliases are recognized:
|
||||
|
||||
| Requested class | Canonical class |
|
||||
| ---------------------- | --------------- |
|
||||
| `implementer` | `code` |
|
||||
| `reviewer` | `review` |
|
||||
| `operator-interaction` | `interaction` |
|
||||
|
||||
No other alias is inferred. In particular, `worker`, `analyst`, and `canary` are custom classes only
|
||||
when an operator supplies a readable contract for that exact class. Tess and Ultron are instance
|
||||
names, not classes. `agents[].alias` is display-only and cannot grant authority.
|
||||
|
||||
Canonicalization happens before role lookup. For example, requesting `implementer` resolves
|
||||
`code.md`; a separate `roles.local/implementer.md` cannot redefine the legacy alias. A canonical
|
||||
`roles.local/code.md` still overrides the baseline `roles/code.md` contract.
|
||||
|
||||
## Protected authority
|
||||
|
||||
Protected authority is immutable metadata derived only from canonical class. Role prose, instance
|
||||
name, display alias, tool policy, runtime, and custom role files cannot grant it.
|
||||
|
||||
| Canonical class | Granted authority | Explicit limits |
|
||||
| ----------------- | -------------------------------------------------- | --------------------------------------------------------------------------------- |
|
||||
| `merge-gate` | Sole approve-to-land and merge authority | No authority is inferred by similarly named custom roles or policies. |
|
||||
| `validator` | May issue a validation certificate | Cannot approve-to-land or merge. |
|
||||
| `orchestrator` | May orchestrate, manage topology, and issue leases | Cannot approve-to-land or merge. |
|
||||
| `team-leader` | May use orchestrator-leased capacity | Cannot issue leases or mutate roster, configuration, credentials, or merge state. |
|
||||
| `interaction` | Request and status surface | Cannot orchestrate, issue leases, mutate roster/configuration, or merge. |
|
||||
| all other classes | No protected authority implicitly | Custom contracts do not acquire protected powers from prose. |
|
||||
|
||||
Roster-v2 semantic validation requires a protected class and its canonical tool policy to match. It
|
||||
also rejects an unprotected class paired with a protected tool policy. The legacy tool-policy name
|
||||
`operator-interaction` canonicalizes to `interaction`.
|
||||
|
||||
This mapping describes authority metadata only. Lease issuance, validation-certificate storage or
|
||||
workflow, lifecycle reconciliation, credentials, roster mutation, and merge execution are outside
|
||||
this resolver contract.
|
||||
@@ -81,35 +81,6 @@ agents:
|
||||
| `agents[].lifecycle.desired_state` | yes | `running` or `stopped` |
|
||||
| `agents[].launch.yolo` | yes | boolean; structured data only, not an arbitrary command escape hatch |
|
||||
|
||||
## Semantic handoff
|
||||
|
||||
`parseRosterV2` and `normalizeRosterV2` remain synchronous and structural. After structural success,
|
||||
call the asynchronous `validateRosterV2Semantics` handoff before using persona identity or authority.
|
||||
That validator batches the baseline `fleet/roles/` and operator `fleet/roles.local/` scans, then
|
||||
delegates every agent to the shared persona resolver.
|
||||
|
||||
Semantic validation:
|
||||
|
||||
- requires the winning role contract to be readable and non-empty; `LIBRARY.md` membership alone does
|
||||
not resolve a class;
|
||||
- retains `requestedClass` separately from `canonicalClass` in typed output;
|
||||
- canonicalizes only `implementer` to `code`, `reviewer` to `review`, and
|
||||
`operator-interaction` to `interaction`;
|
||||
- canonicalizes `tool_policy` with the same exact alias table;
|
||||
- rejects protected class/tool-policy mismatches in either direction, while accepting
|
||||
`class: operator-interaction` with `tool_policy: operator-interaction` as canonical
|
||||
`interaction`;
|
||||
- derives immutable protected authority only from canonical class; and
|
||||
- accepts custom baseline or `roles.local` classes without granting protected authority.
|
||||
|
||||
`agents[].alias` remains display-only. Tess and Ultron are instance names, never semantic classes.
|
||||
Canonicalization happens before role-layer lookup, so a legacy-named override cannot redefine an
|
||||
alias as separate authority. See [Role Classes and Authority](./role-classes.md) and
|
||||
[Customize Fleet Roles](../how-to/customize-roles.md).
|
||||
|
||||
This handoff performs no filesystem, systemd, tmux, roster, credential, lease, certificate, or
|
||||
lifecycle mutation.
|
||||
|
||||
## Fail-closed boundary
|
||||
|
||||
Every object is `additionalProperties: false`. The compiler rejects unknown, missing, malformed,
|
||||
|
||||
415
docs/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md
Normal file
415
docs/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md
Normal file
@@ -0,0 +1,415 @@
|
||||
# KBN-010 — Threat, Authorization, and Constraint-Impact Gate
|
||||
|
||||
- **Issue:** [#753](https://git.mosaicstack.dev/mosaicstack/stack/issues/753)
|
||||
- **Gate status:** **PASS / GO**
|
||||
- **Reviewed baseline:** `origin/main` at `49e8a54` (2026-07-14)
|
||||
- **Frozen target:** `SHARED-CONTRACT.md` v1.0.0-rc.4 and `contracts/*.v1.ts`
|
||||
- **Disposition input:** contract commit `3f6a3387b419eb99453ee10dd25ba888faaab0b5`, tree `7ebab8fa530a7180036928cea9527f808548aa14`
|
||||
- **Scope:** documentation and future-test planning only; no runtime, schema, migration, API, configuration, dependency, CI, or deployment change
|
||||
|
||||
## 1. Decision
|
||||
|
||||
KBN-010 is **PASS / GO** against frozen contract rc.4. The original rc.3 finding remains historical detection evidence:
|
||||
|
||||
- **KBN010-SI-001 — rc.3 invalid mission composite-FK candidate key.** At rc.3, `missionsV1` declared a primary key on `id` and a unique key on `(workspace_id, project_id, id)`, but not a candidate key on `(workspace_id, id)`. Both `artifacts_workspace_mission_fk` and `approval_decisions_workspace_mission_fk` referenced exactly `(missions.workspace_id, missions.id)`. PostgreSQL requires the referenced column list of a foreign key to match a non-partial unique/primary candidate key; uniqueness of `id` alone did not satisfy that two-column reference. The rc.3 DDL was therefore invalid, and KBN-010 correctly blocked it.
|
||||
|
||||
Contract rc.4 resolves SI-001 by adding the non-partial `missions_workspace_id_uidx` candidate key on `(workspace_id, id)` while retaining the global `id` primary key and the project-congruent `(workspace_id, project_id, id)` key. Both polymorphic child FKs retain their exact workspace-safe ordered columns and `ON DELETE RESTRICT`; no target, tenancy, project-congruence, exactly-one-target, N-1, rollback, no-cascade, identity, approval, or fencing authority is weakened.
|
||||
|
||||
Independent Homelab non-author schema/security review returned **APPROVE** for the exact rc.4 commit/tree/content and found no collision with #757 connector fencing. SI-001 has no unresolved contract/schema-design impact.
|
||||
|
||||
This GO completes the KBN-010 analysis/review prerequisite only. It does **not** claim that runtime schema or migration DDL exists. KBN-100 remains held and may be released only after this PR squash-merges, the merged change reaches terminal-green CI on `main`, and issue #753 closes.
|
||||
|
||||
### 1.1 Independent rc.4 evidence identity
|
||||
|
||||
- **Commit:** `3f6a3387b419eb99453ee10dd25ba888faaab0b5`
|
||||
- **Tree:** `7ebab8fa530a7180036928cea9527f808548aa14`
|
||||
- **Stable full-index SHA-256:** `6b40a76265c4f3e6d1d30a7f262a2dd16e0d51997e99c146b59f527e6524cd42`
|
||||
- **Stable patch-id:** `058cf98026fcd1043703c866aee047c8bb144740`
|
||||
- **Verdict:** Homelab independent non-author schema/security review **APPROVE**.
|
||||
- **Reviewed conclusions:** the candidate key repairs both dependent FKs; tenant safety, polymorphic exactly-one-target semantics, RESTRICT/no-cascade behavior, and N-1/rollback semantics remain valid; #757 uses separate tables/indexes/FKs/identity/fence authority and has no collision.
|
||||
|
||||
A command-rendered patch SHA may differ when Git rendering options, headers, or command form differ. That rendering digest is non-authoritative. Canonical review identity is the Git commit object plus tree and exact file content; the stable full-index digest and stable patch-id above are corroborating identities.
|
||||
|
||||
## 2. Method and trust boundaries
|
||||
|
||||
### 2.1 Inputs inspected
|
||||
|
||||
- Canonical requirements: `docs/requirements/native-kanban-sot.md`.
|
||||
- Workstream manifest and read-only task plan.
|
||||
- Frozen health, schema, Mechanical Coordinator, and recovery contracts in full.
|
||||
- Actual current-main schema, Better Auth guard/scope helpers, project/task/mission/team controllers and repositories, fleet backlog, and `TASKS.md` parser/writer.
|
||||
- Issue #753 through the Mosaic provider wrapper.
|
||||
|
||||
### 2.2 Current-main exposure that the target must replace, not inherit
|
||||
|
||||
| Current-main fact | Constraint on future implementation |
|
||||
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Teams are global; projects, missions, tasks, agents, and fleet backlog have no `workspace_id`. | KBN-100 must add the workspace boundary and KBN-110 must query by server-derived workspace in every repository operation. |
|
||||
| `AuthGuard` authenticates a Better Auth user, while `scopeFromUser` falls back through optional tenant/team/org claims and finally user ID. | Kanban tenancy must derive from an authenticated **active workspace membership**, not this compatibility fallback or caller data. |
|
||||
| Team list/get/member endpoints return global team data to any authenticated user. | New Kanban endpoints must use a uniform no-oracle denial and must not reuse global team lookup as authorization. |
|
||||
| Project/task repositories load and mutate by bare IDs; controller checks are separate and sometimes distinguish not-found from forbidden. | Workspace predicates and authorization must be inside the authoritative transaction/repository command path. |
|
||||
| Tasks can have nullable project/mission links, free-text assignee, JSON tags, no aggregate version, and no fence. | Expand/backfill/quarantine must precede NOT NULL/composite constraints; new commands cannot trust legacy fields. |
|
||||
| `mission_tasks.status` is a second status writer. | Pre-expand must prohibit it as a write source and later retire it only after N-1 evidence. |
|
||||
| Fleet `backlog` has global JSON dependencies and TTL claims without workspace, assignment, approval, session, or fencing. | It must be frozen and imported as non-dispatching shadow data; it cannot be adapted into the canonical lease path. |
|
||||
| `packages/coord/src/tasks-file.ts` parses and mutates `TASKS.md`. | KBN-120 must replace production use with generated, read-only projection code and prove there is no import/mutation path. |
|
||||
| No Kanban transaction-local health proof, semantic audit/event chain, change proposals, canonical outbox, approval binding, or fenced lease model exists. | These are new frozen invariants, not behaviors that may be inferred from current endpoints. |
|
||||
|
||||
## 3. Authorization matrix
|
||||
|
||||
The exact route/DTO freeze belongs to KBN-105. This matrix fixes the minimum authorization behavior that freeze and later implementation must preserve.
|
||||
|
||||
| Principal/state | Permitted authority | Required authoritative checks | Explicit denials |
|
||||
| -------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
||||
| Unauthenticated caller | Public health observation only, if deployment exposes it | Health DTO validation; no proof field accepted | All canonical reads/mutations; health observation never authorizes a write |
|
||||
| Active workspace `owner`/`admin` user | Policy-allowed workspace administration and domain commands | Better Auth session; active membership; server-derived workspace; command-family role; expected version/idempotency | Foreign workspace, suspended workspace, revoked membership, caller workspace override |
|
||||
| Active workspace `member` user | Policy-allowed project/task/proposal commands | Active membership plus project/team capability and target checks in the same transaction | Admin, approval, purge, service-only Coordinator, and unrelated project commands |
|
||||
| Active workspace `auditor` user | Workspace-scoped reads and audit/evidence inspection | Active membership and read capability | Every mutation, approval, lease, token issuance, purge |
|
||||
| Active workspace `service` identity | Only explicitly issued command families | Credential maps to workspace+agent+session; agent enabled; session live; role/capability allowlist; token expiry/audience; DB recheck per command | Raw DB credentials, user/admin fallback, cross-workspace scope, command families absent from token and registry |
|
||||
| Enabled agent with live session | Agent commands matching its declared and policy-approved specialist role/capabilities | Exact workspace+agent+session binding, heartbeat/state, assignment target, lease, current decimal-string fence | Ended/offline/degraded session where policy disallows; disabled agent; another assignment/session/fence |
|
||||
| Mechanical Coordinator engine | Pure eligibility/order/expiry decisions from immutable snapshots | Complete workspace-local snapshot and policy revision | Authentication, ID loading, SQL, proof minting, scope invention, approval, certification, merge |
|
||||
| Coordinator persistence service | Service-only assignment/lease/checkpoint/recovery commands | Fresh transaction-local proof; locks; current assignment/approval/task/session/policy/fence | Public/user proof-by-value, stale approval/policy, direct completion/certification/merge |
|
||||
| Reviewer/SecReview/Certifier | Attributable evidence decisions allowed by gate policy | Active authority, author differs from reviewer, mandatory SecReview classification, immutable artifacts | Self-review; missing evidence; Certifier merge/issue-close/release |
|
||||
| Break-glass retention operator | Narrow, time-bounded purge procedure only | Separate break-glass authority, reason, scope, approvals, immutable pre-purge evidence, semantic audit, post-action reconciliation | Normal application role DELETE/UPDATE, bulk unscoped purge, unaudited hard delete |
|
||||
| Revoked/expired/disabled identity or ended session | None beyond policy-permitted public observation | Revocation/lifecycle checked from PostgreSQL on every command | Cached token/Valkey state cannot preserve authority |
|
||||
|
||||
**No-oracle rule:** authentication may return 401, but once authenticated, a foreign-workspace, nonexistent, inaccessible, or wrong-project identifier must follow the one KBN-105-frozen 404/403 policy with the same response shape and no foreign metadata, timing-derived detail, or WebSocket/MCP discrepancy.
|
||||
|
||||
## 4. Threat matrix
|
||||
|
||||
Every disposition is against the frozen target, not a claim about current-main behavior.
|
||||
|
||||
| ID | Attacker or failure | Asset | Precondition and abuse path | Frozen preventive/detective control | Required schema/API/negative-test evidence | Future owner | Residual risk | Disposition |
|
||||
| --- | --------------------------------------------------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
|
||||
| T01 | Authenticated user supplies a foreign workspace/resource ID | Tenant confidentiality and integrity | Caller knows or guesses project/task/mission/team IDs and probes REST, MCP, WebSocket, repository, or Coordinator paths | `workspace_id` on every canonical row; composite relations; server-derived tenant; uniform no-oracle denial | Composite FK/unique DDL; every repository predicate includes workspace; N100-01/02, N110-01..05, N130-01 | KBN-100, 105, 110, 130 | Timing/volume side channels require operational review | Controlled after evidence |
|
||||
| T02 | Revoked or inactive member retains an old session | Ownership and mutation authority | Authentication remains valid after workspace membership revocation | Active membership rechecked in the authoritative transaction for owners, principals, proposers, and decision actors | Active/inactive membership fixtures; N100-03, N110-06/07; no cached membership authority | KBN-100, 110 | Better Auth session may remain valid for unrelated features | Controlled after evidence |
|
||||
| T03 | User joins/forges a team relation outside its workspace | Team-owned projects and tasks | Global-current-main team behavior or a stale membership is reused | Team is intra-workspace only; workspace/team composites; active workspace membership precedes team authorization | Cross-workspace team/member/owner insert and command denials; N100-04/05, N110-08 | KBN-100, 110 | Team-role policy mistakes remain possible | Controlled after evidence |
|
||||
| T04 | Same-workspace IDs from a different project are combined | Planning hierarchy integrity | Valid mission/milestone/parent/current-milestone UUIDs are substituted | Project-congruent composite relations and serialized hierarchy validation | Mission/milestone/parent/current milestone mismatch and parent-cycle tests; N100-06..10, N110-09 | KBN-100, 110 | Deep hierarchy checks can be expensive | Controlled after evidence |
|
||||
| T05 | Foreign or unrelated evidence/link/artifact IDs are attached | Review and audit truth | Caller has a valid same-workspace or foreign artifact UUID | Workspace-aware joins; immutable artifact digest/revision; semantic same-target validation in authoritative transaction | Mixed-workspace and same-workspace wrong-task/mission checkpoint/approval evidence tests; N100-11..14, N210-15/16 | KBN-100, 110, 210 | Same-workspace semantic validation is application-enforced | Controlled after evidence |
|
||||
| T06 | Stolen, over-scoped, or replayed service token | Coordinator and task mutation authority | Service credential is accepted as admin/user or claims are trusted without DB state | Command-family least privilege; agent/session workspace binding; no raw DB credentials; enabled/live state checked per command | Auth registry fixtures prove audience/expiry/role/capability; revoked agent and ended session denials; N105-01, N110-10..13, N210-01/02 | KBN-105, 110, 210 | Credential theft until expiry/revocation check | Controlled after evidence |
|
||||
| T07 | Caller forges public `healthy` or replays a stale health response | Sole-writer/fail-closed invariant | Public health body or caller field reaches mutation context | Public DTO is observation only; public DTOs reject proof/health fields; Gateway mints internal proof after live PG transaction probe | Contradictory union and forbidden-field tests; N105-02, N110-14..17 | KBN-105, 110, 140 | Health endpoint can still be used for reconnaissance | Controlled after evidence |
|
||||
| T08 | Internal stale, wrong-policy, or wrong-transaction proof is reused | Transaction integrity | A branded value leaks or an adapter fails to revalidate it | Non-exported brand; transaction identity, `checkedAt <= now < validUntil`, and policy revision revalidated immediately before mutation | Wrong transaction, expiry boundary, future timestamp, policy mismatch, commit-after-expiry tests; N110-18..22 | KBN-110, 140 | In-process code can bypass TypeScript; runtime checks are mandatory | Controlled after evidence |
|
||||
| T09 | DB/transport uncertainty is mislabeled as deliberate denial or conflict | Safe retry and exactly-once result | Timeout occurs before/after commit and client changes key or retries 503 | Exact 503/502/504/timeout/409 union; unknown outcome retries only with same idempotency key | Exhaustive fixture mapping and commit-before-timeout replay; N105-03, N110-23..27, N120-01/02 | KBN-105, 110, 120, 140 | External client may ignore retry rules | Controlled after evidence |
|
||||
| T10 | Assignment payload forges task version, target agent/session, role, expiry, or proposer | Work routing authority | Lease service trusts command DTO rather than persisted assignment | Persisted assignment identity; exactly-one principal/proposer; exact agent/session composite; acquire accepts IDs then reloads+locks | Cross-workspace and same-workspace target substitutions, stale task version, invalid role, expired assignment; N100-15..18, N210-03..08 | KBN-100, 200, 210 | Compromised authorized proposer can make harmful proposals | Controlled by approval/audit |
|
||||
| T11 | Approval proof is forged by value or borrowed from another assignment | Gate integrity | Caller submits `approved=true`, unrelated decision ID, stale policy, or self-approval | Relational approval bound to assignment; lock/reload; policy revision; author≠reviewer and mandatory SecReview | No proof-by-value DTO; wrong assignment/task/workspace/policy/actor/decision tests; N105-04, N210-09..14, N230-01 | KBN-105, 210, 230 | Colluding principals remain an organizational risk | Controlled after evidence |
|
||||
| T12 | Revoked policy or expired proposal/assignment is raced against lease acquisition | Routing policy | Approval and lease transactions do not lock/revalidate current rows | Lock assignment, approval, task, target session; compare current policy and expiry inside fresh-proof transaction | Concurrent revoke/expire/acquire tests with one valid terminal result; N210-17..19 | KBN-210, 230 | Clock skew if DB time is not canonical | Controlled after evidence |
|
||||
| T13 | Stale worker sends ack/heartbeat/checkpoint/review after reassignment | Canonical task and evidence state | Old process retains task/session IDs | Task-row-locked atomic monotonic bigint fence; every worker command carries exact lease/session/fence | Lower, expired, future, and other-task fences denied; old worker loses after new lease; N100-19/20, N210-20..24 | KBN-100, 210, 230 | Signed bigint exhaustion is theoretical | Controlled after evidence |
|
||||
| T14 | JavaScript precision truncates a fence | Stale-worker exclusion | bigint token is serialized as number above `2^53-1` | Drizzle bigint and decimal-string wire type only | `9007199254740993` and near-`int8` boundary round trips; numeric JSON rejected; N105-05, N210-25 | KBN-105, 210 | Nonconforming external clients | Controlled after evidence |
|
||||
| T15 | Checkpoint/evidence from another lease/task/session is submitted | Recovery and certification evidence | Same-workspace valid IDs are mixed | Exact lease composite binds workspace+task+assignment/session+fence; checkpoint composite binds lease+fence; evidence join plus semantic artifact-owner check | Same-workspace mismatched task/assignment/lease/session/checkpoint/artifact tests; N100-21..23, N210-26..31 | KBN-100, 210 | Artifact URI target may disappear outside DB | Controlled with digest/retention |
|
||||
| T16 | Outage note or pending/rejected proposal mutates/orders work | Sole SOT and gate integrity | Importer/UI treats note/proposal as task state | Proposals are inert; only explicit accept invokes normal typed command after recovery | Row/outbox/task counts unchanged for pending/rejected; no readiness/dependency/lease effect; N110-28..31 | KBN-110, 140 | Humans may act outside Mosaic operationally | Accepted as attributable residual |
|
||||
| T17 | Submission event is missing, foreign, or for another proposal | Proposal audit chain | Caller supplies an existing event UUID | Preallocated proposal ID; event-first same transaction; workspace composite FK; exact event type/aggregate/version semantic check | Missing/foreign/wrong-type/wrong-proposal event rolls back event+proposal; N100-24/25, N110-32..36 | KBN-100, 110 | Semantic checks are transaction code, not only FK | Controlled after evidence |
|
||||
| T18 | Acceptance borrows an unrelated command event | Proposal and target integrity | Same-workspace event exists for another target/command/proposal | Accept locks proposal+target, executes normal command, requires workspace/target match, causation=submission event, payload proposal ID | Foreign, wrong target/type/command/causation/payload event aborts target/event/proposal atomically; N100-26, N110-37..43 | KBN-100, 110 | Event payload schema drift | Controlled by KBN-105 fixtures |
|
||||
| T19 | Application role updates/deletes audit, approval evidence, checkpoint, or artifact | Nonrepudiation | Broad DB grants or parent cascade exists | INSERT/SELECT-only application roles; RESTRICT parent deletes; archive/cancel normal lifecycle | Role-level UPDATE/DELETE denied; parent delete RESTRICT; digest unchanged; N100-27..31 | KBN-100 | DB superuser can alter state | Break-glass/infra audit residual |
|
||||
| T20 | Break-glass purge is used as routine deletion or erases its own evidence | Retention and incident forensics | Elevated credential available | Separate audited retention procedure, bounded scope, reason, pre/post evidence, authority separation | Normal role denied; expired/missing approval denied; purge cannot delete its authorizing audit package; N115-01, N230-02/03 | KBN-115, 230 | Privileged DBA compromise | Accepted operational residual |
|
||||
| T21 | PostgreSQL unavailable or partitioned | Canonical state | Public health/Valkey remains live while transaction probe fails | Fail closed; no alternate writer/hidden queue; 503 only for proven not-applied; transport uncertainty remains unknown | Fault injection proves DB rows/outbox/files/Valkey unchanged on deliberate denial; commit-unknown replay; N110-44..48, N140-01 | KBN-110, 140, 230 | Availability loss is intentional | Accepted by Option A |
|
||||
| T22 | Valkey unavailable, duplicated, stale, or partitioned | Scheduling notifications | Queue wake is treated as truth or publication fails | Valkey derived/expendable; transactional outbox in PG; idempotent publisher; recovery from PG | Commit with Valkey down leaves pending outbox; replay publishes once logically; stale wake reloads PG; N110-49, N140-02, N230-04..06 | KBN-110, 210, 230 | Duplicate at-least-once delivery | Consumers must be idempotent |
|
||||
| T23 | Coordinator restarts between assignment, lease, checkpoint, or outbox steps | Durable orchestration truth | Process-local cache is treated as authority | PostgreSQL stores assignments, execution state, leases, fences, checkpoints, events, outbox; `recoverFromPostgres` | Restart at every transaction boundary reconstructs identical active/expired/pending sets without Valkey/files; N210-32..36, N230-07 | KBN-210, 230 | Recovery latency | Controlled after evidence |
|
||||
| T24 | Dependency cycle or concurrent reciprocal edge | Readiness and dispatch safety | Two transactions each see an acyclic graph before inserting | Unique directed edge; no self-edge; serialized recursive cycle check; readiness evaluates all blockers | Self/duplicate/cycle and concurrent A→B/B→A tests; all predecessor property test; N100-32..35, N200-01/02 | KBN-100, 200, 230 | Very large DAG performance | Bounded operational residual |
|
||||
| T25 | Parent-task cycle or project-incongruent relation | Planning hierarchy | Valid same-workspace IDs are arranged into an invalid tree | Project-congruent composites; serialized parent-cycle/orphan validation required by REQ-PLAN-001 | Self/indirect parent cycle, orphan, and cross-project mission/milestone/parent tests; N100-06..10 | KBN-100, 110 | Cycle validation is service/transaction enforced | Controlled after evidence |
|
||||
| T26 | Concurrent update, duplicate retry, or idempotency payload drift | Aggregate consistency | Two clients use same version/key with different payloads | Expected-version check; semantic event and outbox in same transaction; key returns prior immutable result only for identical command | One update wins; stale gets 409; duplicate identical returns prior; payload drift rejected; N110-50..54, N140-03 | KBN-105, 110, 140 | Long-lived clients face visible conflicts | Intentional user-visible residual |
|
||||
| T27 | State/event/outbox partial commit | Audit and notification consistency | Separate transactions or exception after state write | One PostgreSQL transaction for state+semantic event+outbox | Failure injected after each insert rolls all three back; success revisions align; N110-55..58 | KBN-110, 140 | Outbox publication remains asynchronous | Controlled after evidence |
|
||||
| T28 | Malicious/incorrect importer injects foreign workspace data or dispatchable work | Migration integrity | Source keys collide, lineage is absent, or importer has direct DB authority | Immutable source snapshots/checksums; one-way Gateway/migration-only port; workspace-safe idempotent modes; shadow records cannot dispatch | Foreign/malformed/duplicate/partial-resume/lineage checksum and no-dispatch tests; N300-01..08 | KBN-300, 330 | Source data may be semantically ambiguous | Quarantine and owner sign-off |
|
||||
| T29 | Cutover leaves legacy writer or forward/reverse sync active | Sole-writer invariant | Credentials/processes survive switch or rollback is improvised | Writer inventory, freeze, final delta, Gateway switch, credential shutdown, no dual write; rollback authority changes after first DB mutation | Process/credential inventory; concurrent-writer assertion; before/after-mutation rollback rehearsal; N320-01..06, N330-01 | KBN-320, 330, 340 | Missed external automation | Owner-gated residual |
|
||||
| T30 | Generated `TASKS.md`/`mission.json` is edited or parsed into DB | Canonical state | Current-main parser/writer remains reachable or file watcher imports changes | Generated non-authoritative header/IDs/time/revision; no production importer; regenerate/overwrite only | Static import search, tamper/regeneration, read-only permission, source-revision parity; N120-03..07, N140-04 | KBN-120, 140 | Humans may mistake snapshots for live data | Header and docs mitigate |
|
||||
| T31 | N-1 compatibility copies legacy ambiguity into canonical authority | Data integrity | Nullable/global/current-main fields are guessed during backfill | Nullable-first expand; deterministic mapping or quarantine; checksums; no new-only status before switch; legacy fields retained | Production-shape, ambiguous owner/assignee, status shadow, JSON/config/digest, rollback tests; N100-36..44 | KBN-100 | Quarantined records require human decision | Controlled by signed reconciliation |
|
||||
| T32 | Recovery posture claims durability not provided by mechanisms | Availability and audit retention | Shape-only validation or optimistic RPO is accepted | Normative validator; WAL/PITR/RPO/storage/high-assurance constraints; mechanism and restore evidence | Unknown/impossible/weakened configuration plus actual mechanism/restore tests; N115-02..08 | KBN-115 | Backup operator or storage compromise | Separate failure domain residual |
|
||||
| T33 | rc.3 frozen DDL could not create mission-scoped evidence/approval FKs | Tenant/evidence relational integrity | KBN-100 generated DDL from the rc.3 contract without an exact composite candidate key | rc.4 adds non-partial `missions_workspace_id_uidx(workspace_id,id)` before both dependent FKs while retaining global and project-congruent keys | KBN-100 must execute N100-45..50: exact-key reconciliation, candidate-before-FKs, duplicate feasibility, empty/prod/N-1/rollback, and both-child foreign-workspace negatives | KBN-100 after PR/CI/#753 release | Runtime DDL remains unimplemented and must prove the frozen order | **Resolved by rc.4 + independent APPROVE; implementation evidence remains required** |
|
||||
|
||||
## 5. Constraint-impact matrix
|
||||
|
||||
| Impact ID | Required invariant | Frozen schema impact | API/transaction impact | Required evidence | Owner | Status |
|
||||
| --------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------- |
|
||||
| CI-01 | Hard workspace tenancy and no oracle | `workspace_id`, workspace-aware unique/FKs on all canonical rows | Server-derived workspace; uniform denial on all surfaces | N100-01..14; N110-01..09; N130-01 | KBN-100/105/110/130 | Resolved by frozen controls |
|
||||
| CI-02 | Active user membership | Membership row plus unique `(workspace_id,user_id)`; active state retained | Recheck active membership in same authoritative transaction | N100-03; N110-06/07 | KBN-100/110 | Resolved; not FK-only |
|
||||
| CI-03 | Service identity least privilege/revocation | Agent/session workspace, lifecycle, state, roles, capabilities | Token maps to exact agent/session; command-family allowlist; DB recheck; no admin/raw DB fallback | N105-01; N110-10..13; N210-01/02 | KBN-105/110/210 | Resolved at auth/API layer |
|
||||
| CI-04 | Project-congruent hierarchy | Composite project/mission/milestone/parent/current-milestone relations | Lock/serialized parent-cycle and orphan validation | N100-06..10 | KBN-100/110 | Resolved; cycle behavior required |
|
||||
| CI-05 | Health-proof authority | Internal branded proof has transaction/time/policy fields | Probe and revalidate on same PG transaction; no public field | N105-02/03; N110-14..27 | KBN-105/110 | Resolved by frozen controls |
|
||||
| CI-06 | Assignment/approval identity | Exactly-one principal/proposer, exact agent/session assignment, relational approval | Reload+lock all IDs; compare version/target/state/expiry/policy/decision | N100-15..18; N210-03..19 | KBN-100/210 | Resolved by frozen controls |
|
||||
| CI-07 | Monotonic bigint fencing | Durable bigint counter, exact lease/fence keys, one active lease | Atomic increment/RETURNING; decimal-string DTO; reject every stale worker command | N100-19..23; N210-20..31 | KBN-100/105/210 | Resolved by frozen controls |
|
||||
| CI-08 | Proposal event chain | Both workspace-aware event FKs; event table created first | Exact submission/acceptance semantic checks in one transaction | N100-24..26; N110-28..43 | KBN-100/110 | Resolved; semantic checks not FK-only |
|
||||
| CI-09 | Immutable audit/evidence retention | RESTRICT parents; INSERT/SELECT-only immutable tables | Archive/cancel normal flow; separately authorized purge | N100-27..31; N115-01; N230-02/03 | KBN-100/115/230 | Resolved by frozen controls |
|
||||
| CI-10 | DB/Valkey/outbox/restart semantics | PG outbox and durable orchestration rows | Fail closed; same-key uncertainty retry; Valkey reloads PG; restart from PG | N110-44..49; N140-01/02; N230-04..07 | KBN-110/210/230 | Resolved by frozen controls |
|
||||
| CI-11 | DAG/race/idempotency/version | Unique edge; self check; event idempotency; aggregate versions | Serialized recursive cycle check; payload binding; expected-version conflict | N100-32..35; N110-50..58; N200-01/02 | KBN-100/110/200 | Resolved by frozen controls |
|
||||
| CI-12 | Import/cutover trust boundary | Lineage/artifact/event fields; shadow state cannot dispatch | One-way scoped importer, freeze, no direct DB/file authority, no dual writer | N300-01..08; N320-01..06 | KBN-300/320/330 | Resolved by frozen controls |
|
||||
| CI-13 | Generated-file no-import | No canonical file schema/import contract | Projection-only package; static reachability check removes current parser from production Kanban paths | N120-03..07; N140-04 | KBN-120/140 | Resolved by frozen controls |
|
||||
| CI-14 | Mission-scoped artifact and approval FKs | rc.4 adds non-partial `missions_workspace_id_uidx(workspace_id,id)` and retains global/project-congruent keys | KBN-100 must emit the candidate before both exact RESTRICT FKs and preserve N-1/rollback order | N100-45..50: exact reconciliation, duplicate feasibility, empty/prod/N-1/rollback, and separate artifact/approval foreign-workspace negatives | KBN-100 after PR/CI/#753 release | **Resolved by rc.4 and independent APPROVE; future executable evidence required** |
|
||||
|
||||
## 6. Exact future negative-test catalog
|
||||
|
||||
These names are normative evidence identifiers for future slices. Equivalent test-file names are acceptable only if traceability retains these IDs and expected outcomes.
|
||||
|
||||
### KBN-100 — schema and migration
|
||||
|
||||
- **N100-01** reject every canonical child row whose `workspace_id` differs from its parent.
|
||||
- **N100-02** reject foreign-workspace link, artifact, proposal target, dependency, assignment, lease, checkpoint, approval, and event relationships.
|
||||
- **N100-03** reject an inactive/revoked member as accountable owner, proposer, decision actor, archive actor, or user principal in the authoritative command transaction.
|
||||
- **N100-04** reject a team/project relation crossing workspaces.
|
||||
- **N100-05** reject a team authorization path when the user lacks active membership in the team's workspace.
|
||||
- **N100-06** reject task→mission project mismatch.
|
||||
- **N100-07** reject task→milestone and project→current-milestone project mismatch.
|
||||
- **N100-08** reject task→parent project mismatch and self-parent.
|
||||
- **N100-09** reject indirect parent cycles under concurrent transactions.
|
||||
- **N100-10** reject mission→milestone project mismatch/orphan.
|
||||
- **N100-11** reject checkpoint artifact from another workspace.
|
||||
- **N100-12** reject checkpoint artifact owned by another same-workspace task/mission unless an explicitly frozen evidence rule permits it.
|
||||
- **N100-13** reject approval evidence from another workspace.
|
||||
- **N100-14** reject same-workspace approval evidence unrelated to the approval target.
|
||||
- **N100-15** reject zero/multiple assignment principals and zero/multiple proposers.
|
||||
- **N100-16** reject target session without its exact target agent.
|
||||
- **N100-17** reject assignment task/agent/session crossing workspaces.
|
||||
- **N100-18** reject non-positive task version and expired assignment acquisition.
|
||||
- **N100-19** concurrent lease insert permits one active lease and returns one winner.
|
||||
- **N100-20** successive leases return strictly increasing bigint fences.
|
||||
- **N100-21** reject checkpoint with another task, lease, or fence.
|
||||
- **N100-22** reject duplicate/non-monotonic checkpoint sequence.
|
||||
- **N100-23** reject evidence join for a mismatched checkpoint/task.
|
||||
- **N100-24** proposal insert without exact submission event fails atomically.
|
||||
- **N100-25** foreign/wrong-type/wrong-proposal submission event fails atomically.
|
||||
- **N100-26** foreign/wrong-target/unrelated acceptance event fails atomically.
|
||||
- **N100-27** application role cannot UPDATE/DELETE `task_events`.
|
||||
- **N100-28** application role cannot UPDATE/DELETE checkpoints/artifacts/evidence joins.
|
||||
- **N100-29** parent hard delete is RESTRICTed while audit/evidence children exist.
|
||||
- **N100-30** archive does not alter canonical lifecycle status.
|
||||
- **N100-31** purge without break-glass authority/evidence is denied.
|
||||
- **N100-32** reject dependency self-edge and duplicate directed pair regardless of type.
|
||||
- **N100-33** reject direct and indirect dependency cycles.
|
||||
- **N100-34** concurrent reciprocal dependency inserts cannot both commit.
|
||||
- **N100-35** readiness remains false until every blocking predecessor and completion condition passes.
|
||||
- **N100-36** empty DB migration succeeds after the contract amendment.
|
||||
- **N100-37** production-shape expand retains all legacy declarations.
|
||||
- **N100-38** crash/resume backfill is idempotent and checksum-stable.
|
||||
- **N100-39** ambiguous workspace/owner/assignee is quarantined, never guessed.
|
||||
- **N100-40** no `ready`/`in_review` status is emitted to N-1 readers before switch.
|
||||
- **N100-41** `mission_tasks.status` cannot remain a write source.
|
||||
- **N100-42** tags/assignee/date/mission JSON/config/description/agent fields reconcile without loss.
|
||||
- **N100-43** claimed fleet backlog rows are quarantined and imported rows cannot dispatch.
|
||||
- **N100-44** pre-switch rollback works while post-first-mutation rollback requires freeze/reconciliation.
|
||||
- **N100-45** reconcile both exact child FK column lists to the rc.4 `(workspace_id,id)` mission candidate while retaining the global `id` primary key and `(workspace_id,project_id,id)` key.
|
||||
- **N100-46** empty-DB migration creates `missions_workspace_id_uidx` before `artifacts_workspace_mission_fk` and `approval_decisions_workspace_mission_fk`.
|
||||
- **N100-47** production-shape preflight finds no duplicate `(workspace_id,id)` groups, preserves global `id` uniqueness, and applies the candidate before both dependent FKs.
|
||||
- **N100-48** N-1 startup/read/write remains unchanged; pre-switch rollback drops both dependents before the candidate and preserves the global/project-congruent keys.
|
||||
- **N100-49** artifact insert using a valid mission ID paired with a foreign workspace fails before commit.
|
||||
- **N100-50** approval-decision insert using a valid mission ID paired with a foreign workspace fails before commit.
|
||||
|
||||
### KBN-105/KBN-110/KBN-120/KBN-130/KBN-140 — API and P1
|
||||
|
||||
- **N105-01** every route has an explicit user/service command-family policy; user/admin tokens cannot call service-only Coordinator mutations.
|
||||
- **N105-02** public DTO validation rejects `writeProof`, internal context, body `workspaceId`, and caller-asserted health.
|
||||
- **N105-03** fixture exhaustiveness prevents 503, 502/504/timeout, and 409 cross-mapping.
|
||||
- **N105-04** approval DTO accepts an ID and decision command only, never approval proof-by-value.
|
||||
- **N105-05** all fence fields accept/emit decimal strings and reject JSON numbers.
|
||||
- **N110-01** listing with a foreign `workspaceId` or foreign filter ID follows the frozen no-oracle denial and returns no rows/counts/cursors.
|
||||
- **N110-02** get by foreign or nonexistent aggregate ID has the same frozen denial shape and no foreign metadata.
|
||||
- **N110-03** create/update/archive with a foreign owner, parent, project, mission, milestone, tag, or target ID is denied before mutation.
|
||||
- **N110-04** dependency/proposal commands with foreign target IDs are denied with unchanged state/event/outbox counts.
|
||||
- **N110-05** REST, MCP, WebSocket, and internal Coordinator paths produce equivalent no-oracle behavior for the same foreign ID.
|
||||
- **N110-06** a revoked/inactive owner is denied even with a still-valid Better Auth session.
|
||||
- **N110-07** stale membership/team cache cannot authorize a proposer, decision actor, archive actor, or principal after revocation.
|
||||
- **N110-08** a team ID from another workspace cannot authorize or own the command target.
|
||||
- **N110-09** same-workspace but wrong-project mission/milestone/parent IDs are denied inside the transaction.
|
||||
- **N110-10** an expired service token is denied before repository access.
|
||||
- **N110-11** an audience- or workspace-mismatched service token is denied without an existence oracle.
|
||||
- **N110-12** an over-scoped service token cannot call a command family absent from its role/capability allowlist.
|
||||
- **N110-13** disabled agent or ended session revokes service-token command authority immediately on PostgreSQL recheck.
|
||||
- **N110-14** contradictory public health state/boolean combinations fail validation.
|
||||
- **N110-15** Valkey-only liveness cannot mint or substitute a PostgreSQL write proof.
|
||||
- **N110-16** caller-forged public `healthy` cannot enter internal mutation context.
|
||||
- **N110-17** public REST/MCP/CLI bodies containing health/proof fields are rejected.
|
||||
- **N110-18** an expired internal proof produces no state/event/outbox write.
|
||||
- **N110-19** a future-dated or not-yet-valid proof produces no write.
|
||||
- **N110-20** a policy-revision-mismatched proof produces no write.
|
||||
- **N110-21** a proof minted on another transaction/connection produces no write.
|
||||
- **N110-22** a proof that expires before the final pre-mutation check produces no write.
|
||||
- **N110-23** deliberate read-only/write-unavailable denial maps only to authoritative 503/not-applied/non-retryable.
|
||||
- **N110-24** timeout before commit maps to transport-unknown and permits only same-key retry.
|
||||
- **N110-25** timeout after commit maps to transport-unknown and same-key retry returns the committed canonical result once.
|
||||
- **N110-26** expected-version mismatch maps only to 409/not-applied/non-retryable.
|
||||
- **N110-27** recovery replay with a changed idempotency key cannot masquerade as the original uncertain request.
|
||||
- **N110-28** pending proposal cannot alter target fields/status/rank/version.
|
||||
- **N110-29** rejected proposal cannot affect readiness, dependencies, or gates.
|
||||
- **N110-30** pending/rejected proposal cannot create an assignment or lease.
|
||||
- **N110-31** direct proposal-row state manipulation cannot bypass normal command execution.
|
||||
- **N110-32** proposal submission without a submission event rolls back fully.
|
||||
- **N110-33** foreign-workspace submission event rolls back fully.
|
||||
- **N110-34** wrong aggregate/event type submission event rolls back fully.
|
||||
- **N110-35** same-workspace event for another proposal rolls back fully.
|
||||
- **N110-36** submission event with wrong previous/new version semantics rolls back fully.
|
||||
- **N110-37** foreign-workspace acceptance event rolls back proposal, target, event, and outbox.
|
||||
- **N110-38** same-workspace event for another target aggregate rolls back acceptance.
|
||||
- **N110-39** event from an unrelated normal command rolls back acceptance.
|
||||
- **N110-40** event caused by a different submission event rolls back acceptance.
|
||||
- **N110-41** event whose payload lacks or changes `changeProposalId` rolls back acceptance.
|
||||
- **N110-42** event for another proposal with the same target/command rolls back acceptance.
|
||||
- **N110-43** missing accepted-command event after target handling rolls back the entire transaction.
|
||||
- **N110-44** read-only-degraded denial changes no DB row/outbox/file/Valkey/provider state.
|
||||
- **N110-45** write-unavailable denial changes no DB row/outbox/file/Valkey/provider state.
|
||||
- **N110-46** PostgreSQL disconnect cannot redirect a command to any fallback writer.
|
||||
- **N110-47** commit uncertainty remains `unknown` and never becomes a fabricated 503/not-applied result.
|
||||
- **N110-48** same-key replay after recovery returns one canonical result with no duplicate event/outbox row.
|
||||
- **N110-49** Valkey publication failure leaves committed PG outbox pending and replayable.
|
||||
- **N110-50** two same-version updates produce one winner and one visible 409 loser.
|
||||
- **N110-51** identical duplicate key+payload returns the prior immutable result without another event/outbox row.
|
||||
- **N110-52** same key with payload/command drift is rejected as an idempotency conflict.
|
||||
- **N110-53** the same key in another workspace cannot reveal or reuse the first workspace's result.
|
||||
- **N110-54** stale reconnect/update cannot silently overwrite a newer aggregate revision.
|
||||
- **N110-55** failure after state write but before semantic event rolls back state.
|
||||
- **N110-56** failure after semantic event but before outbox rolls back state and event.
|
||||
- **N110-57** failure after outbox insert but before commit rolls back state, event, and outbox.
|
||||
- **N110-58** success commits matching aggregate/event/outbox revisions and correlation/causation.
|
||||
- **N120-01** CLI never retries an authoritative 503 deliberate denial.
|
||||
- **N120-02** CLI retries only transport-unknown outcomes and preserves the exact idempotency key.
|
||||
- **N120-03** generated projection header contains non-authoritative warning, workspace/project IDs, generated time, and source revision.
|
||||
- **N120-04** projection revision and records match the API snapshot revision exactly.
|
||||
- **N120-05** hand-tampering is overwritten or rejected by regeneration and never mutates PostgreSQL.
|
||||
- **N120-06** static/runtime reachability finds no parser/import path from `TASKS.md`, `mission.json`, or another export.
|
||||
- **N120-07** projection writer has no domain mutation/raw SQL/Valkey authority.
|
||||
- **N130-01** UI foreign/no-access/not-found state follows the frozen no-oracle response and renders no stale foreign data.
|
||||
- **N140-01** real-Gateway DB fault journey proves fail-closed no-fallback behavior.
|
||||
- **N140-02** real-Gateway Valkey-loss journey proves pending outbox replay.
|
||||
- **N140-03** real-Gateway concurrent update/retry journey proves version and idempotency semantics.
|
||||
- **N140-04** generated-file tamper journey proves projection parity and no import.
|
||||
|
||||
### KBN-115/KBN-200/KBN-210/KBN-230 — recovery and coordination
|
||||
|
||||
- **N115-01** retention purge without current break-glass authority, reason, immutable evidence, or bounded scope is denied and audited.
|
||||
- **N115-02** recovery posture with an unknown top-level or storage field is rejected.
|
||||
- **N115-03** PITR retention without WAL archival is rejected.
|
||||
- **N115-04** WAL archival with zero PITR retention is rejected.
|
||||
- **N115-05** claimed RPO better than the configured backup/WAL mechanism is rejected.
|
||||
- **N115-06** unencrypted, optional, or same-failure-domain storage is rejected.
|
||||
- **N115-07** weakened high-assurance values are rejected.
|
||||
- **N115-08** shape-only validation cannot pass without normative mechanism and restore evidence.
|
||||
- **N200-01** cyclic/incomplete dependency snapshots never become eligible.
|
||||
- **N200-02** identical immutable snapshot+policy+time returns identical ordering and explanation with no I/O/model import.
|
||||
- **N210-01** disabled agent cannot claim, ack, heartbeat, checkpoint, or submit review.
|
||||
- **N210-02** ended/offline/mismatched session cannot claim, ack, heartbeat, checkpoint, or submit review.
|
||||
- **N210-03** foreign-workspace task is rejected after lock/reload without an oracle.
|
||||
- **N210-04** stale task version is rejected before fence increment.
|
||||
- **N210-05** assignment target agent mismatch is rejected.
|
||||
- **N210-06** target session mismatch is rejected.
|
||||
- **N210-07** expired assignment is rejected.
|
||||
- **N210-08** assignment in rejected/released/expired/superseded/leased-invalid state is rejected.
|
||||
- **N210-09** missing approval is rejected.
|
||||
- **N210-10** rejected/escalated/requested approval is rejected as approval authority.
|
||||
- **N210-11** stale policy-revision approval is rejected.
|
||||
- **N210-12** foreign-workspace approval is rejected without an oracle.
|
||||
- **N210-13** approval for another assignment is rejected.
|
||||
- **N210-14** author self-approval/review is rejected when independence is required.
|
||||
- **N210-15** foreign-workspace artifact evidence is rejected.
|
||||
- **N210-16** same-workspace artifact unrelated to the assignment/task/gate is rejected.
|
||||
- **N210-17** concurrent policy revocation versus acquire cannot produce a lease under the revoked revision.
|
||||
- **N210-18** concurrent assignment expiry versus acquire cannot produce a lease after expiry.
|
||||
- **N210-19** concurrent session end versus acquire cannot produce a lease for the ended session.
|
||||
- **N210-20** lower fencing token is rejected without writes.
|
||||
- **N210-21** token from an older lease is rejected without writes.
|
||||
- **N210-22** token paired with another task is rejected without writes.
|
||||
- **N210-23** token paired with another session is rejected without writes.
|
||||
- **N210-24** token on an expired/revoked/released lease is rejected without writes.
|
||||
- **N210-25** fences above JavaScript safe integer round-trip exactly as decimal strings.
|
||||
- **N210-26** lease task does not match assignment task and is rejected.
|
||||
- **N210-27** lease agent/session does not match assignment target and is rejected.
|
||||
- **N210-28** checkpoint task does not match lease task and is rejected.
|
||||
- **N210-29** checkpoint fence does not match exact lease fence and is rejected.
|
||||
- **N210-30** checkpoint sequence duplicate/regression is rejected.
|
||||
- **N210-31** checkpoint artifact does not match workspace/task/evidence semantics and is rejected.
|
||||
- **N210-32** restart after assignment persistence reconstructs the pending assignment.
|
||||
- **N210-33** restart after lease commit reconstructs exact active lease and fence.
|
||||
- **N210-34** restart after checkpoint commit reconstructs checkpoint/recovery state.
|
||||
- **N210-35** restart during expiry/retry/quarantine reconstructs durable disposition and eligibility.
|
||||
- **N210-36** restart with pending outbox reconstructs publication work without Valkey/files.
|
||||
- **N230-01** author=self-review and missing mandatory SecReview cannot certify or complete.
|
||||
- **N230-02** normal application role cannot execute retention purge.
|
||||
- **N230-03** break-glass purge cannot delete or alter its own authorization/evidence chain.
|
||||
- **N230-04** Valkey down leaves canonical work in PostgreSQL/outbox.
|
||||
- **N230-05** duplicate wake produces one logical effect after PostgreSQL reload/idempotency.
|
||||
- **N230-06** stale wake cannot revive an expired/revoked assignment or lease.
|
||||
- **N230-07** restart with no Valkey/files reconstructs leases/retry/quarantine/outbox exactly.
|
||||
|
||||
### KBN-300/KBN-320/KBN-330/KBN-340 — migration and cutover
|
||||
|
||||
- **N300-01** source record targeting another workspace is denied/quarantined without an oracle.
|
||||
- **N300-02** malformed source record is rejected with attributable reject evidence.
|
||||
- **N300-03** duplicate source system/key/batch replay is idempotent.
|
||||
- **N300-04** source snapshot/checksum drift aborts apply/verify.
|
||||
- **N300-05** partial import resumes from durable lineage without duplicating state/events.
|
||||
- **N300-06** imported shadow record cannot become ready, assigned, or leased automatically.
|
||||
- **N300-07** missing source key/file/checksum/batch lineage prevents apply/sign-off.
|
||||
- **N300-08** importer cannot use direct DB, generated file, Valkey, or provider issue as canonical write authority.
|
||||
- **N320-01** cutover without a verified write freeze fails safe.
|
||||
- **N320-02** active legacy writer process or credential blocks cutover.
|
||||
- **N320-03** reverse and forward synchronization cannot run concurrently.
|
||||
- **N320-04** failed final delta/reconciliation blocks client switch.
|
||||
- **N320-05** rollback before first canonical DB mutation may switch authority back only after freeze assertion.
|
||||
- **N320-06** rollback after first canonical mutation requires freeze, DB-delta export/reconciliation, and owner decision.
|
||||
- **N330-01** rehearsal cannot sign off while counts/checksums/exceptions/writer inventory differ.
|
||||
- **N340-01** cutover cannot proceed without owner authorization, terminal evidence, scoped identities, and zero active legacy writers.
|
||||
|
||||
## 7. Requirements traceability
|
||||
|
||||
| Requirement | Threats/impacts | Planned evidence |
|
||||
| ---------------- | ---------------------------- | --------------------------------------------------------------- |
|
||||
| REQ-SOT-001 | T16, T21, T22, T27, T29, T30 | N110-28..31, N110-44..49, N110-55..58, N120-03..07, N320-01..06 |
|
||||
| REQ-SOT-002 | T07, T08, T09, T21 | N105-02/03, N110-14..27, N110-44..48 |
|
||||
| REQ-SOT-003 | T30 | N120-03..07, N140-04 |
|
||||
| REQ-SOT-004 | T16..18 | N100-24..26, N110-28..43 |
|
||||
| REQ-TEN-001 | T01..05, T15, T33 | N100-01..14, N100-45..50, N110-01..09, N210-15/16 |
|
||||
| REQ-ID-001 | T02, T03, T06, T10..12 | N105-01, N110-06..13, N210-01..19 |
|
||||
| REQ-PLAN-001 | T04, T25 | N100-06..10 |
|
||||
| REQ-TASK-001 | T13, T26, T31 | N100-20, N100-37..42, N110-50..54 |
|
||||
| REQ-TASK-002 | T16, T24 | N110-28..31, N100-35, N200-01 |
|
||||
| REQ-DEP-001 | T24 | N100-32..35, N200-01 |
|
||||
| REQ-ASN-001 | T10..12 | N100-15..18, N210-03..19 |
|
||||
| REQ-AUD-001 | T17..20, T22, T27 | N100-24..31, N110-32..43, N110-49, N110-55..58 |
|
||||
| REQ-API-001 | T01, T06..18, T26 | N105-01..05 plus KBN-110 catalog |
|
||||
| REQ-UI-002/003 | T01, T15, T26 | N130-01 and real-Gateway KBN-140 journeys |
|
||||
| REQ-COORD-001 | T22..24 | N200-01/02, N210-32..36 |
|
||||
| REQ-COORD-002 | T10..12, T16 | N210-03..19, N110-28..31 |
|
||||
| REQ-COORD-003 | T13..15, T23 | N100-19..23, N210-20..36 |
|
||||
| REQ-COORD-004 | T23, T26 | N210-32..36, N230-07 |
|
||||
| REQ-GATE-001/002 | T11, T19, T20 | N210-09..14, N230-01..03 |
|
||||
| REQ-REC-001 | T20, T32 | N115-01..08 |
|
||||
| REQ-MIG-001/002 | T28, T29, T31 | N100-37..44, N300-01..08, N320-01..06, N330-01, N340-01 |
|
||||
|
||||
REQ-UI-001 and REQ-UI-004 are downstream functional/accessibility requirements rather than schema-threat controls; they remain owned by KBN-130/KBN-140. Their security-relevant tenancy, conflict, and stale-reconnect portions are covered above.
|
||||
|
||||
## 8. Issue #753 acceptance mapping
|
||||
|
||||
| Issue requirement/criterion | Evidence in this document | Result |
|
||||
| --------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------- |
|
||||
| Cross-workspace owners, principals, evidence, project hierarchy | T01–T05, T15, T25; CI-01–04 | Mapped |
|
||||
| Active membership and service-token boundaries | Authorization matrix; T02, T03, T06; CI-02/03 | Mapped |
|
||||
| Stale/forged health and transaction-local proof | T07–T09, T21; CI-05 | Mapped |
|
||||
| Assignment/approval forgery and monotonic fencing | T10–T15; CI-06/07 | Mapped |
|
||||
| Change-proposal abuse and event binding | T16–T18; CI-08 | Mapped |
|
||||
| Immutable audit and break-glass | T19/T20; CI-09 | Mapped |
|
||||
| PostgreSQL/Valkey failures | T21–T23; CI-10 | Mapped |
|
||||
| Dependency/idempotency/version races | T24–T27; CI-11 | Mapped |
|
||||
| Import/cutover and generated-file boundary | T28–T31; CI-12/13 | Mapped |
|
||||
| Every schema/API/test impact explicit | Constraint matrix and negative-test catalog | Mapped |
|
||||
| No unresolved schema impact | CI-14; rc.4 resolved-impact record | **PASS — none unresolved** |
|
||||
| Independent SecReview | Homelab non-author exact commit/tree/content review | **PASS / APPROVE** |
|
||||
| PR merge, terminal-green main CI, and #753 closure | Orchestrator-owned post-worker gates | Pending; KBN-100 remains held until completion |
|
||||
|
||||
## 9. UNRESOLVED SCHEMA IMPACTS
|
||||
|
||||
none
|
||||
|
||||
### Resolved-impact record — KBN010-SI-001
|
||||
|
||||
- **Historical detection:** rc.3 lacked an exact `(workspace_id,id)` candidate key for the artifact and approval-decision mission FKs. This document's original BLOCKED verdict was correct and remains preserved in §1 and T33.
|
||||
- **Resolution:** rc.4 adds non-partial `missions_workspace_id_uidx(workspace_id,id)` before both exact dependent FKs while retaining the global primary key and project-congruent key.
|
||||
- **Reviewed object:** commit `3f6a3387b419eb99453ee10dd25ba888faaab0b5`, tree `7ebab8fa530a7180036928cea9527f808548aa14`.
|
||||
- **Corroborating identities:** full-index SHA-256 `6b40a76265c4f3e6d1d30a7f262a2dd16e0d51997e99c146b59f527e6524cd42`; stable patch-id `058cf98026fcd1043703c866aee047c8bb144740`.
|
||||
- **Independent verdict:** Homelab non-author schema/security review **APPROVE**. It confirmed PostgreSQL candidate/FK validity, unchanged tenant and polymorphic exactly-one-target safety, RESTRICT/no-cascade semantics, N-1/rollback validity, and no shared table/index/FK/identity/fence authority collision with #757.
|
||||
- **Digest interpretation:** a command-rendered patch digest varied with rendering command/options and is non-authoritative. Git commit + tree + exact file content are canonical; stable full-index SHA-256 and stable patch-id corroborate that identity.
|
||||
- **Residual implementation obligations:** KBN-100 must create the candidate before both dependent FKs; prove production-shape duplicate feasibility without weakening global uniqueness; pass empty/prod/N-1/rollback tests; reconcile both exact FK targets; and separately reject foreign-workspace mission references for artifacts and approval decisions (N100-45..50).
|
||||
- **Implementation status:** no runtime schema, migration, API, or deployment implementation is claimed by this gate disposition.
|
||||
|
||||
## 10. Residual risk and handoff
|
||||
|
||||
- Active membership, polymorphic targets, same-task evidence semantics, parent/DAG cycle checks, token scope, and no-oracle behavior depend on authoritative transaction code and must not be treated as FK-only guarantees.
|
||||
- DB superuser and break-glass compromise cannot be eliminated by application constraints; separation of duties, immutable external backup/audit evidence, drills, and monitoring remain required.
|
||||
- PostgreSQL unavailability intentionally sacrifices writes for integrity. Transport-unknown outcomes remain safe only when clients preserve the exact idempotency key.
|
||||
- Imported ambiguous records remain quarantined until owner sign-off; no automated mapping may convert ambiguity into authority.
|
||||
- SI-001 is resolved at frozen contract/design-review level only. KBN-100 still owes N100-45..50 executable migration evidence.
|
||||
|
||||
**Handoff status:** KBN-010 **PASS / GO** at rc.4. KBN-100 remains held until this PR squash-merges, terminal-green CI completes on `main`, and issue #753 closes; the orchestrator owns those remaining gates.
|
||||
@@ -1,9 +1,21 @@
|
||||
# Native Kanban/SOT — Remediated Shared Contract v1
|
||||
|
||||
**Status:** INDEPENDENT REVIEW GO; freezes as v1 when issue #751 canon merges to `main`
|
||||
**Version:** 1.0.0-rc.3
|
||||
**Status:** CONTROL-PLANE SI-001 AMENDMENT AUTHORIZED; prior KCR-001–016 independent-review GO retained; rc.4 requires independent schema/SecReview before KBN-100
|
||||
**Version:** 1.0.0-rc.4
|
||||
**Date:** 2026-07-14
|
||||
**Change authority:** Mosaic control plane/Jason only
|
||||
**SI-001 amendment authority:** `web1:mosaic-100` control-plane decision under issue #753
|
||||
|
||||
## Amendment record
|
||||
|
||||
### 1.0.0-rc.4 — KBN010-SI-001
|
||||
|
||||
- **Choice:** add the explicitly named, non-partial unique candidate key `missions_workspace_id_uidx` on `missions(workspace_id, id)` and retain `missions_workspace_project_id_uidx` on `(workspace_id, project_id, id)`.
|
||||
- **Rationale:** mission `id` remains globally unique, while the composite candidate key makes the frozen tenant-safe generic mission relations valid. `artifacts` and `approval_decisions` are polymorphic exactly-one-target records and do not consistently carry `project_id`; widening both children would unnecessarily broaden v1 and its target semantics.
|
||||
- **Exact effect:** `artifacts_workspace_mission_fk` and `approval_decisions_workspace_mission_fk` continue to reference the exact ordered columns `missions(workspace_id, id)` with RESTRICT deletion, now backed by a matching candidate key.
|
||||
- **Non-effect:** no SOT, tenancy, project-congruence, proposal-audit, approval, fencing, immutability, no-cascade, API, or wire-version invariant changes. The `SuccessEnvelopeV1.contractVersion` remains `1.0.0`.
|
||||
- **Historical evidence boundary:** `KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md` intentionally remains the immutable rc.3 blocker verdict that detected SI-001; this rc.4 record and the #753 scratchpad append are the authorized disposition. Rewriting the gate verdict is outside this amendment's exclusive scope.
|
||||
- **Gate:** this amendment resolves the DDL defect identified by KBN010-SI-001 but does not itself lift KBN-100; independent schema/SecReview remains required.
|
||||
|
||||
## 1. Authority
|
||||
|
||||
@@ -43,6 +55,7 @@ Complete declaration: `contracts/kanban-schema.v1.ts`.
|
||||
- Specialist roles everywhere: `planning | enhance | coder | review | security-review | pr-monitor | certifier`.
|
||||
- Owner uses exactly-one user/team; assignment principal exactly-one user/team/agent; users require active membership; agent/session and all evidence are workspace-bound.
|
||||
- Task→mission/milestone/parent, mission→milestone, and project→current-milestone are project-congruent composite relations.
|
||||
- Mission `id` remains globally unique. The additional non-partial `missions_workspace_id_uidx` candidate key on `(workspace_id, id)` exists only to support the frozen workspace-safe polymorphic artifact and approval-decision mission relations; the project-congruent `(workspace_id, project_id, id)` key remains authoritative wherever `project_id` is present.
|
||||
- Dependency identity is workspace+predecessor+successor independent of type.
|
||||
- Approval evidence and checkpoint evidence are workspace-scoped joins to immutable artifacts, never JSON ID arrays.
|
||||
- Proposal audit links are composite relations: `(workspace_id, submitted_audit_event_id)` and `(workspace_id, accepted_command_audit_event_id)` reference `task_events(workspace_id, id)` with RESTRICT deletion.
|
||||
@@ -76,7 +89,20 @@ Legacy columns remain declared in unified `schema.ts` for expand + full N-1/roll
|
||||
6. **Switch:** stop N-1 writers; Gateway sole command boundary; enable canonical statuses.
|
||||
7. **Contract release:** later release after rollback/N-1; remove compatibility/global uniques/legacy fields.
|
||||
|
||||
### 5.2 New audit/proposal DDL order
|
||||
### 5.2 Mission candidate-key and dependent-FK DDL order
|
||||
|
||||
KBN-100 migration DDL must execute the SI-001 portion in this order:
|
||||
|
||||
1. expand/backfill `missions.workspace_id` and `missions.project_id` while preserving the global `missions.id` primary key and the project-congruent `missions_workspace_project_id_uidx` key;
|
||||
2. prove duplicate-key feasibility on the production-shape dataset: `(workspace_id, id)` has no duplicate groups and global `id` uniqueness remains intact;
|
||||
3. create the non-partial unique index `missions_workspace_id_uidx` on exact ordered columns `(workspace_id, id)`;
|
||||
4. only after step 3, create/alter `artifacts` and add `artifacts_workspace_mission_fk` from `(workspace_id, mission_id)` to exact `missions(workspace_id, id)` with `ON DELETE RESTRICT`;
|
||||
5. only after step 3, create/alter `approval_decisions` and add `approval_decisions_workspace_mission_fk` from `(workspace_id, mission_id)` to exact `missions(workspace_id, id)` with `ON DELETE RESTRICT`;
|
||||
6. validate both constraints and prove a mission ID paired with a foreign workspace is rejected for each child.
|
||||
|
||||
The candidate key is intentionally redundant with globally unique `missions.id`, but PostgreSQL requires a matching unique candidate key for the exact two-column FK target. It is additive and N-1-safe. Pre-switch rollback drops the two dependent FKs/tables before dropping this candidate key, preserves the global primary key and project-congruent key, and follows the existing freeze/reconciliation rule after the first canonical mutation.
|
||||
|
||||
### 5.3 New audit/proposal DDL order
|
||||
|
||||
KBN-100 migration DDL must execute in this order:
|
||||
|
||||
@@ -88,36 +114,39 @@ KBN-100 migration DDL must execute in this order:
|
||||
|
||||
The submission transaction inserts the event first using a preallocated proposal UUID, then the proposal. Acceptance inserts the normal command event before updating the locked proposal. Neither FK is omitted or replaced by a bare UUID/index check.
|
||||
|
||||
### 5.3 Field map
|
||||
### 5.4 Field map
|
||||
|
||||
| Current | Expand/backfill | N-1 compatibility | Switch/contract |
|
||||
| ---------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------- |
|
||||
| global `teams`, `team_members` | add workspace nullable; bootstrap; validate active owners | retain global slug/FKs | workspace composites; global unique contracts later |
|
||||
| `projects.status` | add `canonical_status`; map active/paused/completed/archived | mirror representable values; no `planning` | canonical authority; legacy contracts later |
|
||||
| project `owner_id/team_id/owner_type` | add exact accountable user/team; deterministic map or quarantine | preserve old reads and compare drift | canonical exact-one; remove legacy after parity |
|
||||
| current milestone | create milestones then join table (no circular DDL) | absent to N-1 | join is authority |
|
||||
| nullable `missions.project_id` | derive workspace/project; null/orphan exception, never guess | keep nullable legacy read | canonical required; validate/set NOT NULL later |
|
||||
| mission `description` | add objective; preserve description; reviewed nonblank mapping | N-1 description | objective authority; retain until signed review |
|
||||
| `missions.status` | add canonical; planning→draft, active/paused/completed/failed same | no new-only statuses emitted | canonical authority |
|
||||
| mission `milestones` JSON | normalize with source digest; preserve malformed/original | N-1 reads JSON; no reverse sync | normalized authority; JSON removed after checksum sign-off |
|
||||
| mission config/metadata/phase/user | retain all; map known typed policy only | all remain declared | remove only by signed consumer inventory |
|
||||
| nullable `tasks.project_id` | derive explicit/mission project; orphan quarantine | retain nullable read/write during compatibility | canonical required; NOT NULL later |
|
||||
| `tasks.mission_id` | add project-congruent composite | old relation readable | composite authority |
|
||||
| `tasks.status` | canonical: not-started→backlog, in-progress→in_progress, others same | no ready/in_review emission | canonical authority |
|
||||
| `tasks.assignee` | deterministic active user/team/agent assignment; raw value preserved if ambiguous | mirror text only if unambiguous | canonical owner/assignment; remove after no-loss sign-off |
|
||||
| `tasks.tags` JSON | normalize trim/case/dedupe with original digest | transactionally mirror normalized rows | normalized authority; JSON later removed |
|
||||
| `tasks.due_date` | copy exactly to `due_at` | mirror | due_at authority; legacy later |
|
||||
| task common fields | preserve metadata byte-for-byte; add criteria/rank/retry/archive/version/fence | old reads valid | new fields canonical |
|
||||
| `mission_tasks.status` | keep; prohibit as write source; linked status ignored; unlinked becomes task or reject | read-only compatibility value | membership uses task mission; status dropped after no readers |
|
||||
| mission-task notes/PR/user | map to metadata/artifact/event/link/attribution; preserve | read-only | remove after parity |
|
||||
| `agents.status` | add workspace/lifecycle/runtime/roles; status remains presence | retain all legacy fields | lifecycle/roles authority; status may remain telemetry |
|
||||
| agent project/owner/prompt/tools/skills/config | preserve; validate tenant; derive typed capabilities without loss | N-1 reads | removal only by separate inventory |
|
||||
| fleet `backlog` | map to designated-project tasks; edges; claimed rows quarantine | freeze claims before switch; read-only compare | task/lease authority; retire after stabilization |
|
||||
| Current | Expand/backfill | N-1 compatibility | Switch/contract |
|
||||
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------- |
|
||||
| global `teams`, `team_members` | add workspace nullable; bootstrap; validate active owners | retain global slug/FKs | workspace composites; global unique contracts later |
|
||||
| `projects.status` | add `canonical_status`; map active/paused/completed/archived | mirror representable values; no `planning` | canonical authority; legacy contracts later |
|
||||
| project `owner_id/team_id/owner_type` | add exact accountable user/team; deterministic map or quarantine | preserve old reads and compare drift | canonical exact-one; remove legacy after parity |
|
||||
| current milestone | create milestones then join table (no circular DDL) | absent to N-1 | join is authority |
|
||||
| nullable `missions.project_id` | derive workspace/project; null/orphan exception, never guess | keep nullable legacy read | canonical required; validate/set NOT NULL later |
|
||||
| mission relational candidate keys | retain global `id` PK and project-congruent key; add non-partial `(workspace_id,id)` key before artifact/approval FKs | additive key is ignored safely by N-1 readers/writers | retain both composite keys; generic mission children use exact workspace+ID target |
|
||||
| mission `description` | add objective; preserve description; reviewed nonblank mapping | N-1 description | objective authority; retain until signed review |
|
||||
| `missions.status` | add canonical; planning→draft, active/paused/completed/failed same | no new-only statuses emitted | canonical authority |
|
||||
| mission `milestones` JSON | normalize with source digest; preserve malformed/original | N-1 reads JSON; no reverse sync | normalized authority; JSON removed after checksum sign-off |
|
||||
| mission config/metadata/phase/user | retain all; map known typed policy only | all remain declared | remove only by signed consumer inventory |
|
||||
| nullable `tasks.project_id` | derive explicit/mission project; orphan quarantine | retain nullable read/write during compatibility | canonical required; NOT NULL later |
|
||||
| `tasks.mission_id` | add project-congruent composite | old relation readable | composite authority |
|
||||
| `tasks.status` | canonical: not-started→backlog, in-progress→in_progress, others same | no ready/in_review emission | canonical authority |
|
||||
| `tasks.assignee` | deterministic active user/team/agent assignment; raw value preserved if ambiguous | mirror text only if unambiguous | canonical owner/assignment; remove after no-loss sign-off |
|
||||
| `tasks.tags` JSON | normalize trim/case/dedupe with original digest | transactionally mirror normalized rows | normalized authority; JSON later removed |
|
||||
| `tasks.due_date` | copy exactly to `due_at` | mirror | due_at authority; legacy later |
|
||||
| task common fields | preserve metadata byte-for-byte; add criteria/rank/retry/archive/version/fence | old reads valid | new fields canonical |
|
||||
| `mission_tasks.status` | keep; prohibit as write source; linked status ignored; unlinked becomes task or reject | read-only compatibility value | membership uses task mission; status dropped after no readers |
|
||||
| mission-task notes/PR/user | map to metadata/artifact/event/link/attribution; preserve | read-only | remove after parity |
|
||||
| `agents.status` | add workspace/lifecycle/runtime/roles; status remains presence | retain all legacy fields | lifecycle/roles authority; status may remain telemetry |
|
||||
| agent project/owner/prompt/tools/skills/config | preserve; validate tenant; derive typed capabilities without loss | N-1 reads | removal only by separate inventory |
|
||||
| fleet `backlog` | map to designated-project tasks; edges; claimed rows quarantine | freeze claims before switch; read-only compare | task/lease authority; retire after stabilization |
|
||||
|
||||
### 5.4 Required migration tests
|
||||
### 5.5 Required migration tests
|
||||
|
||||
Empty DB; exact production-shape snapshot; crash/resume; rollback before switch; N-1 startup/read/write; workspace/member negatives; status-shadow/no premature new status; `mission_tasks.status` write prohibition; tags/assignee/date/mission JSON/config/description/agent checksum; project congruence/current-milestone order; backlog freeze/no dispatch; and proof legacy declarations persist until contract release.
|
||||
|
||||
SI-001 adds frozen future executable evidence: empty and production-shape migrations create `missions_workspace_id_uidx` before either dependent FK; duplicate-key feasibility preflight returns no `(workspace_id,id)` duplicate groups without weakening global `id` uniqueness; N-1 startup/read/write behavior is unchanged; pre-switch rollback removes dependents before the candidate key; both exact FK column lists reconcile to the candidate key; and foreign-workspace mission references fail for both artifacts and approval decisions. TDD is not applicable to this design-only amendment; KBN-100 must implement these negative migration tests before runtime schema release.
|
||||
|
||||
Proposal-specific negatives must attempt: missing submission event, foreign-workspace submission event, foreign-workspace acceptance event, same-workspace event for another proposal, event for another target aggregate, and unrelated normal-command event. Every attempt must fail atomically with no accepted proposal and no target mutation.
|
||||
|
||||
## 6. Ownership and Coordinator split
|
||||
@@ -216,4 +245,10 @@ KBN-115/coder2 owns `packages/config/src/recovery-posture.ts`, tests, and recove
|
||||
|
||||
Required release evidence includes empty/prod/partial/rollback/N-1 migration tests; cross-workspace and same-workspace wrong-project negatives; active-membership owners/principals; proposal inertness/normal acceptance; exact failure mapping; concurrent monotonic bigint fences; relational lease/checkpoint/evidence mismatch; immutability privileges/RESTRICT; recovery validation/mechanism evidence; endpoint registry alignment; accessible web journeys; author≠reviewer; mandatory SecReview; final Certifier pass/no merge authority.
|
||||
|
||||
The build hold remains active until independent re-review reports GO for KCR-001–016. Mos alone releases waves and serializes integration roots.
|
||||
### 9.1 SI-001 amendment gate and #757 boundary
|
||||
|
||||
- KBN-100 must provide the §5.2 candidate-key ordering, duplicate-feasibility, exact-FK reconciliation, empty/prod/N-1/rollback, and two-child foreign-workspace evidence before SI-001 can be certified closed.
|
||||
- All prior KCR-001–016 decisions and fixed SOT/tenant/authority, proposal-audit, approval, task-fencing, immutability, and no-cascade invariants remain unchanged.
|
||||
- Read-only PR #757 cross-check: its logical-agent connector lease/CAS fencing uses separate runtime tables/contracts and `lease_epoch`; rc.4 changes only the frozen `missions` candidate key. There is no shared table, index, FK, identity, fence, or authority semantic to consume or reconcile, and #757 remains owned by its existing lane.
|
||||
|
||||
The build hold remains active until independent re-review reports GO for KCR-001–016 and the rc.4 SI-001 amendment. Mos alone releases waves and serializes integration roots.
|
||||
|
||||
@@ -70,19 +70,21 @@ No consumer implementation begins before KBN-105. No schema work begins before K
|
||||
|
||||
### KBN-000 — Remediate and publish canon
|
||||
|
||||
- **Owner:** Mos / publication control plane.
|
||||
- **Mode:** SERIAL; publication gate in progress.
|
||||
- **Status:** COMPLETE — PR #752 squash-merged as `49e8a54`; issue #751 closed; post-merge pipeline #1798 terminal success.
|
||||
- **Owner:** Mosaic publication control plane.
|
||||
- **Mode:** SERIAL; completed.
|
||||
- **IN:** Resolve KCR-001–016 in requirements, schema, health, Coordinator, recovery, migration map, and slices; independent re-review.
|
||||
- **OUT:** Feature implementation.
|
||||
- **Depends on:** none.
|
||||
- **Contract surfaces:** all canon.
|
||||
- **Evidence:** strict TS; Prettier; per-finding traceability; independent author≠reviewer GO.
|
||||
- **Evidence:** strict TS; Prettier; per-finding traceability; independent author≠reviewer GO; Ultron GO; terminal-green CI.
|
||||
|
||||
### KBN-010 — Threat, authorization, and constraint-impact gate
|
||||
|
||||
- **Owner:** coder3; independent `secrev`.
|
||||
- **Mode:** SERIAL prerequisite of KBN-100.
|
||||
- **Exclusive files:** Mos-selected threat/auth docs only.
|
||||
- **Status:** COMPLETE — PR #765 squash-merged as `2e228007`; issue #753 closed; post-merge pipeline #1813 terminal success.
|
||||
- **Owner:** `kbn-coder3`; independent Homelab schema/SecReview and `web1:coder0` Codex-Ultron review.
|
||||
- **Mode:** SERIAL prerequisite of KBN-100; completed.
|
||||
- **Exclusive files:** `docs/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md` and task scratchpad only.
|
||||
- **IN:** Cross-workspace owners/principals/evidence; active membership; stale/forged health; approval forgery; fence monotonicity; audit retention; proposal target/audit-event forgery; service tokens; DB/Valkey outage.
|
||||
- **OUT:** Runtime/schema edits.
|
||||
- **Depends on:** KBN-000 independent re-review GO.
|
||||
@@ -91,14 +93,15 @@ No consumer implementation begins before KBN-105. No schema work begins before K
|
||||
|
||||
### KBN-100 — Unified Drizzle schema and concrete N-1 migration
|
||||
|
||||
- **Owner:** **coder2**.
|
||||
- **Status:** IN PROGRESS — issue [#769](https://git.mosaicstack.dev/mosaicstack/stack/issues/769); implementation held until tracking commit and baseline evidence are pushed.
|
||||
- **Owner:** **`web1:kbn-schema-coder2`** author lane; independent DB reviewer, SecReview, and Codex-Ultron required.
|
||||
- **Mode:** SERIAL.
|
||||
- **Exclusive files:** `packages/db/src/schema.ts`, `packages/db/drizzle/**`, DB tests.
|
||||
- **IN:** All frozen tables/joins/enums; workspace/project-congruent constraints; owners/principals; tags/archive; change proposals with both workspace-aware task-event composite FKs and frozen event-before-proposal DDL order; assignment approvals; durable execution/quarantine; monotonic bigint fence; exact checkpoint/evidence joins; RESTRICT/immutability; concrete current-main expand/backfill/switch/contract map.
|
||||
- **OUT:** Repositories, Gateway, Coordinator behavior, UI, importer.
|
||||
- **Depends on:** **KBN-010 completed**.
|
||||
- **Contract surfaces:** `kanban-schema.v1.ts`; SHARED-CONTRACT current-main delta map.
|
||||
- **Evidence:** reviewed SQL; empty/prod-shape/partial-resume/rollback tests; N-1 app safety; legacy columns remain declared; workspace/project mismatch negatives; proposal event-FK missing/foreign-workspace tests; one active lease; monotonic fence; parent-delete RESTRICT; immutability privileges; SecReview.
|
||||
- **Evidence:** TDD RED/GREEN; reviewed generated SQL/journal; real PostgreSQL empty/prod-shape/partial-resume/rollback tests; N-1 startup/read/write safety; legacy columns remain declared; workspace/project mismatch negatives; N100-01..50 including rc.4 candidate-before-FK and two-child foreign-workspace tests; proposal event-FK missing/foreign/unrelated tests; one active lease; monotonic fence; parent-delete RESTRICT; immutability privileges; independent DB review, SecReview, Codex-Ultron, terminal-green PR/main CI.
|
||||
|
||||
### KBN-105 — Exact Gateway/MCP endpoint, DTO, and error freeze
|
||||
|
||||
|
||||
@@ -485,6 +485,7 @@ export const missionsV1 = pgTable(
|
||||
foreignColumns: [projectsV1.workspaceId, projectsV1.id],
|
||||
}).onDelete('restrict'),
|
||||
uniqueIndex('missions_workspace_project_id_uidx').on(t.workspaceId, t.projectId, t.id),
|
||||
uniqueIndex('missions_workspace_id_uidx').on(t.workspaceId, t.id),
|
||||
index('missions_workspace_project_status_idx').on(
|
||||
t.workspaceId,
|
||||
t.projectId,
|
||||
|
||||
101
docs/scratchpads/753-kbn010-threat-gate.md
Normal file
101
docs/scratchpads/753-kbn010-threat-gate.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# Issue #753 — KBN-010 threat, authorization, and constraint-impact gate
|
||||
|
||||
## Objective
|
||||
|
||||
Complete the mandatory threat/auth/constraint-impact analysis that gates KBN-100 schema implementation.
|
||||
|
||||
## Scope
|
||||
|
||||
- In: threat matrix, frozen-control mapping, schema/API/test impact inventory, security evidence plan.
|
||||
- Out: runtime, schema, migration, API, dependency, CI, deployment, and secret changes.
|
||||
- Canonical requirements: `docs/requirements/native-kanban-sot.md`.
|
||||
- Frozen contract: `docs/native-kanban-sot/SHARED-CONTRACT.md` and `contracts/*.v1.ts`.
|
||||
- Tracking: Mosaic Stack issue #753.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Independently inspect current-main implementation and frozen canon.
|
||||
2. Enumerate tenant, identity, health-proof, approval, fencing, proposal, audit, token, and outage threats.
|
||||
3. Map every threat to required constraints, command behavior, negative tests, and owning future slice.
|
||||
4. Surface any unresolved schema impact as a blocker; do not silently amend the frozen contract.
|
||||
5. Run documentation/static validation and submit for independent SecReview.
|
||||
|
||||
## Execution log
|
||||
|
||||
- 2026-07-14: KBN-000 completed through PR #752 and post-merge pipeline #1798.
|
||||
- 2026-07-14: KBN-010 issue #753 created; task marked in progress; fresh GPT worker pending dispatch.
|
||||
|
||||
## Verification evidence
|
||||
|
||||
Pending worker validation, independent SecReview, Ultron gate, PR merge, post-merge CI, and issue closure.
|
||||
|
||||
## 2026-07-14 worker analysis checkpoint
|
||||
|
||||
- Inspected issue #753, canonical requirements, all frozen v1 contracts, and actual `origin/main` at `49e8a54` across DB schema, Better Auth scope, project/task/mission/team repositories/controllers, fleet backlog, and `TASKS.md` parsing/writing.
|
||||
- Confirmed the worker branch has no source/runtime/schema delta from `origin/main`; orchestrator-owned `.mosaic` state remains dirty and untouched.
|
||||
- Authored the threat, authorization, constraint-impact, negative-test, and requirements-traceability analysis in `docs/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md`.
|
||||
- Gate decision: **BLOCKED** by `KBN010-SI-001`. `missionsV1` lacks a unique candidate key on `(workspace_id, id)`, while `artifacts_workspace_mission_fk` and `approval_decisions_workspace_mission_fk` both reference that exact pair. PostgreSQL cannot create the frozen composite foreign keys as declared.
|
||||
- Decision: do not select or apply a schema fix. Contract authority must version either a `(workspace_id, id)` mission candidate key or project-congruent child keys, then obtain independent re-review before KBN-100.
|
||||
- Additional risks are controlled by frozen transaction/API behavior but require the exact future negative tests cataloged in the deliverable, especially active membership, service-token revocation, same-workspace semantic evidence checks, no-oracle behavior, and serialized parent/DAG cycle checks.
|
||||
- OpenBrain startup recall was attempted but unavailable because `/home/hermes/.config/mosaic/credentials.json` is absent; no project state was written to an alternate memory silo.
|
||||
- TDD: not applicable; this slice changes documentation/test-plan analysis only and implements no runtime behavior.
|
||||
|
||||
## Validation log
|
||||
|
||||
- `pnpm exec prettier --check docs/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md docs/scratchpads/753-kbn010-threat-gate.md` — PASS.
|
||||
- Changed-doc link validator — PASS (`relative_links=0`, one external issue link); `curl -fsSIL https://git.mosaicstack.dev/mosaicstack/stack/issues/753` — PASS.
|
||||
- The first inline link-validator invocation had a Python f-string syntax error; corrected once and rerun successfully without changing the deliverable.
|
||||
- `pnpm format:check` — PASS.
|
||||
- `pnpm lint` — PASS (23 tasks successful).
|
||||
- `pnpm typecheck` — PASS (42 tasks successful).
|
||||
- `pnpm exec tsc -p docs/native-kanban-sot/tsconfig.json --noEmit` — PASS.
|
||||
- Scoped diff review — PASS: authored delta is limited to the exclusive deliverable and this scratchpad; no runtime/schema/config/dependency/CI/deployment file is changed, and `docs/native-kanban-sot/TASKS.md` has no worker worktree delta from tracking commit `9b55de0`.
|
||||
- Independent SecReview remains pending and cannot return PASS until contract authority resolves `KBN010-SI-001`.
|
||||
- Final formatting/diff/test-ID completeness review — PASS (all catalog prefixes contiguous with no duplicate IDs).
|
||||
- Remaining: scoped commit, queue guard, and push.
|
||||
|
||||
## 2026-07-14 KBN010-SI-001 contract-authority amendment
|
||||
|
||||
- Authority: `web1:mosaic-100` directed the minimal rc.4 amendment under issue #753: add a non-partial unique candidate key on `missions(workspace_id, id)` while retaining global `missions.id` uniqueness and the project-congruent `(workspace_id, project_id, id)` key.
|
||||
- Rationale: artifacts and approval decisions are polymorphic exactly-one-target records and do not consistently carry `project_id`; widening both children would broaden frozen v1 semantics without improving tenant safety.
|
||||
- Plan: amend only the frozen schema contract and shared contract, freeze exact DDL ordering and future migration negatives, run scoped/full validation and independent review, then commit and push without opening/merging a PR or closing #753.
|
||||
- TDD: not applicable because this is a design-contract amendment with no runtime schema or migration implementation; rc.4 freezes future executable empty/prod/N-1/rollback/foreign-workspace and duplicate-key-feasibility tests.
|
||||
- Budget: no explicit cap supplied; use a 20K-equivalent soft working cap and one bounded worker lane.
|
||||
- Read-only #757 boundary: PR #757 adds separate logical-agent connector lease/CAS fencing (`logical_agent_connector_leases.lease_epoch`) in runtime schema and connector contracts. SI-001 changes only the frozen mission candidate key; it does not consume, alter, or reinterpret connector fencing, task fencing, lease authority, or #757 ownership.
|
||||
|
||||
### Amendment verification evidence
|
||||
|
||||
- Frozen schema: added exactly one non-partial `missions_workspace_id_uidx` on `(workspace_id, id)`; retained the global `id` primary key and `missions_workspace_project_id_uidx` on `(workspace_id, project_id, id)`.
|
||||
- FK reconciliation: targeted static checks prove the candidate key precedes both `artifacts_workspace_mission_fk` and `approval_decisions_workspace_mission_fk`; each continues to reference exact ordered columns `(workspace_id, mission_id)` → `missions(workspace_id, id)` with RESTRICT deletion.
|
||||
- Shared contract: candidate version is `1.0.0-rc.4`; authority, rationale, exact effect/non-effect, candidate-before-FK DDL order, duplicate feasibility, empty/prod/N-1/rollback/foreign-workspace future tests, and unchanged KCR/SOT/tenant/proposal/fencing/no-cascade invariants are explicit.
|
||||
- Changed-file Prettier, contract ESLint, `pnpm exec tsc -p docs/native-kanban-sot/tsconfig.json`, and targeted SI-001 static checks — PASS.
|
||||
- Full `pnpm format:check && pnpm lint && pnpm typecheck` — PASS (23 lint tasks and 42 typecheck/build tasks).
|
||||
- Independent Codex security review — PASS, zero critical/high/medium/low findings; tenant isolation is preserved.
|
||||
- Independent Codex code review confirmed the candidate key repairs both FK targets and reported no blocker on the authorized delta. Its initial request to rewrite the historical KBN-010 verdict conflicts with the exclusive scope and was resolved by documenting the immutable-evidence boundary in rc.4; its remaining finding concerns pre-existing live `.mosaic` session files, which are untouched and excluded from this commit.
|
||||
- Scoped diff: only the two frozen contract files and this append-only scratchpad amendment are staged for delivery; no runtime schema, migration, task plan, gate verdict, provider artifact, or #757-owned file is included.
|
||||
|
||||
## 2026-07-14 final rc.4 KBN-010 disposition
|
||||
|
||||
- Control-plane direction authorized final disposition edits only to `docs/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md` and this append-only scratchpad; contract author `web1:kbn-contract` remained idle and undisturbed.
|
||||
- Exact reviewed contract object: commit `3f6a3387b419eb99453ee10dd25ba888faaab0b5`, tree `7ebab8fa530a7180036928cea9527f808548aa14`.
|
||||
- Corroborating review identities: full-index SHA-256 `6b40a76265c4f3e6d1d30a7f262a2dd16e0d51997e99c146b59f527e6524cd42`; stable patch-id `058cf98026fcd1043703c866aee047c8bb144740`. A command-rendered patch digest varied by Git rendering command/options and is non-authoritative; commit+tree+exact file content are canonical.
|
||||
- Independent Homelab non-author schema/security review verdict: **APPROVE**. It confirmed the rc.4 `missions_workspace_id_uidx(workspace_id,id)` repairs both dependent FKs while retaining the global PK and project-congruent key; tenant, polymorphic exactly-one-target, RESTRICT/no-cascade, N-1/rollback semantics remain valid.
|
||||
- Read-only #757 cross-check: no shared table, index, FK, identity, fence, or authority collision with connector lease/CAS fencing.
|
||||
- Final KBN-010 gate decision: **PASS / GO** at rc.4 with `UNRESOLVED SCHEMA IMPACTS` equal to exact `none`. Historical SI-001 detection remains in the gate document as evidence that rc.3 was invalid.
|
||||
- No runtime schema/migration/API/config/dependency/CI/deployment implementation is claimed. KBN-100 must still implement candidate-before-dependent-FK ordering, duplicate feasibility, empty/prod/N-1/rollback evidence, exact FK reconciliation, and separate artifact/approval foreign-workspace negatives (N100-45..50).
|
||||
- TDD remains not applicable because this continuation changes only documentation/evidence disposition and no runtime behavior.
|
||||
- Remaining orchestrator-owned sequence: worker validation/commit/push → PR open/update → Ultron review → squash merge → terminal-green post-main CI → close #753 → release KBN-100. KBN-100 is not released earlier.
|
||||
|
||||
### Final worker validation
|
||||
|
||||
- Changed-doc Prettier and link checks — PASS; issue #753 external link returned successfully.
|
||||
- Static future-test catalog check — PASS: all prefixes are individually enumerated, contiguous, and duplicate-free; N100 now spans N100-01..50.
|
||||
- rc.4 disposition assertions — PASS: gate status PASS/GO, frozen target rc.4, exact `none` unresolved section, independent APPROVE, review identities, and N100-50 are present.
|
||||
- Review identity reproduction — PASS: commit tree `7ebab8fa530a7180036928cea9527f808548aa14`, full-index SHA-256 `6b40a76265c4f3e6d1d30a7f262a2dd16e0d51997e99c146b59f527e6524cd42`, and stable patch-id `058cf98026fcd1043703c866aee047c8bb144740` match.
|
||||
- rc.4 frozen-contract static check — PASS: the candidate key is unique in the declaration and precedes both dependent FKs; frozen contract files remain byte-identical to commit `3f6a3387b419eb99453ee10dd25ba888faaab0b5`.
|
||||
- `pnpm exec tsc -p docs/native-kanban-sot/tsconfig.json --noEmit` — PASS.
|
||||
- `pnpm format:check` — PASS.
|
||||
- `pnpm lint` — PASS (23 tasks successful).
|
||||
- `pnpm typecheck` — PASS (42 tasks successful).
|
||||
- Scoped diff — PASS: only the gate document and this scratchpad are authored changes; contracts, TASKS, requirements, runtime/schema/migration/config/dependency/CI/deployment and #757-owned files are unchanged. Live `.mosaic` session state remains untouched and excluded.
|
||||
- Remaining worker steps: final formatting/scoped staging, commit `docs(#753): clear KBN-010 schema gate`, queue guard, push, and control-plane notification.
|
||||
@@ -1,108 +0,0 @@
|
||||
# FCM-M1-002 — Shared role resolution
|
||||
|
||||
- **Task:** `FCM-M1-002`
|
||||
- **Issue:** `mosaicstack/stack#758`
|
||||
- **Branch:** `feat/758-shared-role-resolution`
|
||||
- **Starting head:** `32e75c67b094de443d37fe7d5ff8d25cdfc8b39d`
|
||||
- **Role:** implementation worker; independent review and merge remain outside this worker
|
||||
|
||||
## Objective
|
||||
|
||||
Reuse the existing baseline-plus-`roles.local` persona resolver as the sole class authority for roster-v2 semantics, profile validation, provisioning, and launch/persona resolution. Add exact approved alias canonicalization, fail-closed semantic validation, immutable canonical-class authority contracts, required baseline roles, and operator documentation without implementing lifecycle, mutation, credentials, certificate workflow, or later FCM cards.
|
||||
|
||||
## Budget
|
||||
|
||||
- Soft budget: **25K tokens**.
|
||||
- Strategy: inspect once, implement in small TDD units, run focused suites before the full package gate, and avoid unrelated refactors or M1-003/M2/M4 scope.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Map the existing persona resolver, roster-v2 compiler, profile/provision consumers, launch resolution, role library, and focused tests.
|
||||
2. Write denial/invariant tests first for aliases, canonicalization-before-override, unreadable roles, authority boundaries, policy mismatch, canonical provision output, and resolver parity.
|
||||
3. Run the focused suites and record the expected red evidence.
|
||||
4. Implement one shared canonical resolution and authority contract in/through `fleet-personas.ts`; delegate roster semantic validation and profile/provision paths to it.
|
||||
5. Add baseline `validator`, `team-leader`, and `interaction` role contracts plus `LIBRARY.md` entries while retaining `operator-interaction` compatibility.
|
||||
6. Add the required role reference, alias migration, customization guide, and roster-v2 semantic handoff documentation.
|
||||
7. Run focused tests, the full `@mosaicstack/mosaic` suite, typecheck, lint, Prettier, `git diff --check`, situational verification, independent code/security review, and remediation.
|
||||
8. Commit with the required co-author trailer, run the CI queue guard, push the existing branch, and create/update exactly one PR to `main` with `Refs #758`.
|
||||
|
||||
## TDD evidence
|
||||
|
||||
### Red
|
||||
|
||||
After installing worktree-local dependencies and building `@mosaicstack/db`, the pre-implementation
|
||||
focused run collected the intended tests and failed as expected:
|
||||
|
||||
```text
|
||||
2 test files failed; 32 tests failed; 32 tests passed
|
||||
```
|
||||
|
||||
Expected failures named the missing `canonicalizeRoleClass`,
|
||||
`authorityForCanonicalClass`, and `validateRosterV2Semantics` APIs, absent requested/canonical typed
|
||||
output, and unresolved required canonical role contracts. An earlier run that failed before test
|
||||
collection on an unresolved `yaml` dependency was treated as environment setup, not TDD evidence.
|
||||
|
||||
### Green
|
||||
|
||||
Focused role-resolution and affected service fixtures:
|
||||
|
||||
```text
|
||||
6 test files passed; 109 tests passed
|
||||
```
|
||||
|
||||
The focused set covers personas, profiles, provision, launch persona contract, roster-v2 semantics,
|
||||
and the operator-interaction service fixture. The final profile tests also cover readable lead/floor
|
||||
compatibility and canonical collision denial.
|
||||
|
||||
## Tests and gates
|
||||
|
||||
- Focused suites: pass, **6 files / 109 tests**.
|
||||
- Full `@mosaicstack/mosaic` suite: pass, **50 files / 713 tests**. Workspace package build outputs
|
||||
were prepared first because a clean worktree has no dependency `dist` entries.
|
||||
- `pnpm --filter @mosaicstack/mosaic typecheck`: pass.
|
||||
- `pnpm --filter @mosaicstack/mosaic lint`: pass.
|
||||
- Prettier check over every changed file: pass.
|
||||
- `git diff --check`: pass.
|
||||
- Runtime/file-boundary evidence: real role library, profile/provision filesystem integration,
|
||||
launch-time synchronous contract injection, v1 roster parser round-trip, roster-v2 semantic
|
||||
filesystem checks, and operator-interaction service fixtures all pass without live mutation.
|
||||
- Independent code review: **APPROVE**, no blocking or non-blocking findings; reviewed complete
|
||||
tracked/untracked delta including the canonical collision guard. Residual: roster-v2 semantic
|
||||
validation is an explicit async handoff with production caller wiring owned by later work.
|
||||
- Independent security review: **APPROVE**, no verified authority/security findings on the final
|
||||
delta.
|
||||
|
||||
|
||||
## Risks and boundaries
|
||||
|
||||
- **Security-sensitive authority:** authority must derive only from canonical class, never role prose, aliases, display names, or tool-policy text.
|
||||
- **Resolver divergence:** no second regex, registry, scanner, or prose parser may be introduced.
|
||||
- **Alias capture:** aliases must canonicalize before baseline/`roles.local` lookup so local files cannot redefine legacy aliases as separate authority.
|
||||
- **Readable persona requirement:** semantic success requires a resolved readable persona, not class-set membership.
|
||||
- **Scope control:** no roster mutation, lifecycle, lease issuance, certificate workflow/storage, credentials, remote reconciliation, provision-v2 conversion, or shipped-example disposition execution.
|
||||
- **Coordination:** `docs/TASKS.md` is read-only and remains orchestrator-owned.
|
||||
|
||||
## Acceptance-evidence mapping
|
||||
|
||||
| Requirement / criterion | Verification evidence |
|
||||
| --- | --- |
|
||||
| `FCM-REQ-02` shared semantic resolver | Async/sync resolver parity; roster-v2 delegates batched scans and resolution; profiles/provision and launch reuse `fleet-personas.ts`; no second scanner or class-marker regex added. |
|
||||
| `FCM-REQ-07` canonical classes and authority boundaries | Exact alias and non-alias tests; immutable authority invariant tests; all required canonical contracts resolve through the real role library. |
|
||||
| `AC-FCM-01` structural + semantic roster validation | Synchronous parser/normalizer tests remain intact; async semantic tests cover aliases, custom roles, unreadable/unresolved roles, `LIBRARY`-only rejection, and bidirectional protected policy mismatch. |
|
||||
| `AC-FCM-07` protected authority invariants | Denial tests prove merge-gate-only merge, validator certificate-only, orchestrator/team-leader/interaction limits, no implicit custom-role authority, and canonical tool-policy matching. |
|
||||
|
||||
## Documentation
|
||||
|
||||
- `docs/fleet/reference/role-classes.md`
|
||||
- `docs/fleet/migration/legacy-class-aliases.md`
|
||||
- `docs/fleet/how-to/customize-roles.md`
|
||||
- `docs/fleet/reference/roster-v2-fields.md` semantic handoff
|
||||
- Baseline role contracts and `LIBRARY.md` rows for `validator`, `team-leader`, and `interaction`
|
||||
|
||||
## Residual risks
|
||||
|
||||
- Provisioning remains intentionally v1 and does not emit `reports_to`; canonical topology is retained
|
||||
in its typed seat/summary path only, matching the existing v1 parser boundary.
|
||||
- Alias support remains for compatibility; new configuration should emit canonical identities.
|
||||
- This card defines authority metadata and validation only. Enforcement workflows for leases,
|
||||
certificates, lifecycle, and mutation remain owned by later FCM cards.
|
||||
52
docs/scratchpads/769-kbn100-schema-migration.md
Normal file
52
docs/scratchpads/769-kbn100-schema-migration.md
Normal file
@@ -0,0 +1,52 @@
|
||||
# Issue #769 — KBN-100 unified schema and N-1 migration
|
||||
|
||||
## Status
|
||||
|
||||
IN PROGRESS — tracking and baseline gate. No schema or migration implementation is authorized until this scratchpad and `docs/native-kanban-sot/TASKS.md` are committed/pushed and baseline evidence is recorded.
|
||||
|
||||
## Requirement authority
|
||||
|
||||
- Provider issue: <https://git.mosaicstack.dev/mosaicstack/stack/issues/769>
|
||||
- Canonical requirements: `docs/requirements/native-kanban-sot.md`
|
||||
- Frozen integration contract: `docs/native-kanban-sot/SHARED-CONTRACT.md` v1.0.0-rc.4
|
||||
- Frozen target schema: `docs/native-kanban-sot/contracts/kanban-schema.v1.ts`
|
||||
- Threat/auth/constraint gate: `docs/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md`
|
||||
- Dependency evidence: PR #765 merge `2e228007`, issue #753 closed, post-main pipeline #1813 terminal success.
|
||||
|
||||
## Fixed decisions
|
||||
|
||||
1. PostgreSQL is the sole writable project/task/orchestration SOT; generated projections and external transports are never import/write authority.
|
||||
2. Expand is additive and N-1-safe. Do not drop, rename, narrow, or reinterpret legacy data during this card.
|
||||
3. Backfill is bounded, idempotent, resumable, checksummed, and quarantines ambiguity rather than guessing.
|
||||
4. rc.4 SI-001 creates `missions_workspace_id_uidx(workspace_id,id)` before both dependent artifact/approval FKs while retaining global and project-congruent keys.
|
||||
5. Runtime repositories, Gateway/MCP, Coordinator behavior, clients, fleet, channels, connector fencing, deployment, and production migration execution are out of scope.
|
||||
6. Critical schema/data behavior uses TDD RED/GREEN and real PostgreSQL integration evidence; PGlite-only evidence cannot certify the migration.
|
||||
|
||||
## Authorized paths
|
||||
|
||||
- `packages/db/src/schema.ts`
|
||||
- `packages/db/drizzle/**`
|
||||
- DB-package tests/config files explicitly enumerated by the author before first edit
|
||||
- `docs/native-kanban-sot/TASKS.md`
|
||||
- this scratchpad
|
||||
|
||||
Any additional path requires control-plane approval before edit.
|
||||
|
||||
## Delivery cycle
|
||||
|
||||
`baseline -> test design/RED -> schema+migration GREEN -> focused tests -> real PostgreSQL migration matrix -> full gates -> independent DB review -> SecReview -> remediate/rereview -> Codex-Ultron -> PR CI -> squash merge -> post-main CI -> issue close`
|
||||
|
||||
## Baseline evidence
|
||||
|
||||
Pending fresh author-lane intake and baseline test run.
|
||||
|
||||
## Collision boundaries
|
||||
|
||||
- #758 owns generic local Fleet configuration/lifecycle cards.
|
||||
- #757/#755 owns logical-agent connector identity/lease/fencing.
|
||||
- #756 channel foundation is merged and remains separate.
|
||||
- KBN-105 and all KBN consumers remain held until #769 completes.
|
||||
|
||||
## Completion evidence
|
||||
|
||||
Pending implementation, reviews, PR, merge, terminal-green main CI, and issue closure.
|
||||
@@ -12,22 +12,19 @@ on demand. Engineering personas have no explicit `domain:` marker (they are the
|
||||
implicit `engineering` domain); cross-domain personas carry a `domain:` key in
|
||||
their intro so tooling can group them.
|
||||
|
||||
> This file is an index, not an authority source. The fleet persona resolver reads
|
||||
> its rows for discovery compatibility, then requires a readable `*.md` contract;
|
||||
> authority is derived from canonical class metadata in code, never from this prose.
|
||||
> This file is an index only — no code imports it. To add a persona, drop a new
|
||||
> `*.md` next to the others (mirroring the existing structure) and add a row here.
|
||||
|
||||
## engineering
|
||||
|
||||
| Persona | Purpose |
|
||||
| --------------- | ------------------------------------------------------------------------------ |
|
||||
| orchestrator | Always-on coordinator — runs the supervisor loop, dispatches ready work |
|
||||
| team-leader | Coordinates only orchestrator-leased capacity for one bounded project |
|
||||
| board | Multi-lens deliberation panel; owns the mission's direction, not its execution |
|
||||
| planner | Turns ratified objectives into a phased FR plan wired into a `depends_on` DAG |
|
||||
| decomposition | Splits FRs into one-PR-each cards wired with `depends_on` edges |
|
||||
| code | Primary executor — one card, one branch, one PR to green CI |
|
||||
| review | Correctness reviewer — judges an open PR on correctness, scope, and coverage |
|
||||
| validator | Independent final evidence certificate; never approves-to-land or merges |
|
||||
| security-review | Second line of review — secrets, auth, and forbidden-path safety |
|
||||
| site-tester | Runtime verifier — runs the change and checks behavior vs. acceptance criteria |
|
||||
| documentation | Prose maintainer — keeps human-facing docs and projections in sync |
|
||||
@@ -36,7 +33,6 @@ their intro so tooling can group them.
|
||||
| operator | Escalation and control surface — owns exceptions and the fleet pause switch |
|
||||
| session-review | Post-task retrospective — turns finished work into improvement signals |
|
||||
| enhancer | Continuous-improvement loop — upgrades the fleet's tools, skills, and harness |
|
||||
| interaction | Operator request/status surface; routes orchestration and merge decisions |
|
||||
|
||||
## executive
|
||||
|
||||
|
||||
@@ -1,16 +0,0 @@
|
||||
# Interaction — fleet role definition
|
||||
|
||||
The **interaction** role (`class: interaction`) is the operator-facing request and status surface for Mosaic.
|
||||
|
||||
## Mandate
|
||||
|
||||
1. Receive operator requests and present observable fleet or runtime status.
|
||||
2. Route orchestration requests to the orchestrator and merge decisions to the merge-gate.
|
||||
3. Report supported actions and their outcomes without claiming another role's authority.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- Request/status only; it does not orchestrate, issue leases, approve-to-land, or merge.
|
||||
- It does not mutate roster configuration, role authority, or credentials.
|
||||
- A configured instance name such as Tess is display data, never a class or authority source.
|
||||
- `operator-interaction` remains a compatibility alias for this canonical class.
|
||||
@@ -1,16 +0,0 @@
|
||||
# Team leader — fleet role definition
|
||||
|
||||
The **team-leader** (`class: team-leader`) coordinates a bounded project team using only capacity granted by an orchestrator-issued lease.
|
||||
|
||||
## Mandate
|
||||
|
||||
1. Direct the leased coder, reviewer, and validator capacity for the assigned project scope.
|
||||
2. Track delivery status and return results or blockers to the orchestrator.
|
||||
3. Stop using capacity when the lease or assignment ends.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- Leased capacity only; this role does not issue or expand its own lease.
|
||||
- It cannot change fleet roster membership, role authority, fleet configuration, or credentials.
|
||||
- It cannot approve-to-land or merge.
|
||||
- It does not displace the orchestrator's topology and lease authority.
|
||||
@@ -1,16 +0,0 @@
|
||||
# Validator — fleet role definition
|
||||
|
||||
The **validator** (`class: validator`) is the independent final evidence seat. It examines the accepted requirements, test evidence, review record, and candidate head and may issue a validation certificate for that exact evidence set.
|
||||
|
||||
## Mandate
|
||||
|
||||
1. Validate acceptance evidence independently from the implementation author.
|
||||
2. Issue or withhold a final validation certificate for the reviewed candidate.
|
||||
3. Report missing, stale, or contradictory evidence without altering it.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- **Certificate only:** the validator does not approve-to-land or merge.
|
||||
- It does not replace correctness or security review.
|
||||
- It does not write product code, mutate the roster, issue leases, or access credentials.
|
||||
- A configured instance name such as Ultron is display data, never a class or authority source.
|
||||
@@ -4,13 +4,10 @@ import { dirname, join, resolve } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
|
||||
import {
|
||||
authorityForCanonicalClass,
|
||||
canonicalizeRoleClass,
|
||||
extractClassesFromDir,
|
||||
listPersonaClasses,
|
||||
personaStatus,
|
||||
resolvePersona,
|
||||
resolvePersonaSync,
|
||||
} from './fleet-personas.js';
|
||||
import { loadProfiles, validateProfile, type FleetProfile } from './fleet-profiles.js';
|
||||
|
||||
@@ -57,122 +54,6 @@ afterEach(async () => {
|
||||
await rm(tmp, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
describe('FCM class canonicalization and authority', () => {
|
||||
it.each([
|
||||
['implementer', 'code'],
|
||||
['reviewer', 'review'],
|
||||
['operator-interaction', 'interaction'],
|
||||
])('canonicalizes the approved alias %s to %s', (requested: string, canonical: string) => {
|
||||
expect(canonicalizeRoleClass(requested)).toEqual({
|
||||
requestedClass: requested,
|
||||
canonicalClass: canonical,
|
||||
});
|
||||
});
|
||||
|
||||
it.each(['worker', 'analyst', 'canary', 'tess', 'ultron'])(
|
||||
'does not infer an alias for %s',
|
||||
(requested: string) => {
|
||||
expect(canonicalizeRoleClass(requested)).toEqual({
|
||||
requestedClass: requested,
|
||||
canonicalClass: requested,
|
||||
});
|
||||
},
|
||||
);
|
||||
|
||||
it('canonicalizes before override lookup and lets the canonical override win', async () => {
|
||||
await mkdir(overrideDir, { recursive: true });
|
||||
await writeFile(
|
||||
join(overrideDir, 'implementer.md'),
|
||||
overridePersona('implementer', 'legacy'),
|
||||
'utf8',
|
||||
);
|
||||
await writeFile(
|
||||
join(overrideDir, 'code.md'),
|
||||
overridePersona('code', 'engineering', 'CANONICAL-OVERRIDE'),
|
||||
'utf8',
|
||||
);
|
||||
|
||||
const resolved = await resolvePersona('implementer', { rolesDir, overrideDir });
|
||||
expect(resolved).toMatchObject({
|
||||
requestedClass: 'implementer',
|
||||
canonicalClass: 'code',
|
||||
klass: 'code',
|
||||
layer: 'override',
|
||||
});
|
||||
expect(resolved?.content).toContain('CANONICAL-OVERRIDE');
|
||||
expect(resolved?.content).not.toContain('legacy');
|
||||
});
|
||||
|
||||
it('keeps sync and async resolution equivalent for aliases and canonical overrides', async () => {
|
||||
await mkdir(overrideDir, { recursive: true });
|
||||
await writeFile(
|
||||
join(overrideDir, 'code.md'),
|
||||
overridePersona('code', 'engineering', 'CANONICAL-OVERRIDE'),
|
||||
'utf8',
|
||||
);
|
||||
|
||||
const asyncResolution = await resolvePersona('implementer', { rolesDir, overrideDir });
|
||||
const syncResolution = resolvePersonaSync('implementer', { rolesDir, overrideDir });
|
||||
expect(syncResolution).toEqual(asyncResolution);
|
||||
});
|
||||
|
||||
it('derives immutable protected authority only from the canonical class', () => {
|
||||
expect(authorityForCanonicalClass('merge-gate')).toMatchObject({ mayMerge: true });
|
||||
for (const klass of [
|
||||
'validator',
|
||||
'orchestrator',
|
||||
'team-leader',
|
||||
'interaction',
|
||||
'code',
|
||||
'custom-role',
|
||||
]) {
|
||||
expect(authorityForCanonicalClass(klass).mayMerge).toBe(false);
|
||||
}
|
||||
expect(authorityForCanonicalClass('validator')).toMatchObject({
|
||||
mayIssueValidationCertificate: true,
|
||||
mayMerge: false,
|
||||
});
|
||||
expect(authorityForCanonicalClass('orchestrator')).toMatchObject({
|
||||
mayOrchestrate: true,
|
||||
mayIssueLeases: true,
|
||||
mayMerge: false,
|
||||
});
|
||||
expect(authorityForCanonicalClass('team-leader')).toMatchObject({
|
||||
leasedCapacityOnly: true,
|
||||
mayMutateRoster: false,
|
||||
mayAccessCredentials: false,
|
||||
mayMerge: false,
|
||||
});
|
||||
expect(authorityForCanonicalClass('interaction')).toMatchObject({
|
||||
requestStatusOnly: true,
|
||||
mayOrchestrate: false,
|
||||
mayMerge: false,
|
||||
});
|
||||
expect(Object.isFrozen(authorityForCanonicalClass('merge-gate'))).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('required FCM role library', () => {
|
||||
it.each([
|
||||
'code',
|
||||
'review',
|
||||
'validator',
|
||||
'orchestrator',
|
||||
'team-leader',
|
||||
'enhancer',
|
||||
'interaction',
|
||||
'merge-gate',
|
||||
])('resolves %s through the real framework role library', async (klass: string) => {
|
||||
const resolved = await resolvePersona(klass, {
|
||||
rolesDir: realRolesDir,
|
||||
overrideDir: join(tmp, 'none'),
|
||||
});
|
||||
expect(resolved).not.toBeNull();
|
||||
expect(resolved?.canonicalClass).toBe(klass);
|
||||
expect(resolved?.content.trim()).not.toBe('');
|
||||
});
|
||||
});
|
||||
|
||||
describe('extractClassesFromDir (shared extraction)', () => {
|
||||
it('records class + domain from inline markers and degrades on missing dir', async () => {
|
||||
const base = await extractClassesFromDir(rolesDir);
|
||||
|
||||
@@ -59,73 +59,6 @@ const LIBRARY_ROW = /^\|\s*([a-z][a-z0-9-]*)\s*\|/gm;
|
||||
/** Where a resolved persona's definition came from. */
|
||||
export type PersonaLayer = 'baseline' | 'override';
|
||||
|
||||
export const ROLE_CLASS_ALIASES = Object.freeze({
|
||||
implementer: 'code',
|
||||
reviewer: 'review',
|
||||
'operator-interaction': 'interaction',
|
||||
} as const);
|
||||
|
||||
export interface CanonicalRoleClass {
|
||||
readonly requestedClass: string;
|
||||
readonly canonicalClass: string;
|
||||
}
|
||||
|
||||
/** Canonicalize only the three explicitly approved compatibility aliases. */
|
||||
export function canonicalizeRoleClass(requestedClass: string): CanonicalRoleClass {
|
||||
const requested = requestedClass.trim();
|
||||
const canonical = ROLE_CLASS_ALIASES[requested as keyof typeof ROLE_CLASS_ALIASES] ?? requested;
|
||||
return Object.freeze({ requestedClass: requested, canonicalClass: canonical });
|
||||
}
|
||||
|
||||
export interface RoleAuthority {
|
||||
readonly mayMerge: boolean;
|
||||
readonly mayIssueValidationCertificate: boolean;
|
||||
readonly mayOrchestrate: boolean;
|
||||
readonly mayManageTopology: boolean;
|
||||
readonly mayIssueLeases: boolean;
|
||||
readonly leasedCapacityOnly: boolean;
|
||||
readonly requestStatusOnly: boolean;
|
||||
readonly mayMutateRoster: boolean;
|
||||
readonly mayMutateConfiguration: boolean;
|
||||
readonly mayAccessCredentials: boolean;
|
||||
}
|
||||
|
||||
const NO_PROTECTED_AUTHORITY: RoleAuthority = Object.freeze({
|
||||
mayMerge: false,
|
||||
mayIssueValidationCertificate: false,
|
||||
mayOrchestrate: false,
|
||||
mayManageTopology: false,
|
||||
mayIssueLeases: false,
|
||||
leasedCapacityOnly: false,
|
||||
requestStatusOnly: false,
|
||||
mayMutateRoster: false,
|
||||
mayMutateConfiguration: false,
|
||||
mayAccessCredentials: false,
|
||||
});
|
||||
|
||||
/** Immutable authority contracts keyed only by canonical class identity. */
|
||||
export const ROLE_AUTHORITY_BY_CANONICAL_CLASS: Readonly<Record<string, RoleAuthority>> =
|
||||
Object.freeze({
|
||||
'merge-gate': Object.freeze({ ...NO_PROTECTED_AUTHORITY, mayMerge: true }),
|
||||
validator: Object.freeze({
|
||||
...NO_PROTECTED_AUTHORITY,
|
||||
mayIssueValidationCertificate: true,
|
||||
}),
|
||||
orchestrator: Object.freeze({
|
||||
...NO_PROTECTED_AUTHORITY,
|
||||
mayOrchestrate: true,
|
||||
mayManageTopology: true,
|
||||
mayIssueLeases: true,
|
||||
}),
|
||||
'team-leader': Object.freeze({ ...NO_PROTECTED_AUTHORITY, leasedCapacityOnly: true }),
|
||||
interaction: Object.freeze({ ...NO_PROTECTED_AUTHORITY, requestStatusOnly: true }),
|
||||
});
|
||||
|
||||
/** Return protected authority for an already-canonical class; custom classes get none. */
|
||||
export function authorityForCanonicalClass(canonicalClass: string): RoleAuthority {
|
||||
return ROLE_AUTHORITY_BY_CANONICAL_CLASS[canonicalClass] ?? NO_PROTECTED_AUTHORITY;
|
||||
}
|
||||
|
||||
/** One discovered persona file (a single role contract on disk). */
|
||||
export interface PersonaFile {
|
||||
klass: string;
|
||||
@@ -277,8 +210,7 @@ export async function listPersonaClasses(opts: PersonaDirs = {}): Promise<Set<st
|
||||
|
||||
export type PersonaStatus = 'baseline' | 'overridden' | 'custom';
|
||||
|
||||
export interface PersonaResolution extends CanonicalRoleClass {
|
||||
/** Compatibility name for the canonical class. */
|
||||
export interface PersonaResolution {
|
||||
klass: string;
|
||||
layer: PersonaLayer;
|
||||
/** The file the resolved persona was read from (override wins). */
|
||||
@@ -313,11 +245,9 @@ export async function resolvePersona(
|
||||
* is identical to {@link resolvePersona}: override layer wins, then baseline.
|
||||
*/
|
||||
export async function resolvePersonaFrom(
|
||||
requestedClass: string,
|
||||
klass: string,
|
||||
layers: { rolesDir: string; overrideDir: string; base: DirClasses; over: DirClasses },
|
||||
): Promise<PersonaResolution | null> {
|
||||
const { requestedClass: requested, canonicalClass: klass } =
|
||||
canonicalizeRoleClass(requestedClass);
|
||||
const { rolesDir, overrideDir, base, over } = layers;
|
||||
|
||||
const fromLayer = async (
|
||||
@@ -334,30 +264,14 @@ export async function resolvePersonaFrom(
|
||||
try {
|
||||
const content = await readFile(byName, 'utf8');
|
||||
const dm = DOMAIN_MARKER.exec(content);
|
||||
return {
|
||||
requestedClass: requested,
|
||||
canonicalClass: klass,
|
||||
klass,
|
||||
layer,
|
||||
file: byName,
|
||||
content,
|
||||
...(dm?.[1] ? { domain: dm[1] } : {}),
|
||||
};
|
||||
return { klass, layer, file: byName, content, ...(dm?.[1] ? { domain: dm[1] } : {}) };
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
try {
|
||||
const content = await readFile(pf.file, 'utf8');
|
||||
return {
|
||||
requestedClass: requested,
|
||||
canonicalClass: klass,
|
||||
klass,
|
||||
layer,
|
||||
file: pf.file,
|
||||
content,
|
||||
...(pf.domain ? { domain: pf.domain } : {}),
|
||||
};
|
||||
return { klass, layer, file: pf.file, content, ...(pf.domain ? { domain: pf.domain } : {}) };
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
@@ -378,11 +292,9 @@ export async function resolvePersonaFrom(
|
||||
* one module so the launch-time and command-time resolutions never diverge.
|
||||
*/
|
||||
export function resolvePersonaSync(
|
||||
requestedClass: string,
|
||||
klass: string,
|
||||
opts: PersonaDirs = {},
|
||||
): PersonaResolution | null {
|
||||
const { requestedClass: requested, canonicalClass: klass } =
|
||||
canonicalizeRoleClass(requestedClass);
|
||||
const { rolesDir, overrideDir } = resolveDirs(opts);
|
||||
const base = extractClassesFromDirSync(rolesDir);
|
||||
const over = extractClassesFromDirSync(overrideDir);
|
||||
@@ -400,30 +312,14 @@ export function resolvePersonaSync(
|
||||
try {
|
||||
const content = readFileSync(byName, 'utf8');
|
||||
const dm = DOMAIN_MARKER.exec(content);
|
||||
return {
|
||||
requestedClass: requested,
|
||||
canonicalClass: klass,
|
||||
klass,
|
||||
layer,
|
||||
file: byName,
|
||||
content,
|
||||
...(dm?.[1] ? { domain: dm[1] } : {}),
|
||||
};
|
||||
return { klass, layer, file: byName, content, ...(dm?.[1] ? { domain: dm[1] } : {}) };
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
try {
|
||||
const content = readFileSync(pf.file, 'utf8');
|
||||
return {
|
||||
requestedClass: requested,
|
||||
canonicalClass: klass,
|
||||
klass,
|
||||
layer,
|
||||
file: pf.file,
|
||||
content,
|
||||
...(pf.domain ? { domain: pf.domain } : {}),
|
||||
};
|
||||
return { klass, layer, file: pf.file, content, ...(pf.domain ? { domain: pf.domain } : {}) };
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
|
||||
@@ -203,91 +203,6 @@ describe('loadProfiles with a temp override dir', () => {
|
||||
await rm(dir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it('canonicalizes approved aliases across lead, floor, roster, and topology', async () => {
|
||||
await writeFile(
|
||||
join(dir, 'aliases.yaml'),
|
||||
[
|
||||
'id: aliases',
|
||||
'title: Aliases',
|
||||
'description: legacy class compatibility',
|
||||
'lead: operator-interaction',
|
||||
'floor: [operator-interaction]',
|
||||
'roster:',
|
||||
' - class: operator-interaction',
|
||||
' - class: implementer',
|
||||
' reports_to: operator-interaction',
|
||||
' - class: reviewer',
|
||||
' reports_to: operator-interaction',
|
||||
'',
|
||||
].join('\n'),
|
||||
);
|
||||
|
||||
const profile = await loadProfile('aliases', {
|
||||
profilesDir: dir,
|
||||
rolesDir,
|
||||
overrideDir: join(dir, 'roles.local'),
|
||||
});
|
||||
expect(profile.lead).toBe('interaction');
|
||||
expect(profile.floor).toEqual(['interaction']);
|
||||
expect(profile.roster).toEqual([
|
||||
{ class: 'interaction', multiplicity: 1 },
|
||||
{ class: 'code', reportsTo: 'interaction', multiplicity: 1 },
|
||||
{ class: 'review', reportsTo: 'interaction', multiplicity: 1 },
|
||||
]);
|
||||
});
|
||||
|
||||
it('rejects roster entries that collapse to the same canonical class', async () => {
|
||||
await writeFile(
|
||||
join(dir, 'alias-collision.yaml'),
|
||||
[
|
||||
'id: alias-collision',
|
||||
'title: Alias collision',
|
||||
'description: ambiguous canonical topology',
|
||||
'lead: orchestrator',
|
||||
'floor: [orchestrator]',
|
||||
'roster:',
|
||||
' - class: orchestrator',
|
||||
' - class: code',
|
||||
' reports_to: orchestrator',
|
||||
' - class: implementer',
|
||||
' reports_to: orchestrator',
|
||||
'',
|
||||
].join('\n'),
|
||||
);
|
||||
|
||||
await expect(
|
||||
loadProfile('alias-collision', {
|
||||
profilesDir: dir,
|
||||
rolesDir,
|
||||
overrideDir: join(dir, 'roles.local'),
|
||||
}),
|
||||
).rejects.toThrow(/duplicate classes after canonicalization/);
|
||||
});
|
||||
|
||||
it('allows a readable lead or floor persona that is not itself a roster seat', async () => {
|
||||
await writeFile(
|
||||
join(dir, 'external-topology.yaml'),
|
||||
[
|
||||
'id: external-topology',
|
||||
'title: External topology',
|
||||
'description: structural compatibility',
|
||||
'lead: orchestrator',
|
||||
'floor: [enhancer]',
|
||||
'roster:',
|
||||
' - class: code',
|
||||
'',
|
||||
].join('\n'),
|
||||
);
|
||||
|
||||
const profile = await loadProfile('external-topology', {
|
||||
profilesDir: dir,
|
||||
rolesDir,
|
||||
overrideDir: join(dir, 'roles.local'),
|
||||
});
|
||||
expect(profile.lead).toBe('orchestrator');
|
||||
expect(profile.floor).toEqual(['enhancer']);
|
||||
});
|
||||
|
||||
it('throws when a profile references an unknown class (validated against real roles)', async () => {
|
||||
await writeFile(
|
||||
join(dir, 'bad.yaml'),
|
||||
|
||||
@@ -29,7 +29,6 @@ import {
|
||||
defaultOverrideDir,
|
||||
extractClassesFromDir,
|
||||
listPersonaClasses as listOverrideAwarePersonaClasses,
|
||||
resolvePersonaFrom,
|
||||
} from './fleet-personas.js';
|
||||
|
||||
function defaultMosaicHome(): string {
|
||||
@@ -200,61 +199,6 @@ export function validateProfile(profile: FleetProfile, validClasses: Set<string>
|
||||
return problems;
|
||||
}
|
||||
|
||||
export async function resolveProfilePersonas(
|
||||
profile: FleetProfile,
|
||||
rolesDir: string,
|
||||
overrideDir: string,
|
||||
): Promise<FleetProfile> {
|
||||
const [base, over] = await Promise.all([
|
||||
extractClassesFromDir(rolesDir),
|
||||
extractClassesFromDir(overrideDir),
|
||||
]);
|
||||
const requestedClasses = new Set<string>([
|
||||
profile.lead,
|
||||
...profile.floor,
|
||||
...profile.roster.flatMap((entry: ProfileRosterEntry): string[] =>
|
||||
entry.reportsTo ? [entry.class, entry.reportsTo] : [entry.class],
|
||||
),
|
||||
]);
|
||||
const canonicalByRequested = new Map<string, string>();
|
||||
for (const requestedClass of requestedClasses) {
|
||||
const resolved = await resolvePersonaFrom(requestedClass, {
|
||||
rolesDir,
|
||||
overrideDir,
|
||||
base,
|
||||
over,
|
||||
});
|
||||
if (!resolved || resolved.content.trim() === '') {
|
||||
throw new Error(`persona class "${requestedClass}" does not resolve to a readable persona`);
|
||||
}
|
||||
canonicalByRequested.set(requestedClass, resolved.canonicalClass);
|
||||
}
|
||||
const canonical = (requestedClass: string): string =>
|
||||
canonicalByRequested.get(requestedClass) ?? requestedClass;
|
||||
const roster = profile.roster.map(
|
||||
(entry: ProfileRosterEntry): ProfileRosterEntry => ({
|
||||
class: canonical(entry.class),
|
||||
multiplicity: entry.multiplicity,
|
||||
...(entry.reportsTo ? { reportsTo: canonical(entry.reportsTo) } : {}),
|
||||
}),
|
||||
);
|
||||
const canonicalRosterClasses = roster.map((entry: ProfileRosterEntry): string => entry.class);
|
||||
if (new Set(canonicalRosterClasses).size !== canonicalRosterClasses.length) {
|
||||
throw new Error('profile roster contains duplicate classes after canonicalization');
|
||||
}
|
||||
const resolvedProfile: FleetProfile = {
|
||||
...profile,
|
||||
lead: canonical(profile.lead),
|
||||
floor: profile.floor.map(canonical),
|
||||
roster,
|
||||
};
|
||||
const problems = validateProfile(resolvedProfile, new Set(canonicalByRequested.values()));
|
||||
if (problems.length > 0) {
|
||||
throw new Error(problems.join('\n - '));
|
||||
}
|
||||
return resolvedProfile;
|
||||
}
|
||||
|
||||
export interface LoadProfilesOptions {
|
||||
/** Override the profiles dir (tests). Defaults to <mosaicHome>/fleet/profiles. */
|
||||
profilesDir?: string;
|
||||
@@ -293,8 +237,10 @@ export async function loadProfiles(opts: LoadProfilesOptions = {}): Promise<Flee
|
||||
}
|
||||
files.sort();
|
||||
|
||||
// Validation resolves each reference to an actually readable winning persona;
|
||||
// LIBRARY membership alone is not semantic success.
|
||||
// Override-aware: a profile may reference a user-customized or user-ADDED
|
||||
// persona living in the roles.local/ layer (H4), so validate against the
|
||||
// baseline ⊕ override union, not the baseline alone.
|
||||
const validClasses = await listPersonaClassesWithOverrides(rolesDir, overrideDir);
|
||||
const profiles: FleetProfile[] = [];
|
||||
const seen = new Map<string, string>();
|
||||
|
||||
@@ -309,14 +255,11 @@ export async function loadProfiles(opts: LoadProfilesOptions = {}): Promise<Flee
|
||||
}
|
||||
seen.set(profile.id, file);
|
||||
|
||||
let resolvedProfile: FleetProfile;
|
||||
try {
|
||||
resolvedProfile = await resolveProfilePersonas(profile, rolesDir, overrideDir);
|
||||
} catch (error: unknown) {
|
||||
const detail = error instanceof Error ? error.message : String(error);
|
||||
throw new Error(`Profile ${file} is invalid:\n - ${detail}`);
|
||||
const problems = validateProfile(profile, validClasses);
|
||||
if (problems.length > 0) {
|
||||
throw new Error(`Profile ${file} is invalid:\n - ${problems.join('\n - ')}`);
|
||||
}
|
||||
profiles.push(resolvedProfile);
|
||||
profiles.push(profile);
|
||||
}
|
||||
return profiles;
|
||||
}
|
||||
|
||||
@@ -172,46 +172,6 @@ describe('override-aware persona validation', () => {
|
||||
expect(result.summary).toContain('persona=override');
|
||||
});
|
||||
|
||||
it('canonicalizes aliased profile classes and topology identities before emission', async () => {
|
||||
const overrideDir = join(dir, 'roles.local');
|
||||
const customProfilesDir = join(dir, 'profiles');
|
||||
await mkdir(overrideDir, { recursive: true });
|
||||
await mkdir(customProfilesDir, { recursive: true });
|
||||
await writeFile(
|
||||
join(customProfilesDir, 'aliases.yaml'),
|
||||
[
|
||||
'id: aliases',
|
||||
'title: Aliases',
|
||||
'description: legacy aliases',
|
||||
'lead: operator-interaction',
|
||||
'floor: [operator-interaction]',
|
||||
'roster:',
|
||||
' - class: operator-interaction',
|
||||
' - class: implementer',
|
||||
' reports_to: operator-interaction',
|
||||
' - class: reviewer',
|
||||
' reports_to: operator-interaction',
|
||||
'',
|
||||
].join('\n'),
|
||||
);
|
||||
|
||||
const result = await runProvision('aliases', {
|
||||
mosaicHome: dir,
|
||||
profilesDir: customProfilesDir,
|
||||
rolesDir,
|
||||
overrideDir,
|
||||
full: true,
|
||||
});
|
||||
expect(result.yaml).toContain('name: interaction');
|
||||
expect(result.yaml).toContain('class: interaction');
|
||||
expect(result.yaml).toContain('name: code');
|
||||
expect(result.yaml).toContain('class: code');
|
||||
expect(result.yaml).toContain('name: review');
|
||||
expect(result.yaml).toContain('class: review');
|
||||
expect(result.yaml).not.toContain('class: implementer');
|
||||
expect(result.summary).toContain('reports_to=interaction');
|
||||
});
|
||||
|
||||
it('FAILS with a clear message when a profile references a bogus class', async () => {
|
||||
const customProfilesDir = join(dir, 'profiles');
|
||||
await mkdir(customProfilesDir, { recursive: true });
|
||||
|
||||
@@ -26,11 +26,12 @@ import type { Command } from 'commander';
|
||||
import YAML from 'yaml';
|
||||
import {
|
||||
loadProfile,
|
||||
validateProfile,
|
||||
type FleetProfile,
|
||||
type ProfileRosterEntry,
|
||||
defaultProfilesDir,
|
||||
defaultRolesDir,
|
||||
resolveProfilePersonas,
|
||||
listPersonaClassesWithOverrides,
|
||||
} from './fleet-profiles.js';
|
||||
import {
|
||||
defaultOverrideDir,
|
||||
@@ -200,35 +201,18 @@ export async function generateRoster(
|
||||
);
|
||||
}
|
||||
|
||||
const canonicalEntry: ProfileRosterEntry = {
|
||||
class: resolved.canonicalClass,
|
||||
multiplicity: entry.multiplicity,
|
||||
...(entry.reportsTo
|
||||
? {
|
||||
reportsTo:
|
||||
(
|
||||
await resolvePersonaFrom(entry.reportsTo, {
|
||||
rolesDir,
|
||||
overrideDir,
|
||||
base,
|
||||
over,
|
||||
})
|
||||
)?.canonicalClass ?? entry.reportsTo,
|
||||
}
|
||||
: {}),
|
||||
};
|
||||
const runtimeChoice = resolveSeatRuntime(resolved.canonicalClass, isFloor, isLead);
|
||||
for (const name of seatNames(canonicalEntry)) {
|
||||
const runtimeChoice = resolveSeatRuntime(entry.class, isFloor, isLead);
|
||||
for (const name of seatNames(entry)) {
|
||||
const seat: GeneratedSeat = {
|
||||
name,
|
||||
className: resolved.canonicalClass,
|
||||
className: entry.class,
|
||||
runtime: runtimeChoice.runtime,
|
||||
personaLayer: resolved.layer,
|
||||
};
|
||||
if (runtimeChoice.modelHint) seat.modelHint = runtimeChoice.modelHint;
|
||||
if (isFloor || isLead) seat.persistentPersona = true;
|
||||
if (!isFloor && !isLead) seat.resetBetweenTasks = true;
|
||||
if (canonicalEntry.reportsTo) seat.reportsTo = canonicalEntry.reportsTo;
|
||||
if (entry.reportsTo) seat.reportsTo = entry.reportsTo;
|
||||
seats.push(seat);
|
||||
}
|
||||
}
|
||||
@@ -295,7 +279,13 @@ export async function validateProfileForProvision(
|
||||
opts: ProvisionOptions,
|
||||
): Promise<void> {
|
||||
const { rolesDir, overrideDir } = resolveDirs(opts);
|
||||
await resolveProfilePersonas(profile, rolesDir, overrideDir);
|
||||
const validClasses = await listPersonaClassesWithOverrides(rolesDir, overrideDir);
|
||||
const problems = validateProfile(profile, validClasses);
|
||||
if (problems.length > 0) {
|
||||
throw new Error(
|
||||
`Profile "${profile.id}" is invalid; cannot provision:\n - ${problems.join('\n - ')}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
@@ -77,25 +77,12 @@ describe('readPersonaContractBlock — launch-time persona injection (A3b)', ()
|
||||
});
|
||||
|
||||
it('injects an override-only (user-added) persona with no baseline at all', () => {
|
||||
seedOverride(home, 'mascot', '# Mascot\n\n(`class: mascot`)\n\nCUSTOM-ROLE.\n');
|
||||
const block = readPersonaContractBlock(home, 'mascot');
|
||||
expect(block).toContain('# Persona Contract (mascot)');
|
||||
seedOverride(home, 'reviewer', '# Reviewer\n\n(`class: reviewer`)\n\nCUSTOM-ROLE.\n');
|
||||
const block = readPersonaContractBlock(home, 'reviewer');
|
||||
expect(block).toContain('# Persona Contract (reviewer)');
|
||||
expect(block).toContain('CUSTOM-ROLE');
|
||||
});
|
||||
|
||||
it('canonicalizes an approved alias before launch-time override lookup', () => {
|
||||
seedBaseline(home, 'code', '# Code\n\n(`class: code`)\n\nCANONICAL-CODE.\n');
|
||||
seedOverride(
|
||||
home,
|
||||
'implementer',
|
||||
'# Legacy implementer\n\n(`class: implementer`)\n\nLEGACY-OVERRIDE.\n',
|
||||
);
|
||||
const block = readPersonaContractBlock(home, 'implementer');
|
||||
expect(block).toContain('# Persona Contract (code)');
|
||||
expect(block).toContain('CANONICAL-CODE');
|
||||
expect(block).not.toContain('LEGACY-OVERRIDE');
|
||||
});
|
||||
|
||||
it('no-ops (empty string) when the class is undefined', () => {
|
||||
seedBaseline(home, 'coder', BASELINE_CODER);
|
||||
expect(readPersonaContractBlock(home, undefined)).toBe('');
|
||||
|
||||
@@ -1,14 +1,11 @@
|
||||
import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import { readFile } from 'node:fs/promises';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { afterEach, describe, expect, it } from 'vitest';
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import {
|
||||
ROSTER_V2_JSON_SCHEMA,
|
||||
RosterV2ValidationError,
|
||||
parseRosterV2,
|
||||
renderRosterV2Yaml,
|
||||
validateRosterV2Semantics,
|
||||
} from './roster-v2.js';
|
||||
|
||||
const validRoster = `
|
||||
@@ -43,133 +40,6 @@ agents:
|
||||
yolo: true
|
||||
`;
|
||||
|
||||
let semanticTmp: string | undefined;
|
||||
|
||||
afterEach(async (): Promise<void> => {
|
||||
if (semanticTmp) await rm(semanticTmp, { recursive: true, force: true });
|
||||
semanticTmp = undefined;
|
||||
});
|
||||
|
||||
async function semanticDirs(): Promise<{ rolesDir: string; overrideDir: string }> {
|
||||
semanticTmp = await mkdtemp(join(tmpdir(), 'roster-v2-semantics-'));
|
||||
const rolesDir = join(semanticTmp, 'roles');
|
||||
const overrideDir = join(semanticTmp, 'roles.local');
|
||||
await mkdir(rolesDir, { recursive: true });
|
||||
await mkdir(overrideDir, { recursive: true });
|
||||
for (const klass of [
|
||||
'code',
|
||||
'review',
|
||||
'interaction',
|
||||
'orchestrator',
|
||||
'merge-gate',
|
||||
'validator',
|
||||
'team-leader',
|
||||
]) {
|
||||
await writeFile(join(rolesDir, `${klass}.md`), `# ${klass}\n\n(\`class: ${klass}\`)\n`, 'utf8');
|
||||
}
|
||||
return { rolesDir, overrideDir };
|
||||
}
|
||||
|
||||
function rosterWithClass(klass: string, toolPolicy = klass): string {
|
||||
return validRoster
|
||||
.replace('class: code', `class: ${klass}`)
|
||||
.replace('tool_policy: code', `tool_policy: ${toolPolicy}`);
|
||||
}
|
||||
|
||||
describe('roster v2 semantic validation', (): void => {
|
||||
it.each([
|
||||
['implementer', 'code'],
|
||||
['reviewer', 'review'],
|
||||
['operator-interaction', 'interaction'],
|
||||
])(
|
||||
'canonicalizes requested alias %s while retaining requested and canonical class',
|
||||
async (requested: string, canonical: string) => {
|
||||
const dirs = await semanticDirs();
|
||||
const roster = parseRosterV2(rosterWithClass(requested, requested), 'yaml');
|
||||
const validated = await validateRosterV2Semantics(roster, dirs);
|
||||
expect(validated.agents[0]).toMatchObject({
|
||||
requestedClass: requested,
|
||||
canonicalClass: canonical,
|
||||
canonicalToolPolicy: canonical,
|
||||
});
|
||||
},
|
||||
);
|
||||
|
||||
it.each(['worker', 'analyst', 'canary'])(
|
||||
'rejects %s when no genuine custom role exists',
|
||||
async (klass: string) => {
|
||||
const dirs = await semanticDirs();
|
||||
await expect(
|
||||
validateRosterV2Semantics(parseRosterV2(rosterWithClass(klass), 'yaml'), dirs),
|
||||
).rejects.toThrow(/unresolved|readable persona/i);
|
||||
},
|
||||
);
|
||||
|
||||
it('accepts a genuine custom roles.local class without protected authority', async () => {
|
||||
const dirs = await semanticDirs();
|
||||
await writeFile(join(dirs.overrideDir, 'worker.md'), '# worker\n\n(`class: worker`)\n', 'utf8');
|
||||
const validated = await validateRosterV2Semantics(
|
||||
parseRosterV2(rosterWithClass('worker'), 'yaml'),
|
||||
dirs,
|
||||
);
|
||||
expect(validated.agents[0]?.authority).toMatchObject({
|
||||
mayMerge: false,
|
||||
mayOrchestrate: false,
|
||||
});
|
||||
});
|
||||
|
||||
it('rejects a LIBRARY-only class with no readable resolved persona', async () => {
|
||||
const dirs = await semanticDirs();
|
||||
await writeFile(
|
||||
join(dirs.rolesDir, 'LIBRARY.md'),
|
||||
'| Persona | Purpose |\n| --- | --- |\n| phantom | Missing |\n',
|
||||
'utf8',
|
||||
);
|
||||
await expect(
|
||||
validateRosterV2Semantics(parseRosterV2(rosterWithClass('phantom'), 'yaml'), dirs),
|
||||
).rejects.toThrow(/readable persona/i);
|
||||
});
|
||||
|
||||
it('rejects an unreadable resolved persona', async () => {
|
||||
const dirs = await semanticDirs();
|
||||
const file = join(dirs.overrideDir, 'worker.md');
|
||||
await writeFile(file, '# worker\n\n(`class: worker`)\n', 'utf8');
|
||||
await chmod(file, 0o000);
|
||||
try {
|
||||
await expect(
|
||||
validateRosterV2Semantics(parseRosterV2(rosterWithClass('worker'), 'yaml'), dirs),
|
||||
).rejects.toThrow(/readable persona/i);
|
||||
} finally {
|
||||
await chmod(file, 0o600);
|
||||
}
|
||||
});
|
||||
|
||||
it.each([
|
||||
['merge-gate', 'code'],
|
||||
['validator', 'merge-gate'],
|
||||
['orchestrator', 'interaction'],
|
||||
['team-leader', 'orchestrator'],
|
||||
['interaction', 'orchestrator'],
|
||||
['code', 'merge-gate'],
|
||||
['worker', 'validator'],
|
||||
])(
|
||||
'denies protected class/tool-policy mismatch %s with %s',
|
||||
async (klass: string, toolPolicy: string) => {
|
||||
const dirs = await semanticDirs();
|
||||
if (klass === 'worker') {
|
||||
await writeFile(
|
||||
join(dirs.overrideDir, 'worker.md'),
|
||||
'# worker\n\n(`class: worker`)\n',
|
||||
'utf8',
|
||||
);
|
||||
}
|
||||
await expect(
|
||||
validateRosterV2Semantics(parseRosterV2(rosterWithClass(klass, toolPolicy), 'yaml'), dirs),
|
||||
).rejects.toThrow(/tool policy.*must match|mismatch/i);
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
describe('roster v2 structural compiler', (): void => {
|
||||
it('parses YAML into a normalized typed model and renders canonical YAML', (): void => {
|
||||
const roster = parseRosterV2(validRoster, 'yaml');
|
||||
|
||||
@@ -1,15 +1,4 @@
|
||||
import YAML from 'yaml';
|
||||
import {
|
||||
authorityForCanonicalClass,
|
||||
canonicalizeRoleClass,
|
||||
defaultOverrideDir,
|
||||
defaultRolesDir,
|
||||
extractClassesFromDir,
|
||||
resolvePersonaFrom,
|
||||
type PersonaDirs,
|
||||
type PersonaResolution,
|
||||
type RoleAuthority,
|
||||
} from '../commands/fleet-personas.js';
|
||||
|
||||
export const ROSTER_V2_SUPPORTED_RUNTIMES = ['claude', 'codex', 'opencode', 'pi'] as const;
|
||||
export const ROSTER_V2_REASONING_LEVELS = ['low', 'medium', 'high'] as const;
|
||||
@@ -69,80 +58,6 @@ export interface FleetRosterV2 {
|
||||
readonly agents: readonly FleetRosterV2Agent[];
|
||||
}
|
||||
|
||||
export interface SemanticallyValidatedRosterV2Agent extends FleetRosterV2Agent {
|
||||
readonly requestedClass: string;
|
||||
readonly canonicalClass: string;
|
||||
readonly canonicalToolPolicy: string;
|
||||
readonly persona: PersonaResolution;
|
||||
readonly authority: RoleAuthority;
|
||||
}
|
||||
|
||||
export interface SemanticallyValidatedRosterV2 extends Omit<FleetRosterV2, 'agents'> {
|
||||
readonly agents: readonly SemanticallyValidatedRosterV2Agent[];
|
||||
}
|
||||
|
||||
const PROTECTED_TOOL_POLICY_CLASSES = new Set([
|
||||
'merge-gate',
|
||||
'validator',
|
||||
'orchestrator',
|
||||
'team-leader',
|
||||
'interaction',
|
||||
]);
|
||||
|
||||
/**
|
||||
* Validate filesystem-backed roster semantics after synchronous structural parsing.
|
||||
* Directory scans are batched once and every class must resolve to readable content.
|
||||
*/
|
||||
export async function validateRosterV2Semantics(
|
||||
roster: FleetRosterV2,
|
||||
opts: PersonaDirs = {},
|
||||
): Promise<SemanticallyValidatedRosterV2> {
|
||||
const rolesDir = opts.rolesDir ?? defaultRolesDir(opts.mosaicHome);
|
||||
const overrideDir = opts.overrideDir ?? defaultOverrideDir(opts.mosaicHome);
|
||||
const [base, over] = await Promise.all([
|
||||
extractClassesFromDir(rolesDir),
|
||||
extractClassesFromDir(overrideDir),
|
||||
]);
|
||||
|
||||
const agents: SemanticallyValidatedRosterV2Agent[] = [];
|
||||
for (const agent of roster.agents) {
|
||||
const requestedClass = agent.className;
|
||||
const { canonicalClass } = canonicalizeRoleClass(requestedClass);
|
||||
const canonicalToolPolicy = canonicalizeRoleClass(agent.toolPolicy).canonicalClass;
|
||||
const persona = await resolvePersonaFrom(requestedClass, {
|
||||
rolesDir,
|
||||
overrideDir,
|
||||
base,
|
||||
over,
|
||||
});
|
||||
if (!persona || persona.content.trim() === '') {
|
||||
throw new RosterV2ValidationError(
|
||||
`Roster v2 agent "${agent.name}" class "${requestedClass}" does not resolve to a readable persona.`,
|
||||
);
|
||||
}
|
||||
if (
|
||||
(PROTECTED_TOOL_POLICY_CLASSES.has(canonicalClass) ||
|
||||
PROTECTED_TOOL_POLICY_CLASSES.has(canonicalToolPolicy)) &&
|
||||
canonicalToolPolicy !== canonicalClass
|
||||
) {
|
||||
throw new RosterV2ValidationError(
|
||||
`Roster v2 agent "${agent.name}" protected class "${canonicalClass}" tool policy must match its canonical class; received "${agent.toolPolicy}".`,
|
||||
);
|
||||
}
|
||||
agents.push(
|
||||
Object.freeze({
|
||||
...agent,
|
||||
requestedClass,
|
||||
canonicalClass,
|
||||
canonicalToolPolicy,
|
||||
persona,
|
||||
authority: authorityForCanonicalClass(canonicalClass),
|
||||
}),
|
||||
);
|
||||
}
|
||||
return Object.freeze({ ...roster, agents: Object.freeze(agents) });
|
||||
}
|
||||
|
||||
export class RosterV2ValidationError extends Error {
|
||||
constructor(message: string) {
|
||||
super(message);
|
||||
|
||||
Reference in New Issue
Block a user