docs: establish canonical documentation architecture (#1210)
ci/woodpecker/push/publish Pipeline failed
ci/woodpecker/push/publish Pipeline failed
This commit was merged in pull request #1210.
This commit is contained in:
@@ -1,118 +0,0 @@
|
||||
# RM-61 — CI contract exemption for #1000 teardown artifact
|
||||
|
||||
**Tracking:** RM-61 / issue #1000
|
||||
|
||||
**Branch:** `fix/rm-61-ci-contract-exemption`
|
||||
**Owner:** `coder-mos1`
|
||||
|
||||
## Objective
|
||||
|
||||
Determine, by red-first provider controls, whether the `ci-postgres` pod-not-found teardown signature discriminates from a real PostgreSQL failure. Only if it discriminates may a named, bounded CI-contract exemption be implemented. The exemption must retire when #1000 is fixed; fixing #1000 is the closure path.
|
||||
|
||||
## Pre-registered kill criterion
|
||||
|
||||
If an injected real `ci-postgres` failure also yields `pods "wp-svc-<ULID>-ci-postgres" not found` as the service's provider-visible failure, the signature does not discriminate. Option B is unsafe; stop exemption implementation and fall to Option A (#1000).
|
||||
|
||||
## Plan
|
||||
|
||||
1. Capture full `-f json` records for the 11 supplied observations and state counts.
|
||||
2. Run one startup-failure control using the real pgvector/PostgreSQL image with an invalid `initdb` argument.
|
||||
3. Run one post-readiness crash control using real PostgreSQL, `pg_isready`, and a deliberate postmaster kill while a DB-dependent probe is active.
|
||||
4. Compare the raw `ci-postgres` service record independently of failures in dependent steps.
|
||||
5. Investigate runner/time/head clustering only as a hypothesis; never encode incidental correlates or retries into policy.
|
||||
6. If and only if the controls discriminate, implement and test the exact exemption, document its two-way boundary, and track retirement at #1000.
|
||||
|
||||
## Budget
|
||||
|
||||
No explicit token cap supplied. Working estimate: 20K–30K tokens. Limit provider controls to the two pre-registered runs; no retries or re-roll policy.
|
||||
|
||||
## Initial evidence
|
||||
|
||||
Historical JSON saved locally under `.evidence/rm-61/` (not for commit). Supplied pipelines: 11 total. Child-step counts: five pipelines with 9 children and six with 10 children. Seven contain the `ci-postgres` pod-not-found failure (#2170, #2175, #2180, #2181, #2182, #2187, #2188); four do not (#2158, #2167, #2184, #2186). Every observed workflow reports `agent_id=44`, so the available JSON does not separate clean and artifact runs by runner. This refutes runner identity as a discriminator in the sampled record.
|
||||
|
||||
## Progress
|
||||
|
||||
- [x] Requirements and kill criterion recorded before control implementation.
|
||||
- [x] Historical full-JSON records captured.
|
||||
- [x] Startup-failure control observed terminal.
|
||||
- [x] Post-readiness crash control observed terminal.
|
||||
- [x] Discrimination verdict recorded: Option B may proceed.
|
||||
- [x] Conditional exemption implementation.
|
||||
|
||||
## Tests / evidence
|
||||
|
||||
### Control 1 — real startup failure
|
||||
|
||||
- Commit: `3931b0e29eb834914f7b17e4db7e221481d436fa`
|
||||
- Pipeline: #2189, exact commit match.
|
||||
- Full JSON child scan: 9 total — 7 success, 2 failure, 0 skipped/pending/running.
|
||||
- `ci-postgres`: `state=failure`, `exit_code=1`, `error=null`, with a five-second execution window.
|
||||
- `test`: `state=failure`, `exit_code=1` after the readiness budget expired.
|
||||
- Pipeline/workflow: terminal `failure`.
|
||||
|
||||
This control is red and its service record differs from #1000 (`exit_code=0` plus pod-not-found). It proves the startup-failure direction only. It does not settle the dangerous post-readiness crash/garbage-collection path.
|
||||
|
||||
### Control 2 — real post-readiness crash
|
||||
|
||||
- Commit: `25ac59715a94dd1b52ef42577472eb44ecc4b446`
|
||||
- Pipeline: #2191, exact commit match.
|
||||
- Full JSON child scan: 9 total — 7 success, 2 failure, 0 skipped/pending/running.
|
||||
- Service log proves PostgreSQL reached `database system is ready to accept connections`, the test created the arm table, and the service then killed postmaster PID 7.
|
||||
- Test log proves a successful `SELECT 1` followed by `Connection refused`; it exited the pre-registered control code 61.
|
||||
- `ci-postgres`: `state=failure`, `exit_code=137`, `error=null`, with a 203-second execution window.
|
||||
- `test`: `state=failure`, `exit_code=61`.
|
||||
- Pipeline/workflow: terminal `failure`.
|
||||
|
||||
This is the dangerous post-readiness crash path. Its service record is not pod-not-found and therefore differs from #1000 independently of the dependent test failure.
|
||||
|
||||
### Discrimination verdict
|
||||
|
||||
Both real failures are provider-visible as process exits (`exit_code=1` startup; `exit_code=137` crash) with no pod-not-found error. The seven observed #1000 artifacts are provider reconciliation misses (`exit_code=0` plus the exact pod-not-found error). The declared kill criterion did not fire, so Option B may proceed with a matcher requiring the full conjunction. This evidence does **not** prove every future Kubernetes failure is distinguishable; it proves these two concrete real-failure classes remain blocking and bounds the exemption to the observed reconciliation shape.
|
||||
|
||||
### Unit red-first checkpoint
|
||||
|
||||
The nine-case contract harness was written before the verifier. First execution exited 1 because `verify-terminal-green.py` did not exist; no exemption implementation was live. Cases pre-register ordinary green, the exact artifact, both provider controls, near-miss signatures, an independent failure, and a skipped step.
|
||||
|
||||
### Control 2 setup attempt — invalid, excluded from evidence
|
||||
|
||||
- Commit: `9455cd6a2650b2b7e70f746c07933d96e5cb3d20`
|
||||
- Pipeline: #2190, exact commit match.
|
||||
- Full JSON child scan: 9 total — 7 success, 2 failure, 0 skipped/pending/running.
|
||||
- Service log: `/bin/sh: 0: -c requires an argument`.
|
||||
- Root cause: Woodpecker service `commands` did not become the third `sh -c` argument. PostgreSQL never started, so this run is **not** the post-readiness crash control and provides no discrimination evidence.
|
||||
- Focused remediation: place the script directly in the third `entrypoint` element and supply `PGPASSWORD` for the marker query. This is a control-fixture correction, not a retry of #1000 and not evidence for either verdict.
|
||||
|
||||
## Implementation evidence
|
||||
|
||||
- `verify-terminal-green.py` consumes only the full JSON/API record; it performs no fetch, retry, or trigger.
|
||||
- Exact #2188 record: exit 0, 10 children, 9 success + 1 named exemption.
|
||||
- Historical set: #2158/#2167/#2184/#2186 pass with no exemption; #2170/#2175/#2182/#2187/#2188 pass with one named exemption; #2180/#2181 remain red because independent failures exist.
|
||||
- Provider controls: #2189 and #2191 both exit 1 under the verifier; neither is exempted.
|
||||
- Unit harness: initial 9/9 cases passed after the red-first checkpoint; review remediation expands this to 12 cases with expected-head match/missing/mismatch coverage.
|
||||
- Test-membership guard: PASS, population 45; 26 enumerated, 19 signed exclusions; all 39 surface paths present.
|
||||
- Python compile: PASS.
|
||||
- `pnpm typecheck`: PASS, 45/45 tasks.
|
||||
- `pnpm lint`: PASS, 25/25 tasks.
|
||||
- `pnpm format:check`: PASS after moving local evidence outside the repository tree.
|
||||
- `test:framework-shell`: RM-61 and all preceding suites passed, then the pre-existing wake assertion aborted with exit 97 because this host's Bash 5.2.15 reports `BASH_LINENO [3 5]` where that suite requires `[3 4]`. RM-61 does not modify the wake suite; the command is not fully runnable on this host as written and no substitute result is claimed.
|
||||
|
||||
## Independent review
|
||||
|
||||
- Review 67 / comment 20403 at exact head `e7b29219e11efd0a19395156ac0b154bec0c3a73`: **REQUEST CHANGES**.
|
||||
- Blocker: the verifier echoed the pipeline commit but did not bind it to the current PR head; mutating only #2188's commit still returned terminal-green.
|
||||
- Remediation: require `--expect-commit <full-40>`, add a pipeline anomaly on missing/mismatched record commits, emit expected and observed values, wire both CI documentation and the merge-gate baseline to pass provider PR head, and add match/missing/mismatch tests.
|
||||
- This binding is not prohibited head-based clustering policy: it proves the evidence belongs to the commit under verdict. Runner/node/time/head correlation remains excluded from the teardown signature itself.
|
||||
- Review 69 later approved the commit-binding remediation at exact head `033b2ffb46674b2c0bcc5197273c109b461f62d9`; pipeline #2193 was 9/9 success. Before merge-gate, an independent adjudicator found that Python treats JSON `false == 0`, allowing a non-integer exit value to match. The prior gate-ready state was withdrawn. The type-strict set distinguishes genuine red-first controls (`false`, `0.0`, which wrongly exempted) from regression guards (`true`, `"0"`, `null`, which already blocked). Remediation requires the decoded type to be exactly `int` and excludes `bool` explicitly.
|
||||
|
||||
## Documentation checklist
|
||||
|
||||
- [x] CI contract documented in the canonical framework CI/CD guide.
|
||||
- [x] Operator command documented in the Woodpecker tool README.
|
||||
- [x] Merge-gate baseline points to the deterministic verifier and named retirement.
|
||||
- [x] Tracking and retirement cite issue #1000.
|
||||
- [x] Both positive and negative guarantee boundaries are stated.
|
||||
- [x] No API/auth/schema/user-facing navigation change; OpenAPI, user guide, and sitemap are not applicable.
|
||||
|
||||
## Risks
|
||||
|
||||
The controls establish discrimination for deterministic startup failure and an armed post-readiness postmaster crash on the current Woodpecker Kubernetes provider. They cannot prove that every future Kubernetes failure mode will preserve a non-zero exit before reconciliation. The exact matcher minimizes that residual risk, and issue #1000 remains the mandatory provider-seam closure and retirement trigger.
|
||||
@@ -1,52 +0,0 @@
|
||||
# Fleet CLI Local Canary Dogfood — 2026-06-20
|
||||
|
||||
## Objective
|
||||
|
||||
Move the durable tmux fleet PoC into a functional local canary on this server. This is **not** production deployment. It is a canary/dogfood path for a small local agent fleet using an isolated tmux socket.
|
||||
|
||||
## Issue
|
||||
|
||||
- Gitea issue: #562 — `feat(fleet): local CLI canary dogfood`
|
||||
|
||||
## Scope
|
||||
|
||||
Implement enough product surface to use the fleet locally:
|
||||
|
||||
- `mosaic fleet init/install/start/stop/restart/status/verify`
|
||||
- `mosaic agent roster/status/send/reset/tail`
|
||||
- roster schema and examples
|
||||
- local canary docs and rollback instructions
|
||||
- tests for CLI behavior where practical
|
||||
- canary verification on named tmux socket `mosaic-fleet`
|
||||
|
||||
## Non-goals
|
||||
|
||||
- No production rollout.
|
||||
- No migration of existing default tmux sessions.
|
||||
- No image build/deploy work.
|
||||
- No hardcoded USC/local roster as product default.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- CLI can initialize a minimal roster outside product defaults.
|
||||
- CLI can install user systemd units and fleet helper scripts to a configurable Mosaic home.
|
||||
- CLI can start/stop/status/verify a canary fleet using `mosaic-fleet`.
|
||||
- `mosaic agent send` uses existing named-socket/exact-target tmux tooling.
|
||||
- `mosaic agent reset` targets only the named agent session on the named socket.
|
||||
- Verification proves default tmux sessions remain untouched.
|
||||
- Baseline repo gates pass.
|
||||
- PR CI is green before merge.
|
||||
- Local canary evidence is captured after merge/install.
|
||||
|
||||
## Budget / Routing
|
||||
|
||||
- Agent: codex preferred.
|
||||
- Estimate: 25K-40K tokens.
|
||||
- Worker owns implementation/tests/docs in branch `feat/fleet-cli-local-canary`.
|
||||
- Orchestrator owns `docs/TASKS.md`, issue/PR/merge, and local canary install verification.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-06-20: #557 PoC primitives merged to `main` as `45e2c2a`.
|
||||
- 2026-06-20: issue #562 created for local CLI canary dogfood.
|
||||
- 2026-06-20: worktree created at `/home/jarvis/src/mosaicstack-stack-worktrees/fleet-cli-local-canary`.
|
||||
@@ -1,35 +0,0 @@
|
||||
# Fleet release hardening
|
||||
|
||||
## Objective
|
||||
|
||||
Harden the Mosaic local fleet release path for operator sends, tmux/systemd verification, package contents, and dogfood release documentation.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Do not edit `docs/TASKS.md`.
|
||||
- Do not change production deployment refs.
|
||||
- Keep fleet transport generic and named-socket safe.
|
||||
- Preserve strict roster validation.
|
||||
- Add tests first or alongside fixes.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add regression tests for deterministic `mosaic agent send` source labels.
|
||||
2. Strengthen fleet status/verify/package/install-systemd coverage.
|
||||
3. Implement focused CLI/source-label changes.
|
||||
4. Update local canary documentation with dogfood preflight.
|
||||
5. Run formatting, targeted tests, typecheck, lint, and package dry-run evidence.
|
||||
|
||||
## Evidence Log
|
||||
|
||||
- Started from existing `docs/PRD.md`; durable local fleet canary is in v0.1.0 scope.
|
||||
- Loaded `mosaic-fleet-operations` skill; key constraints are isolated tmux sockets, no default tmux positive tests, and `active (exited)` is not liveness.
|
||||
- TDD red: `pnpm --filter @mosaicstack/mosaic test -- src/commands/fleet.spec.ts` initially failed because `node_modules` was absent; after `pnpm install`, the new source-label tests failed on missing `-S`, missing helper, and unknown `--source-label`.
|
||||
- Green implementation: `mosaic agent send` now passes `-S <hostname>:operator` by default and accepts `--source-label` / `--source` overrides.
|
||||
- Test coverage added for tmux-based fleet verify liveness, package `files` allowlist containing `framework`, and explicit operator source-label command construction.
|
||||
- Formatting: `pnpm exec prettier --write packages/mosaic/src/commands/fleet.ts packages/mosaic/src/commands/fleet.spec.ts docs/guides/fleet-local-canary.md docs/scratchpads/2026-06-20-fleet-release-hardening.md`.
|
||||
- Targeted tests: `pnpm --filter @mosaicstack/mosaic test -- src/commands/fleet.spec.ts src/cli-smoke.spec.ts` passed with 49 tests.
|
||||
- Typecheck: `pnpm typecheck` passed.
|
||||
- Lint: `pnpm lint` passed.
|
||||
- Package dry-run: `npm pack --dry-run --json` from `packages/mosaic` included `framework/fleet`, `framework/systemd/user`, `framework/tools/fleet/start-agent-session.sh`, and `framework/tools/tmux/{agent-send.sh,send-message.sh}`.
|
||||
- Review: `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` approved the supplied diff with no findings; the review tool noted its read-only sandbox could not inspect files directly.
|
||||
@@ -1,54 +0,0 @@
|
||||
# Scratchpad — issue #387 updater simplification + Gitea wrapper repo context
|
||||
|
||||
- Objective: simplify updater behavior to `@mosaicstack/mosaic` only, and fix Gitea wrapper scripts so merge/CI/issue operations work reliably when tea needs explicit repo/login context.
|
||||
- Scope:
|
||||
- `packages/mosaic/src/runtime/update-checker.ts`
|
||||
- `packages/mosaic/__tests__/update-checker.test.ts`
|
||||
- any package metadata/version bumps needed
|
||||
- repo-source git wrappers under `packages/mosaic/framework/tools/git/`
|
||||
- Constraints:
|
||||
- Jason approved breaking changes; legacy `@mosaicstack/cli` support is out of scope.
|
||||
- Keep changes focused and mergeable.
|
||||
- Acceptance:
|
||||
- updater only targets `@mosaicstack/mosaic`
|
||||
- wrapper path works on Gitea in this environment without manual repo guessing
|
||||
- PR merges squash-only after green CI
|
||||
|
||||
## Progress
|
||||
|
||||
### 2026-04-04
|
||||
|
||||
#### Update Checker Simplification (DONE)
|
||||
|
||||
- Removed `LEGACY_PKG`, `INSTALLED_PACKAGE_ORDER` constants — only `PKG = '@mosaicstack/mosaic'` remains
|
||||
- `getInstalledVersion()` — removed loop over multiple packages, only checks `@mosaicstack/mosaic`
|
||||
- `getLatestVersion()` — removed `installedPackage` parameter and candidate iteration; single query for `@mosaicstack/mosaic`
|
||||
- `checkForUpdate()` — removed `currentPackage`-based cache key comparison; cache is now package-agnostic
|
||||
- `RegistryCache` — removed `currentPackage` and `targetPackage` fields
|
||||
- `formatUpdateNotice()` — removed `targetChanged` branch (package migration notice no longer relevant)
|
||||
- All legacy fallback/compatibility logic removed
|
||||
|
||||
#### Test Updates (DONE)
|
||||
|
||||
- Removed legacy `@mosaicstack/cli` fallback test
|
||||
- Removed cache cross-contamination test (was testing legacy→modern package transition)
|
||||
- Added `does not query legacy @mosaicstack/cli package` test — asserts no `@mosaicstack/cli` npm commands are issued
|
||||
- Added `returns empty result when package is not installed` test
|
||||
- All 8 tests pass ✅
|
||||
|
||||
#### Gitea Wrapper Fixes (DONE)
|
||||
|
||||
- `pr-merge.sh`:
|
||||
- Added `OWNER=$(get_repo_owner)` / `REPO=$(get_repo_name)` before case block
|
||||
- tea merge command now includes `--repo $OWNER/$REPO --login ${GITEA_LOGIN:-mosaicstack}`
|
||||
- `issue-close.sh`:
|
||||
- Added `OWNER=$(get_repo_owner)` / `REPO=$(get_repo_name)` after detect_platform
|
||||
- Both `tea issue comment` and `tea issue close` now include `--repo "$OWNER/$REPO" --login "${GITEA_LOGIN:-mosaicstack}"`
|
||||
- `pr-ci-wait.sh`: No changes needed — uses curl API calls (not tea), already passes owner/repo correctly
|
||||
- `detect-platform.sh`: No changes needed — provides the `get_repo_owner`/`get_repo_name` functions used by wrappers
|
||||
|
||||
#### Verification
|
||||
|
||||
- `vitest run` — 8/8 tests pass
|
||||
- `tsc --noEmit` — no errors in update-checker.ts (pre-existing workspace dep errors unrelated)
|
||||
- `eslint` — clean, no warnings
|
||||
@@ -1,30 +0,0 @@
|
||||
# Scratchpad — P5-001 Plugin Host
|
||||
|
||||
- Task: P5-001 / issue #41
|
||||
- Branch: feat/p5-plugin-host
|
||||
- Objective: add global NestJS plugin host module, wire Discord import, register active plugins from env, and attach to AppModule.
|
||||
- TDD: skipped as optional for module wiring/integration work; relying on targeted typecheck/lint and module-level situational verification.
|
||||
- Constraints: ESM .js imports, explicit @Inject(), follow existing gateway patterns, do not touch TASKS.md.
|
||||
|
||||
## Progress Log
|
||||
|
||||
- 2026-03-13: session started in worktree; loading gateway/plugin package context.
|
||||
- 2026-03-13: implemented initial plugin module, service, interface, and AppModule wiring; pending verification.
|
||||
- 2026-03-13: added `@mosaicstack/discord-plugin` as a gateway workspace dependency and regenerated `pnpm-lock.yaml`.
|
||||
- 2026-03-13: built gateway dependency chain so workspace packages exported `dist/*` for clean TypeScript resolution in this fresh worktree.
|
||||
- 2026-03-13: verification complete.
|
||||
|
||||
## Verification
|
||||
|
||||
- `pnpm --filter @mosaicstack/gateway... build` ✅
|
||||
- `pnpm --filter @mosaicstack/gateway typecheck` ✅
|
||||
- `pnpm --filter @mosaicstack/gateway lint` ✅
|
||||
- `pnpm format:check` ✅
|
||||
- `pnpm typecheck` ✅
|
||||
- `pnpm lint` ✅
|
||||
|
||||
## Review
|
||||
|
||||
- Automated review: `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted`
|
||||
- Manual review: diff inspection of gateway plugin host changes
|
||||
- Result: no blocker findings
|
||||
@@ -1,60 +0,0 @@
|
||||
# Scratchpad — FED-M3-04 Scope Service
|
||||
|
||||
## Objective
|
||||
|
||||
Implement `apps/gateway/src/federation/server/scope.service.ts` for the M3 inbound federation scope-enforcement pipeline.
|
||||
|
||||
## Scope / Constraints
|
||||
|
||||
- Task: FED-M3-04, issue #462.
|
||||
- Branch: `feat/federation-m3-scope-service` from `origin/main` @ 0.0.48.
|
||||
- Pure service: no direct DB access; native RBAC/data access is injected per evaluation call.
|
||||
- Reuse `parseFederationScope` from M2-03.
|
||||
- Workers do not edit `docs/federation/TASKS.md` per repo AGENTS.md.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. Resource allowlist and `excluded_resources` enforced.
|
||||
2. Native RBAC evaluated as `subjectUserId` through an injected evaluator.
|
||||
3. Scope filter intersection supports `include_teams` and `include_personal` without widening native RBAC.
|
||||
4. `max_rows_per_query` caps requested limits.
|
||||
5. Service returns `{ allowed: true, filter }` or a structured deny reason usable by M4 audit.
|
||||
6. Unit tests cover every deny path.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Inspect existing federation scope/schema/auth guard contracts.
|
||||
2. Add pure `FederationScopeService` plus typed result/filter/deny interfaces.
|
||||
3. Add focused unit tests for happy paths, filter intersection, row cap, and deny paths.
|
||||
4. Export/register service for future verb controllers.
|
||||
5. Run situational tests, baseline gates, code review, then PR.
|
||||
|
||||
## Budget
|
||||
|
||||
- Provided model tier: sonnet.
|
||||
- Estimate from task row: 10K tokens.
|
||||
- Working cap assumption: keep implementation focused to FED-M3-04 surfaces only.
|
||||
|
||||
## Progress
|
||||
|
||||
- Intake complete; dirty base worktree avoided by creating isolated worktree at `/home/jarvis/src/mosaic-mono-v1-fed-m3-04`.
|
||||
- Project PRD and federation task spec reviewed.
|
||||
- Added `FederationScopeService` with structured allow/deny result types and injected native RBAC evaluator contract.
|
||||
- Added unit coverage for happy path, row cap, filter intersection, and every deny path.
|
||||
- Exported/registered the service for upcoming M3 verb controllers.
|
||||
|
||||
## Verification Evidence
|
||||
|
||||
- `pnpm --filter @mosaicstack/gateway test -- src/federation/server/__tests__/scope.service.spec.ts` — pass (10 tests before review update; 11 tests after adding include_personal no-leak coverage).
|
||||
- `pnpm build` — pass (23 successful tasks).
|
||||
- `pnpm typecheck` — pass (41 successful tasks; re-run after review update).
|
||||
- `pnpm lint` — pass (23 successful tasks; re-run after review update).
|
||||
- `pnpm format:check` — pass (re-run after review update).
|
||||
- `pnpm test` — pass after starting local `postgres`/`valkey` and running `pnpm --filter @mosaicstack/db db:push` for the DB-backed cross-user isolation suite (41 successful tasks; gateway 477 passed / 11 skipped).
|
||||
- Code review: `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — approve, 0 findings.
|
||||
- Security review: `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted` — risk none, 0 findings.
|
||||
|
||||
## Risks / Blockers
|
||||
|
||||
- Issue #462 is already closed in provider output; likely milestone tracking mismatch. Will still reference #462 in PR body unless orchestrator redirects.
|
||||
- Local full-test setup required `docker compose up -d postgres valkey` + `db:push`; containers were stopped with `docker compose down` after verification.
|
||||
@@ -1,38 +0,0 @@
|
||||
# Scratchpad — FED-M3-06 get verb
|
||||
|
||||
## Objective
|
||||
|
||||
Implement `POST /api/federation/v1/get/:resource/:id` for M3 inbound federation reads.
|
||||
|
||||
## Scope
|
||||
|
||||
- `apps/gateway/src/federation/server/verbs/get.controller.ts`
|
||||
- `apps/gateway/src/federation/server/verbs/get-query.service.ts`
|
||||
- Unit coverage for controller pipeline + query service RBAC guardrails
|
||||
- Register controller/service in `FederationModule`
|
||||
|
||||
## Plan
|
||||
|
||||
1. Mirror the list verb pipeline: `FederationAuthGuard` → `FederationScopeService` → read-only query service.
|
||||
2. Return one `_source: "local"` tagged item on success.
|
||||
3. Return federation error envelopes:
|
||||
- `404 not_found` when the resource id does not exist.
|
||||
- `403 scope_violation` when the row exists but falls outside native RBAC/scope intersection.
|
||||
- `400 invalid_request` for malformed ids/scope requests.
|
||||
4. Keep read audit persistence deferred to M4; no body or response persistence in M3.
|
||||
|
||||
## Verification Evidence
|
||||
|
||||
- Rebased onto `origin/main` at `86e106fcc9a1dfa3a18f7846bb477be128794aad` after M3-05 merged; resolved `FederationModule` by registering both list and get verb controllers/services.
|
||||
- Review-change coverage added for comment 15971:
|
||||
- get note access now requires subject ownership AND authorized mission intersection.
|
||||
- missing federation context returns structured `401 unauthorized` envelope.
|
||||
- unsupported get resources fail closed with structured denial.
|
||||
- PGlite regressions cover cross-user note exclusion and subject-note unauthorized-mission exclusion.
|
||||
- `pnpm --filter @mosaicstack/gateway test -- src/federation/server/verbs/__tests__/get.controller.spec.ts src/federation/server/verbs/__tests__/get-query.service.spec.ts` — pass (2 files / 17 tests; re-run after review changes).
|
||||
- `pnpm --filter @mosaicstack/gateway build` — pass (re-run after review changes).
|
||||
- `pnpm build` — pass (23 successful tasks before review changes).
|
||||
- `pnpm typecheck` — pass (41 successful tasks; re-run after review changes).
|
||||
- `pnpm lint` — pass (23 successful tasks; re-run after review changes).
|
||||
- `pnpm format:check` — pass (re-run after review changes).
|
||||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — approve, 0 findings after review changes.
|
||||
@@ -1,50 +0,0 @@
|
||||
# Issue 536 Wrapper Login Pin Scratchpad
|
||||
|
||||
## Metadata
|
||||
|
||||
- Date: 2026-06-12
|
||||
- Worktree: `/home/hermes/agent-work/536-wrapper-audit`
|
||||
- Branch: `fix/536-wrapper-login-pin`
|
||||
- Coordinator: `mos-claude`
|
||||
- Issue: `mosaicstack/stack#536`
|
||||
- Scope: Audit and fix Gitea git wrappers that hardcode or incorrectly inherit tea login/instance selection.
|
||||
|
||||
## Objective
|
||||
|
||||
Fix the framework git wrappers so Gitea issue/PR operations resolve the tea login from the target repository host instead of pinning `mosaicstack`. The fix must cover the class of bug across `packages/mosaic/framework/tools/git/`, not only `issue-close.sh`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. `issue-close.sh` no longer uses `--login mosaicstack` for non-mosaic hosts.
|
||||
2. All wrappers in `packages/mosaic/framework/tools/git/` avoid hardcoded Gitea login fallback where host-specific resolution is available.
|
||||
3. Host-specific resolution works for `git.mosaicstack.dev` and `git.uscllc.com` using configured credentials / tea login data.
|
||||
4. Read-only verification runs against both Gitea instances where possible.
|
||||
5. Queue guard passes before push, PR is opened referencing #536, and merge is left to the coordinator.
|
||||
|
||||
## Progress Log
|
||||
|
||||
- Read required Mosaic hard-gate docs and coordinator briefing.
|
||||
- Read issue #536 via Gitea API with mosaicstack credentials.
|
||||
- Initial audit found hardcoded `${GITEA_LOGIN:-mosaicstack}` in issue and PR wrappers, plus shared `get_gitea_repo_args`.
|
||||
- Added host-aware Gitea login resolution in `detect-platform.sh`, including exact host matching for `tea login list` entries and HTTPS remotes with embedded credentials.
|
||||
- Updated Gitea issue, PR, milestone, and CI wrappers to use resolved host-specific tea login arguments instead of defaulting to `mosaicstack`.
|
||||
- Added authenticated API fallbacks for close/reopen paths so wrappers can still operate when a matching `tea` login is absent but token credentials are available.
|
||||
- Added regression coverage for stale `GITEA_LOGIN`, exact host matching, `--repo` override flows, USC issue close routing, mosaicstack API fallback, and PR metadata/merge fallbacks.
|
||||
- Delta after PR #538 review: extended host-aware login/repo resolution to PowerShell wrappers, Bash milestone wrappers, and API-only `--repo` fallback paths.
|
||||
- Delta after live USC `pr-create.sh` repro: tightened `GITEA_LOGIN` trust so stale login names are ignored unless the tea login itself matches the target host, and added USC API fallback coverage for `pr-create.sh`.
|
||||
|
||||
## Verification
|
||||
|
||||
- `bash -n packages/mosaic/framework/tools/git/*.sh`
|
||||
- `packages/mosaic/framework/tools/git/test-gitea-login-resolution.sh`
|
||||
- `packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh`
|
||||
- `packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh`
|
||||
- `pwsh -NoProfile` parse check for all `packages/mosaic/framework/tools/git/*.ps1`
|
||||
- `pnpm typecheck`
|
||||
- `pnpm lint`
|
||||
- `pnpm format:check`
|
||||
- `pnpm --filter @mosaicstack/mosaic test -- src/commands/git-wrapper-redirects.spec.ts`
|
||||
- `pnpm test` progressed past wrapper redirect assertions; local run then stopped on `apps/gateway` Postgres connection refused at `localhost:5433`, which CI provides as a service.
|
||||
- Live read-only: direct Gitea API read of `mosaicstack/stack#536` with `User-Agent: curl/8`.
|
||||
- Live read-only: USC temporary repo remote to `https://git.uscllc.com/USC/uconnect.git`; `issue-list.sh -n 1` resolved the USC login and returned USC issues.
|
||||
- Independent Codex review final verdict: approve, no findings.
|
||||
@@ -1,55 +0,0 @@
|
||||
# Scratchpad — #544 Agent Reflection Loop (durable kernel)
|
||||
|
||||
**Started:** 2026-06-16 · **Branch:** `feat/agent-reflection-loop` · **Base:** `main` @ c461380
|
||||
|
||||
## Goal
|
||||
|
||||
Bake the durable kernel of the agent reflection loop into the Mosaic Stack
|
||||
monorepo through full delivery gates. Kernel only; closed loop (§7–§8) gated on
|
||||
Phase-0. Authoritative spec: `docs/plans/agent-reflection-loop-PRD.md`. Task
|
||||
breakdown: `docs/tasks/544-agent-reflection-loop.md`.
|
||||
|
||||
## Timeline / decisions
|
||||
|
||||
- Mapped house style against `main` truth (the earlier recon had mapped a dirty
|
||||
feature branch and returned non-existent paths; re-cloned `main` clean).
|
||||
- macp uses co-located `*.spec.ts`; types uses `src/<mod>/{*.ts, *.dto.ts, __tests__/*.spec.ts}`.
|
||||
- zod v4 + class-validator/class-transformer present in `@mosaicstack/types`;
|
||||
`packages/types/tsconfig.json` enables `experimentalDecorators`/`emitDecoratorMetadata`.
|
||||
- **Gotcha (fixed):** `class-transformer`'s `@Type` calls `Reflect.getMetadata`
|
||||
at module-load time; the types vitest env has no `reflect-metadata`, so any test
|
||||
importing the reflection barrel crashed on import. `chat.dto.ts` avoids this by
|
||||
using class-validator only. Fix: dropped `@Type`/`@ValidateNested` from the DTO;
|
||||
zod owns deep nested validation.
|
||||
- **Gotcha (fixed):** Stop hook `EXIT` trap referenced a `main`-local `lock` →
|
||||
`unbound variable` under `set -u` at exit. Promoted to a global `LOCKFILE`.
|
||||
- **Gotcha (fixed):** the hook's own lock + `.mosaic/` scratch leaked into
|
||||
`files_changed`. Excluded `^\.mosaic/` from the change-surface scan.
|
||||
|
||||
## Verification evidence
|
||||
|
||||
- macp: typecheck OK, lint OK, **88 tests pass** (15 new risk-floor).
|
||||
- types: typecheck OK, lint OK, **64 tests pass** (10 new reflection).
|
||||
- Root: `pnpm typecheck` (41 tasks), `pnpm lint` (23), `pnpm format:check`, `pnpm build` (23) — all green.
|
||||
- Stop hook smoke (throwaway git repo): TEST1 no-op (mode unset, 0 files);
|
||||
TEST2 solo degraded, `.mosaic/` excluded, auth→needs_review; TEST3 self-report
|
||||
merged, degraded=false; TEST4 lock suppresses re-fire. All pass, always exit 0.
|
||||
- shellcheck clean: hook + `reflect-{git-history,board-history,calibration}.sh`.
|
||||
- Phase-0 smoke: P2 on this repo (142 failures classified), P1 AUC=0.875 on a
|
||||
synthetic fixture, P3 base-rate on a synthetic board — all emit structured output
|
||||
- kill conditions.
|
||||
|
||||
## Open risks / follow-ups
|
||||
|
||||
- Full `pnpm test` (DB-bound packages) validated via CI's postgres service, not
|
||||
locally; affected packages (macp, types) are DB-independent and green here.
|
||||
- sequential-thinking MCP was registered mid-session (effective next session);
|
||||
this session compensated with the written PRD as the planning artifact.
|
||||
- Phase-0 corpora are not yet wired — scripts are harnesses + pre-registered
|
||||
rubrics (P1/P2/P3 tasks tracked in jarvis-brain `agent-reflection-loop` project).
|
||||
|
||||
## Gate status
|
||||
|
||||
- [x] PRD authored · [x] issue #544 created + linked · [x] code + tests
|
||||
- [x] local gates green · [ ] independent code review · [ ] PR opened
|
||||
- [ ] CI terminal green · [ ] merged to main · [ ] issue closed
|
||||
@@ -1,87 +0,0 @@
|
||||
# Wrapper hardening fold-in: #559 (eval removal) + #560 (host-derived login)
|
||||
|
||||
**Branch:** `fix/wrapper-hardening-tls-credpath-cicwait` (PR #551)
|
||||
**Worker:** coderlite0 (Sonnet lane) · coordinated by mos-claude
|
||||
**Date:** 2026-06-20
|
||||
**Scope:** `packages/mosaic/framework/tools/git/*.sh` only
|
||||
|
||||
## What the issues asked for vs. what was already landed
|
||||
|
||||
Both issues were largely satisfied by prior merged work; this fold-in closes the
|
||||
remaining gaps (regression tests + a loud diagnostic + one residual word-split site)
|
||||
rather than re-implementing finished functionality.
|
||||
|
||||
### #559 — remove `eval` from issue-create.sh (and siblings)
|
||||
|
||||
- `eval`-based command construction was already removed across the wrapper surface
|
||||
(landed in #549). A full scan of `tools/git/*.sh` finds **zero** `eval` usages.
|
||||
- `issue-create.sh`, `pr-create.sh`, `issue-edit.sh`, `issue-assign.sh` already build
|
||||
their `tea`/`gh` invocations as argv arrays (`CMD=(...)`, `"${CMD[@]}"`), so Markdown
|
||||
bodies pass through verbatim.
|
||||
- **Residual found & fixed:** `issue-comment.sh` still used unquoted
|
||||
`$(get_gitea_repo_args)` word-splitting (the comment body itself was already safely
|
||||
quoted, so no injection bug — but it was the inconsistent, fragile pattern #559 targets,
|
||||
and it failed silently when no login resolved). Converted to an argv array with an
|
||||
explicit, loud login-resolution error.
|
||||
- **Added regression test:** `test-issue-create-body-safety.sh` — feeds a hostile
|
||||
Markdown body (`$(touch SENTINEL)`, backticks, single/double quotes, `$HOME`/`${PATH}`,
|
||||
pipes/`&&`/`;`) through `issue-create.sh` and asserts (1) no command substitution
|
||||
executes (sentinel file never created) and (2) the `--description` `tea` receives is
|
||||
byte-for-byte the original body.
|
||||
|
||||
### #560 — auto-detect Gitea `--login` from repo origin host
|
||||
|
||||
- Centralized host→login resolution already exists in `detect-platform.sh`
|
||||
(`get_gitea_login_for_host` → `find_tea_login_for_host`, matching `urlparse(url).hostname`).
|
||||
Every wrapper routes through it (or `get_gitea_login` / `get_gitea_login_for_repo_override`);
|
||||
**no wrapper hardcodes `${GITEA_LOGIN:-mosaicstack}`**. Explicit `GITEA_LOGIN` wins only
|
||||
when it matches the host (`tea_login_matches_host`), so stale overrides are rejected.
|
||||
- **Gap fixed — silent failure → loud diagnostic:** the failure path of
|
||||
`get_gitea_login_for_host` returned non-zero with no message. Added
|
||||
`print_gitea_login_diagnostic`, emitted to **stderr** on resolution failure: names the
|
||||
unresolved host, lists available tea logins (name + host), and gives the `GITEA_LOGIN`
|
||||
override + `tea login add` fix. Stderr-only, so it never contaminates stdout (the
|
||||
resolved login name) or the log-grep assertions in the existing harnesses. Callers with
|
||||
an API fallback (pr-merge, issue-close, pr-create, issue-create) still follow with their
|
||||
own "using API fallback" line, giving a clear "no login → fallback" trail.
|
||||
- **Extended test:** `test-gitea-login-resolution.sh` now also asserts (a) the loud
|
||||
diagnostic fires and lists available logins for an unresolved host, (b) login is derived
|
||||
from origin host for **both** instances (mosaicstack + usc) via a scoped second `tea`
|
||||
mock, and (c) a valid `GITEA_LOGIN` override is honored. The scoped mock keeps the
|
||||
existing API-fallback assertions (which require mosaicstack to have _no_ tea login) valid.
|
||||
|
||||
## Files changed (wrapper surface only)
|
||||
|
||||
- `detect-platform.sh` — add `print_gitea_login_diagnostic`; call it on the
|
||||
`get_gitea_login_for_host` failure path.
|
||||
- `issue-comment.sh` — argv array + loud login-resolution error (was unquoted
|
||||
`$(get_gitea_repo_args)`).
|
||||
- `test-issue-create-body-safety.sh` — **new** (#559 regression).
|
||||
- `test-gitea-login-resolution.sh` — extended (#560 diagnostic + both-host + override).
|
||||
|
||||
## Verification
|
||||
|
||||
All wrapper harnesses pass locally:
|
||||
|
||||
- `test-issue-create-body-safety.sh` — PASS
|
||||
- `test-gitea-login-resolution.sh` — PASS
|
||||
- `test-pr-merge-gitea-empty-uid.sh` — PASS
|
||||
- `test-pr-metadata-gitea.sh` — PASS
|
||||
- `test-lane-brief-pr-linkage.sh` — PASS
|
||||
|
||||
## Open items flagged to mos-claude (orchestrator decisions)
|
||||
|
||||
1. **CHANGELOG absent.** The task said "update CHANGELOG (append-only), keep the existing
|
||||
#550/#551 entry." No CHANGELOG file exists anywhere in the repo, and #550/#551 are not
|
||||
recorded in one. **ASSUMPTION:** documenting #559/#560 in this scratchpad + the PR
|
||||
description (`Closes #559 Closes #560`) follows the repo's actual convention
|
||||
(`docs/scratchpads/`). Did not invent a new CHANGELOG structure.
|
||||
2. **`docs/TASKS.md` is orchestrator single-writer.** It carries a "Workers read but never
|
||||
modify" banner. As a worker I did **not** edit it; task tracking is via the linked Gitea
|
||||
issues #559/#560 + this scratchpad. Orchestrator may add a rollup row if desired.
|
||||
3. **Wrapper `test-*.sh` are not CI-wired.** `.woodpecker/ci.yml` runs `pnpm
|
||||
typecheck/lint/format:check/test` (`turbo run test`); the framework dir has no
|
||||
`package.json`, so these shell harnesses run **locally/manually only** — they do not gate
|
||||
the PR in Woodpecker. **ASSUMPTION:** out of scope to wire a shell-test step into CI in
|
||||
this PR (would broaden the diff beyond the wrapper surface). Flagging for a follow-up if
|
||||
the fleet wants these gated.
|
||||
@@ -1,33 +0,0 @@
|
||||
# Issue #561 — Bare python on agent hosts
|
||||
|
||||
## Objective
|
||||
|
||||
Make the durable bootstrap/provisioning guidance ensure agent hosts provide a bare `python` command that resolves to Python 3.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add Debian/Ubuntu `python-is-python3` to agent-host prerequisites in bootstrap docs.
|
||||
- Check for actual OS package provisioning scripts and update only if an existing agent-host package install path exists.
|
||||
- Do not touch live host state.
|
||||
- Do not update `docs/TASKS.md`; repo guidance says workers read it but never modify it.
|
||||
|
||||
## Recon
|
||||
|
||||
- Issue #561 confirms repeated `python: command not found` failures from fleet agents that emit `python foo.py`.
|
||||
- `guides/BOOTSTRAP.md` and `packages/mosaic/framework/guides/BOOTSTRAP.md` are the source and packaged framework copies of the bootstrap guide.
|
||||
- Targeted repo sweep found no agent-host Debian package provisioning script. Existing `apt-get install` hits are CI/test helper paths or unrelated deployment docs.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add a host prerequisite section to both bootstrap guide copies.
|
||||
2. Include `python-is-python3` in the Debian/Ubuntu package list with an issue comment.
|
||||
3. Note the non-Debian equivalent as a `/usr/bin/python -> python3` symlink.
|
||||
4. Validate markdown/diff, run shell syntax checks where applicable, run required review, commit, queue guard, and push.
|
||||
|
||||
## Validation Log
|
||||
|
||||
- `rg` recon: no existing agent-host Debian package provisioning script; only CI/test helper `apt-get install` paths and unrelated deployment docs.
|
||||
- `git diff --check`: passed.
|
||||
- `bash -n packages/mosaic/framework/install.sh tools/install.sh packages/mosaic/framework/tools/bootstrap/init-project.sh packages/mosaic/framework/tools/_scripts/mosaic-bootstrap-repo`: passed. No touched shell scripts.
|
||||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted`: approved, 0 findings.
|
||||
- `pnpm format:check`: initially blocked because `node_modules` was absent and `prettier` was unavailable; `pnpm install --frozen-lockfile` initially hit an invalid `/root` pnpm store path. Reran install with `--store-dir /home/hermes/agent-work/.pnpm-store`, then `pnpm format:check` passed.
|
||||
@@ -1,32 +0,0 @@
|
||||
# #631 — re-seed must preserve user fleet data (CRITICAL data-loss)
|
||||
|
||||
- **Issue:** #631 · **Branch:** `fix/631-reseed-preserves-fleet-data`
|
||||
|
||||
## Root cause
|
||||
|
||||
`mosaic update` auto-runs `install.sh` keep-mode sync (#610). install.sh's rsync `--delete` (keep mode)
|
||||
honored PRESERVE_PATHS, but `fleet/` wasn't listed → the sync WIPED `~/.config/mosaic/fleet/roster.yaml`
|
||||
(+ run/, agents/). Any user running `mosaic update` lost their roster. (overwrite mode wipes by design;
|
||||
the live loss was keep mode.)
|
||||
|
||||
## Fix (PRIMARY)
|
||||
|
||||
- install.sh PRESERVE_PATHS += `fleet/*.yaml`, `fleet/agents`, `fleet/run` — the framework still SEEDS
|
||||
fleet/examples + fleet/roles + fleet/roster.schema.json (synced), but user files survive.
|
||||
- Made the cp-fallback (no-rsync) GLOB-AWARE so `fleet/*.yaml` preserves every user roster there too;
|
||||
fixed the restore to re-glob per-pattern (so only the user file is restored, not the whole fleet/ dir).
|
||||
- file-adapter.ts (TS installer): mirrored the preserve list for parity. (TS syncDirectory is copy-only,
|
||||
never --delete, so it never had the bug — belt-and-suspenders + parity.)
|
||||
|
||||
## Fix (SECONDARY)
|
||||
|
||||
- `refreshActiveFleetUnits()` (update-checker.ts): the re-seed updates ~/.config/mosaic/systemd/user but
|
||||
systemd runs ~/.config/systemd/user, so unit fixes (#627) didn't take effect. After the re-seed,
|
||||
`mosaic update` now copies the fresh mosaic-\*.service → the active dir + daemon-reload (best-effort,
|
||||
only when a fleet is already installed). Wired into the cli.ts update flow.
|
||||
|
||||
## Verification
|
||||
|
||||
- bash F6 fixture (6 checks: roster/custom-yaml/agents/run survive + examples refreshed + schema seeded);
|
||||
20/20 migration matrix green. TS file-adapter test (roster/run/agents survive keep sync). 2 unit tests
|
||||
for refreshActiveFleetUnits. tsc/eslint/prettier/sanitize clean.
|
||||
@@ -1,54 +0,0 @@
|
||||
# #633 — comms-block emitter + FLEET-LAUNCH runbook
|
||||
|
||||
Branch: `feat/633-comms-block-runbook` (off `bf2a6745`, post-#632 merge)
|
||||
Issue: #633 · Follow-up filed: #636 (PATH B)
|
||||
|
||||
## Goal
|
||||
|
||||
PATH A of the orchestrator-launch fix: give every launch path the Fleet-Comms onboarding, and
|
||||
document the canonical roster-driven launcher so the orchestrator stops being a bespoke snowflake.
|
||||
|
||||
## Deliverables
|
||||
|
||||
1. **`mosaic fleet comms-block <role> [--host <h>]`** — explicit-arg, comms-block-only emitter.
|
||||
- Backed by new `resolveCommsBlock(mosaicHome, role, fleetHost?)` in `fleet/comms-onboarding.ts`
|
||||
returning `{ ok, output, error }`.
|
||||
- Unlike `readFleetCommsBlock` (returns `''` on any miss so `composeContract` can no-op silently
|
||||
during launch), the emitter **fails loud**: unknown role / missing roster → `ok:false` → CLI
|
||||
prints to stderr + sets `process.exitCode = 1`. A typo is never a silent no-op.
|
||||
- Distinct from `mosaic compose-contract <runtime>` (whole prompt, env-coupled via
|
||||
`MOSAIC_AGENT_NAME`); comms-block is the targeted, explicit-arg, comms-only view.
|
||||
2. **`docs/fleet/FLEET-LAUNCH.md`** — worker path + orchestrator `.env` fold + 3 launch gotchas +
|
||||
#632 preserve note + North-Star 4-field arc.
|
||||
|
||||
## Key findings (drove the design)
|
||||
|
||||
- `mosaic yolo claude` **already** forwards `--channels`/`--permission-mode` to the binary
|
||||
(`launch.ts` claude case `cliArgs.push(...args)`) AND injects the comms block via
|
||||
`composeContract` → `readFleetCommsBlock(home, env.MOSAIC_AGENT_NAME)`. So no `launch.ts` change
|
||||
was needed — PATH A is `.env` + doc only.
|
||||
- `start-agent-session.sh` line ~41 `[ -z "$MOSAIC_AGENT_COMMAND" ]` short-circuits the line-44
|
||||
default, so an `.env` `MOSAIC_AGENT_COMMAND` override bypasses the hardcoded `yolo` entirely — the
|
||||
yolo-conditional is therefore a PATH B (default-path) concern, not PATH A.
|
||||
- `generateAgentEnv` (`fleet.ts` ~202-207) emits NAME/RUNTIME/MODEL but **not** `MOSAIC_AGENT_COMMAND`
|
||||
— the seam PATH B (#636) closes.
|
||||
|
||||
## A → B → webUI arc (North Star)
|
||||
|
||||
- A = `.env` `MOSAIC_AGENT_COMMAND` hatch (manual, ships now, #632-safe).
|
||||
- B (#636) = roster-native launch-config: harness ✅ + model ✅ already there; add **yolo** (line-44
|
||||
conditional `MOSAIC_AGENT_YOLO`) + **command/channels** (`generateAgentEnv` emission).
|
||||
- webUI binds dropdowns/toggles to those four roster fields. One launcher, no new launch path.
|
||||
|
||||
## Results
|
||||
|
||||
- TDD: spec first (`comms-onboarding.spec.ts`, 6 new `resolveCommsBlock` cases) → red → implement → green.
|
||||
- `fleet.spec.ts` subcommand-list assertion extended with `comms-block`.
|
||||
- 177 fleet+comms tests green; typecheck clean; eslint clean; prettier clean.
|
||||
|
||||
## Risks / notes
|
||||
|
||||
- Pre-existing local-only failure `uninstall.spec.ts > removeFramework > handles missing mosaicHome
|
||||
gracefully` (EACCES on `/nonexistent` as non-root) — unrelated to #633, passes in CI as root.
|
||||
- Did NOT run `mosaic update` / anything auto-reseed: installed CLI still 0.0.40 (roster-wipe live
|
||||
until mos-claude-0 ships 0.0.41). All work is in-repo + vitest, never touches the live mosaic home.
|
||||
@@ -1,25 +0,0 @@
|
||||
# Scratchpad — fleet-personas spec timeout
|
||||
|
||||
## Objective
|
||||
|
||||
Raise the `@mosaicstack/mosaic` Vitest timeout to 30s at config level so filesystem-backed fleet drift-guard specs (`fleet-personas`, `fleet-profiles`, and siblings) stop false-reding under contended CI.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Move timeout policy into `packages/mosaic/vitest.config.ts` with `testTimeout: 30_000`.
|
||||
2. Remove the narrower `fleet-personas.spec.ts` local override so PR #677 fixes the suite class, not one file.
|
||||
3. Run targeted fleet specs plus typecheck/lint/format gates.
|
||||
4. Commit, queue guard, push, PR update.
|
||||
|
||||
## Evidence
|
||||
|
||||
- `pnpm --filter @mosaicstack/mosaic test -- src/commands/fleet-personas.spec.ts` — pass (8 tests; initial narrow fix).
|
||||
- `pnpm typecheck` — pass (41 tasks; initial narrow fix).
|
||||
- `pnpm lint` — pass (23 tasks; initial narrow fix).
|
||||
- `pnpm format:check` — pass after formatting this scratchpad (initial narrow fix).
|
||||
- Package-wide timeout follow-up:
|
||||
- `pnpm --filter @mosaicstack/mosaic test -- src/commands/fleet-personas.spec.ts src/commands/fleet-profiles.spec.ts` — pass (24 tests).
|
||||
- `pnpm --filter @mosaicstack/mosaic test` — pass (44 files / 618 tests).
|
||||
- `pnpm typecheck` — pass (41 tasks).
|
||||
- `pnpm lint` — pass (23 tasks).
|
||||
- `pnpm format:check` — pass.
|
||||
@@ -1,49 +0,0 @@
|
||||
# #703 Git Wrapper Interactive and Auth Resilience
|
||||
|
||||
## Objective
|
||||
|
||||
Restore the deployed Git wrapper contract: issue-create supports interactive invocation and Gitea mutation behavior tolerates a stale Tea authenticated user by validating current identity and using the existing host-scoped API fallback.
|
||||
|
||||
## Scope
|
||||
|
||||
- `packages/mosaic/framework/tools/git/issue-create.sh`
|
||||
- `packages/mosaic/framework/tools/git/detect-platform.sh`
|
||||
- Git wrapper regression harnesses
|
||||
- This scratchpad
|
||||
|
||||
## Requirements / acceptance evidence
|
||||
|
||||
1. `issue-create -i` and `--interactive` prompt for missing issue fields without exposing credentials.
|
||||
2. Explicit command-line fields retain precedence and do not trigger prompt input.
|
||||
3. Gitea wrapper resolves the current user dynamically from the target host and does not rely on the saved Tea user identity.
|
||||
4. A Tea `GetUserByName` failure falls back to authenticated API creation.
|
||||
5. Existing body-safety, login-resolution, issue-create, and pr-create paths remain green.
|
||||
6. Source framework is re-seeded to deployed `~/.config/mosaic`, then deployed wrappers are verified end to end.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add failing shell regression harness for interactive input and stale Tea user fallback.
|
||||
2. Implement minimal helper and parser changes.
|
||||
3. Run wrapper harnesses, syntax checks, and repository baseline checks.
|
||||
4. Re-seed deployed framework and run live wrapper verification.
|
||||
5. Commit, queue guard, push, open PR, and stop for independent review.
|
||||
|
||||
## Progress
|
||||
|
||||
- Issue #703 filed before code; issue comment records #536 root cause and stale-login trigger.
|
||||
- Deployed wrapper `issue-create.sh -i` reproduced: `Unknown option: -i` (exit 1).
|
||||
- Live Tea mutation did not reproduce `GetUserByName` on this host because the current mosaicstack Tea login is valid. The test harness models the reported stale authenticated-user condition.
|
||||
- Implemented `-i` / `--interactive` prompt collection and a dynamic Tea `/user` validation. A stale Tea identity now selects the existing host-scoped Gitea API fallback before mutation for both issue and PR creation.
|
||||
- Re-seeded the framework with `MOSAIC_INSTALL_MODE=keep MOSAIC_SYNC_ONLY=1 bash packages/mosaic/framework/install.sh`. Installed and source wrapper SHA-256 values matched.
|
||||
- Live deployed verification: interactive issue-create opened then closed #704; installed dynamic identity resolved `jason.woltje`.
|
||||
|
||||
## Verification
|
||||
|
||||
- PASS: `packages/mosaic/framework/tools/git/test-issue-create-interactive-auth.sh`
|
||||
- PASS: `packages/mosaic/framework/tools/git/test-issue-create-body-safety.sh`
|
||||
- PASS: `packages/mosaic/framework/tools/git/test-gitea-login-resolution.sh`
|
||||
- PASS: `packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh`
|
||||
- PASS: `packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh`
|
||||
- PASS: `bash packages/mosaic/framework/tools/git/test-lane-brief-pr-linkage.sh`
|
||||
- PASS: `bash -n packages/mosaic/framework/tools/git/*.sh`
|
||||
- PASS: Prettier check for this scratchpad
|
||||
@@ -1,43 +0,0 @@
|
||||
# #747 — De-hardcode orchestrator and interaction agent names
|
||||
|
||||
## Objective
|
||||
|
||||
Replace branded Mos/Tess symbols, filenames, DI tokens, and error prose with role-neutral orchestrator/interaction vocabulary without changing env-driven runtime identity behavior. Add optional roster `alias` and `provider` fields and show aliases in `mosaic fleet ps` with name fallback.
|
||||
|
||||
## Scope and constraints
|
||||
|
||||
- Requirements: `/home/hermes/agent-work/reviews/747-wsa-dehardcode-brief.md`.
|
||||
- Branch: `feat/747-dehardcode-orchestrator-interaction-names` from `main` at `e72388b2`.
|
||||
- Keep `MOSAIC_AGENT_NAME` and `MOSAIC_ORCHESTRATOR_AGENT_NAME` unchanged.
|
||||
- Sample/test data may retain operator display names.
|
||||
- No behavior change beyond optional roster metadata and alias display.
|
||||
- Budget: no explicit cap; conservative mechanical-rename scope only.
|
||||
- TDD: optional and skipped because this is a mechanical rename with existing focused coverage; add focused alias/schema regression coverage before completion.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Rename coordination and durable-session files and symbols using canonical vocabulary.
|
||||
2. Scrub branded symbol names and error prose in the assigned source trees while preserving allowed sample data.
|
||||
3. Extend roster schema with optional `alias` and `provider`; update fleet roster typing/rendering and focused tests.
|
||||
4. Run grep-clean verification, build, typecheck, lint/format, focused coord/durable-session/fleet tests, and roster validation.
|
||||
5. Commit, queue-guard, push, open a Gitea PR closing #747, and report to the coordinator.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-07-13: Task resumed from coordinator brief; repository clean at `e72388b2`.
|
||||
- Renamed coordination and durable-session files, exports, gateway DI symbols, DTOs, services, repositories, and tests.
|
||||
- Replaced branded authority/error prose while preserving the existing `/api/coord/mos` compatibility route and env-variable identity inputs.
|
||||
- Added optional roster `alias`/`provider` support and alias-first `fleet ps` display with canonical-name fallback.
|
||||
|
||||
## Verification
|
||||
|
||||
- `pnpm typecheck`: passed (42 tasks).
|
||||
- `pnpm build`: passed (23 tasks).
|
||||
- `pnpm lint`: passed (23 tasks).
|
||||
- `pnpm format:check`: passed.
|
||||
- Coordination tests: 7 passed.
|
||||
- Agent durable-session/runtime tests: 23 passed.
|
||||
- Gateway coordination/durable-session/integration tests: 20 passed.
|
||||
- Full `fleet.spec.ts`: 192 passed, including alias/provider parsing and alias display.
|
||||
- JSON Schema 2020 validation: legacy minimal roster and extended alias/provider roster passed; `alias` and `provider` remain absent from `required`.
|
||||
- Grep verification: no branded symbol/type/file/DI names or error prose remain in assigned source trees; one allowed `Tess Owner` test-data display name remains.
|
||||
@@ -1,152 +0,0 @@
|
||||
# Issue #751 — Native Kanban/SOT canonical publication
|
||||
|
||||
## Objective
|
||||
|
||||
Publish the owner-ratified P0–P3 requirements, mission manifest, task decomposition, and frozen shared contracts before feature implementation.
|
||||
|
||||
## Authority and decisions
|
||||
|
||||
- Owner: Jason
|
||||
- Plan owner/orchestrator: web1 control plane; takeover by mosaic-100 during Claude quota outage
|
||||
- Tracking: Mosaic Stack issue #751
|
||||
- Foundation: current Stack main + Drizzle/PostgreSQL
|
||||
- Fixed invariants: PostgreSQL sole writable SOT; writes fail closed; exports never import; outage notes become attributable proposals; mechanical Coordinator has no scope/gate/certify/merge authority; Certifier has no merge authority.
|
||||
- Recovery posture only is configurable through Lite, Standard, and High-assurance profiles.
|
||||
|
||||
## Execution log
|
||||
|
||||
- 2026-07-14: Existing planner-sol canon remediation reviewed from staging. KCR-001–016 claimed resolved; static checks passed.
|
||||
- 2026-07-14: Independent GPT/Terra re-review dispatched to rev1.
|
||||
- 2026-07-14: Re-review returned NO-GO: proposal audit-event IDs were not workspace-bound, leaving attribution forgeable; formatter evidence was not reproducible. Focused remediation round 2 routed to planner-sol.
|
||||
- 2026-07-14: Remediation bound proposal audit links to `task_events(workspace_id,id)`, froze same-transaction semantic validation and negative tests, and made formatter/type/static checks reproducible.
|
||||
- 2026-07-14: Independent rev1 re-review returned GO with KCR-001–016 closed and no new blocker. Canon copied into the issue #751 publication worktree; feature implementation remains held until merge.
|
||||
- 2026-07-14: Independent publication validation returned FAIL on formatting/trailing whitespace, stale staging wording, ignored review evidence, and missing worktree dependencies. Bounded publication remediation routed to planner-sol; no runtime source change authorized.
|
||||
- 2026-07-14: Publication remediation installed locked dependencies outside the repository cache, fixed formatting and wording, and preserved docs-only scope. Independent gaterun revalidation returned PASS across staged scope, formatting, lint, typecheck, strict contract compile, links, rollups, review artifacts, and fixed invariants.
|
||||
- 2026-07-14: Ultron final gate returned GO with zero BLOCKER/HIGH findings; residual LOW items remain explicit implementation obligations.
|
||||
- 2026-07-14: First commit attempt was correctly blocked by the lint-staged hook because docs contract `.ts` files were outside TypeScript project-service scope. Added a strict no-emit workstream `tsconfig.json` with exact Drizzle declaration paths; targeted contract TSC, contract ESLint, format, full lint/typecheck, strictness, and docs-only scope independently passed.
|
||||
|
||||
## Verification evidence
|
||||
|
||||
- Initial review: `docs/reports/native-kanban-sot/canon-initial-review-no-go.md`
|
||||
- Final GO: `docs/reports/native-kanban-sot/canon-final-rereview-go.md`
|
||||
- Ultron GO: `docs/reports/native-kanban-sot/ultron-final-go.md`
|
||||
- Pending: PR gates, squash merge, terminal-green CI, and issue closure.
|
||||
|
||||
## Publication remediation session — planner-sol
|
||||
|
||||
**Assignment:** Remediate only issue #751 publication blockers from `/home/hermes/agent-work/reviews/751-kanban-canon-publication-validation.md`; no source, package, lock, provider, CI, build, deploy, commit, or push action.
|
||||
|
||||
**Plan:**
|
||||
|
||||
1. Install the locked pnpm dependencies without modifying package metadata.
|
||||
2. Replace only stale publication/staging wording while retaining the canon-merge and KBN prerequisite implementation hold.
|
||||
3. Format all changed candidate Markdown and contract TypeScript; remove trailing whitespace.
|
||||
4. Run worktree `format:check`, `lint`, `typecheck`, strict no-emit contract compilation, tracked/untracked whitespace checks, and static invariants.
|
||||
5. Verify package/lock/source paths are unchanged and append exact evidence here.
|
||||
|
||||
**Budget:** No explicit token cap; bounded docs-only remediation, no exploratory/runtime work.
|
||||
**TDD:** Not applicable—documentation/contract-publication formatting and wording only; strict/static validation is the primary gate.
|
||||
|
||||
## Publication remediation results
|
||||
|
||||
### Changes
|
||||
|
||||
- `docs/native-kanban-sot/INDEX.md`: replaced staging/pending-GO wording with current publication and independent-GO wording; retained the merge hold and dependency-ordered KBN prerequisite hold.
|
||||
- `docs/native-kanban-sot/TASKS.md`: replaced “Mos using this staging set” with “Mos / publication control plane”; made the post-merge KBN prerequisite hold explicit.
|
||||
- Formatted all changed candidate Markdown and four contract TypeScript files with current-worktree Prettier 3.8.1.
|
||||
- Removed trailing whitespace from candidate Markdown, including both linked review reports.
|
||||
- Preserved both review reports and their links; they remain ignored by `.gitignore:11` for coordinator force-tracking.
|
||||
|
||||
### Dependency installation
|
||||
|
||||
The first target-worktree install attempt used the environment's default root-owned pnpm store and failed without changing package metadata:
|
||||
|
||||
```text
|
||||
cd /home/hermes/agent-work/stack-kanban-canon && pnpm install --frozen-lockfile
|
||||
EACCES: permission denied, open '/root/.local/share/pnpm/store/v10/server/server.json'
|
||||
```
|
||||
|
||||
Successful locked install using an authorized cache outside the repository:
|
||||
|
||||
```bash
|
||||
cd /home/hermes/agent-work/stack-kanban-canon
|
||||
pnpm install --frozen-lockfile --store-dir /home/hermes/agent-work/pnpm-store
|
||||
```
|
||||
|
||||
Result: PASS, 1,240 packages installed; lockfile resolution skipped as up to date. `node_modules` remains ignored. Tool versions: pnpm 10.6.2, Prettier 3.8.1, TypeScript 5.9.3, Drizzle ORM 0.45.1, Turbo 2.8.16.
|
||||
|
||||
### Exact quality-gate results
|
||||
|
||||
```text
|
||||
pnpm format:check
|
||||
PASS — All matched files use Prettier code style.
|
||||
|
||||
pnpm lint
|
||||
PASS — 23 successful lint tasks.
|
||||
|
||||
pnpm typecheck
|
||||
PASS — 42 successful tasks. Turbo invoked configured dependency build prerequisites as part of the repository's exact typecheck graph; no standalone build command was run.
|
||||
```
|
||||
|
||||
Candidate formatting commands:
|
||||
|
||||
```bash
|
||||
pnpm exec prettier --write <3 tracked rollups + 9 native-kanban artifacts + requirements + scratchpad>
|
||||
pnpm exec prettier --check <same files>
|
||||
pnpm exec prettier --ignore-path /dev/null --write \
|
||||
docs/reports/native-kanban-sot/canon-initial-review-no-go.md \
|
||||
docs/reports/native-kanban-sot/canon-final-rereview-go.md
|
||||
pnpm exec prettier --ignore-path /dev/null --check \
|
||||
docs/reports/native-kanban-sot/canon-initial-review-no-go.md \
|
||||
docs/reports/native-kanban-sot/canon-final-rereview-go.md
|
||||
```
|
||||
|
||||
Result: PASS. The explicit `/dev/null` ignore path is required because `docs/reports/` is intentionally ignored pending coordinator force-tracking.
|
||||
|
||||
Tracked and untracked whitespace checks:
|
||||
|
||||
```text
|
||||
git diff --check
|
||||
PASS
|
||||
|
||||
git diff --no-index --check /dev/null <each untracked/ignored candidate>
|
||||
PASS for all candidates
|
||||
```
|
||||
|
||||
Strict contract compilation initially could not resolve pnpm-isolated `drizzle-orm` from the external docs directory. A temporary, removed dependency-context symlink made current-worktree resolution explicit:
|
||||
|
||||
```bash
|
||||
LINK=docs/native-kanban-sot/node_modules
|
||||
ln -s ../../packages/db/node_modules "$LINK"
|
||||
trap 'unlink "$LINK"' EXIT
|
||||
pnpm exec tsc \
|
||||
--noEmit \
|
||||
--strict \
|
||||
--skipLibCheck \
|
||||
--target ES2022 \
|
||||
--module NodeNext \
|
||||
--moduleResolution NodeNext \
|
||||
docs/native-kanban-sot/contracts/*.ts
|
||||
```
|
||||
|
||||
Result: `strict-contract-noemit=PASS`; temporary link removed.
|
||||
|
||||
Static result:
|
||||
|
||||
```text
|
||||
proposal-audit-links=PASS
|
||||
kcr-invariant-regression=PASS
|
||||
publication-wording=PASS
|
||||
vocabulary-alignment=PASS
|
||||
```
|
||||
|
||||
### Scope-integrity evidence
|
||||
|
||||
Baseline and final hashes are identical:
|
||||
|
||||
```text
|
||||
package.json 93a50eaefc7a0446a56234e427df03f6a2256f8da17c0bede17c22206928c8c0
|
||||
pnpm-lock.yaml 8b6448d51ac7797c8f782af52a080c0e38ab8bf364f32624f94e636bf5743229
|
||||
```
|
||||
|
||||
`tracked-package-lock-source-unchanged=PASS`: every tracked/untracked nonignored change remains under `docs/`; no package, lock, application source, plugin source, configuration, CI trigger, standalone build/deploy, container, provider, commit, or push action occurred.
|
||||
@@ -1,101 +0,0 @@
|
||||
# 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,148 +0,0 @@
|
||||
# Issue #755 — Logical Mos identity and connector lease fencing
|
||||
|
||||
- Task: `MOS-PORT-M1-001`
|
||||
- Branch: `feat/mos-logical-identity-fencing`
|
||||
- Base: `origin/main`
|
||||
- Started: 2026-07-14
|
||||
- Working budget: 38K tokens (task ledger estimate); one implementation lane, bounded to M1.
|
||||
|
||||
## Objective
|
||||
|
||||
Implement the first runtime-portability security boundary: normalized logical-agent identity plus a PostgreSQL-durable exclusive connector lease and server-validated fencing grants.
|
||||
|
||||
## Scope
|
||||
|
||||
- Normalized identity contract independent of harness/provider-native session IDs.
|
||||
- DB migration/schema/repository for one lease per tenant/logical-agent/binding.
|
||||
- CAS acquire/takeover, monotonic epoch, TTL, heartbeat, release, expiry handling.
|
||||
- Server-derived grants bound to tenant, logical agent, binding, connector, scopes, expiry, and lease epoch.
|
||||
- Reject and credential-safely audit stale, expired, forged, unauthorized, cross-tenant, and cross-binding grants before adapter side effects.
|
||||
- Runtime adapter boundary consumes normalized lease context.
|
||||
- Unit, migration, close/reopen, concurrency, abuse, and gateway integration tests.
|
||||
- Required developer/operations documentation for schema and security behavior.
|
||||
|
||||
## Explicit exclusions
|
||||
|
||||
No checkpoint/handoff payloads, exactly-once journal/receipts, concrete Claude/Pi/Codex harness adapter, channel cutover, or full cross-harness failover E2E.
|
||||
|
||||
## Reconciliation baseline
|
||||
|
||||
- Prospective remediation handoff: `web1:coder1`; PR [#757](https://git.mosaicstack.dev/mosaicstack/stack/pulls/757), issue [#755](https://git.mosaicstack.dev/mosaicstack/stack/issues/755).
|
||||
- Before rebase: `dff8ce4f79ef90370c29d925002118a708010091`; required base: `origin/main` at `2e2280070ae67288be45f41743cf67052a8ca5a6`; original branch base: `d0771835542deab048ad8e79f271e3abdb6151f7`.
|
||||
- Provider metadata: #757 is open, targets `main`, head is `feat/mos-logical-identity-fencing`, prior CI is green, and the provider reports it is not mergeable because of conflicts.
|
||||
- Affected delivery paths: `apps/gateway/src/agent/agent.module.ts`; connector-lease gateway repository/service and three focused tests; `packages/agent/src/connector-lease.ts` plus test/export; `packages/types/src/agent/connector-lease.dto.ts` plus test/export; `packages/db/src/schema.ts`, migration `0016_salty_morlocks.sql`, Drizzle snapshot/journal; `docs/PRD.md`, `docs/SITEMAP.md`, MOS architecture/operations pages, this scratchpad, and `docs/tess/TASKS.md`.
|
||||
- Read-only merge-tree inspection found only `docs/PRD.md` and `docs/SITEMAP.md` conflicts. Current-main #756 channel contracts, #758 roster-v2 structural compiler, and Native Kanban SOT use distinct contract domains; no substantive architecture collision was identified before mechanical reconciliation.
|
||||
- Reconciliation constraints: retain all current-main #752/#756/#758/KBN content; add only nonduplicative #755 references; do not alter semantics or conflate connector leases/grants with Kanban task leases/fences, local Fleet leases, auth sessions, ResetSession generations, or federation grants.
|
||||
|
||||
## Plan (TDD RED → GREEN → REFACTOR)
|
||||
|
||||
1. Map existing contracts, DB/migration conventions, gateway authorization/audit boundaries, and test infrastructure.
|
||||
2. Add failing contract/repository/concurrency/restart/abuse/gateway tests and capture RED evidence.
|
||||
3. Implement the smallest normalized contracts, schema/migration/repository, grant validator, audit sink, and gateway service/adapter boundary needed to pass.
|
||||
4. Refactor for clear invariants and credential-safe observability; rerun focused suites.
|
||||
5. Run package/repo typecheck, lint, format, and appropriate tests.
|
||||
6. Run independent code + security review, remediate, and re-review.
|
||||
7. Inspect the final diff for security/scope drift; commit; queue guard; push; open PR with `Refs #755` and exact verification; stop without merge/issue closure.
|
||||
|
||||
## Constraints and safety notes
|
||||
|
||||
- `docs/tess/TASKS.md` is orchestrator-only and will not be edited.
|
||||
- Existing dirty `.mosaic/orchestrator/mission.json` and `.mosaic/orchestrator/session.lock` are launcher/orchestrator state and will not be staged or altered intentionally.
|
||||
- No client-supplied identity may confer authority.
|
||||
- No credential, token, or raw grant material may be persisted to audit/log output.
|
||||
- Existing authorization checks remain intact; fencing is an additional fail-closed layer.
|
||||
|
||||
## Assumptions resolved from existing architecture
|
||||
|
||||
- `ASSUMPTION:` M1 exposes no public lease endpoint. The gateway service is an internal policy surface with deny-all default policy because concrete connector activation/cutover is explicitly deferred.
|
||||
- `ASSUMPTION:` Fencing epochs use PostgreSQL `bigint` and cross-module decimal strings, preserving JSON portability without JavaScript number precision loss.
|
||||
- `ASSUMPTION:` Process-local grant provenance intentionally fails closed across restart; durable lease/epoch state survives and fresh grants require current policy + lease validation.
|
||||
|
||||
## TDD evidence
|
||||
|
||||
RED observed before implementation:
|
||||
|
||||
- `corepack pnpm --filter @mosaicstack/types exec vitest run src/agent/connector-lease.dto.spec.ts` → failed to load missing `connector-lease.dto.js`.
|
||||
- `corepack pnpm --filter @mosaicstack/agent exec vitest run src/connector-lease.test.ts` → failed to load missing `connector-lease.js`.
|
||||
- Gateway focused tests failed before implementation because the new repository/service boundaries did not exist (workspace dependencies were then built before behavioral GREEN runs).
|
||||
|
||||
GREEN to date:
|
||||
|
||||
- Types contract: 6/6 passed.
|
||||
- Agent grant/fencing unit suite: 5/5 passed.
|
||||
- Gateway PGlite repository + policy/side-effect integration: 7/7 passed; 1 real-PostgreSQL test skipped when `DATABASE_URL` absent.
|
||||
- Real PostgreSQL focused run with configured `DATABASE_URL`: 1/1 passed (credential value not emitted in reports).
|
||||
|
||||
## Documentation checklist
|
||||
|
||||
- [x] `docs/PRD.md` contains current MOS-PORT M1 scope and acceptance criteria.
|
||||
- [x] Developer architecture: `docs/architecture/mos-runtime-portability-m1.md`.
|
||||
- [x] Admin/operations guidance: `docs/guides/mos-connector-lease-operations.md`.
|
||||
- [x] `docs/SITEMAP.md` links both pages.
|
||||
- [x] No user-guide change: M1 exposes no user-facing flow or channel cutover.
|
||||
- [x] No OpenAPI/endpoint-index change: M1 adds no HTTP endpoint.
|
||||
- [x] Migration/restart/rollback safety and credential-safe audit constraints documented.
|
||||
- [x] Canonical source remains in-repo; no external publishing action is in scope.
|
||||
- [x] Independent review confirms documentation matches implementation; implementation-specific findings were remediated.
|
||||
|
||||
## Independent review and remediation
|
||||
|
||||
Codex code/security review ran in multiple rounds. Findings and root-cause remediations:
|
||||
|
||||
1. Policy could not inspect requested scope/TTL → policy subject now receives normalized requested scopes and explicit requested TTL.
|
||||
2. Unbounded authority lifetime → hard defaults cap leases at 5 minutes and grants at 30 seconds; overrides may only tighten; over-limit tests added.
|
||||
3. Cross-tenant denial could audit under submitted tenant → mismatch audit uses authenticated tenant plus sanitized `untrusted` target metadata; integration assertion added.
|
||||
4. Malformed forged grant could break the denial/audit path → runtime-safe shape validation with sanitized fallback audit; malformed-input test added.
|
||||
5. Gateway integration test depended on prior test state → denial test now seeds a unique binding itself; isolated `-t` run passed.
|
||||
6. Reviewer repeatedly identified launcher-generated `.mosaic/orchestrator/*` state; those files remain unstaged and excluded from the implementation commit.
|
||||
|
||||
Latest independent security review: no critical/high/medium/low findings. Final commit-level code review remains to run after the intended diff is committed without launcher state.
|
||||
|
||||
## Verification evidence
|
||||
|
||||
- Focused contracts/fencing: types 6/6; agent 9/9.
|
||||
- Gateway focused PGlite repository/policy integration: 7/7; isolated denial test 1/1.
|
||||
- Real PostgreSQL close/reopen/CAS test: 1/1 with configured `DATABASE_URL`.
|
||||
- Root `corepack pnpm typecheck`: 42/42 Turbo tasks passed.
|
||||
- Root `corepack pnpm lint`: 23/23 Turbo tasks passed.
|
||||
- Root `corepack pnpm format:check`: all matched files passed.
|
||||
- Root `corepack pnpm test`: 42/42 Turbo tasks passed; gateway 616 passed / 12 environment-gated skipped; DB 19 passed / 7 environment-gated skipped; Mosaic 650 passed.
|
||||
|
||||
## Known residual risks
|
||||
|
||||
- Concrete connector policies and Claude/Pi/Codex adapters are intentionally deferred; production policy defaults deny-all.
|
||||
- Gateway pre-side-effect validation cannot make an external system exactly-once. Adapters must propagate/enforce the epoch at downstream effect boundaries; receipts/journaling are later #754 scope.
|
||||
- Migration rollback is additive-only; dropping lease/audit tables is intentionally manual to avoid destroying authority/audit evidence.
|
||||
|
||||
## Commit-level review remediation
|
||||
|
||||
- Commit-level Codex code review found one `should-fix`: heartbeat, release, and grant issuance authorized caller-supplied lease fields before canonical normalization.
|
||||
- TDD RED: the isolated gateway policy-boundary test showed mixed-case/padded logical agent, binding, connector, scope, and epoch values reaching policy unchanged.
|
||||
- Remediation: exported the coordinator's canonical lease normalizer and applied it at the gateway boundary before tenant/policy checks and coordinator dispatch for heartbeat, release, and grant issuance.
|
||||
- GREEN: isolated policy test 1/1; focused types 6/6, agent 9/9, gateway 8/8; root typecheck 42/42, lint 23/23, format check passed, and root tests 42/42 (gateway 617 passed / 12 environment-gated skipped).
|
||||
- Commit-level security review remained clean: no critical/high/medium/low findings.
|
||||
|
||||
## Durable grant-expiry review remediation
|
||||
|
||||
- Final commit review found a second `should-fix`: grant expiry was capped against submitted lease metadata after current-authority validation, rather than the durable lease row.
|
||||
- TDD RED: a crafted same-authority lease with a later submitted expiry produced a grant expiring after the durable row.
|
||||
- Remediation: grant authority fields and expiry now derive from the durable current lease; submitted scopes remain an additional narrowing constraint.
|
||||
- GREEN: focused agent fencing suite 10/10.
|
||||
|
||||
## Current-main reconciliation (2026-07-14)
|
||||
|
||||
- Rebased the existing PR branch from `dff8ce4f79ef90370c29d925002118a708010091` (old base `d0771835542deab048ad8e79f271e3abdb6151f7`) onto `origin/main` `2e2280070ae67288be45f41743cf67052a8ca5a6`; current uncommitted reconciliation head is `d190732a550918161b91d3eb54640f4ea0e2e499`.
|
||||
- Resolved only `docs/PRD.md` and `docs/SITEMAP.md`: preserved current-main #752 Native Kanban, #756 official-channel, and #758 FCM material; retained the nonduplicative #755 M1 workstream and placed its two documentation links in the existing Runtime-neutral Mos section. No #755 source semantics changed.
|
||||
- Compatibility review confirmed separate authority domains: connector lease/epoch/grant remains distinct from KBN task leases/fences, local Fleet roster lifecycle, auth sessions, ResetSession context, and federation grants. No channel cutover, adapter activation, checkpoint/exactly-once behavior, UI convergence, or #754 expansion was added.
|
||||
- Focused verification after building the required workspace dependencies: types contract 6/6; agent fencing/grant 10/10; gateway repository/PGlite and policy integration 8/8. The focused real-PostgreSQL test was skipped because `DATABASE_URL` was not configured; no credentials were inspected or emitted.
|
||||
- Generated schema check: `pnpm --filter @mosaicstack/db db:generate` reported no schema changes; migration `0016_salty_morlocks`, snapshot, and journal were unchanged by generation.
|
||||
- Full verification: `pnpm typecheck` 42/42; `pnpm lint` 23/23; `pnpm format:check` passed; `pnpm test` 42/42 (gateway 627 passed / 12 environment-gated skipped). Scoped diff check and local documentation-link scan passed.
|
||||
- Pending only: commit this reconciliation record, queue guard, force-with-lease push of the rebased existing branch, then fresh independent DB/code/security review and Ultron. Do not claim merge or issue closure.
|
||||
|
||||
## Durable lifecycle-authority remediation (2026-07-14)
|
||||
|
||||
- Independent review found that heartbeat and release authorized the submitted lease, allowing forged lifecycle scope data to influence policy before the durable row was consulted.
|
||||
- Remediation: lifecycle operations tenant-check the submitted lease, load the durable current lease, compare tenant, logical agent, binding, lease UUID, connector, epoch, and canonical ordered scopes, audit and deny any absent/mismatched authority, then run policy and coordinator lifecycle calls with the durable lease. Coordinator CAS/fencing checks remain unchanged.
|
||||
- Adversarial gateway integration coverage proves forged `tool.execute` scopes on a durable `runtime.send` lease deny before policy or mutation, preserve heartbeat/release state, and write a denial audit for both lifecycle actions; canonical heartbeat and release remain accepted.
|
||||
- Verification: focused types 6/6; agent 10/10; gateway PGlite integration/repository 9/9 with one `DATABASE_URL`-gated PostgreSQL test skipped; Drizzle check passed; root typecheck 42/42; lint 23/23; format check passed; root test 42/42 (gateway 628 passed / 12 environment-gated skipped).
|
||||
- Pending: commit, queue-guard, force-with-lease push, then independent DB/code/security rereview and CI. Do not merge or close #755.
|
||||
@@ -1,57 +0,0 @@
|
||||
# Scratchpad — #756 Official Discord channel plugin
|
||||
|
||||
- **Task / issue:** Official Discord channel plugin / #756
|
||||
- **Branch:** `feat/756-official-discord-plugin`
|
||||
- **Worktree:** `/home/hermes/agent-work/stack-discord-plugin`
|
||||
- **Base:** `origin/main` at `49e8a54105eddf41e8e0e44603ded616ee76044f`
|
||||
- **Objective:** Deliver harness-neutral Discord routing, native mention-to-thread behavior, untagged in-channel interaction, fail-closed channel/user authorization, and transport-neutral contracts for future official channel plugins.
|
||||
- **Collision boundary:** Do not modify orchestrator-to-Pi migration, logical-agent lease/fencing (#754/#755), runtime provider implementations, or orchestrator-owned `docs/TASKS.md`.
|
||||
- **Working budget:** 55K tokens for requirements, implementation, tests, documentation, independent review, and delivery. No user-specified hard cap. Reduce optional refactoring before reducing acceptance coverage.
|
||||
|
||||
## Assumptions
|
||||
|
||||
1. **ASSUMPTION:** Every configured Discord channel is intentionally agent-bound, so an authorized human's untagged message is agent input and receives an in-channel response. Rationale: this satisfies the requested no-tag behavior without activating the bot in arbitrary channels.
|
||||
2. **ASSUMPTION:** Mentioning the bot in a parent channel creates or reuses a public Discord thread; messages already in a thread remain in that thread without repeated mentions. Rationale: Discord does not support nested threads and the request describes tags as the thread-selection signal.
|
||||
3. **ASSUMPTION:** One bot process may host multiple configured channel-to-logical-agent bindings. Rationale: bindings are already configuration-owned and this avoids per-agent Discord credentials.
|
||||
4. **ASSUMPTION:** Static guild/channel/user allowlists and paired-user roles remain the administration surface for this slice. Rationale: dynamic admin UI is larger and can be added without changing adapter contracts.
|
||||
5. **ASSUMPTION:** The stable conversation handle contains logical agent plus Discord channel/thread identity and never a harness/provider identifier. Rationale: runtime re-enrollment and the active lease work can change Claude/Codex/Pi/OpenCode behind the same channel connection.
|
||||
6. **ASSUMPTION:** Canonical documentation remains in-repository for this slice; no external publishing is performed.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Update `docs/PRD.md` before code with #756 scope, constraints, assumptions, and acceptance criteria.
|
||||
2. Add failing Discord behavior and authorization tests first.
|
||||
3. Add transport-neutral channel DTO/contracts in `@mosaicstack/types`.
|
||||
4. Implement mention-to-thread, untagged in-channel, existing-thread, stable conversation, and adapter health behavior without runtime-specific imports.
|
||||
5. Update admin/developer/channel protocol docs and documentation checklist.
|
||||
6. Run focused tests, typecheck, lint, formatting, full applicable baseline, and coverage.
|
||||
7. Run independent code and security review; remediate and re-review.
|
||||
8. Commit, queue-guard, push, open PR to `main`, wait for green CI, squash merge, verify merged CI, and close #756.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-07-14: Loaded mission state (none active), global/project guidance, current `origin/main`, existing Discord/Tess/fleet connector architecture, issue #709 history, and active portability issues #754/#755.
|
||||
- 2026-07-14: Created issue #756 through the Mosaic wrapper.
|
||||
- 2026-07-14: Created isolated worktree/branch from current `origin/main`; the stale root checkout and unrelated QA artifacts remain untouched.
|
||||
|
||||
## TDD decision
|
||||
|
||||
Required and applied. This change modifies authorization-sensitive remote ingress and routing behavior. Failing permission and routing tests will be captured before implementation.
|
||||
|
||||
## Risks / blockers
|
||||
|
||||
- Active logical-agent lease work may later add stronger fencing fields. This slice must expose a clean, harness-neutral seam without duplicating that schema.
|
||||
- Discord thread creation is an external side effect. Unit tests use a typed fake; live credential smoke testing is out of scope and must not use committed secrets.
|
||||
- Repository-wide checks may expose unrelated baseline debt; changed-scope evidence and CI remain mandatory.
|
||||
|
||||
## Verification evidence
|
||||
|
||||
- `pnpm format:check` — passed.
|
||||
- `git diff --check` — passed.
|
||||
- `pnpm typecheck` — passed (42 Turbo tasks).
|
||||
- `pnpm lint` — passed (23 Turbo tasks).
|
||||
- `pnpm build` — passed (23 Turbo tasks).
|
||||
- `pnpm --filter @mosaicstack/discord-plugin test` — passed: 44 tests; V8 coverage 92.18% statements/lines, 86.55% branches, 100% functions (all configured thresholds ≥85%).
|
||||
- Focused gateway verification passed: Discord ingress/security, cross-surface, ownership, redaction/concurrency, and agent attachment tests.
|
||||
- `pnpm test` — changed-scope suites passed; repository baseline remains blocked by `apps/gateway/src/__tests__/cross-user-isolation.test.ts` requiring PostgreSQL at localhost port 5433 (`ECONNREFUSED`). The failure is unrelated to this change.
|
||||
- Independent code/security re-reviews requested after final remediation; reports are stored under ignored `docs/reports/` evidence paths.
|
||||
@@ -1,148 +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.
|
||||
|
||||
### Post-PR fail-closed remediation
|
||||
|
||||
Independent rereview found resolver fail-open edges that the original green PR head did not cover. The
|
||||
remediation remained uncommitted until every finding was reproduced red-first and the same reviewer
|
||||
approved the complete two-file delta.
|
||||
|
||||
Final regression evidence:
|
||||
|
||||
```text
|
||||
persona resolver: 47/47
|
||||
focused affected suites: 6 files / 138 tests
|
||||
root-container resolver suites: 86/86
|
||||
full canonical run: 42/42 Turbo tasks; Mosaic 50 files / 733 tests
|
||||
```
|
||||
|
||||
DB migration, typecheck, lint, Prettier, and `git diff --check` also passed. Coverage now proves:
|
||||
|
||||
- unreadable, unscannable, direct-dangling, ancestor-dangling, and literal `..` traversal override paths
|
||||
fail closed across async, sync, listing, and status APIs;
|
||||
- genuinely missing override directories still permit baseline fallback;
|
||||
- cached missing scans are revalidated before fallback;
|
||||
- marker-defined identity and domain metadata are revalidated on the second read;
|
||||
- `LIBRARY.md` rows and incidental later markers cannot define, shadow, or advertise personas.
|
||||
|
||||
Exact-head pipeline `1819` passed for rebased head `4d990eee…`, but the independent reviewer-of-record
|
||||
returned **REQUEST CHANGES** after reproducing three additional edge failures: a canonical filename could
|
||||
inherit protected authority despite a conflicting explicit first marker, cached `scanned` absence could
|
||||
miss an override created before baseline fallback, and inherited plain-object names such as `constructor`
|
||||
could corrupt alias/authority lookup. Merge remained held.
|
||||
|
||||
Each failure was reproduced red-first in the persona suite (4 failing assertions), then remediated without
|
||||
expanding card scope. Explicit first markers now own identity and filename fallback applies only to
|
||||
markerless contracts; every second read rejects a newly introduced conflicting marker regardless of
|
||||
cached classification; cached async resolution re-scans the override layer immediately before every
|
||||
baseline fallback; alias and authority registries require own-property matches. Current uncommitted
|
||||
evidence is persona **52/52**, focused affected suites **6 files / 143 tests**, and full Mosaic package
|
||||
**50 files / 738 tests**, plus typecheck, lint, Prettier, and `git diff --check`. Independent
|
||||
finding-specific rereview **APPROVED** the complete uncommitted three-file remediation after direct
|
||||
adversarial reproduction of all three findings and the follow-up markerless TOCTOU. All post-commit
|
||||
exact-head gates remain required.
|
||||
|
||||
## 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.
|
||||
@@ -1,37 +0,0 @@
|
||||
# FCM-M1-003 — Executable example/profile/service-preset dispositions
|
||||
|
||||
- **Task / issue:** FCM-M1-003 / #758
|
||||
- **Branch / base:** `test/758-example-profile-dispositions` from `origin/main` `a5e8e554012f27898e035d2882a8e47e1a02fe97`
|
||||
- **Objective:** Make every artifact in the M0 legacy disposition inventory executable evidence: it must validate canonically, be explicitly retained as a v1 fixture, or be retired with a replacement/deprecation link.
|
||||
- **Scope:** Validation and explicit version/retirement metadata only for shipped examples, profiles, and the operator-interaction service preset. Reuse the central resolver and existing v2 roster compiler.
|
||||
- **Out of scope:** Generated environment boundaries, CRUD, reconciliation/apply, migration, live fleet mutation, and `docs/TASKS.md`.
|
||||
- **Budget:** 20K card allocation; use focused package tests before full package validation.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Inventory exact shipped artifacts and existing compiler/resolver/profile tests.
|
||||
2. Add failing behavior tests covering all listed artifacts and their documented disposition.
|
||||
3. Implement minimal declarative fixture/disposition validation; do not add a role/class resolver.
|
||||
4. Run focused and package quality gates; obtain independent code and security review.
|
||||
5. Commit, queue-guard, push, open one `main` PR with `Refs #758`.
|
||||
|
||||
## Progress
|
||||
|
||||
- Intake complete: verified no branch, worktree, or open PR for this card before creating this isolated worktree.
|
||||
- Requirements read: FCM PRD, FCM-M1-003 task row, M0 disposition inventory, delivery/QA/documentation guides.
|
||||
- TDD: RED recorded with `pnpm --filter @mosaicstack/mosaic test -- example-profile-dispositions.spec.ts` failing because the new module did not exist; GREEN recorded after the minimal guard implementation. The focused suite now has 4 passing tests, including undeclared-artifact and missing-explicit-v1-version denials.
|
||||
- Independent review: initial code review found the service policy path was hardcoded; remediation iterates declared `canonical-service-policy` artifacts. Exact-head code review approved and exact-head security review found no issues.
|
||||
|
||||
## Risks / decisions
|
||||
|
||||
- The M0 inventory permits unresolved legacy roles only when explicitly v1-versioned or retired. Do not infer aliases beyond the three approved by FCM-M1-002.
|
||||
- `docs/TASKS.md` is orchestrator-owned and will not be edited.
|
||||
|
||||
## Verification evidence
|
||||
|
||||
- Focused TDD guard: `pnpm --filter @mosaicstack/mosaic test -- example-profile-dispositions.spec.ts` — PASS (4 tests).
|
||||
- Full package suite: `pnpm --filter @mosaicstack/mosaic test` — PASS (51 files, 742 tests).
|
||||
- Static gates: `pnpm --filter @mosaicstack/mosaic typecheck`, `pnpm --filter @mosaicstack/mosaic lint`, and `pnpm format:check` — PASS.
|
||||
- Diff gate: `git diff --check` — PASS.
|
||||
- Exact-head reviews: `codex-code-review.sh --uncommitted` — APPROVE; `codex-security-review.sh --uncommitted` — no findings.
|
||||
- Delivery: committed as `9a9ad1a`, pushed after `ci-queue-wait.sh --purpose push`, and opened PR [#770](https://git.mosaicstack.dev/mosaicstack/stack/pulls/770) to `main` with `Refs #758`. `pr-ci-wait.sh -n 770` reported terminal-green Woodpecker pipeline [#1823](https://ci.mosaicstack.dev/repos/47/pipeline/1823/1).
|
||||
@@ -1,46 +0,0 @@
|
||||
# FCM-M2-002 — Generation-Guarded Fleet Agent CRUD
|
||||
|
||||
- **Task / issue:** FCM-M2-002 / #758
|
||||
- **Branch / base:** `feat/758-fleet-agent-crud` from `origin/main` `191efaefeb5c0c6bb218c1292d12ce8e73ace12b`
|
||||
- **Budget:** 30K card allocation; no deployment or live-fleet actions.
|
||||
|
||||
## Objective
|
||||
|
||||
Provide local roster-owned create, get, update, and delete mutations with a generation precondition, deterministic dry-run plan, complete-state structural/semantic/projection validation before writes, atomic roster persistence, and redacted recovery output on a late projection failure.
|
||||
|
||||
## Scope and exclusions
|
||||
|
||||
- Roster v2 is the sole desired-state authority. Reuse `parseRosterV2`, `renderRosterV2Yaml`, `validateRosterV2Semantics`, and the generated-environment boundary.
|
||||
- Fresh create defaults to `enabled: true` and `desired_state: stopped`; this card never starts a runtime.
|
||||
- Excluded: reconcile/apply; lifecycle/session/systemd/tmux actions; migration/canary; remote/connector/gateway mutation; arbitrary commands/channels/secrets; generated files as authority; `docs/TASKS.md` and orchestration ledger changes.
|
||||
|
||||
## Red-first plan
|
||||
|
||||
1. Add failing tests for dry-run non-mutation, stale generation, concurrent writer locking, stopped default create, equivalent idempotency, complete proposed-state semantic/boundary validation, atomic roster write, and injected late projection failure with redacted recovery details.
|
||||
2. Implement only a roster-v2 CRUD service and file adapter; no legacy `fleet add/remove` behavior expansion.
|
||||
3. Add operator/reference docs for JSON outcomes, generation retries, recovery, and no-runtime-action boundary.
|
||||
|
||||
## Progress
|
||||
|
||||
- Preflight: clean exact base and no duplicate PR confirmed.
|
||||
- Intake read: FCM PRD/AC-FCM-03, task row, launch and generated-env boundaries, roster v2/resolver contracts, legacy fleet command behavior, delivery/QA/TypeScript/security/documentation guidance.
|
||||
- TDD: RED observed for the missing CRUD module. GREEN: focused suite passes 7 tests covering stopped-default create, stale generation, idempotency, dry-run non-mutation, concurrent lock denial, exact stale/absent generated-projection delete cleanup, and redacted late-projection recovery.
|
||||
- REVIEW-1 remediation: RED observed for absent CLI create/get/update/delete/plan wiring. Added roster-v2-only JSON commands, including safe `get`, read-only planning/dry-run, explicit persisted-start recording (never runtime start), stable handled error codes, and focused CLI coverage.
|
||||
- REVIEW-2 remediation: RED observed for missing direct fleet-control-plane registration and ambiguous partial late-I/O result. The public surface is now direct `mosaic fleet {create,get,update,delete,plan}` (not root gateway `mosaic agent`); a late filesystem projection failure returns non-zero redacted JSON with `authoritativeRoster: committed` and `projections: incomplete`, proving no rollback/no-op claim.
|
||||
- REVIEW-3 remediation: RED observed for unnamed update/delete plans and deleted-agent quarantine conflict. `plan <operation> [name]` now requires target names only for update/delete; delete validates/removes only exact generated state while retaining local/legacy/quarantine/unrelated files. Actual CLI/filesystem tests cover create/update/delete plans, plan validation/non-mutation, retained artifacts/dry-run bytes, unsafe permission/symlink rejection, and post-roster delete recovery. Added the required operator how-to.
|
||||
- REVIEW-4 remediation: RED observed that actual Commander create accepted and silently dropped disallowed `command`, `channel`, and `secretRef` keys. The `--agent` object and nested `launch` now use strict own-property allowlists; non-plain/prototype-sensitive shapes and unknown keys fail `invalid-request` before resolver, roster, or projection mutation. Actual Commander plan/create/update tests cover top-level command/channel/secretRef/constructor/prototype/`__proto__` shapes and nested launch unknown fields, byte-identical retained artifacts, non-zero exit, and diagnostics that never echo rejected values. Docs state the same boundary.
|
||||
|
||||
## Risks / assumptions
|
||||
|
||||
- **ASSUMPTION:** M2 mutations operate exclusively on the existing v2 roster contract because generation/lifecycle fields are v2-only; legacy v1 add/remove commands remain unchanged compatibility paths.
|
||||
- A multi-file roster/projection write cannot be one filesystem rename. The roster is authoritative; a post-roster projection failure returns a redacted recovery plan naming only safe paths/actions, never environment values.
|
||||
|
||||
## Verification evidence
|
||||
|
||||
- `pnpm --filter @mosaicstack/mosaic test -- fleet-agent-crud-command.spec.ts fleet-agent-crud.spec.ts generated-env-boundary.spec.ts` — PASS (48 tests after REVIEW-4 remediation).
|
||||
- `pnpm --filter @mosaicstack/mosaic test` — PASS (54 files, 794 tests after REVIEW-4 remediation).
|
||||
- `pnpm --filter @mosaicstack/mosaic lint` — PASS.
|
||||
- `pnpm --filter @mosaicstack/mosaic typecheck` — PASS.
|
||||
- `pnpm format:check` and `git diff --check` — PASS.
|
||||
- Root `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, and `git diff --check` — PASS after REVIEW-4 remediation; full package test is 54 files / 794 tests.
|
||||
- REVIEW-4 remediation focused checks are green; fresh full-delta independent review is required before author-green. No commit, push, or PR opened.
|
||||
@@ -1,39 +0,0 @@
|
||||
# FCM-M3-001 — Local roster-owned reconciliation and lifecycle
|
||||
|
||||
- **Task / issue:** FCM-M3-001 / #758
|
||||
- **Branch / base:** `feat/758-local-reconciler` from `origin/main` `bc5e73629e92c56a80fa6a769ebad17c0177f504`
|
||||
- **Base tree:** `1b9ebe4fa1a90734b6f81118e120bae5290cd350`
|
||||
- **Scope:** source, isolated fake-adapter tests, and card documentation only. No live fleet/systemd/tmux action.
|
||||
|
||||
## Objective
|
||||
|
||||
Provide local roster-v2 `apply`/`reconcile` and lifecycle/status contracts. The roster remains desired-state authority; projections and runtime observations are derived state.
|
||||
|
||||
## Red-first evidence
|
||||
|
||||
The initial focused reconciler test failed because `fleet-reconciler.ts` did not exist. The initial new-worktree test invocation also exposed absent dependencies; `pnpm install --frozen-lockfile --store-dir /home/jarvis/.local/share/pnpm/store` restored local workspace dependencies without changing source.
|
||||
|
||||
## Design
|
||||
|
||||
- A new `fleet-reconciler.ts` accepts only typed roster-v2 input plus injected command and projection adapters.
|
||||
- It targets only exact `mosaic-agent@<roster-name>.service` units and the exact configured tmux socket/session.
|
||||
- It classifies unowned/unmanaged state and fails mutation closed rather than adopting or killing it.
|
||||
- It validates the private install-derived holder identity and complete expected tmux global environment before mutating lifecycle state.
|
||||
- REVIEW-1 remediation: RED review evidence found service-level apply could omit generation and had no mutation lock. Every non-observational command now requires an expected generation; a private exclusive roster-adjacent lock is acquired before effects and released on success or partial failure. Tests cover missing/stale values, concurrent denial, no effects, release, and lock-free observation.
|
||||
- REVIEW-2 remediation: lock acquisition now validates private real `MOSAIC_HOME`/`fleet` ancestors, rejects symlink or unsafe leaves, distinguishes `EEXIST` concurrency from other I/O, and binds release to the created inode plus random ownership token. A replacement lock is retained and reported, not unlinked. A crash may leave a stale lock for inspection; no stale-lock break is claimed.
|
||||
- REVIEW-3 remediation: a lock cleanup failure now adds bounded `cleanup` diagnostics to a known successful or partial effect result without replacing its projection/lifecycle/recovery truth. Cleanup is not claimed as complete, and the retained lock requires inspection before retry.
|
||||
- REVIEW-4 remediation: command JSON with an additive cleanup diagnostic now exits non-zero even where known effects completed; clean effect and observational JSON remain zero-exit.
|
||||
- REVIEW-5 remediation: mutating operations acquire the private lock before rereading canonical `roster.yaml`; the fenced reread, not a caller snapshot, supplies generation validation, plan, projection, and lifecycle authority.
|
||||
- `apply` starts only enabled agents whose persisted desired state is `running`; stopped/default agents are never started by reconciliation.
|
||||
- Observational commands produce JSON classification only. Partial projection or lifecycle effects report explicit recovery without values.
|
||||
|
||||
## Boundaries
|
||||
|
||||
Excluded: live host actions, remote/SSH/connector lifecycle mutation, migrations, canaries, deployment, gateway changes, arbitrary command/channel/secret inputs, `docs/TASKS.md`, and orchestration ledgers.
|
||||
|
||||
## Verification
|
||||
|
||||
- Focused reconciler/Commander/CRUD/fleet tests: 4 files / 229 tests passed.
|
||||
- Full `@mosaicstack/mosaic` suite: 56 files / 820 tests passed after REVIEW-5 canonical roster fencing remediation.
|
||||
- Package and root typecheck/lint, root format check, and `git diff --check`: passed.
|
||||
- Isolated launcher and systemd template harnesses passed; they use fixtures only. No live fleet, systemd, tmux, session, remote, connector, or runtime action occurred.
|
||||
@@ -1,84 +0,0 @@
|
||||
# FCM-M3-002 — Reconciler lifecycle acceptance gates
|
||||
|
||||
- **Task / issue:** FCM-M3-002 / mosaicstack/stack#758
|
||||
- **Branch:** `test/758-reconciler-lifecycle-gates`
|
||||
- **Required starting head:** `499090508ef1d768660e4d54e7934cbcf13cb1cd`
|
||||
- **Required starting tree:** `2f1bb7fed48291f3f7ba8b21c2b52491aa14fe2b`
|
||||
- **Scope:** isolated acceptance coverage and card-required evidence/tracking only; no live fleet, systemd, tmux, session, site, migration, canary, deployment, runtime, connector, or remote action.
|
||||
- **Budget:** use the task estimate of 25K as the working cap; keep the delta to one coherent acceptance suite plus required task/scratchpad evidence. No production change unless a failing reproducer proves an in-scope defect.
|
||||
|
||||
## Intake evidence
|
||||
|
||||
- Clean exact local branch/head/tree verified before editing.
|
||||
- `origin/test/758-reconciler-lifecycle-gates` fetched and verified at the same required head.
|
||||
- The Mosaic PR wrapper reported no open pull requests, so no open-PR branch collision exists.
|
||||
- Parent issue #758 is open and remains intentionally open through M5.
|
||||
- Requirements loaded from `docs/PRD.md` FCM requirements and `AC-FCM-05`, `docs/TASKS.md` FCM DAG, the M3 rows in `docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md`, and the FCM-M3-001 implementation scratchpad.
|
||||
|
||||
## Objective
|
||||
|
||||
Add broad, behavior-oriented acceptance evidence around the shipped local reconciler contracts. Exercise only injected fake systemd/tmux adapters and temporary filesystem fixtures. Prove exact ownership/targeting, persisted stopped-state safety, truthful partial-failure recovery, rollback behavior, and stable command JSON/exit outcomes without touching live services or sessions.
|
||||
|
||||
## Acceptance mapping and evidence
|
||||
|
||||
| FCM-M3-002 acceptance concern | Delivered isolated evidence |
|
||||
| --- | --- |
|
||||
| Systemd/tmux lifecycle | `fleet-reconciler.acceptance.spec.ts` drives apply, reconcile, stop, restart, status, and recovery reconcile through one stateful injected fake host. The fake models exact systemd effects and tmux session observations; no host commands run. |
|
||||
| Drift | Canonical roster-v2 YAML drives the Commander `fleet status` boundary and classifies `missing-session`, `unexpected-session`, and `disabled-running`, including combined drift, while asserting observation emits no lifecycle mutation. |
|
||||
| Exact default/named socket targeting | Canonical v2 requires an explicit non-empty named socket; the parser rejects missing/empty values and the Commander acceptance path asserts exact `-L mosaic-fleet` targeting. A separate canonical legacy-v1 roster loader plus runtime-transport path proves a socket-less compatibility roster targets the literal tmux default server with no `-L`. No unreachable empty-socket v2 fixture is used. |
|
||||
| Unmanaged-session classification | Stateful fixtures report sorted `coder0-shadow`/`unmanaged` sessions, then prove an exact roster stop leaves both sessions and the near-collision service intact. |
|
||||
| Crash/partial failure | Injected restart failure is applied after the fake effect to model crash/partial truth: result is `lifecycle: incomplete`, the roster is unchanged, and observed runtime may be active. |
|
||||
| Rollback/recovery semantics | M3 has no rollback command and explicitly does not claim automatic rollback. The acceptance workflow proves the bounded recovery contract: inspect, then exact reconcile restores the persisted stopped target without a start or fuzzy effect. M4 migration/canary rollback remains outside this card. |
|
||||
| Stopped-state preservation | Stateful apply and reconcile both stop an initially running observed agent whose persisted target is stopped; failed explicit restart leaves desired state stopped; recovery reconcile restores stopped state. No start call is emitted. |
|
||||
| Zero fuzzy destructive targeting | Near-collision `coder0-shadow` service/session plus `unmanaged` session remain untouched. The recorded destructive calls contain only exact `[email protected]`; no tmux kill action is emitted. |
|
||||
| Stable JSON/exit behavior | Temporary canonical roster fixture invokes the CLI boundary and asserts exactly one JSON line, exact partial-result shape, and exit code 1. Existing focused command specs continue to cover clean zero-exit and stable error JSON. |
|
||||
| Redacted truthful recovery | Fake stderr includes `PASSWORD=acceptance-secret`; exact CLI JSON contains only bounded recovery metadata and excludes the key, value, and raw diagnostic. |
|
||||
|
||||
## Plan
|
||||
|
||||
1. Inventory existing reconciler and command specs against the table above; avoid duplicating narrow assertions already present.
|
||||
2. Add one acceptance-level spec using only fake/injected adapters and temporary files.
|
||||
3. If a real defect is exposed, preserve the failing reproducer and make only the smallest FCM-M3-002-required fix; otherwise leave production unchanged.
|
||||
4. Reconcile `docs/TASKS.md` only for delivered M1/M2/M3-001 truth and mark FCM-M3-002 in progress.
|
||||
5. Run focused tests, full `@mosaicstack/mosaic` tests, package/root typecheck and lint, Prettier/format and diff checks, plus adversarial fake-runner cases.
|
||||
6. Record exact evidence and leave the tree uncommitted for independent synthetic-tree review.
|
||||
|
||||
## TDD decision
|
||||
|
||||
This card adds acceptance coverage to already-delivered behavior. Test-first applies to any product defect discovered: retain a failing reproducer before an in-scope fix. If the shipped behavior already satisfies the acceptance contract, no production code will be changed and the acceptance suite itself is the deliverable.
|
||||
|
||||
## Progress
|
||||
|
||||
- Intake and immutable baseline verification complete.
|
||||
- Existing coverage inventory confirmed strong unit coverage but no stateful cross-command lifecycle acceptance harness.
|
||||
- Added `packages/mosaic/src/fleet/fleet-reconciler.acceptance.spec.ts`: one injected stateful fake systemd/tmux host, temporary canonical v2 and legacy-v1 roster fixtures, and seven acceptance tests.
|
||||
- Production source is unchanged; no product defect requiring an FCM-M3-002 fix was found.
|
||||
- `docs/TASKS.md` reconciles only merged M1/M2/M3-001 truth and marks FCM-M3-002 in progress.
|
||||
|
||||
## Verification evidence
|
||||
|
||||
All commands ran from `/home/jarvis/src/mosaic-stack-local-reconciler` and passed unless explicitly noted.
|
||||
|
||||
- `pnpm --filter @mosaicstack/mosaic exec vitest run src/fleet/fleet-reconciler.acceptance.spec.ts` — final remediation run: 1 file, 7 tests passed; canonical v2 named-socket parsing/Commander status, missing/empty v2 rejection, and canonical legacy-v1 default-server runtime targeting are distinct reachable cases.
|
||||
- Focused reconciler/roster/transport command covering acceptance, reconciler, command, CRUD, v2 parser, and runtime transport specs — 8 files, 304 tests passed.
|
||||
- `pnpm --filter @mosaicstack/mosaic test` — final remediation run: 57 files, 827 tests passed.
|
||||
- `pnpm --filter @mosaicstack/mosaic typecheck` — passed.
|
||||
- `pnpm --filter @mosaicstack/mosaic lint` — passed.
|
||||
- `pnpm typecheck` — 42/42 Turbo tasks successful.
|
||||
- `pnpm lint` — 23/23 Turbo tasks successful.
|
||||
- `pnpm exec prettier --check docs/TASKS.md docs/scratchpads/758-fcm-m3-002-reconciler-lifecycle-gates.md packages/mosaic/src/fleet/fleet-reconciler.acceptance.spec.ts` — passed.
|
||||
- `pnpm format:check` — all matched files use Prettier style.
|
||||
- `git diff --check` — passed with no output.
|
||||
- Initial scoped Prettier check found style drift in the new spec and tracking table; `pnpm exec prettier --write ...` remediated it before all final gates above.
|
||||
- No live fleet, systemctl, tmux, process, site, migration, canary, deploy, runtime, connector, or remote command was invoked.
|
||||
|
||||
## Review boundary
|
||||
|
||||
This is an author handoff. No self-review is represented as reviewer-of-record. The uncommitted synthetic tree is intended for independent review.
|
||||
|
||||
## Risks / blockers
|
||||
|
||||
- M3 truthfully reports incomplete lifecycle effects and bounded recovery; it does not implement or claim an automatic rollback command. This suite proves stopped-state restoration by the documented exact recovery reconcile. M4 retains migration/canary rollback ownership.
|
||||
- The fake host models only the public systemd/tmux runner contract and temporary roster filesystem boundary. This is intentional under the no-live-effects hold.
|
||||
- Parent issue closure, commit, push, PR, merge, deployment, and branch cleanup remain explicit holds.
|
||||
- No residual implementation blocker.
|
||||
@@ -1,80 +0,0 @@
|
||||
# FCM-M4-001 — v1-to-v2 inventory, preview, and migrator
|
||||
|
||||
- **Task / issue:** FCM-M4-001 / mosaicstack/stack#758
|
||||
- **Branch / base:** `feat/758-v1-v2-migrator` from `origin/main` `c1aecfabe97a5dc81a72f44910cd4e626f41863f`
|
||||
- **Base tree:** `46cdfbcdc1d1ff9c7b8b2b9cf3841086590bf774`
|
||||
- **Scope:** field-complete inventory, non-mutating preview, canonical v2 migration output, and migration/recovery disposition evidence. All effects use injected fakes or temporary fixtures.
|
||||
- **Budget:** 35K task estimate is the hard working cap. Keep one card/one PR and prefer focused reuse of the v2 compiler, shared role resolver, generated-env boundary, M1 executable disposition inventory, and reconciler observations.
|
||||
|
||||
## Objective
|
||||
|
||||
Implement preview-first v1 migration that never infers unresolved classes or lifecycle, preserves observed running/stopped state, quarantines forbidden legacy environment inputs with key-name/SHA-256-only diagnostics, inventories remote/connector/schema-only entries without reconciling them, covers every M1-classified shipped artifact, and emits deterministic recovery disposition evidence for the later M4-002 canary/rollback gate.
|
||||
|
||||
## Acceptance mapping
|
||||
|
||||
1. Field-by-field v1 inventory and no-mutation preview.
|
||||
2. Canonical output compiled by `roster-v2.ts` and semantically validated by the existing baseline-plus-`roles.local` resolver.
|
||||
3. Only approved deterministic aliases; every other noncanonical class requires an explicit disposition.
|
||||
4. Observed stopped/running maps explicitly to persisted lifecycle; stopped observations never produce running targets.
|
||||
5. Generated env is regenerated; strict local data is relocated; forbidden keys are quarantine inputs reported only by key name and SHA-256.
|
||||
6. Remote/connector/schema-only entries are inventory-only and excluded from local reconciliation output.
|
||||
7. Every shipped M1 example/profile/service preset has executable migration disposition evidence.
|
||||
8. Deterministic migration/recovery evidence records source, output, exclusions, quarantine, and restore prerequisites without executing a canary or rollback.
|
||||
|
||||
## Boundaries
|
||||
|
||||
Out of scope: FCM-M4-002 executable canary/rollback and host fixture, #766 communications, #636 commands/channels, live fleet/systemd/tmux/session/migration/deploy/connector/remote/gateway effects, `docs/TASKS.md`, parent issue mutation, commit, push, and PR operations.
|
||||
|
||||
## TDD plan
|
||||
|
||||
Migration rules and redaction are critical data-mutation/security logic, so tests are written red-first for inventory completeness, explicit class disposition, observed-state preservation, quarantine redaction, inventory-only remote/schema entries, compiler/resolver reuse, artifact coverage, and recovery evidence. Production code follows only after the focused tests fail for the missing behavior.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Map existing v1 loader, v2 compiler/resolver, env quarantine, reconciler observation, and M1 disposition guard.
|
||||
2. Add behavior-oriented failing migration tests with temporary fixtures and injected observation/filesystem adapters only.
|
||||
3. Implement the narrow migration module and CLI boundary without a second resolver or live command runner.
|
||||
4. Add scoped M4 migration/recovery documentation and executable shipped-artifact evidence.
|
||||
5. Run focused tests, full package tests, package/root typecheck and lint, formatting, diff checks, and adversarial redaction/no-effect verification.
|
||||
6. Run independent code/security review, remediate findings, reconstruct the synthetic tree using a temporary index, and stop uncommitted.
|
||||
|
||||
## Progress
|
||||
|
||||
- Collision checks passed: no local/remote branch, worktree, target path, or open PR owned `feat/758-v1-v2-migrator`.
|
||||
- Dedicated worktree created at the exact green `origin/main` base.
|
||||
- Required global/repository guides and FCM requirements/evidence loaded.
|
||||
- No matching migration skill exists under the configured skill directories; no unrelated skill loaded.
|
||||
- Added a preview-only CLI and migration module that compile with the existing v2 parser/renderer and validate through the shared persona resolver.
|
||||
- Added value-free raw-v1 inventory, strict unknown-field/synonym/duplicate detection, inventory-only remote and connector handling, and explicit class/tool-policy decisions.
|
||||
- Added separate reviewed lifecycle observations with only unambiguous running/stopped mappings.
|
||||
- Added sanitized, non-mutating environment preflight and recovery evidence explicitly marked non-executable.
|
||||
- Added executable disposition evidence derived from the exact 13-entry M1 inventory and operator documentation.
|
||||
- Tightened untrusted decisions/observations to reject unknown keys, invalid types/enums, extra local records, and competing automatic-alias dispositions.
|
||||
- Remediated independent review findings: v1 runtime/reset defaults are preserved, `~` workdirs expand only at env preflight, malformed/required agent fields fail closed before remote exclusion, and all seven shipped v1 fixtures now execute real previews with explicit evidence.
|
||||
- Remediated socket and locality authority blockers: socket-only agents stay local; `host == fleetHost` stays local; only `host != fleetHost` is inventory-only; ssh-only, missing reviewed fleet-host identity, and contradictory host/ssh targets block explicitly without lifecycle omission.
|
||||
- Remediated final exact-tree blockers: a declared v1 root socket cannot be overridden; matching/conflicting socket decisions retain reviewed running evidence; canonical ordering uses a shared locale-independent Unicode code-point comparator; migration evidence preserves all four legacy environment dispositions; backup documentation no longer claims validation that M4-001 does not perform.
|
||||
- Remediated immutable-review socket-presence blocker: both `socket_name` and `socketName` are field-presence-aware, so explicit empty/default-server declarations remain authoritative and incompatible named decisions block rather than replacing them.
|
||||
- Remediated the replacement-tree blockers: the shared v2 compiler and reconciler accept an explicit empty socket as literal default-server identity; present-empty holder session, default/agent work directory, runtime reset command, and alias values block rather than defaulting; missing preview inputs emit one stable blocked JSON object with non-zero status. Snake/camel aliases and whitespace-only input have adversarial coverage.
|
||||
- Remediated the subsequent authority blockers: each present-empty CLI path emits exactly one stable blocked JSON object with exit 1 before file reads, and reconciler `start`/`restart` or desired-state `apply`/`reconcile` fail closed before fixed `mosaic-fleet` systemd services can act on a default-server roster.
|
||||
- Remediated committed-head review blockers: explicitly declared empty runtime objects use the production v1 `/clear` reset fallback while omitted `pi` retains `/new`; lifecycle observations are sorted by canonical agent name; and bare CLI path flags reach preview validation, emit one stable blocked JSON object with exit 1, and perform zero reads. Built production-CLI subprocess tests cover all three bare flags.
|
||||
- Remediated late-audit blockers: the documented M4 guard invokes the 13-artifact validator and all seven v1 previews; canonical `~`/`~/...` workdirs remain unchanged in migration evidence and traversal-free forms expand at the shared production projection boundary while ordinary relative and home-relative traversal paths remain rejected; remote inventory and exclusion evidence sort canonically; and every default-server lifecycle-mutating reconciler path fails before observation, projection preparation/application, or fixed-unit effects. Explicit regressions preserve `plan`, `status`, `doctor`, and `verify` as observational default-server commands.
|
||||
- Remediated exact-tree traversal review: `~/../escape` and `~/src/../../escape` remain unexpanded and fail the unchanged shared `unsafe-path` validation. Both the shared generated-environment boundary and the production v1 environment caller have red-first regressions, preventing earlier caller normalization from bypassing the boundary.
|
||||
|
||||
## Verification evidence
|
||||
|
||||
- Focused migration/compiler/environment/reconciler/CLI: 8 files, 372 tests passed.
|
||||
- Documented 13-artifact guard: 1 matching test passed and executed all seven v1 previews.
|
||||
- Full `@mosaicstack/mosaic`: 59 files, 902 tests passed.
|
||||
- Workspace build: 23 tasks passed.
|
||||
- Root typecheck: 42 tasks passed.
|
||||
- Root lint: 23 tasks passed.
|
||||
- Root format check and `git diff --check`: passed.
|
||||
- Built production CLI: canonical `~/src` remains in ready roster/YAML evidence; generated projection preflight succeeds with no blockers; a bare path flag emits one blocked JSON object, exit 1, and no stderr.
|
||||
- Independent high-effort late-audit review: no blocker remained in the four assigned repair surfaces; separate exact-tree security audits found no qualifying newly introduced vulnerability.
|
||||
- Exact temporary-index synthetic tree includes every tracked changed path; immutable SHA and duplicate reconstruction are recorded in the final handoff.
|
||||
|
||||
## Risks / blockers
|
||||
|
||||
- M4-001 emits rollback prerequisites/evidence only; executable rollback/canary and the managed/unmanaged host fixture remain owned by M4-002.
|
||||
- Remote/connector entries remain inventory-only; later federation or connector reconciliation requires separately reviewed work.
|
||||
- Existing environment data is only preflighted. Cutover backup, quarantine write, legacy removal, and generated projection application remain later reviewed effects.
|
||||
@@ -1,183 +0,0 @@
|
||||
# Scratchpad — KBN-101 DB runtime/migration role split (#771)
|
||||
|
||||
- **Branch:** `docs/771-kbn101-db-role-split`
|
||||
- **Base:** `main` `e9c4aa3`
|
||||
- **Scope:** planning/documentation only; authorized files are PRD, Native Kanban task/shared/index docs, sitemap, this scratchpad, and the new KBN-101 contract.
|
||||
- **Explicit exclusions:** source/runtime/config/deployment/secret/migration/compose/CI/lock/package/KBN-100 branch edits; no production mutation.
|
||||
|
||||
## Objective
|
||||
|
||||
Freeze an implementation-ready PostgreSQL role/connection split so the Gateway uses a non-owner runtime identity and only a dedicated migration phase uses an owner/migrator identity. Make real deployed-role certification—not synthetic role tests—a serial prerequisite of KBN-100 and KBN-105.
|
||||
|
||||
## Intake and current-state evidence
|
||||
|
||||
- Mission MVP is active; W3 Native Kanban/SOT is planning-complete. The task state shows KBN-010 as the predecessor and KBN-100 as the current schema slice.
|
||||
- Current branch started at `e9c4aa3`; `.mosaic/orchestrator/{mission.json,session.lock}` were already runtime-modified and remain untouched.
|
||||
- `packages/db/src/client.ts`, `migrate.ts`, and `drizzle.config.ts` resolve one `DATABASE_URL` (with default fallback). `packages/storage/src/adapters/postgres.ts` calls `runMigrations(this.url)`.
|
||||
- `apps/gateway/src/database/database.module.ts` calls `storageAdapter.migrate()` at startup for PostgreSQL; this is the owner-runtime defect to remove in KBN-101 implementation.
|
||||
- `packages/config/src/mosaic-config.ts`, installer wizard, local/federated compose, Portainer test stack, and `.woodpecker/ci.yml` currently expose one URL. PGlite has an existing explicit local migration path.
|
||||
- Current KBN contract requires immutable events/checkpoints/artifacts/evidence, `RESTRICT`, and KBN-100 generated Drizzle consistency. It did not establish a deployable runtime identity split.
|
||||
|
||||
## Frozen decisions
|
||||
|
||||
1. `DATABASE_URL` is the non-owner runtime URL; `DATABASE_MIGRATION_URL` is migration-only. Both are required in their respective PostgreSQL phases; PGlite is the explicit local exception; migration never falls back to runtime/default/config URL.
|
||||
2. PostgreSQL Gateway runtime never auto-runs migration/DDL. Dedicated migrator uses `pg_try_advisory_lock(hashtext('mosaic-schema-migration-v1'))`; replicas only check exact ordered Drizzle-ledger readiness and fail closed.
|
||||
3. Roles are non-login `mosaic_platform_database_owner`, non-login `mosaic_schema_owner`, login/noinherit `mosaic_migrator`, non-login `mosaic_runtime_capability`, and login/inherit `mosaic_runtime`. Runtime inherits only its capability role with SET/ADMIN denied, has no owner/migrator membership, no unsafe attributes/ownership/DDL authority, and an explicit trusted search path.
|
||||
4. Runtime gets mutable DML only as needed, but INSERT/SELECT only on `task_events`, `artifacts`, `task_checkpoints`, `task_checkpoint_artifacts`, and `approval_decision_artifacts`. KBN-100 still enforces RESTRICT/no-cascade.
|
||||
5. Startup verifies effective role/ownership/attributes/inherited capability/TEMP/function-execute/ledger grants/search path/immutable denials/schema fingerprint without DSN exposure. It also requires authenticated CA/hostname-verified TLS. Stable sanitized errors and redaction rules are required.
|
||||
6. N-1 retains single runtime URL only as a non-certified compatibility release; staged role provisioning/migration/runtime deployment then enforces the split. Rollback never injects migration URL into Gateway.
|
||||
7. Vault target paths, rotation, deployment injection, CI, installer, compose, Portainer, and observability are separate one-card/one-PR handoffs. The migration-only file manifest includes `packages/db/drizzle.config.ts`; KBN-101 repairs the known PostgreSQL runner/journal ordering defect and proves a clean database applies every hash once before its foundation certificate. No application migration creates roles/passwords or hardcodes credentials.
|
||||
8. KBN-101 foundation merges/certifies first. KBN-100 then rebases, restores Drizzle declaration/snapshot/journal consistency, and bounds procedural immutable-table grant/trigger/backfill work to its own slice. Because those immutable relations do not exist until KBN-100, KBN-101’s real deployed-role immutable-operation certificate follows KBN-100 and is the serial gate before KBN-105.
|
||||
|
||||
## Assumptions
|
||||
|
||||
- `standalone` and `federated` are all current PostgreSQL production-like modes; a future PostgreSQL tier inherits this contract unless versioned otherwise.
|
||||
- Deployment will support a dedicated migration Job/one-shot command. A target that cannot run it cannot receive production/federated KBN certification.
|
||||
- Canonical Vault target paths require deployment-owner verification before provisioning; the planning document does not claim they already exist.
|
||||
|
||||
## Documentation produced
|
||||
|
||||
- `docs/PRD.md`: bounded KBN-101 requirements and acceptance criteria.
|
||||
- `docs/native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md`: normative rc.5 implementation, threat, migration/rollback, evidence, and exact file DAG contract.
|
||||
- `docs/native-kanban-sot/SHARED-CONTRACT.md`: rc.5 amendment preserving rc.4.
|
||||
- `docs/native-kanban-sot/TASKS.md`: KBN-101 inserted before and blocks KBN-100; KBN-105 held.
|
||||
- Native Kanban index and root sitemap links.
|
||||
|
||||
## Validation plan
|
||||
|
||||
1. Prettier only for changed Markdown.
|
||||
2. Markdown link target/check checks scoped to modified docs.
|
||||
3. Strict contract check with `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json` (the frozen TypeScript contracts remain unchanged).
|
||||
4. Diff allowlist proves only authorized documentation files changed, apart from pre-existing Mosaic runtime state.
|
||||
5. Independent documentation/security self-review: role escalation, fallback, startup DDL, schema readiness, grants/default privileges, immutable tables, secret leakage, deployment and KBN-100 boundaries.
|
||||
|
||||
## Review corrections
|
||||
|
||||
Independent Codex review found two blockers and security review found two medium defects; all were remediated in the frozen contract:
|
||||
|
||||
1. Split the KBN-101 certificate into a foundation role/schema-boundary certificate (before KBN-100) and real immutable-operation certificate (after KBN-100, before KBN-105). This preserves the requested KBN-100 block without requiring evidence for tables not yet created.
|
||||
2. Removed the legacy owner-runtime exception. N-1 compatibility preserves variable/config shape only; the KBN-101 runtime refuses owner/migrator identity and current single-URL installs remain on their previous release until role cutover.
|
||||
3. Introduced `mosaic_platform_database_owner` as a separate non-login platform role. `mosaic_schema_owner` owns application/ledger schemas only, not the database and has no database CREATE/ALTER/extension authority.
|
||||
4. Replaced blocking `pg_advisory_lock` with `pg_try_advisory_lock` and the deterministic `DATABASE_MIGRATION_LOCKED` failure.
|
||||
5. Review also flagged active `.mosaic/orchestrator` state. It was pre-existing launcher state and remains unstaged/uncommitted.
|
||||
6. Second review added `packages/db/drizzle.config.ts` to the migration-only slice, mandates `DATABASE_MIGRATION_URL` with a missing-variable negative, grants runtime only `USAGE` plus `SELECT` on `drizzle.__drizzle_migrations`, and verifies/revokes its ledger writes.
|
||||
7. Security review added `DATABASE_TLS_CA_CERT_PATH` / `DatabaseTlsConfigDto` with authenticated TLS and hostname/CA verification in production-like modes, explicit database `TEMPORARY` revocation/catalog denial testing, and default-PUBLIC function EXECUTE revocation with SECURITY DEFINER prohibited by default.
|
||||
8. Final review corrected the runtime login to inherit only its capability role with SET/ADMIN denied, and moved the known hash-complete migration-runner/journal repair into KBN-101-03 before the foundation certificate.
|
||||
9. Final manifest review added all live runtime DDL paths (`packages/storage/src/tier-detection.ts`, Gateway startup, and `fleet-backlog`) to KBN-101-02, requiring read-only extension probes and no PostgreSQL runtime auto-migration. It also requires KBN-101-04 to stop persisting either DSN into generated `.env`/`mosaic.config.json`, using only Vault/deployment references and injected variables.
|
||||
10. Provisioning review separated the external privileged platform bootstrap actor from the NOCREATEDB database-owner role and added KBN-101-00. That IaC/bootstrap card owns fresh/existing database role/ownership/grant/Vault transition evidence and is a foundation-certificate dependency.
|
||||
|
||||
## Results
|
||||
|
||||
- `pnpm exec prettier --check` on every authorized Markdown file: PASS.
|
||||
- Markdown link and whitespace checker on all seven authorized Markdown files: PASS.
|
||||
- `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json`: PASS (frozen strict contracts unchanged).
|
||||
- Codex code review iterated through role inheritability, hash-complete migration ordering, all reachable runtime DDL entrypoints, installer DSN persistence, and platform-bootstrap ownership; each finding was incorporated into the final frozen contract/DAG. The last security review found no new KBN-101 vulnerability; its sole low finding is the pre-existing unstaged Mosaic session-lock metadata, which is excluded from this commit.
|
||||
- Commit: `82ce3252df38a687c50485f8d048b53ca8db5989` (`docs(#771): freeze database runtime role split`).
|
||||
- Pre-push queue guard: `ci-queue-wait.sh --purpose push -B main` returned `state=unknown` without failure. The push hook ran repository `pnpm typecheck`, `pnpm lint`, and `pnpm format:check`: PASS.
|
||||
- Pushed branch `docs/771-kbn101-db-role-split` at the exact commit above; no PR was opened, merged, or closed. `web1:mosaic-100` received the handoff with head, decisions, DAG, and validation.
|
||||
- Awaiting independent security/Ultron review.
|
||||
|
||||
## 2026-07-15 — rc.6 exact-head remediation session
|
||||
|
||||
- **Objective / correction:** Replace the prior planning-author handoff and close every finding in the [independent exact-head report](../reports/native-kanban-sot/kbn-101-contract-security-review-82ce325.md) against `da742ca2da4a2ff466916c818fe275c4f7ffd384`. The report is a verbatim durable copy of the task-supplied review artifact; scope remains documentation-only, `.mosaic` is excluded, and source/config/compose/CI/deployment/secrets/migrations remain untouched.
|
||||
- **Finding 1 — closed DDL control plane:** rc.6 names `mosaic-db-migrator` as the sole application/CI/test PostgreSQL DDL runner, requires `DATABASE_MIGRATION_URL` before connection/DDL, inventories `runMigrations`, Drizzle config/scripts, `db:push`, storage CLI, adapter/Gateway startup, fleet-backlog, extension probes/bootstrap, direct federated integration DDL, CI, and future scripts, and specifies route/deny/test disposition for each. Tests use runner-prepared disposable PostgreSQL or invoke that runner; `db:push` is local-disposable-only and rejects production-like URLs.
|
||||
- **Finding 2 — deployable TLS:** rc.6 freezes distinct runtime/migrator URL and CA/server leaf Vault/compose/Swarm secret identifiers, `0400` key and `0600` URL/cert/CA mount requirements, actual compose/Swarm service-DNS SANs, PostgreSQL TLS settings, legacy-client drain/termination plus `hostssl` enforcement, verified-TLS readiness ordering, fresh/existing transition, CA-overlap rotation/TLS-only rollback, and standalone plus federated/Swarm positive and missing/wrong CA/SAN/downgrade negatives. PGlite is explicitly non-PostgreSQL evidence.
|
||||
- **Finding 3 — manifest/0009:** rc.6 defines manifest v1 canonical UTF-8 serialization and raw SQL-byte SHA-256, logical journal order, manifest ownership/grants, exact one-to-one observed hash tuple mapping, non-normative physical insertion order, safe original-0009 conditions, ambiguous-effect fail-closed recovery, and the full required reconciliation/backup test matrix. It preserves shipped 0009 bytes and forbids manual ledger adoption/insertion.
|
||||
- **Finding 4 — advisory lock:** replaced `hashtext` with fixed signed-int4-safe `(1297044289,1262636593)` (`MOSA`,`KBN1`), one `max:1` runner session, close-on-crash semantics, and contention/crash/readiness/unrelated-key evidence.
|
||||
- **Finding 5 — identifiers/search path:** selects `mosaic`, exact `pg_catalog,mosaic` per pooled connection and `SET LOCAL` transactions, plans audited public-object/extension/Drizzle relocation, forbids config-derived identifiers, limits bootstrap quoting to server-side `%I` on fixed allowlist, and requires injection/pool-reset negatives.
|
||||
- **Finding 6 — safe DAG:** cards 00–07 are inactive prepared capability while owner-runtime remains N-1; KBN-101-08 is the one atomic activation release after platform roles/TLS and compatible code. Mosaic control plane/Jason alone can activate/rollback; no force-on-red, runtime bypass, or temporary compatibility survives the gate. The approved role graph, post-KBN-100 immutable certification, and KBN-105 gate remain unchanged.
|
||||
- **Review remediation:** Codex review found the legacy plaintext cutover gap, missing URL-secret bindings, historical `public` migration incompatibility, non-reproducible checkout-byte hashing, CONNECT allowlisting regression, and undocumented direct-DDL operator instructions. rc.6 now requires drain/scale-to-zero, residual non-TLS session termination, `hostssl` with no `host` rule, zero plaintext-session proof, TLS-only post-enforcement rollback, distinct named runtime/migrator secret consumers, canonical Git-blob/LF manifest bytes, a runner-only owner-controlled legacy-public bootstrap followed by `mosaic` relocation, explicit CONNECT/TEMP revocation, and KBN-101-07 replacement of direct-DDL documentation. It also required the durable exact-head report link above. Pre-existing `.mosaic` runtime state remains excluded.
|
||||
- **Validation:** Prettier on all changed Markdown, repository Markdown link/whitespace check, and strict native-kanban contract TypeScript passed before final staging; the final staged diff excludes `.mosaic`. No source-code TDD applies because this is contract-only remediation.
|
||||
|
||||
## 2026-07-15 — rc.7 residual remediation session
|
||||
|
||||
- **Objective / correction:** Close every residual in the independent exact-head rc.6 re-review at `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview-45ba3d6.md` for `45ba3d6ad4d5383f457a303c05bc816144cfa48a`, without changing source, compose, CI, deployment, migration, or secret artifacts. Only the existing authorized planning/documentation paths are eligible; pre-existing `.mosaic` state remains excluded.
|
||||
- **Source-backed scope confirmed:** the active `federated-pgvector.integration.test.ts` executes `CREATE TEMP TABLE`; tracked `docker/init-db.sql` and `infra/pg-init/01-extensions.sql` both create `vector`; `migrate-tier.ts` advertises raw `CREATE EXTENSION`; and `tools/federation-harness/docker-compose.two-gateways.yml` is current plaintext two-PostgreSQL/two-Gateway topology. Current `schema.ts` has 36 default-schema `pgTable` declarations, 6 default `pgEnum` declarations, and an unqualified `vector` custom type; historical migrations contain `public` references.
|
||||
- **Plan:** (1) make the finite DDL/static-bypass inventory and `DATABASE_URL`-only denial matrix exact, including the runner-prepared persistent pgvector fixture and migrated two-gateway harness; (2) freeze executable `public`-to-`mosaic` and `mosaic_extensions` transition, Drizzle ownership, object-catalog classes/order, eligibility and rollback tests; (3) bind repository/control-plane ownership, UID/GID validation, exact artifact/mount rules, and both gateway TLS topology; (4) correct PRD acceptance mapping and cross-document rc.7 status; then run formatting, link/contract, source-path, diff, review, commit, queue guard, and push.
|
||||
- **Independent review closure:** initial Codex review found Gateway-key consumer wording, `CLAUDE.md` omission, final schema-owner set, and placeholder SANs; all are now explicit. Re-review found the legacy `0001` vector-type resolution problem and `docs/federation/SETUP.md` raw-DDL instruction; the legacy runner now uses only its fixed non-writable `pg_catalog,public,mosaic_extensions` history path, while runtime remains `pg_catalog,mosaic`, and the federation setup path is assigned to KBN-101-07/static inventory. Security review final verdict: no confident vulnerability. The review also repeated the pre-existing tracked `.mosaic` session-state concern; it remains deliberately unstaged/excluded by this task.
|
||||
- **Completion evidence:** changed Markdown is Prettier-formatted; local links and strict native-kanban TypeScript passed; source-path inventory confirmed all current referenced paths (the new `apps/gateway/Dockerfile` is explicitly a planned KBN-101-05 artifact); diff check and authorized-doc allowlist passed. No source-code TDD applies to this documentation-only remediation.
|
||||
|
||||
## 2026-07-15 — rc.8 exact residual remediation session
|
||||
|
||||
- **Objective / correction:** Close all three HIGH findings in the independent rc.7 exact-head re-review at `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview2-0778eba.md` for `0778eba2db3c2dfbaca3af352b12ba0389d3552b`. Scope remains documentation-only: no source, config, Compose, CI, deployment, secret, or migration artifact changed; pre-existing `.mosaic/orchestrator` state remains excluded.
|
||||
- **Finite authority closure:** KBN-101-06 now classifies exact current source/scripts/package bins, operator docs, and deploy manifests. `packages/db/src/index.ts` has explicit removal/compile-import negative ownership; `docs/fleet/backlog-conventions.md` and `docs/PERFORMANCE.md` now remove first-use/direct-Drizzle/Gateway-startup migration instructions and point to sole runner/readiness. Byte-immutable historical SQL, PGlite-only routines, negative-test literals, vendored/generated artifacts, and labeled historical reports are exact-path/category reviewed allowlists; unknown hits fail. The contract explicitly rejects relying on a naive token scan alone.
|
||||
- **Executable and exclusive handoff closure:** KBN-101-03 exclusively owns the published `mosaic-db-migrator` bin, `packages/db/src/cli.ts`, private migrator modules, `docker/db-migrator.Dockerfile`, exact `--run|--verify|--help`, environment/argv limits, sanitized exits, and command/order tests. KBN-101-00 exclusively owns `infra/pg-bootstrap/roles.sql`, `infra/pg-bootstrap/extensions.sql`, `infra/pg-bootstrap/README.md`, and bootstrap tests. KBN-101-05 exclusively owns `tools/db/render-postgres-secrets.ts`, its tests, and deployment declarations, consuming the versioned bootstrap interface without overlap.
|
||||
- **pgvector owner closure:** `mosaic_extension_owner` is dedicated NOLOGIN, available only to the external bootstrap actor during bootstrap; fresh vector/member ownership remains there. The contract records PostgreSQL's unsupported extension-owner transfer and forbids catalog mutation, ownership adoption, and `DROP CASCADE`. Approved-owner existing extensions use verified `ALTER EXTENSION ... SET SCHEMA`; legacy runtime-owned extensions fail closed to a controlled backup/shadow/runner/copy-evidence/quiesce/final-delta/atomic-switch/read-only-rollback migration. It requires `pg_extension.extowner`, member/schema/version, and runtime/migrator/schema-owner ALTER/DROP/member-update denial tests across clean, approved-owner, legacy shadow, partial/resume/rollback, and N-1.
|
||||
- **Cross-document state:** PRD, KBN contract, shared contract, task decomposition, index, sitemap, current operator docs, and this scratchpad are rc.8-consistent. The only intended next action is a fresh independent exact-head re-review after validation/push.
|
||||
- **Validation / review:** Prettier passed for all nine changed Markdown documents; local links passed (9 documents); `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json` passed; source-path inventory passed (20 paths: 8 current, 12 explicitly planned); finite-authority requirement checklist and `git diff --check` passed. Manual documentation/security review checked the three requested paths, private-only runner boundary/exit contract, non-overlapping 00/03/05 ownership, extension-owner denial and shadow path, and `.mosaic` exclusion. No source-code TDD applies because this is contract-only remediation.
|
||||
- **Delivery evidence:** committed `1423c2ad02b5471eab006fb4c878808e5b29c387` as `docs(#771): close role split rc.8 residuals`. Push queue guard returned `state=unknown` without error; push hook ran repository `pnpm typecheck`, `pnpm lint`, and `pnpm format:check`, all PASS; branch push succeeded. This final evidence append is committed next, then the exact remote head is verified. The only intended next action is a fresh independent exact-head re-review.
|
||||
|
||||
## 2026-07-15 — rc.9 final residual remediation session
|
||||
|
||||
- **Objective / correction:** Close the three findings in `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview3-9cf5d2f.md` against exact head `9cf5d2f6641b14082dc3294e2a84d1fb4ccc019d`: move `mosaic_extensions` schema ownership to `mosaic_extension_owner`; replace all broad/conflicting KBN-101 card ownership with a complete disjoint exact-path/test manifest; and classify the current architecture-plan `db:migrate` instruction with pinned scanner mechanics. Scope remains documentation-only; no source/config/Compose/CI/deployment/secret/migration artifact and no `.mosaic` path may be modified.
|
||||
- **Plan:** inspect current tracked source topology to name only existing paths; update the normative contract first and synchronize PRD/shared/task/index/sitemap/version language; run Prettier, changed-doc links, strict contract TypeScript, source/path and manifest-overlap checks, diff allowlist, independent documentation/security review; then stage docs only, commit, queue-guard, push, and verify exact remote SHA. No source-code TDD applies because this is contract-only remediation.
|
||||
- **Closure implemented:** rc.9 makes `mosaic_extension_owner` create and own `mosaic_extensions`, `vector`, and members; the external bootstrap actor alone temporarily `SET ROLE`s for fresh/approved-owner work, while schema owner has only `USAGE` for legacy type resolution and never temporary `CREATE`. Catalog/default-ACL plus direct DDL/member denials now cover runtime, migrator, and schema owner through fresh, relocation, shadow/resume, and rollback evidence.
|
||||
- **Delivery decomposition:** Replaced broad ownership with complete disjoint 00–09 manifests, exact tests/evidence, producer-before-consumer edges, and an explicit no-intermediate-deploy N-1 activation statement. `packages/storage/src/{cli,migrate-tier}.ts` belongs only to -02; the current tracked init artifacts are retired by -02 as direct-DLL closure; -03 owns all runner/index/migrate/config/schema assets and exact compiled-bin/image mapping; -07 owns docs only; -08/-09 own evidence only.
|
||||
- **Classifier closure:** -06 has exact scanner/inventory/matrix paths, canonical inventory fields, classes/dispositions, fixed token/rule set, exact allowlist categories/restrictions, and self-test requirements for unknown, duplicate-owner, ownerless, missing-path, and historical masking cases. The architecture plan now marks direct `db:migrate` superseded and uses `mosaic-db-migrator --run`.
|
||||
- **Validation:** Prettier check, strict native-kanban contract TypeScript, changed-document local-link resolution, `git diff --check`, and an automated manifest-overlap/owner/current-source-path check passed. Targeted documentation/security review verified role ownership/default privileges/search path/preflight/legacy/shadow/rollback consistency, disjoint manifests/DAG/activation, scanner mechanics, exact bin/entrypoint, and no `.mosaic` staging intent. No source-code TDD applies because this is documentation-only remediation.
|
||||
- **Next:** stage documentation only, commit, queue-guard, push, verify exact remote SHA, then wait for fresh exact-head review.
|
||||
- **Delivery evidence:** committed `8cbad2bcd9bc7507052f74f35670ef7c8e39e44e` as `docs(#771): close role split rc.9 residuals`; `ci-queue-wait.sh --purpose push -B main` returned `state=unknown` without error; push-hook `pnpm typecheck`, `pnpm lint`, and `pnpm format:check` all passed; push succeeded and `origin/docs/771-kbn101-db-role-split` resolved to that exact SHA. Pre-existing `.mosaic/orchestrator/{mission.json,session.lock}` remains modified but intentionally unstaged/excluded. The only next action is a fresh independent exact-head re-review.
|
||||
|
||||
## 2026-07-15 — rc.10 Ultron NO-GO remediation intake
|
||||
|
||||
- **Objective / scope:** Close only HIGH-1 and HIGH-2 in `/home/hermes/agent-work/reviews/771-kbn101-ultron-11f09a1.md` against exact head `11f09a15e43e72afda6a0374668996b4bda9e536`. Documentation only: preserve approved content; no source/config/Compose/CI/deploy/secret/migration edits and no `.mosaic` staging.
|
||||
- **Plan:** (1) replace the impossible `NOLOGIN NOSUPERUSER` extension owner with the exact non-login, zero-member `NOLOGIN SUPERUSER` external-control exception and document the non-delegable superuser residual; (2) require the audited external superuser session to `SET ROLE`/`RESET ROLE` for fresh, approved-owner, and shadow extension work, then prove catalog ownership and all service-role denial; (3) assign the active migrate-tier guide exclusively to KBN-101-07, add its active secure route to the -06 inventory/matrix/scanner schema, and freeze `--target-url-file /run/secrets/mosaic_migrate_target_url` plus pre-migrated target/dedicated non-DDL importer requirements; (4) synchronize PRD/shared/tasks/index/sitemap/guide and rc.10 status; (5) validate formatting, links, contracts, source paths, finite operator inventory, diff, review, commit, queue guard, push, and exact remote SHA.
|
||||
- **Target-image evidence before edits:** local `pgvector/pgvector:pg17` control file reports `default_version = '0.8.2'`, `relocatable = true`, and no `trusted`/`superuser` override (untrusted PostgreSQL extension). An isolated PostgreSQL 17 container proved a `NOLOGIN SUPERUSER` `mosaic_extension_owner` can create `mosaic_extensions` and `vector` under external-superuser `SET ROLE`, returns to the external session after `RESET ROLE`, has `rolcanlogin=false`, `rolsuper=true`, zero role members, exact extension/schema and owner-bearing-member ownership, and denies `SET ROLE`, `ALTER EXTENSION`, `DROP EXTENSION`, and schema ownership changes to runtime, migrator, schema owner, and data importer. Ownerless PostgreSQL catalog member classes (`pg_am`, `pg_cast`) were intentionally not misrepresented as ownable members.
|
||||
- **TDD decision:** skipped as not applicable: this is a documentation-only contract remediation. Future KBN-101-00/-02/-06 tests are specified as the situational evidence; no source/test artifact is permitted in this task.
|
||||
- **Final scope correction:** Per control-plane direction, remediation remains bounded to the two Ultron findings. The active guide is explicitly a non-operative KBN-101 contract until its owned implementation/activation lands; no additional design, source, CI, deployment, secret, or test artifact was added.
|
||||
- **Validation evidence:** target-image/container role proof PASS (pgvector `0.8.2`, `relocatable=true`, trusted absent/untrusted; external-superuser `SET ROLE`/`RESET ROLE`; exact extension/schema/owner-bearing-member ownership; zero membership and service-role denials). Changed-doc Prettier, strict native-kanban contract TypeScript, local-link resolver (8 docs), finite operator-doc inventory (one active KBN-101-07 route with no credential argv in executable blocks), source-path check (6 current paths), and `git diff --check` PASS. Pre-existing `.mosaic/orchestrator/{mission.json,session.lock}` remains intentionally excluded.
|
||||
|
||||
## 2026-07-15 — rc.11 exact-head re-review remediation intake
|
||||
|
||||
- **Objective / scope:** Close only HIGH-1 and HIGH-2 in `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview5-f60144e.md` against `f60144eb3eab6234ab01bda592052081c777897e`: target-bind the non-DDL tier importer with a runner-produced signed attestation, and disposition every current non-normative documentation scanner hit, including the active user-guide route and federation historical status. Documentation only; no source/config/Compose/CI/deployment/secret/migration edits and no `.mosaic` staging.
|
||||
- **Frozen decision:** `mosaic-db-migrator --verify` is trusted only after TLS/identity/manifest/schema verification and signs a credential-free JCS/Ed25519 v1 artifact from a runner-only fixed root-owned private-key file. The artifact binds secret version/exact URL-file digest, canonical TLS/CA/SPKI/server/database/importer/manifest/schema identity, issued/expiry/nonce, and producer build/correlation; importer gets pinned public key plus artifact only. It validates both files and all bindings before target connection, opens/digests/connects from one in-memory URL read, validates server identity before DML, and distinguishes zero connection from zero DML. Key overlap/revocation, secret-rotation invalidation, replay cache, atomic rename, and sanitized errors are mandatory.
|
||||
- **Ownership:** -03 owns producer/signing DTO/tests; -02 importer interface/verification tests; -05 key/artifact mounts/render tests; -06 inventory/matrix and non-masking scanner tests; -07 operator guide. The exact manifests remain disjoint.
|
||||
- **Operator correction:** `storage migrate` is schema-wrapper delegation only; legacy `--from hot --to cold` tier-copy guidance is unavailable. Secure tier copy is `migrate-tier` with `--target-url-file` plus `--target-attestation-file`. Federation M1 task language is status-only and adjacent KBN-101 text says it authorizes no current DDL.
|
||||
- **TDD decision:** skipped as not applicable: this bounded task changes documentation only. Future -02/-03/-05/-06 tests are specified as the required implementation evidence.
|
||||
- **Validation / review:** Prettier PASS on all 18 changed Markdown/root-doc files; `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json` PASS; changed-doc local-link resolver PASS (71 links); full current docs scanner/disposition PASS (10 non-normative paths, 4 normative-contract paths; no unknown active command); legacy `storage migrate --from` and raw target-URL bypass scan PASS; attestation field/interface assertion PASS; exact source ownership/manifest-overlap assertion PASS; `git diff --check`, docs-only scope, and secret-leak scan PASS. Manual documentation/security review verified key isolation, JCS/detached signature, secret-file hash as non-secret evidence, verification ordering/TOCTOU/replay/rotation, no connection vs zero DML, non-masking scanner class, status-only federation history, and no regression to pgvector closure. No source-code TDD applies.
|
||||
- **Delivery evidence:** committed `6227f076c819bd124383851633b16d4ef9c88a98` as `docs(#771): bind tier importer to verified target`; staged scope was 18 documentation files only and excluded `.mosaic`. Pre-push queue guard returned `state=unknown` without failure. Push hook ran repository `pnpm typecheck`, `pnpm lint`, and `pnpm format:check`: PASS. Branch push succeeded. Verify the exact remote SHA after this final delivery-evidence append, then idle for independent exact-head re-review and Ultron reverify. `.mosaic/orchestrator/{mission.json,session.lock}` remains pre-existing and excluded.
|
||||
|
||||
## 2026-07-15 — rc.12 bounded deployable-importer/SETUP remediation plan
|
||||
|
||||
- **Objective / scope:** Close the two HIGH findings in `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview6-65663d4.md` against exact head `65663d4f72f2ace5148bce9aeba04b5a8d5beee9`. Documentation/tracking only; preserve every earlier closure; do not modify source, deployment, Compose, CI, migration, Vault, or `.mosaic` artifacts.
|
||||
- **Plan:** (1) make KBN-101-05 own canonical KV-v2 importer URL/version provenance, separate immutable generation-pinned renderer consumers, importer CA/public-key/attestation mounts, fixed importer/migrator identities, safe-fd lifecycle, isolation/rotation/TOCTOU/error evidence, and -02/-03/-06 handoffs; (2) convert `docs/federation/SETUP.md` to a non-operative N-1 reference with only the required external-bootstrap → TLS/roles → runner `--run` → `--verify` → Gateway-readiness sequence; (3) broaden scanner grammar plus path-specific semantic negatives so indirect first-boot/startup/init/Compose authority cannot be masked by a named, normative, or status record; (4) synchronize PRD/shared/tasks/index/sitemap/federation task state and this scratchpad; (5) run formatting, links, strict contracts, complete-doc scanner/semantic assertions, diff/operator inventory, material/manifest overlap, review, docs-only stage, commit, queue guard, push, and exact remote-SHA verification.
|
||||
- **TDD decision:** skipped because this bounded change is documentation-only; the affected -02/-03/-05/-06 implementation tests and scanner semantic fixtures are specified as mandatory future evidence.
|
||||
- **Review correction:** independent Codex review found the initial `10003` producer → immutable `10002` importer artifact handoff impossible. rc.12 now specifies the required privileged deployment handoff controller: after runner success it safe-opens/verifies producer artifact plus generation, exact-byte copies/fsyncs/atomically renames to a distinct `10002:10002` `0400` importer mount, seals it read-only, and starts no importer on partial/wrong-generation/owner/mode failure. It receives only a root-owned non-secret expected-version/URL-digest/generation descriptor plus public verifier key, never URL bytes/private key; producer/importer share no writable file or mount. Dry-run nonce consumption now requires fresh `--verify` and artifact before `--yes`; the active-route schema requires `targetCredentialVersionFile`. Pre-existing `.mosaic` state is confirmed excluded from staging.
|
||||
- **Validation result:** changed-doc Prettier and `git diff --check` PASS; strict `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json` PASS; contract/SETUP material and non-operative semantic assertions PASS. Pending final docs-only stage, commit, queue guard, push, and remote-head verification.
|
||||
|
||||
## 2026-07-15 — rc.13 MILESTONES semantic-scan remediation intake
|
||||
|
||||
- **Objective / scope:** Close only HIGH-1 from `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview7-7365dcf.md` against `7365dcf15c09262a46132b9c011769ad98243641`. Documentation/tracking only: assign `docs/federation/MILESTONES.md` exclusively to KBN-101-07 and its exact former startup-extension wording to the KBN-101-06 semantic fixture/inventory; replace the wording with a non-operative historical/status disposition. No source, deployment, Compose, CI, Vault, migration, provider, or `.mosaic` artifact is authorized.
|
||||
- **Frozen remediation:** runtime/startup extension provisioning is superseded and forbidden. The sole eligible sequence is external bootstrap → TLS/roles → `mosaic-db-migrator --run` → `mosaic-db-migrator --verify` → Gateway readiness. The MILESTONES record authorizes no current DDL, Compose/init, or startup path. The scanner must prove the exact former wording fails before any inventory/status-only mask and rerun its full current-doc operator/deploy-manifest scan outside reports/scratchpads.
|
||||
- **Plan:** update only MILESTONES plus the exact KBN-101 contract/inventory/manifests and necessary PRD/shared/task/index/sitemap/version/status references; run full lexical+semantic scan, Prettier, links, strict contract TypeScript, diff and manifest-overlap checks; stage docs only (excluding pre-existing `.mosaic`), commit, queue-guard, push, and verify the exact remote SHA. No source-code TDD applies because this bounded task changes documentation only.
|
||||
- **Remediation result (pre-commit):** `MILESTONES.md` now makes runtime/startup extension provisioning superseded and forbidden, with only external bootstrap → TLS/roles → `mosaic-db-migrator --run` → `--verify` → Gateway readiness; it authorizes no current DDL/Compose/init/startup path. The KBN-101-07 manifest/inventory is exclusive and KBN-101-06 documents the exact former wording as a semantic negative that fails before inventory masking. Full current-doc scan outside reports/scratchpads: 103 Markdown files, 10 lexical-hit paths classified, 2 owned Compose-before-runner references, and zero ownerless indirect/literal routes. Prettier, strict native-kanban TypeScript, local links (64/0), diff check, and 95-path manifest-overlap reconstruction (0 overlaps; MILESTONES only -07) passed. Pre-existing `.mosaic/orchestrator/{mission.json,session.lock}` remains excluded.
|
||||
- **Delivery checkpoint:** committed remediation as `237bac81c93dc4305470cea23a67e4ced730bd61` (`docs(#771): close MILESTONES startup authority`). Push queue guard returned `state=unknown` without failure; the push hook ran repository `pnpm typecheck`, `pnpm lint`, and `pnpm format:check`, all PASS; the remote branch resolved to that exact SHA. This final evidence append is committed next, then the exact remote head is verified and the branch waits for independent exact-head rereview/Ultron reverify. `.mosaic` remains unstaged.
|
||||
|
||||
## 2026-07-15 — rc.13 current-document safety remediation intake
|
||||
|
||||
- **Objective / scope:** Close only HIGH-1 and HIGH-2 in `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview8-aeacc70.md` against exact head `aeacc702353740aad0f2f086974cc0670e360d1d`. This is documentation/tracking only. Preserve all prior gates; do not edit source, Compose, deployment artifacts, CI, migrations, Vault data, reports, or `.mosaic`.
|
||||
- **Source-backed decision:** Current `docker-compose.yml` mounts `infra/pg-init` into PostgreSQL init and that SQL creates `vector`; it cannot be used as a current PostgreSQL start route before KBN-101 bootstrap/runner artifacts exist. The checked-in configuration declares a supported `local` PGlite tier (`DEFAULT_LOCAL_CONFIG` and `tier-detection` both establish in-process PGlite with no external service probe), so docs may retain a local/PGlite route and start only non-PostgreSQL Compose services such as `valkey`.
|
||||
- **Plan:** (1) replace the README and dev-guide Compose-first PostgreSQL instructions with a PGlite/no-PostgreSQL developer path and an explicit held PostgreSQL/federated future activation sequence; (2) replace the deployment quick-start and bare-metal production procedure with non-operative status, no production `.env`/automatic dotenv/`EnvironmentFile`/credential export-or-argv/restart guidance, and only a non-executable future renderer/Vault generation-pinned process-exec or `LoadCredential` schematic; (3) expand KBN-101-06/-07 semantic fixture/disposition language to fail the exact former README/dev/deployment Compose-first sequences and production credential routes before ownership/status masking; (4) synchronize PRD/shared/tasks/index/sitemap/status/version and this scratchpad; (5) run formatting, links, strict contract TypeScript, full current-doc lexical+semantic scan outside reports/scratchpads, manifest-overlap, review, docs-only stage, commit, queue guard, push, and exact remote-SHA verification.
|
||||
- **TDD decision:** no source or fixture implementation may be changed in this documentation-only remediation. The -06 future fixture requirements are frozen as acceptance evidence; validation here is static semantic inventory plus documentation quality gates.
|
||||
- **Correction from independent review:** The initial local-Gateway PGlite wording was unsafe. `apps/gateway/src/main.ts` loads daemon/root/app-local environment files before tier selection; an inherited daemon `DATABASE_URL` can select PostgreSQL, whose current startup reaches extension creation and migrations. No source is authorized in this docs-only task. The remediation therefore holds Gateway/Web local startup, preserves only PGlite data-layer plus selected non-PostgreSQL Compose work, and assigns KBN-101-02 the fail-closed daemon/inherited/root/app-local DSN and non-local-tier rejection before connection/DDL, with a regression proof. The future renderer boundary remains KBN-101-05.
|
||||
- **Remediation evidence:** Removed active PostgreSQL Compose-first and production credential guidance from README, CLAUDE, dev/deployment, and the residual historical TUI/MCP routes; local documentation now permits only PGlite data-layer/non-PostgreSQL Valkey work while Gateway/Web startup is explicitly held. KBN-101-06/-07 now freeze exact former README/dev/deployment Compose sequences plus production credential patterns as pre-classification semantic negatives. Independent review surfaced the current daemon/root/app dotenv loader as an unsafe source boundary; no source is authorized here, so the docs hold that startup and assign fail-closed removal/regression proof to KBN-101-02.
|
||||
- **Validation:** Prettier PASS (12 changed docs); local-link resolver PASS (71 links); `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json` PASS; full README/CLAUDE/docs inventory PASS (104 documents, 0 active non-normative Compose/init/production-credential violations); manifest reconstruction PASS (10 cards, 95 declared path tokens, 0 overlaps); `git diff --check` PASS. Pre-existing `.mosaic/orchestrator/{mission.json,session.lock}` remains intentionally unstaged.
|
||||
- **Final route correction:** Held the residual MCP environment/restart and historical TUI smoke-test routes after review showed they could bypass the Gateway local-start hold; no bearer-token-over-HTTP or Gateway restart route remains in this remediation scope.
|
||||
- **Delivery:** committed `7cc156b777189ee89448e4d569a8b3f69560a240` (`docs(#771): hold unsafe database startup routes`) and `d8f935c20ade835aa3ec03fe5d6961885d8b5f0b` (`docs(#771): record final route correction`). Push queue guard returned `state=unknown` without failure; both pushes completed and the remote matched `d8f935c` before this final delivery-evidence append. `.mosaic/orchestrator/{mission.json,session.lock}` remains pre-existing and unstaged. Await a fresh independent exact-head re-review/Ultron verification.
|
||||
|
||||
## 2026-07-15 — rc.15 exact one-finding runner/legacy-CI remediation intake
|
||||
|
||||
- **Objective / scope:** Close only HIGH-1 in `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview9-be0ebfd.md` against `be0ebfdc6a2b32a0ab6989117ebbb12f43854d71`. Documentation/tracking only: no source, Compose, CI, deployment, migration, Vault, reports, or `.mosaic` edit.
|
||||
- **Plan:** Replace imperative current runner routes in the architecture plan and PERFORMANCE with one explicit non-operative future procedure; make fleet backlog current behavior PGlite-only and PostgreSQL held; classify README's checked-in direct CI `db:migrate` as legacy N-1/uncertified/non-authorizing pending KBN-101-06 removal; then extend the future KBN-101-06 lexical/semantic inventory contract so unqualified runner/current-CI authority fails before masking while only the complete named held procedure passes. Synchronize required contract/PRD/shared/task/index/sitemap state, run full docs scan and document gates, stage docs only, commit, queue-guard, push, and verify remote SHA.
|
||||
- **TDD decision:** not applicable: the user authorizes documentation only and the named -06 fixture/inventory files do not yet exist; the contract records their required future implementation evidence.
|
||||
- **Remediation / review closure:** Architecture, PERFORMANCE, federation SETUP/MILESTONES, deployment/dev/migrate-tier, and README now use one Markdown-bounded `Held future procedure` form where needed: non-operative/no-current-command-authority; KBN-101-00/-03/-05; external bootstrap → TLS/roles → `mosaic-db-migrator --run` → `mosaic-db-migrator --verify` → Gateway/Compose readiness. Any runner hit outside that section is a -06 semantic failure. Fleet backlog current behavior is PGlite-only. README accurately records the checked-in direct CI migration as an active, isolated-disposable-database, uncertified legacy N-1 DDL exception that is non-authorizing as an operator route and pending -06 removal; it no longer falsely claims the current CI role lacks DDL capability. Independent Codex review found and this pass closed the readiness-endpoint, standalone-verify, CI-factuality, and scanner-boundary findings. Its only residual finding concerns pre-existing tracked `.mosaic/orchestrator` runtime state, which is explicitly excluded and unstaged by task scope; security review found no vulnerability.
|
||||
- **Validation:** changed-doc Prettier PASS; `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json` PASS; changed-doc local links 72/0; `git diff --check` PASS; full README/CLAUDE/docs lexical+semantic scan outside reports/scratchpads PASS (106 Markdown documents; 7 operator documents with runner tokens; zero unqualified future-runner/current-CI authority routes); KBN-101 manifest check PASS (10 dependency-ordered cards; -07 docs/-06 fixtures disjoint); docs-only allowlist PASS (16 docs, pre-existing `.mosaic` excluded).
|
||||
- **Delivery evidence:** committed `d857463a8a4658e34a77177737860cf82cc26ac6` (`docs(#771): hold unimplemented runner routes`). Pre-push queue guard returned `state=unknown` without failure; the push hook ran repository `pnpm typecheck`, `pnpm lint`, and `pnpm format:check`, all PASS. Push succeeded and `origin/docs/771-kbn101-db-role-split` matched `d857463a8a4658e34a77177737860cf82cc26ac6`. This evidence append is committed and pushed next; `.mosaic/orchestrator/{mission.json,session.lock}` stays pre-existing, unstaged, and excluded. Await exact-head independent re-review/Ultron reverify.
|
||||
|
||||
## 2026-07-15 — rc.16 exact one-finding generic-wrapper remediation intake
|
||||
|
||||
- **Objective / scope:** Close only HIGH-1 in `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview10-18e253c.md` against exact head `18e253c8790bdbb5bc30a06c116472213b83b22f`. Documentation/tracking only: no source, Compose, CI, deployment, migration, Vault, report, or `.mosaic` change.
|
||||
- **Source-backed correction:** `packages/storage/src/cli.ts` currently labels `storage migrate` a thin wrapper for `pnpm --filter @mosaicstack/db db:migrate` and executes that direct Drizzle command with `execSync`; no `mosaic-db-migrator` executable exists. Therefore the README commented form and user-guide executable form must not describe runner delegation or provide current command authority.
|
||||
- **Plan:** Remove the current wrapper command from README/user-guide command guidance; record it as legacy N-1, uncertified, non-operative, and forbidden pending KBN-101-02/-03/-06/-08 activation. Retain only the held future ordered bootstrap → TLS/roles → runner `--run` → `--verify` → readiness sequence and the separately held secure migrate-tier route. Extend KBN-101-06's future semantic fixture/matrix with both exact former forms (including the README commented code-fence form), requiring their failure before inventory/status masking and a source-consistency assertion that direct Drizzle wrapper source cannot be described as runner delegation. Synchronize status/version references only where required, then run document gates, stage docs only, commit, queue-guard, push, and verify the remote SHA.
|
||||
- **TDD decision:** not applicable: this bounded task changes documentation only; the required future -06 semantic/source-consistency fixtures are specified as implementation acceptance evidence.
|
||||
- **Remediation / validation:** README and user-guide remove the generic wrapper from command guidance and state the direct-Drizzle current-source truth, legacy-N-1/uncertified/non-operative MUST-NOT-INVOKE boundary, named -02/-03/-06/-08 activation cards, future external-bootstrap → TLS/roles → runner `--run` → `--verify` → readiness sequence, and separately held secure migrate-tier route. The KBN-101 rc.16 contract records both exact former forms (README commented code fence and user-guide executable code fence), requires failure before inventory/ownership/status masking, and requires the direct-Drizzle/no-runner-bin source-consistency proof. Prettier passed on all nine changed Markdown documents; changed-doc local links passed (72/0); strict native-kanban contract TypeScript and `git diff --check` passed; full README/CLAUDE/docs scan outside reports/scratchpads passed (106 documents, zero non-normative executable generic-wrapper or false runner-delegation route); and manifest validation passed (10 cards, 90 exact tokens, zero overlaps). Pre-existing `.mosaic/orchestrator/{mission.json,session.lock}` remains excluded.
|
||||
@@ -1,529 +0,0 @@
|
||||
# Scratchpad — #791 Upgrade config protection (ms-791 worker lane)
|
||||
|
||||
**Lane:** web1:ms-791 → reports to MS-LEAD (web1:mosaic-100). Do NOT contact Jason/Mos directly.
|
||||
**Worktree:** `/home/hermes/agent-work/stack-agents-dir-791`, branch `feat/791-upgrade-config-protection`
|
||||
off `origin/main` `9745bc3f` (verified exact head).
|
||||
|
||||
## Mission prompt (verbatim intent)
|
||||
Protect operator-owned config under `~/.config/mosaic` from framework-upgrade wipes. Ratified
|
||||
combination (Mos-approved, do NOT re-litigate): (b) strict ownership separation [PRIMARY] + (a)
|
||||
transactional pre-update snapshot [safety net] + (d) regeneration-from-SSOT [recovery]. (c) periodic
|
||||
timer DEFERRED. HARD GATE: unit test that an upgrade run touches NO path outside the manifest.
|
||||
Design-first: write design doc, send to MS-LEAD, WAIT for confirmation before impl.
|
||||
|
||||
## Session 1 (2026-07-16) — Phase 1 design
|
||||
|
||||
### Evidence gathered (wipe mechanism, file/line)
|
||||
- `mosaic update` → `update-checker.ts:509` `buildReseedCommand` → `bash install.sh`
|
||||
(`MOSAIC_SYNC_ONLY=1`, `MOSAIC_INSTALL_MODE=keep`).
|
||||
- Wipe = `packages/mosaic/framework/install.sh:199` `rsync -a --delete` + `PRESERVE_PATHS` denylist
|
||||
(`install.sh:47`). cp-fallback `install.sh:223` `find ... -exec rm -rf`.
|
||||
- Denylist gaps → WIPED: `agents/*.conf`, `policy/*.md`, `*.local.md`, harvester/SOP,
|
||||
`tools/_lib/credentials.json`.
|
||||
- Stale comment `update-checker.ts:492` claims `*.local` preserved — PRESERVE_PATHS has no such entry.
|
||||
- TS path `file-adapter.ts:157` → `file-ops.ts:66` `syncDirectory` = non-destructive copy-overlay, BUT
|
||||
its preserve list (`file-adapter.ts:164`) already DRIFTED from install.sh (missing `fleet/backlog`,
|
||||
`fleet/roles.local`). Evidence for single shared manifest SSOT.
|
||||
- Existing snapshot (`install.sh:76`) = /tmp, crash-trap only, deleted on success → inadequate; no
|
||||
`mosaic restore`.
|
||||
- `fleet-reconciler.ts:93,234` already has `regenerate-projections-from-roster` phase separate from
|
||||
lifecycle → `mosaic fleet regen` = thin projection-only wrapper (no restart), no FCM-M4/M5 preemption.
|
||||
|
||||
### Design decisions
|
||||
- **(b)** Invert to allow-list: shared `framework/framework-manifest.json` (framework globs +
|
||||
operatorReserved carve-outs); resolve per-path, deny-wins; **UNKNOWN ⇒ operator (fail-safe)**.
|
||||
Mechanism: drop `--delete`; non-deleting bulk copy + explicit manifest-scoped prune pass (iterate
|
||||
framework globs only → operator/unknown structurally unreachable). Pure prune-planner fn for tests.
|
||||
- **(a)** Snapshot to `~/.local/state/mosaic/backups/pre-update-<ts>/` 0700/0600, retention N=5,
|
||||
post-sync verify+restore, `mosaic restore --list/--from`. No secret values in output.
|
||||
- **(d)** `mosaic fleet regen` projection-only, preview-first, never restart.
|
||||
- HARD GATE test includes a deliberately-unanticipated operator path to prove fail-safe default.
|
||||
- **PR split:** PR1 manifest+guard (root fix, ships alone) → PR2 snapshot/restore (secrev) → PR3
|
||||
regen+docs. PR2/PR3 depend on PR1.
|
||||
|
||||
### Status
|
||||
Design doc written: `docs/design/791-upgrade-config-protection.md`. Sent to MS-LEAD.
|
||||
|
||||
## Session 1 (cont.) — MS-LEAD CONFIRMED → Phase 2 GO
|
||||
All 4 asks approved. Binding conditions:
|
||||
- TDD tests-first, red-first proof per PR; ≥85% new-code; co-located `*.spec.ts`; never `--no-verify`.
|
||||
- HARD GATE test (§2.4, unanticipated sentinel survives byte-identical + mtime unchanged) = MERGE-BLOCKING for PR1.
|
||||
- Manifest-completeness test (§6.2) required.
|
||||
- Bash+TS read ONE shared `framework-manifest.json`; parity test (§6.1) required (closes #631 drift class).
|
||||
- UNKNOWN⇒operator (rule 3) non-negotiable. Keep prune-planner PURE.
|
||||
- `fleet regen`: NEVER restart; dry-run default, `--write` to apply; "never issues restart" test mandatory.
|
||||
- Independent review every PR; PR2 dedicated secrev.
|
||||
- One PR at a time through DAG. Report PR1 exact head + red→green evidence for review commission.
|
||||
|
||||
### Now: implementing PR1 (manifest + resolver + non-deleting sync + scoped prune + guard tests).
|
||||
|
||||
## Session 2 (2026-07-16) — PR1 built, tests-first, red→green proven
|
||||
|
||||
Deviation noted to MS-LEAD in PR: manifest is `framework-manifest.txt` (line-oriented), NOT `.json`.
|
||||
Rationale: keep the bash installer free of a python3/jq dependency. The "ONE shared file, parity-
|
||||
tested" requirement is honored — `manifest-parity.spec.ts` drives the bash resolver as a subprocess
|
||||
and asserts byte-identical ownership vs the TS resolver over 34 probe paths spanning every class.
|
||||
|
||||
### PR1 artifacts
|
||||
- SSOT: `packages/mosaic/framework/framework-manifest.txt` ([framework]/[operator], deny-wins, fail-safe).
|
||||
- TS resolver: `src/framework/manifest.ts` (pure: parse/matchGlob/resolveOwnership/frameworkSubtreeRoots/
|
||||
planPrune) + `manifest.spec.ts` (18 tests incl. planPrune property test + §6.2 completeness).
|
||||
- Bash resolver: `framework/tools/_lib/manifest.sh` (compiled globs → fork-free `manifest_is_framework`;
|
||||
CLI `resolve|subtree-roots|classify`). Sourced by install.sh.
|
||||
- HARD GATE (§2.4): `framework/tools/quality/scripts/test-upgrade-manifest-guard.sh` — keep-mode reseed,
|
||||
10 operator sentinels (incl. unanticipated `unknown-operator-dir/x`, `harvester/sop.md`,
|
||||
`fleet/my-fleet.yaml`) survive byte-identical + mtime-unchanged; retired framework file pruned;
|
||||
secret value absent from output. RED=31 fail (orig install.sh) → GREEN=48 pass (fixed).
|
||||
- install.sh: keep mode now manifest-driven (`sync_framework_keep`, no `--delete`); overwrite unchanged.
|
||||
PRESERVE_PATHS denylist deleted.
|
||||
- TS sync: `file-ops.syncDirectory` gains `isOperatorOwned` guard; `file-adapter.syncFramework` derives
|
||||
it from `loadManifest` — hardcoded (drifted) preservePaths deleted. Fixture uses the REAL manifest.
|
||||
- Parity: `manifest-parity.spec.ts` (§6.1) — bash↔TS agree on 34 paths + subtree roots.
|
||||
- Migration matrix `test-install-migration.sh`: F6 flipped — `my-fleet.yaml` now MUST survive (fail-safe).
|
||||
- CI: new merge-blocking `upgrade-guard` step (`.woodpecker/ci.yml`) runs both bash suites (adds rsync).
|
||||
- update-checker.ts reseed comment corrected to the manifest model.
|
||||
|
||||
### Gates (all green)
|
||||
- `pnpm typecheck` ✓ · `pnpm lint` ✓ · `pnpm format:check` ✓
|
||||
- Full mosaic vitest: 1062 passed (cli-smoke needs `pnpm build` first — build-artifact dep, not this change).
|
||||
- HARD GATE 48/48 · migration 21/21 · parity 3/3 · manifest 18/18 · file-adapter 8/8.
|
||||
|
||||
### PR opened + reported (2026-07-16)
|
||||
- **PR #802** http://git.mosaicstack.dev/mosaicstack/stack/pulls/802 — base `main`@`9745bc3f`,
|
||||
head `34e55d4a` (commit `feat(mosaic): manifest-owned upgrade guard…`). 15 files, +1160/-142.
|
||||
- Reported PR head + red→green evidence to MS-LEAD (web1:mosaic-100); queued (lead busy).
|
||||
Standing by for the independent-review commission at head `34e55d4a`.
|
||||
- **TWO items flagged to MS-LEAD for decision (awaiting reply):**
|
||||
1. Deviation `.txt` vs `.json` — confirm accept (parity-tested) or convert to `.json`+jq.
|
||||
2. `pr-create -i 791` appended `Fixes #791` → would auto-close the tracking issue on PR1 merge
|
||||
while PR2/PR3 remain. Recommended edit to `Part of #791`; awaiting go-ahead to patch PR body.
|
||||
- DO NOT start PR2/PR3 until PR1 merges (DAG; one PR at a time).
|
||||
|
||||
### MS-LEAD ruling → #797 ledger-survival sentinel folded into PR1 (2026-07-16)
|
||||
MS-LEAD ruled both my decisions: (1) `.txt` format ACCEPTED (parity must be strict/merge-blocking incl.
|
||||
format edge cases + negative probe); (2) trailer `Fixes #791`→`Part of #791` APPROVED (patched PR #802
|
||||
body via Gitea API — tracking issue no longer auto-closes on PR1 merge). Plus Mos-ELEVATED merge-blocker
|
||||
(spec `~/agent-work/planning/epic-796/791-ledger-survival-sentinel-SPEC.md`): #797 Runtime Session Ledger
|
||||
must survive upgrade. Two coupled deliverables landed in PR1:
|
||||
- (i) Carve-out: `fleet/run/**` was ALREADY an explicit `[operator]` entry — glob matches the spec's
|
||||
pinned `fleet/run/**` EXACTLY, so NO divergence to route back to planner-opus. Strengthened its comment
|
||||
to name the ledger (`fleet/run/sessions/` events.ndjson + ledger.json) so it is unmistakably load-bearing.
|
||||
- (ii) HARD-GATE sentinel: seeded populated ledger (events.ndjson 3 events + ledger.json node+edge+gen,
|
||||
0600 under 0700) into test-upgrade-manifest-guard.sh sentinels; asserts byte-identical + mtime-unchanged
|
||||
+ dir-perms unchanged. Negative control (retired framework file IS pruned) relabeled explicitly.
|
||||
HARD GATE now 58/58 (was 48).
|
||||
- Decision-1 parity hardening: format-edge fixtures (comments/blanks/whitespace, duplicate+overlapping
|
||||
globs deny-wins, section/glob-ordering independence) + explicit UNKNOWN→operator negative probe, driven
|
||||
through BOTH resolvers via MANIFEST_FILE override. Parity 7/7 (was 3).
|
||||
- RED-FIRST honesty note: the bash ledger sentinel stays GREEN even against the pre-fix installer (the
|
||||
ledger was incidentally safe from the rsync --delete bug; overall pre-fix run 30/58 as expected). The
|
||||
carve-out's TRUE load-bearing value (deny-wins if framework ownership ever broadens to `fleet/**`) is
|
||||
isolated by a dedicated resolver-seam red→green in manifest.spec.ts: WITHOUT `fleet/run/**` operator
|
||||
entry + hypothetical `fleet/**` framework → ledger resolves framework and planPrune DELETES it (RED);
|
||||
WITH the carve-out → deny-wins → operator, unprunable (GREEN). manifest.spec.ts 21/21 (was 18).
|
||||
- Gates all green: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1069 passed · HARD GATE 58/58
|
||||
· migration 21/21. Committing FORWARD on the branch (NOT rebasing 34e55d4a out from under review).
|
||||
|
||||
### MS-LEAD REQUEST CHANGES @ 0a5e703a → B1/B2/B3 fixed red-first (2026-07-16)
|
||||
MS-LEAD returned REQUEST CHANGES (routed merge-blockers satisfied; 2 CRITICAL reliability defects from
|
||||
the commissioned independent review). Fixed forward on the branch, red-first:
|
||||
- **B1 (CRITICAL) — dead ERR trap.** install.sh had `set -euo pipefail` (no `-E`), so the
|
||||
`trap restore_snapshot ERR` never fired for a failure inside sync_framework_keep() (function body) —
|
||||
a mid-sync abort left a half-written target with NO rollback. Fix: `set -Eeuo pipefail` (errtrace) +
|
||||
disarm the trap at the top of restore_snapshot() to prevent re-entrancy. New gate
|
||||
`test-upgrade-rollback.sh`: injects a mid-sync `cp` EACCES (read-only divergent framework file);
|
||||
Part A asserts the shipped installer rolls back (restore message fires AND target byte-identical to
|
||||
pre-upgrade); Part B control strips `-E` and asserts the rollback message does NOT fire (dead trap) —
|
||||
self-verifying red→green. 7/7.
|
||||
- **B2/B3 (CRITICAL) — empty/unreadable/malformed manifest divergence.** Pre-fix: TS `parseManifest('')`
|
||||
returned `{framework:[],operator:[]}` (NO throw) → silent no-op "Installation complete"; bash aborted
|
||||
fragilely (the `_manifest_compile` `"${MANIFEST_OPERATOR[@]:-}"` artifact returned 1 with no message)
|
||||
AND the CLI dispatch swallowed manifest_load's rc (no `|| exit`) so `resolve` exited 0 resolving
|
||||
everything operator. Fix (fail-loud + identical both langs):
|
||||
* TS `parseManifest`: throw on zero framework entries; `loadManifest`: wrap read error →
|
||||
"Cannot read framework manifest …".
|
||||
* bash `manifest_load`: explicit unreadable guard (`[[ ! -r ]]`) + zero-`[framework]` guard, both loud
|
||||
stderr + return 1; `_manifest_compile` gets explicit `return 0` (kills the empty-array artifact);
|
||||
CLI dispatch `manifest_load … || exit 1`.
|
||||
* `finalize.ts`: wrap syncFramework → `spin.stop('Framework sync aborted …')` + rethrow (never falls
|
||||
through to "Installation complete").
|
||||
Tests: manifest.spec.ts +5 fail-closed (empty/comment-only/operator-only/empty-section/missing);
|
||||
manifest-parity.spec.ts +7 failure-mode parity (both reject empty/comment-only/operator-only/
|
||||
empty-section/entry-before-header/unknown-header/missing — TS throws, bash CLI exits non-zero+stderr);
|
||||
HARD GATE +4 end-to-end fail-closed matrices (empty/operator-only/malformed/missing → abort non-zero,
|
||||
manifest error surfaced, every operator sentinel byte-identical). RED proven by reverting
|
||||
manifest.ts+manifest.sh to HEAD → 12 new tests fail; restore → 40/40 green.
|
||||
- **Non-blocking addressed.** MEDIUM install.sh:222 find-empty now warns on a real failure instead of
|
||||
blanket `|| true`. LOW: corrected the "both destructive paths rsync vs cp" overstatement in the HARD
|
||||
GATE header + cp-fallback comment + ci.yml (keep mode is a single cp-based path; the rsync-present vs
|
||||
-absent runs prove rsync-independence). `.pre-constitution.bak` triage: single-shot backup is
|
||||
intentional (reconcile_framework_files backs up once), no change.
|
||||
- Gates: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1081 passed (was 1069, +12) · HARD GATE
|
||||
118/118 (was 58) · rollback 7/7 (new) · migration 21/21. No --no-verify. Rollback test wired into
|
||||
ci.yml upgrade-guard. Committing FORWARD (no rebase of 34e55d4a/0a5e703a).
|
||||
|
||||
### Codex round 2 (pre-push self-review) → blockers A/B + should-fix C fixed red-first (2026-07-16)
|
||||
Before committing round 1 I re-ran codex on the change set; it surfaced two fresh reliability defects
|
||||
and one messaging defect on the SAME rollback/manifest path. Fixed forward, red-first:
|
||||
- **Blocker-A (CRITICAL) — signal trap resumed instead of terminating.** A bash INT/TERM handler that
|
||||
merely `restore_snapshot` (returns) does NOT terminate the script — execution RESUMES past the
|
||||
interrupt, cleans the snapshot and reports success, leaving a partial post-interrupt update. Fix:
|
||||
`trap 'restore_snapshot; exit 1' ERR INT TERM` so both the errtrace (ERR) and signal (INT/TERM) paths
|
||||
exit non-zero. Rollback test Part C: a `cp` shim that `kill -TERM $PPID` mid-sync then succeeds (so
|
||||
set -e never fires and only the signal path governs) → asserts abort non-zero + restore fires + does
|
||||
NOT print "file phase complete"; control strips `exit 1` and asserts the buggy resume-to-success.
|
||||
- **Blocker-B (CRITICAL) — degenerate `[framework]` section resolved everything operator.** A manifest
|
||||
whose framework entries are all empty / bare-dot (`/`, `./`, `.`, `..`) passed the non-empty guard yet
|
||||
yielded zero usable globs → nothing is framework → a keep-mode sync silently no-ops (bash resolved
|
||||
`operator`, exit 0). Fix (both langs, parity): reject when no entry has a char other than `/`/`.` —
|
||||
TS `isUsableFrameworkGlob` = `/[^/.]/.test(normalizeRel(glob))`, throws `ManifestError`; bash mirror
|
||||
loops `[[ "$(_manifest_norm "$_g")" =~ [^/.] ]]`, loud stderr + return 1. Tests: manifest.spec.ts
|
||||
`it.each(['/','./','.','..','/\n./'])` throw; parity +3 `expectBothReject` (root-slash/dot-slash/
|
||||
bare-dot). RED: reverting the guard makes `[framework]\n/` resolve `operator` exit 0.
|
||||
- **Should-fix-C — misleading abort message.** finalize.ts printed one generic "may be partially
|
||||
applied" for every sync failure. A `ManifestError` is a PRE-sync validation abort (manifest is
|
||||
validated before any copy) → nothing was written; conflating it with a mid-copy failure misdirects
|
||||
recovery. Fix: introduce `ManifestError` (exported from manifest.ts, thrown by every fail-closed
|
||||
parse/load path), and classify in finalize.ts — ManifestError → "no files were changed"; any other →
|
||||
"may be partially applied". New co-located `finalize-sync-abort.spec.ts` (3 tests) asserts both
|
||||
branches re-throw the original error + the correct message, and that config writes are never reached.
|
||||
RED proven by collapsing the classification → the ManifestError test fails.
|
||||
- Gates: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1094 (was 1081, +3 finalize-abort;
|
||||
manifest specs already counted) · HARD GATE 193/193 · rollback 14/14 · migration 21/21.
|
||||
|
||||
### Codex round 3 (pre-push self-review) → blockers D1/D2 fixed red-first (2026-07-16)
|
||||
Re-ran codex again; it found two more rollback-path gaps `set -E` cannot catch. Fixed forward, red-first:
|
||||
- **Blocker-D1 (CRITICAL) — `find` scan failures swallowed by process substitution.** Both the overlay
|
||||
copy and the scoped prune consumed `< <(find … -print0)`. Bash does NOT propagate the producer's exit
|
||||
status to the `while`, so an EACCES/I/O failure mid-scan truncates the file list yet leaves the loop
|
||||
exiting 0 → a partial upgrade commits and reports success; the ERR/restore trap never fires. Fix:
|
||||
`_scan_or_die` runs `find … -print0 > "$tmp"` to completion, checks its status, and returns non-zero
|
||||
(→ ERR trap → restore) on failure; both loops now read from the checked temp file. Rollback test
|
||||
Part D: a `find` shim that fails every `-print0` scan → shipped installer aborts non-zero + restores +
|
||||
emits "Could not enumerate framework files" + target byte-identical; control neuters the `# D1-GUARD`
|
||||
`return 1` → find failure swallowed, upgrade wrongly reports "file phase complete", no rollback.
|
||||
- **Blocker-D2 (CRITICAL) — silent `set -e` exit on a failed target reset.** restore_snapshot did a bare
|
||||
`rm -rf "$TARGET_DIR"; mkdir -p "$TARGET_DIR"` (trap disarmed, under set -e). If `rm`/`mkdir` fails —
|
||||
possibly after `rm` deleted part of the target — the script exits immediately, skipping the cp AND the
|
||||
recovery pointer, leaving a half-removed target and an orphaned snapshot the operator can't locate.
|
||||
Fix: `if ! rm -rf … || ! mkdir -p …; then fail "Snapshot restore could not reset … preserved at:
|
||||
$SNAPSHOT_DIR — copy it back …"; return 1; fi` (tested like the cp -a check; snapshot NOT deleted).
|
||||
Rollback test Part E: cp-poison triggers restore + an `rm` shim fails `rm -rf <TARGET>` → shipped
|
||||
emits the recovery pointer, the named snapshot dir survives, secret value never leaked; control deletes
|
||||
the recovery line → operator gets no pointer. RED: reverting D1+D2 → 7 shipped/control assertions fail.
|
||||
- Gates: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1094 · HARD GATE 193/193 ·
|
||||
rollback 28/28 (was 14, +14 for D1/D2 with controls) · migration 21/21. shellcheck clean on new lines.
|
||||
No --no-verify. Committing FORWARD (no rebase of 34e55d4a/0a5e703a).
|
||||
|
||||
## Session 3 (2026-07-16) — PR1 MERGED, starting PR2 (durable snapshot + restore + secrev)
|
||||
PR1 (#802) squash-merged → main `32a0ffba`; issue #791 stays open (3-PR DAG umbrella). Independent Opus
|
||||
adversarial/security review APPROVED at head `af627e75` (Gitea RoR cmt 17892); lead ran rollback 28/28 +
|
||||
HARD GATE 193/193 green; CI #1877 green. PR2 UNBLOCKED.
|
||||
|
||||
PR2 branch: `feat/791-pr2-snapshot-restore` off `origin/main` 32a0ffba. Same treatment applies:
|
||||
tests-first red-first, independent review + durable Gitea Reviewer-of-Record comment BEFORE MS-LEAD runs
|
||||
the queue guard/merge. Report PR2 number + exact head when ready. PR body: `Part of #791` (NOT Fixes).
|
||||
|
||||
### PR2 scope (ratified §3/§5 of design doc, Mos-approved — do NOT re-litigate)
|
||||
- **(a) Durable pre-update snapshot** to `${XDG_STATE_HOME:-~/.local/state}/mosaic/backups/pre-update-<UTC-ts>/`
|
||||
— OUTSIDE ~/.config/mosaic and any repo. Perms dir 0700 / files 0600 (umask 077 + explicit chmod).
|
||||
Scope = operator-owned surface that EXISTS (operatorReserved paths), not the framework tree. Taken
|
||||
BEFORE any mutation. Retention N=5 (`MOSAIC_BACKUP_RETENTION`), prune older.
|
||||
- **Post-sync verify + selective restore**: diff operator surface vs snapshot; (b) should never touch
|
||||
operator paths, so ANY diff = manifest bug → restore affected paths + warn loudly. (a) catches a (b) miss.
|
||||
- **`mosaic restore`** (TS CLI): `--list` (default, dry-run) enumerates snapshots by ts; `--from <ts>`
|
||||
restores over operator surface, confirmation-gated. Counts/paths only.
|
||||
- **Secret-safety (secrev)**: snapshot/restore NEVER emit file contents; only paths/counts. Tests assert
|
||||
0700/0600 AND that a secret value seeded in tools/_lib/credentials.json never appears in any output.
|
||||
|
||||
### PR2 implementation status (2026-07-16, ready-for-review)
|
||||
All three tasks implemented, red-first proven, unit-green:
|
||||
- **Task #10 — durable snapshot (install.sh)**: `backup_root()`/`enumerate_operator_files()`/
|
||||
`prune_durable_snapshots()`/`make_durable_snapshot()` wired into keep-mode main() after `manifest_load`,
|
||||
before any mutation. umask 077 + explicit chmod 700/600. UTC ts, collision suffix. FAIL-OPEN (a backup
|
||||
failure never aborts the upgrade it protects). Retention `MOSAIC_BACKUP_RETENTION` (default 5), in-place
|
||||
`sort -r -o` prune (no `mv` — stays inside the rsync-absent coreutils whitelist).
|
||||
- **Task #11 — post-sync verify net (install.sh)**: `verify_operator_surface()` runs after sync (trap
|
||||
disarmed), `cmp -s` each snapshot file vs target; restores any diverged/missing operator file + warns
|
||||
loudly (a divergence = manifest bug). VERIFY-NET wired before `cleanup_snapshot`.
|
||||
- **Task #12 — `mosaic restore` (TS)**: `src/commands/restore.ts` + co-located spec (19 tests).
|
||||
`--list` default (dry-run enumerate), `--from <ts>` confirmation-gated restore, `--dry-run`, `--yes`/
|
||||
`MOSAIC_ASSUME_YES`. Injectable `confirm` for testability (proceed/decline/env-bypass covered). Restored
|
||||
files forced 0600. Registered in `cli.ts`. Path convention mirrors install.sh `backup_root()`.
|
||||
- **CI**: `.woodpecker/ci.yml` upgrade-guard runs the new `test-upgrade-durable-snapshot.sh` gate.
|
||||
- **Gates green**: typecheck ✓ lint ✓ format:check ✓ · full mosaic vitest 1241 (+5) ·
|
||||
durable-snapshot 26/26 · manifest-guard 193/193 · rollback 28/28 · migration 21/21.
|
||||
Est. new-code coverage ≈93% (only the interactive readline default + process.exit-on-error uncovered).
|
||||
- Regression fixed: PR2's `date`/`sort`/`mv` broke the rsync-absent manifest-guard PATH whitelist →
|
||||
made date/sort fail-open, replaced `mv` with in-place `sort -o`, added `date sort` to the test whitelist
|
||||
+ isolated `XDG_STATE_HOME`. All 193 manifest-guard assertions green under restricted PATH.
|
||||
- Codex code-review + security-review (secrev) run on the uncommitted diff before commit.
|
||||
|
||||
### PR2 review round 1 — findings + remediations (2026-07-16, pre-PR)
|
||||
Codex code-review returned **request-changes** (1 blocker + 3 should-fix); Codex security-review returned
|
||||
**high** (1 high + 1 medium). Deduped to 5 distinct defects, ALL legitimate, ALL fixed FORWARD, each with
|
||||
a red-first regression test whose control neuters exactly the guard under test:
|
||||
|
||||
- **A · BLOCKER — verify net undid the legacy bin/ migration (install.sh).** On a pre-v2 install `bin/**`
|
||||
is operator-classified, so the durable snapshot captured it; `run_migrations()` deletes bin/ on purpose,
|
||||
but `verify_operator_surface()` then saw it "missing" and healed it back — the migration would be silently
|
||||
undone forever once the version stamps. **Fix:** `MIGRATION_REMOVED_PATHS[]` recorded by run_migrations
|
||||
(`bin`,`rails`) + `is_migration_removed()` skip in the verify loop (`# MIGRATION-SKIP-GUARD`).
|
||||
**Test:** Part 6 — v1 fixture with bin/; shipped keeps it removed + stamps v3; control (guard stripped)
|
||||
wrongly restores bin/tool.sh.
|
||||
- **B · HIGH (CWE-59) — restore/verify wrote secrets THROUGH a symlink (install.sh + restore.ts).** An
|
||||
attacker swapping an operator path (e.g. tools/_lib/credentials.json) for a symlink after the snapshot
|
||||
would make `cp`/`copyFileSync` write the snapshot's secret out through the link. **Fix (bash):** refuse a
|
||||
symlinked ancestor (`has_symlinked_parent`), drop a symlinked leaf before restore
|
||||
(`# SYMLINK-LEAF-GUARD`). **Fix (TS):** reuse audited `secure-file.ts` — `assertCanonicalContainment`
|
||||
+ `ensureManagedDirectory` on every dst, open the leaf `O_NOFOLLOW|O_CREAT|O_TRUNC` 0600 (ELOOP =
|
||||
fail-closed). **Tests:** Part 7 (shipped leaves external exfil target untouched, restores a real 0600
|
||||
file; control leaks the secret through the link) + restore.spec symlinked-leaf/ancestor cases (red-first).
|
||||
- **C · MEDIUM/should-fix (CWE-22) — `--from` traversal escaped the backup root (restore.ts).**
|
||||
`join(root, from)` accepted `../poison`. **Fix:** validate the selector against
|
||||
`^\d{8}T\d{6}Z(?:-\d+)?$`, build exactly `join(root,'pre-update-'+ts)`, `lstat` (reject symlinked snap
|
||||
dir). **Test:** restore.spec `it.each` of 6 malformed selectors + `--from ../poison` fail-closed (red-first).
|
||||
- **D · should-fix — verify `mkdir -p` unguarded under set -e (install.sh).** A parent replaced by a
|
||||
regular file aborted the installer before the recovery pointer printed. **Fix:** guard `mkdir -p`, warn
|
||||
+ `continue` on failure (keeps healing remaining files).
|
||||
- **E · should-fix — snapshot `umask 077` leaked process-global (install.sh).** Later sync copies/dirs
|
||||
inherited 0600/0700. **Fix:** save `old_umask`, restore on EVERY return path (`# UMASK-RESTORE-NORMAL`).
|
||||
**Test:** Part 8 — synced framework file is 0644 while the secret backup stays 0600; control (restore
|
||||
stripped) makes the synced file 0600.
|
||||
|
||||
**Full gate suite re-run after fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic
|
||||
vitest **1252** · restore.spec **30** · durable-snapshot **41** · manifest-guard 193 · rollback 28 ·
|
||||
migration 21. shellcheck clean on all new lines; new test markers mirror the existing `# VERIFY-NET`
|
||||
anchor convention. NOTE: codex self-review does NOT satisfy the independent-review gate — an independent
|
||||
(author≠reviewer) review + durable Gitea Reviewer-of-Record comment is still required before MS-LEAD merges.
|
||||
|
||||
## Session 4 (2026-07-16) — PR2 MERGED, PR3 built (fleet regen — recovery layer)
|
||||
PR2 (#811) squash-merged → main `31607a4a`; issue #791 stays open (final PR of the 3-PR DAG). Independent
|
||||
exact-head RoR at `d12c5f78` APPROVE (Gitea cmt 17904); #1882 green; busybox-portable Part 7 control fix
|
||||
verified in-Alpine. PR3 UNBLOCKED.
|
||||
|
||||
PR3 branch: `feat/791-pr3-fleet-regen` off `origin/main` 31607a4. Same discipline: tests-first red-first,
|
||||
independent review + durable Gitea RoR BEFORE MS-LEAD runs the queue guard/merge. PR body `Part of #791`.
|
||||
|
||||
### PR3 scope (ratified §4/§7 of design doc) — `mosaic fleet regen`
|
||||
Projection-only recovery command: rebuilds each `fleet/agents/<name>.env.generated` from `roster.yaml`
|
||||
(SSOT). Dry-run default; `--write` applies; `--json` machine output. Structural guarantee: NO code path to
|
||||
systemd lifecycle — **never restarts an agent**. Single-SSOT: reuses `projectRosterV2AgentGeneratedEnv`
|
||||
(extracted, shared with the reconciler apply path) so regen and reconcile cannot drift. Secrev: paths +
|
||||
counts only, never the rendered KEY=value body.
|
||||
|
||||
New files: `commands/fleet-regen-command.ts` (+ `.spec.ts`), guide `docs/guides/upgrade-safety-and-recovery.md`
|
||||
(three-layer model: PR1 manifest ownership → PR2 snapshot/restore → PR3 regen; do-NOT-restart-before-verify
|
||||
runbook), regen reference added to `docs/guides/fleet-local-canary.md`. Wired in `commands/fleet.ts`.
|
||||
|
||||
### Independent review (3 reviewers: subagent code-reviewer + codex code-review + codex security) → 4 fixes, red-first
|
||||
- **A · BLOCKER (codex) — regen mutated/deleted legacy operator env.** `applyPreparedAgentEnvironmentProjection`
|
||||
also writes `.env.local`/`.env.quarantine` and unlinks legacy `.env`. Violated projection-only contract.
|
||||
**Fix:** NEW generated-only boundary primitives `prepareGeneratedAgentEnvironmentProjection` +
|
||||
`applyPreparedGeneratedAgentEnvironmentProjection` (write ONLY `<name>.env.generated`). regen now has no
|
||||
code path that touches `.env`/`.env.local`/`.env.quarantine`. **Test:** projection-only leaves legacy `.env`
|
||||
verbatim, no local/quarantine fabricated.
|
||||
- **B · should-fix (codex + subagent + security) — partial write on mid-loop failure.** Interleaved
|
||||
prepare/apply left earlier agents written when a later agent failed prepare. **Fix:** PREPARE ALL agents
|
||||
before writing ANY (mirrors reconciler `defaultPrepareProjections`). **Test:** 2nd agent's projection
|
||||
pre-seeded 0644 → prepare rejects → coder0 NOT written, exit 1.
|
||||
- **C · subagent — semantic-validation bypass.** Default readRoster skipped `validateRosterV2Semantics`, so
|
||||
a tampered protected-class `tool_policy` would be silently projected. **Fix:** default readRoster now runs
|
||||
`validateRosterV2Semantics` (persona resolution + protected-class match), rolesDir/overrideDir defaults
|
||||
mirroring the reconciler. **Test:** merge-gate agent w/ tool_policy=code → fails closed, no write.
|
||||
- **D · MEDIUM (codex security, CWE-362) — concurrent-reconcile race.** regen `--write` wrote without the
|
||||
reconcile lock. **Fix:** `--write` acquires `acquirePrivateReconcileLock(mosaicHome)` for the whole
|
||||
read-prepare-apply sequence, released in `finally`; dry-run stays lock-free. **Test:** pre-held lock →
|
||||
regen fails closed, no write.
|
||||
|
||||
**Gate suite after fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest **1265**
|
||||
(regen spec 13, incl. 4 new red-first regressions). NOTE: codex self-review does NOT satisfy the
|
||||
independent-review gate — an independent (author≠reviewer) review + durable Gitea RoR is still required
|
||||
before MS-LEAD merges. STOP at PR-open for MS-LEAD's exact-head review; do NOT self-merge.
|
||||
|
||||
## Session 5 — PR3 review round 2 (finding L + M1/M2/M3), red-first fixes
|
||||
|
||||
Second review pass on the lock-cleanup plumbing surfaced one round-1 residual (L) and three round-2
|
||||
findings (M1 blocker, M2/M3 should-fix). All fixed red-first (RED proven per-finding, then GREEN).
|
||||
|
||||
- **L · should-fix (codex r1) — mutation-lock release swallowed unlink failures.** regen's
|
||||
`acquirePrivateRosterMutationLock` release copied CRUD's `unlink().catch(()=>{})`, hiding a stale
|
||||
`roster.yaml.mutation.lock`. **Fix:** its release PROPAGATES the unlink fault (finding-J stale-lock
|
||||
warning then fires for this lock too). **Test:** acquire real lock, `rm` it, assert `release()` rejects.
|
||||
- **M1 · BLOCKER (codex r2) — replacement-lock race.** The propagating release from L did an
|
||||
UNCONDITIONAL `unlink(lockPath)` without proving ownership. If the lock is cleared + re-created by
|
||||
another writer mid-op, regen deletes the STRANGER's live lock → a third writer enters → mutual
|
||||
exclusion defeated. **Fix (reuse, not reimplement):** generalized the reconciler's ownership-proving
|
||||
lock body into shared `acquirePrivateManagedRosterLock(mosaicHome, lockLeaf, busyMessage, openLock)`;
|
||||
`acquirePrivateReconcileLock` delegates to it (behavior-identical: same leaf/codes/messages), and a NEW
|
||||
hardened `acquirePrivateRosterMutationLock` (now in fleet-reconciler.ts, leaf `roster.yaml.mutation.lock`)
|
||||
records dev/ino + ownership token and RE-PROVES ownership (`assertLockOwnership`) before unlinking —
|
||||
fails closed as `lock-cleanup-failed` if replaced. Removed the crud-based export; reverted
|
||||
`acquireMutationLock` (fleet-agent-crud.ts) to its original inline empty-file/swallowing-release form
|
||||
(CRUD behavior intentionally unchanged). Compatibility: CRUD empty-file `wx` and regen tokened `wx`
|
||||
contend on the same path but never co-own (wx winner owns; loser → concurrent-mutation), so the token
|
||||
is only ever read back by the same regen invocation. **Test:** acquire, `rm`+recreate lock (new inode),
|
||||
assert `release()` rejects AND the replacement survives (not unlinked).
|
||||
- **M2 · should-fix (codex r2) — acquire-unwind fault dropped.** The acquire-failure catch discarded
|
||||
`releaseFleetLocks`' return (a possible fault on the already-held first lock). **Fix:** capture and
|
||||
augment — `const releaseFault = await releaseFleetLocks(releases); throw augmentWithLockCleanupFault(error, releaseFault);`
|
||||
(symmetric to finding J). **Test:** mutation lock acquires w/ faulting release + reconcile acquire
|
||||
throws → thrown error mentions stale/lock, nothing written.
|
||||
- **M3 · should-fix (codex r2 + subagent REQUEST-CHANGES) — cleanup warning named only reconcile lock.**
|
||||
Finding L made the mutation-lock release fault reachable, so the `cleanup` marker can originate from
|
||||
EITHER lock. **Fix:** `formatFleetRegenReport`'s WARNING now names BOTH `roster.yaml.mutation.lock` and
|
||||
`roster.yaml.reconcile.lock`, matching `augmentWithLockCleanupFault`. **Test:** fault the mutation-lock
|
||||
release specifically → report names both lock files.
|
||||
|
||||
**Refactor note (no cycle):** neither fleet-reconciler nor fleet-agent-crud imports the other; regen
|
||||
imports lock acquirers from fleet-reconciler and the projection mapping from fleet-reconciler. The two
|
||||
reconcile-lock reviewers reconciled: independent reviewer validated acquire-time empty-file compatibility
|
||||
(preserved), codex flagged RELEASE-time replacement race (closed by ownership proof) — non-contradictory.
|
||||
|
||||
**Gate suite after fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest **1275**
|
||||
(regen spec 23, incl. 7 red-first lock regressions E/F/G/K/L/M1/M2/M3). RED proven per-finding by
|
||||
temporary revert before re-applying each fix. Independent (author≠reviewer) review of M1/M2/M3 + codex
|
||||
code/security re-run in flight. STOP at PR-open for MS-LEAD's exact-head review + durable Gitea RoR; do
|
||||
NOT self-merge; #791 umbrella stays OPEN; PR body `Part of #791`.
|
||||
|
||||
### Round 3 review (after M1/M2/M3) — independent review PASS + codex residual-TOCTOU disposition
|
||||
Three reviewers on the post-M1/M2/M3 head:
|
||||
- **Independent (subagent, author≠reviewer) — PASS.** Verified M1/M2/M3 all correctly fixed; "never
|
||||
restarts" is STRUCTURAL (runner never referenced in executable code); no secrets; no deadlock (only
|
||||
regen holds both locks); tests meaningful (assert inode preservation + exact lock-file names). Raised:
|
||||
- **should-fix #1 (fixed, red-first):** generalizing the lock helper left `assertSafeLockLeafIfPresent`/
|
||||
`assertLockOwnership` hardcoding "reconciliation lock" in thrown messages → a MUTATION-lock fault
|
||||
misreported as the reconcile lock, undercutting M3's accurate-diagnosis goal. **Fix:** thread
|
||||
`lockLabel = fleet/<leaf>` through both helpers + the generic lock-io messages, so every fault names
|
||||
the actual lock file. Red-first: strengthened the M1 test to assert `/roster\.yaml\.mutation\.lock/`
|
||||
(RED: got "reconciliation lock"; GREEN after). Also resolves nit #3 (generic-message drift).
|
||||
- **nit #2 (fixed):** `FleetRegenResult.cleanup` JSDoc still said "the shared reconcile lock"; now names
|
||||
both locks (regen holds both).
|
||||
- **nit #4 (fixed):** removed the redundant duplicate `assertLockOwnership` call before unlink
|
||||
(pre-existing in merged main; harmless but dead — dropped since the fn was already being touched).
|
||||
- **Codex security — clean (risk: none).** Validates roster semantics, constrains env values, no shell
|
||||
eval, no secret output, generated-only writes, serialized against both locks.
|
||||
- **Codex code — request-changes, 1 "blocker": residual check-then-unlink TOCTOU.** Between the final
|
||||
`assertLockOwnership` and the path-based `unlink`, an external actor could vacate our inode and a new
|
||||
writer grab the path, so the unlink deletes the stranger's lock. **Disposition: documented known
|
||||
limitation, NOT fixed in PR3.** Rationale: (1) byte-identical to the MERGED, shipped reconcile-lock
|
||||
release on origin/main (fleet-reconciler.ts L654-659) — not introduced here; (2) UNREACHABLE within the
|
||||
`wx` writer protocol — no Mosaic writer removes a lock it doesn't own (wx fails EEXIST while our inode
|
||||
exists), so only external interference can vacate our inode in the sub-instruction window; (3) the
|
||||
ownership guard DOES close the reachable case (stale-lock reaper/operator cleared our lock + another
|
||||
writer took it BEFORE release began → fail closed, don't delete stranger's lock); (4) the true atomic
|
||||
fix — fd-held advisory lock (flock/lockf) adopted by ALL fleet writers (CRUD + reconcile + regen) — is
|
||||
a cross-cutting mechanism change touching merged CRUD + reconciler, out of scope for a projection-only
|
||||
recovery PR. Documented honestly in the acquirer doc + M1 test comment. **The binding independent
|
||||
review did NOT treat this as a blocker.** Recommendation to MS-LEAD: proceed to PR-open + spin a
|
||||
SEPARATE follow-up issue for the fd-advisory-lock migration; MS-LEAD adjudicates scope at exact-head
|
||||
review (merge authority).
|
||||
|
||||
**Gates after round-3 fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest
|
||||
**1275** (regen spec 23). Fresh codex code re-run in flight to confirm no NEW issues from the label fix.
|
||||
|
||||
---
|
||||
|
||||
## Session 6 — Round 4/5 convergence (stranded-lock robustness)
|
||||
|
||||
**Two independent reviewers converged on the SAME should-fix** on the init-failure cleanup path,
|
||||
strengthening confidence it was real:
|
||||
|
||||
- **Codex code-review-5 — 0 blockers, 1 should-fix.** "Stat failure after lock creation strands the new
|
||||
lock." When `handle.stat()` ITSELF fails right after the `wx` create (transient EIO/EBADF), `created`
|
||||
is `undefined`, so `removeOwnedLockLeafBestEffort` had `if (!created) return;` → no cleanup → the
|
||||
just-created `roster.yaml.mutation.lock`/`reconcile.lock` is stranded, permanently blocking future
|
||||
regen + CRUD. (Notably NO blocker, and the TOCTOU is no longer flagged in code-review as of r5.)
|
||||
- **Independent delta reviewer (author≠reviewer, pr-review-toolkit) — no blockers, same should-fix.**
|
||||
Independently flagged the identical `!created` gap; validated FIX 1 (label threading — no call site
|
||||
missed, codes unchanged, no test depended on old text) and FIX 2 (dev/ino-guarded cleanup, best-effort,
|
||||
happy-path release reuses captured dev/ino) as correct. Suggested an unconditional best-effort unlink
|
||||
in the `!created` branch; I took the **safer** variant below.
|
||||
- **Codex security-review-5 — 0 crit / 0 high / 1 medium.** The single medium is the SAME residual
|
||||
check-then-unlink TOCTOU already dispositioned in round 3 (its own remediation = "migrate every writer
|
||||
to an fd-held advisory lock" = the follow-up issue). No new security finding. No secrets.
|
||||
|
||||
**Fix (red-first, safer than an unconditional unlink):** thread the persisted random `token` into
|
||||
`removeOwnedLockLeafBestEffort`. Two independent ownership proofs now: primary dev/ino (unchanged), and a
|
||||
**fallback** when the post-create stat failed — read the leaf and unlink ONLY if its content equals our
|
||||
`randomUUID()` token. Only OUR lock carries that token, so a CRUD (empty) or differently-tokened
|
||||
replacement is never deleted. `tokenPersisted` guards passing the token (only after `writeFile` lands).
|
||||
Doubly-degenerate case (stat fails AND token write never landed) leaves the lock in place rather than
|
||||
risk deleting a stranger's file — requires two independent fs faults on a just-created fd; documented.
|
||||
|
||||
- **Red-first proof:** new test `does not strand the lock file when the post-create stat itself fails`
|
||||
injects a real `wx` create + a Proxy handle whose `stat()` rejects (writeFile/close succeed), asserts
|
||||
`exists(lockPath) === false`. RED before fix (`expected true to be false` — lock stranded); GREEN after.
|
||||
- **Also fixed (delta nit #3):** `fleet-regen-command.ts` `acquireRosterMutationLock` JSDoc said "CRUD's
|
||||
private lock"; the default is the reconciler's hardened ownership-proving acquirer for the same
|
||||
`fleet/roster.yaml.mutation.lock` path. Corrected.
|
||||
- **PR-description note (delta nit #2):** FIX 1 also collapsed a pre-existing duplicate back-to-back
|
||||
`assertLockOwnership` call in the release closure (identical args, no intervening logic) into one — a
|
||||
no-op simplification of merged code, not a behavior change. Called out so a future reader doesn't
|
||||
wonder if the duplicate had a purpose.
|
||||
|
||||
**Gates after round-4 fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest
|
||||
**1277** (regen spec now 25: +1 stat-failure stranded-lock regression). Residual TOCTOU still deferred to
|
||||
the fd-advisory-lock follow-up issue; MS-LEAD adjudicates scope at exact-head review (merge authority).
|
||||
|
||||
---
|
||||
|
||||
## Session 6 — Round 6 (persona-root wiring)
|
||||
|
||||
**Codex code-review-6 — 0 blockers, 1 should-fix (NEW, distinct from the lock work).** "Forward
|
||||
configured persona directories to regen." `registerFleetRegenCommand` was registered at
|
||||
`fleet.ts:2069` with only `{ runner, mosaicHome }`, discarding `deps.reconcileDeps.rolesDir` /
|
||||
`overrideDir`. The regen command ALREADY has those seams (validates roster semantics via
|
||||
`validateRosterV2Semantics({ rolesDir, overrideDir })`, defaulting to `<mosaicHome>/fleet/roles{,.local}`),
|
||||
but the top-level wiring never forwarded the configured roots. **Impact:** in a deployment with custom
|
||||
persona roots, `fleet reconcile` (which honors the overrides) would ACCEPT a roster while `fleet regen`
|
||||
REJECTS the same roster (persona resolution against the wrong default dir) — blocking the recovery
|
||||
command and violating the documented "resolves personas the SAME way reconcile does" contract.
|
||||
|
||||
**Fix (red-first):** forward `rolesDir`/`overrideDir` from `deps.reconcileDeps` into
|
||||
`registerFleetRegenCommand` at `fleet.ts:2069`. Red-first test `forwards configured persona roots
|
||||
(rolesDir/overrideDir) from reconcileDeps into regen`: seeds personas ONLY under a custom root, leaves
|
||||
the default `<home>/fleet/roles` empty, registers with `reconcileDeps: { rolesDir, overrideDir }`, and
|
||||
requires `fleet regen` to SUCCEED. RED before fix (`expected 1 not to be 1` — regen validated against the
|
||||
empty default and exited 1); GREEN after.
|
||||
|
||||
**Codex security-review-6 — 0 crit / 0 high / 1 medium.** Same residual check-then-unlink TOCTOU, now
|
||||
noted at BOTH the release closure and the init-cleanup path; remediation = fd-held advisory lock across
|
||||
all writers = the SAME deferred follow-up item. No new security finding, no secrets.
|
||||
|
||||
**Independent confirmation review of the token-fallback fix (Session 6/round 4) — PASS, no findings.**
|
||||
All 7 verification points confirmed; reviewer mechanically reverted `removeOwnedLockLeafBestEffort` to
|
||||
the pre-fix `if (!created) return;` and re-ran the new test → RED (`expected true to be false`),
|
||||
confirming the test genuinely pins the fix; restored after. No lint/type issues; doc-comment accurate.
|
||||
|
||||
**Gates after round-6 fix (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest
|
||||
**1278** (regen spec now 26: +1 persona-root wiring regression).
|
||||
|
||||
---
|
||||
|
||||
## Session 6 — Round 7 convergence (review CLOSED for PR-open)
|
||||
|
||||
- **Codex code-review-7 — 0 blockers, 1 should-fix = the residual TOCTOU** (previously a "blocker" in r3,
|
||||
dropped in r4/r5, now re-surfaced as a should-fix). **Codex security-review-7 — 0 crit / 0 high /
|
||||
1 medium = the SAME residual TOCTOU.** Codex has CONVERGED: the only remaining finding across both
|
||||
streams is that one race, whose own remediation is "fd-held advisory lock shared by all fleet writers"
|
||||
= the deferred follow-up. No new distinct finding; the wiring fix introduced nothing.
|
||||
- **Independent confirmation review of the persona-root wiring fix — PASS, no findings.** Reviewer
|
||||
mechanically reverted the two forwarded lines → RED (`Roster v2 agent "coder0" class "code" does not
|
||||
resolve to a readable persona` → exit 1), restored → GREEN (26 regen + 204 fleet tests). Confirmed the
|
||||
optional-chaining fallback preserves default-deployment behavior and no type/lint issue.
|
||||
|
||||
**Review disposition for PR-open:** ALL actionable findings fixed red-first across rounds 3–6 (label
|
||||
threading, stranded-lock on init failure, stat-failure strand, persona-root wiring). The residual
|
||||
check-then-unlink TOCTOU is the ONLY open item and is DEFERRED to a follow-up issue (fd-advisory-lock
|
||||
migration across CRUD + reconcile + regen) — byte-identical to merged origin/main's reconcile-lock
|
||||
release, unreachable within the `wx` writer protocol (no Mosaic writer removes a lock it doesn't own;
|
||||
only external `rm`/a stale-lock reaper can vacate the inode mid-release), and its true fix is a
|
||||
cross-cutting mechanism change out of scope for a projection-only recovery PR. Two independent human-agent
|
||||
reviews (author≠reviewer) treated it as non-blocking. MS-LEAD adjudicates scope at exact-head review
|
||||
(merge authority); recommendation = proceed to PR-open + spin the follow-up issue.
|
||||
|
||||
**Final gates (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest **1278**
|
||||
(regen spec 26). No secret values in any snapshot/projection/report output (counts + paths only). Regen
|
||||
NEVER issues a lifecycle/restart call (load-bearing recordingRunner gate). STOP at PR-open for MS-LEAD's
|
||||
exact-head review + durable Reviewer-of-Record before any merge; do NOT self-merge.
|
||||
@@ -1,86 +0,0 @@
|
||||
# Issue #804 — fail closed on unknown installer arguments
|
||||
|
||||
## Objective
|
||||
|
||||
Implement Part 1 of Gitea issue #804 only: `tools/install.sh` must reject every unrecognized flag or argument with an actionable STDERR error and nonzero exit before installation starts.
|
||||
|
||||
## Scope and constraints
|
||||
|
||||
- Preserve all currently recognized options and behavior, including `-y` and `--ref <branch>`.
|
||||
- No positional arguments are currently accepted by the parser.
|
||||
- Do not add `--next`, `MOSAIC_NEXT`, prerelease routing, or any Part 2 behavior.
|
||||
- TDD is mandatory: add and observe a failing process-level regression test before changing `tools/install.sh`.
|
||||
- Worker lifecycle ends after branch push, PR creation, and coordinator notification; do not merge or close #804.
|
||||
- Existing launcher-owned changes in `.mosaic/orchestrator/mission.json` and `.mosaic/orchestrator/session.lock` are out of scope and must not be committed.
|
||||
|
||||
## Requirements and acceptance criteria
|
||||
|
||||
- Unknown input names the offending argument on STDERR.
|
||||
- STDERR includes a short installer usage hint.
|
||||
- Exit status is nonzero.
|
||||
- The installer does not invoke npm or otherwise proceed into installation.
|
||||
- Existing recognized flags remain unchanged.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add a process-level Vitest regression using the installer test location under `packages/mosaic/src/commands/`.
|
||||
2. Run the focused test and record the expected RED failure.
|
||||
3. Commit the RED test as `test(#804): ...`.
|
||||
4. Replace the parser catch-all with a fail-closed STDERR error and usage hint.
|
||||
5. Update concise installer-facing documentation without introducing prerelease behavior.
|
||||
6. Run focused tests, shell syntax validation, package tests, lint, typecheck, and format checks.
|
||||
7. Run independent review tooling and remediate findings.
|
||||
8. Commit as `fix(#804): ...`, queue-guard, push, open a PR containing `Closes #804.`, notify the coordinator, and exit.
|
||||
|
||||
## Budget
|
||||
|
||||
- No explicit token cap supplied.
|
||||
- Working estimate: 8K tokens; narrow two-file behavior/test change plus concise docs and delivery gates.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-07-17: Loaded mission state, issue #804, delivery/QA/documentation rails, and relevant TDD/Vitest/pnpm/Gitea skills.
|
||||
- 2026-07-17: Confirmed the parser has no legitimate positional arguments and currently drops all unmatched input via `*) shift ;;`.
|
||||
- 2026-07-17: Installed locked workspace dependencies with a worktree-local pnpm store; no lockfile changes.
|
||||
- 2026-07-17: Added the process-level unknown-argument regression with an isolated `$HOME` and npm shim.
|
||||
- 2026-07-17: Replaced the silent catch-all with STDERR error + usage output and exit 2 before preflight or installation.
|
||||
- 2026-07-17: Initial Codex code review found an unknown option could still be consumed as the `--ref` value. Added a second RED reproducer, then rejected option-shaped/missing `--ref` values without changing valid `--ref <branch>` behavior. The review's launcher-state note is handled by excluding both `.mosaic/orchestrator/` files from commits.
|
||||
- 2026-07-17: Updated README, user guide, and packaged framework README with the fail-closed argument contract. No API, auth, admin, sitemap/navigation, or publishing surface changed.
|
||||
|
||||
## Verification
|
||||
|
||||
- RED: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/install-arguments.spec.ts` — expected failure: installer exited `0` instead of nonzero at the exit-status assertion; confirms the test reproduces the silent-drop defect before production changes.
|
||||
- Remediation RED: the added `--cli --ref --bogus` case exited `0`, proving `--ref` could swallow an unknown option before the guard was added.
|
||||
- GREEN: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/install-arguments.spec.ts src/commands/install-heading.spec.ts` — 2 files, 3 tests passed.
|
||||
- Situational process check: unknown positional input exited 2, named the input on STDERR, printed usage, and did not call the npm shim.
|
||||
- `bash -n tools/install.sh` — passed.
|
||||
- Bare `--ref` process check — exited 2 with `Missing value for --ref` and usage.
|
||||
- `pnpm --filter @mosaicstack/mosaic test` — 69 files, 1,287 tests passed; framework shell checks passed. The first attempt lacked generated `dist/cli.js`; `pnpm --filter @mosaicstack/mosaic build` restored the required test precondition and the full rerun passed.
|
||||
- `pnpm lint` — 23/23 tasks passed.
|
||||
- `pnpm typecheck` — 42/42 tasks passed.
|
||||
- `pnpm format:check` — passed.
|
||||
- Codex code re-review against `origin/main` — `approve`, 0 blockers/should-fix/suggestions.
|
||||
- Codex security re-review against `origin/main` — risk `none`, 0 findings.
|
||||
|
||||
## Acceptance evidence
|
||||
|
||||
| Criterion | Evidence |
|
||||
| --- | --- |
|
||||
| Unknown input is named on STDERR | Process-level Vitest assertions for `--bogus`, including after `--ref` |
|
||||
| Short usage hint is printed on STDERR | Vitest usage regex + manual process output |
|
||||
| Exit is nonzero | Vitest status assertions and manual exit 2 |
|
||||
| Installation does not proceed | Isolated npm shim marker remains absent |
|
||||
| Recognized behavior is preserved | Parser cases are unchanged except validation of malformed `--ref`; full Mosaic package suite passed |
|
||||
| Part 2 is excluded | No `--next`, `MOSAIC_NEXT`, dist-tag, or prerelease routing changes |
|
||||
|
||||
## Documentation checklist
|
||||
|
||||
- Current canonical `docs/PRD.md` remains unchanged; issue #804 and the coordinator brief supply this bounded defect's acceptance contract.
|
||||
- Updated installer behavior in root README, user guide, and packaged framework README in the same logical change set.
|
||||
- API/OpenAPI, auth/permissions, admin operations, developer architecture, sitemap/navigation, and external publishing are not affected.
|
||||
- Scratchpad remains under `docs/scratchpads/`; no root-hygiene changes.
|
||||
|
||||
## Risks and blockers
|
||||
|
||||
- Part 2 remains owner-gated under #805 and is intentionally excluded.
|
||||
- No implementation blocker remains. Independent coordinator RoR, CI, merge, and issue closure remain pending after worker handoff.
|
||||
@@ -1,64 +0,0 @@
|
||||
# Issue #807 — GLPI list wrappers accept HTTP 206
|
||||
|
||||
- **Branch:** `fix/807-glpi-206`
|
||||
- **Task:** Gitea issue #807
|
||||
- **Role:** Author-only worker reporting to `mosaic-100`; no self-review or merge
|
||||
- **Started:** 2026-07-16
|
||||
|
||||
## Objective
|
||||
|
||||
Fix the shipped GLPI ticket, computer, and user list wrappers so ranged responses with HTTP 206 Partial Content render successfully while genuine HTTP failures remain non-zero errors.
|
||||
|
||||
## Scope
|
||||
|
||||
- Modify only the three affected list wrappers and a focused shell regression test.
|
||||
- Do not touch `session-init.sh`, `ticket-create.sh`, or `docs/TASKS.md`.
|
||||
- Add task-local delivery evidence here as required by the mission protocol.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add a deterministic shell harness that copies each wrapper beside stubbed `session-init.sh`, credentials, and `curl` boundaries.
|
||||
2. Prove RED against the current 200-only gates: 206 must fail before the implementation change.
|
||||
3. Update all three status gates to accept exactly 200 or 206.
|
||||
4. Prove GREEN for 206 rendering and genuine 401/500 failures, then run repository quality gates.
|
||||
5. Commit with co-author attribution, run the push queue guard, push, and open a PR for independent review and merge by the team lead.
|
||||
|
||||
## Budget
|
||||
|
||||
- No explicit token cap supplied.
|
||||
- Soft estimate: 8K tokens; narrow single-worker execution with no exploratory scope.
|
||||
|
||||
## Progress
|
||||
|
||||
- [x] Mission, task, PRD, QA, documentation, and code-review guidance loaded.
|
||||
- [x] RED regression evidence captured: `test-list-http-status.sh` exited 1; all three wrappers rejected 206 while retaining 401 failures.
|
||||
- [x] Implementation complete.
|
||||
- [x] Relevant tests and repository gates green.
|
||||
- [ ] Commit pushed and PR opened.
|
||||
|
||||
## Tests and evidence
|
||||
|
||||
- RED (before source fix): `packages/mosaic/framework/tools/glpi/test-list-http-status.sh` → exit 1; ticket/computer/user 206 assertions failed, all 401 assertions passed.
|
||||
- GREEN: `bash -n packages/mosaic/framework/tools/glpi/{ticket-list.sh,computer-list.sh,user-list.sh,test-list-http-status.sh}` → pass.
|
||||
- GREEN: `shellcheck packages/mosaic/framework/tools/glpi/test-list-http-status.sh` → pass.
|
||||
- GREEN: `packages/mosaic/framework/tools/glpi/test-list-http-status.sh` → 6 assertions pass (206 renders and 401 errors for all three wrappers).
|
||||
- GREEN: `pnpm typecheck` → 42/42 tasks pass.
|
||||
- GREEN: `pnpm lint` → 23/23 tasks pass.
|
||||
- GREEN: `pnpm format:check` → all matched files pass.
|
||||
- Setup note: initial gate attempts could not start because the fresh worktree lacked dependencies; `pnpm install --frozen-lockfile --store-dir /home/hermes/.local/share/pnpm/store` restored the locked workspace dependencies without lockfile changes.
|
||||
|
||||
## Acceptance criteria mapping
|
||||
|
||||
| Criterion | Evidence |
|
||||
| --- | --- |
|
||||
| HTTP 206 succeeds and renders each ranged list | Focused test's three 206 render assertions pass |
|
||||
| Genuine HTTP failures remain non-zero with existing diagnostics | Focused test's three HTTP 401 assertions pass |
|
||||
| Only affected list wrappers change | Diff contains the three status predicates plus focused test/evidence; session and create wrappers untouched |
|
||||
|
||||
## Documentation decision
|
||||
|
||||
No operator/API documentation change is needed: this restores documented list behavior for a healthy GLPI response without changing command syntax, output, configuration, or public contracts. This task scratchpad records delivery evidence.
|
||||
|
||||
## Risks / blockers
|
||||
|
||||
- Existing dirty `.mosaic/orchestrator/mission.json` and `.mosaic/orchestrator/session.lock` are runtime-owned and will not be edited or committed.
|
||||
@@ -1,37 +0,0 @@
|
||||
# Issue #808 — agent-send sender identity
|
||||
|
||||
## Objective
|
||||
|
||||
Fix cross-socket `agent-send.sh` preambles so replies route to the real sender rather than a destination-socket holder session.
|
||||
|
||||
## Scope and acceptance criteria
|
||||
|
||||
- Prefer exported `MOSAIC_AGENT_NAME` as the authoritative sender session name.
|
||||
- If it is unset, query the sender's local/default tmux socket for `#S` without destination `-L` arguments.
|
||||
- Preserve `?` when sender identity cannot be determined.
|
||||
- Do not alter destination socket dispatch.
|
||||
- Add red-first regressions for all three identity paths.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Extend `agent-send.test.sh` with deterministic fake-tmux coverage.
|
||||
2. Run the test against the unpatched implementation and record RED evidence.
|
||||
3. Apply the minimal sender lookup fix only.
|
||||
4. Run the focused suite and repository quality gates.
|
||||
5. Commit, queue-guard, push, and open an author-only PR for independent review.
|
||||
|
||||
## Constraints and risks
|
||||
|
||||
- Worker lane is author-only: no self-review or merge.
|
||||
- `docs/TASKS.md` and mission state are orchestrator-owned and will not be modified.
|
||||
- Pre-existing runtime changes under `.mosaic/orchestrator/` are excluded from this work.
|
||||
- Budget: no explicit token cap; keep changes limited to the shell tool, sibling regression test, and this scratchpad.
|
||||
|
||||
## Evidence
|
||||
|
||||
- RED: `bash packages/mosaic/framework/tools/tmux/agent-send.test.sh` failed on the unpatched implementation with `PASS=12 FAIL=3`; it selected `destination-holder` instead of both `MOSAIC_AGENT_NAME=authoritative-agent` and local session `local-agent`. The genuinely unavailable sender case already exercised and preserved `?`.
|
||||
- GREEN: `bash packages/mosaic/framework/tools/tmux/agent-send.test.sh` passed with `PASS=15 FAIL=0`; coverage includes env authority, local/default tmux fallback across a destination `-L`, explicit rejection of the destination holder, and `?` fallback.
|
||||
- Syntax: `bash -n packages/mosaic/framework/tools/tmux/agent-send.sh packages/mosaic/framework/tools/tmux/agent-send.test.sh` passed.
|
||||
- Quality gates: `pnpm typecheck` (42/42 tasks), `pnpm lint` (23/23 tasks), and `pnpm format:check` all passed after installing the frozen lockfile dependencies. The first install attempt failed because pnpm's configured store pointed at `/root`; retrying with the existing user-owned store (`--store-dir /home/hermes/.local/share/pnpm/store`) succeeded without changing tracked dependency files.
|
||||
- Documentation: no public API or operator workflow changed; the source comment, regression-test contract, and this implementation record cover the internal bug fix.
|
||||
- Independent review: intentionally pending for the reviewer assigned by `mosaic-100`; this author-only lane will not self-review or merge.
|
||||
@@ -1,58 +0,0 @@
|
||||
# Issue #812 — durable Gitea PR review comments
|
||||
|
||||
- **Lane:** ms-812
|
||||
- **Branch:** `fix/812-pr-review-comment`
|
||||
- **Issue:** mosaicstack/stack#812
|
||||
- **Budget:** 15K working estimate; single focused shell-wrapper/test/docs change.
|
||||
|
||||
## Objective
|
||||
|
||||
Make the Gitea `comment` action in `packages/mosaic/framework/tools/git/pr-review.sh` use the supported Gitea comments REST API and report success only after provider read-back verifies the created comment against the intended repository, PR, and exact body.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add and commit a failing shell regression harness before production changes.
|
||||
2. Verify RED against the nonexistent `tea pr comment` fallback false-positive.
|
||||
3. Implement the minimal supported write plus ID-based provider read-back.
|
||||
4. Document that wrapper write output is not durable provenance until read-back succeeds.
|
||||
5. Run focused regression tests, touched-package tests, and repository quality gates.
|
||||
6. Remediate review findings, queue-guard, and push for coordinator-owned independent review. Do not open or merge a PR.
|
||||
|
||||
## Progress checkpoints
|
||||
|
||||
- [x] RED regression committed and reported to mosaic-100 (rebased commit `770e3f57`)
|
||||
- [x] Initial minimal fix implemented (rebased commit `ea7f8c57`)
|
||||
- [x] Rebased cleanly onto main `627cf2bb387f7c84a532d88819903a7679ce0d72`
|
||||
- [x] Codex blocker remediated by replacing unsupported `tea api` with authenticated REST write/read-back
|
||||
- [x] Focused, package, and repository gates green
|
||||
- [ ] Coordinator-owned independent review pending after push
|
||||
- [x] No PR opened; no self-review or self-merge
|
||||
|
||||
## Tests run
|
||||
|
||||
- RED after rebase: the regression harness failed against `origin/main` with status 1 after reproducing the old `tea pr comment` zero-exit fallback and false success echo.
|
||||
- GREEN at resumed head: the same harness passed with REST POST 201 plus GET 200 read-back.
|
||||
- All `packages/mosaic/framework/tools/git/test-*.sh` harnesses passed.
|
||||
- `shellcheck -x` passed for the changed scripts; `bash -n` passed.
|
||||
- Manifest resolver returned `framework` for `tools/git/test-pr-review-gitea-comment.sh`.
|
||||
- `pnpm test` passed (43/43 Turbo tasks; Mosaic 75 files/1434 tests; Gateway 56 files/628 tests plus documented skips).
|
||||
- `pnpm typecheck` passed (42/42 tasks), `pnpm lint` passed (23/23), and `pnpm format:check` passed.
|
||||
- Firewall checks found no user-home paths or operator identities in changed shipped files; no token value is logged or echoed.
|
||||
|
||||
## Risks / blockers
|
||||
|
||||
- No active implementation blocker. #789 reached terminal merged state and the coordination hold was lifted.
|
||||
- Review round 1 found one portability blocker: the API base reconstructed `https://$host` and discarded configured schemes/path prefixes.
|
||||
- Review round 2 found a second subpath portability blocker: clone-derived `get_repo_slug` retained the deployment prefix, duplicating it under `/api/v1/repos/`.
|
||||
- Round 3 resolves owner/repo relative to the configured Gitea base path for HTTP(S) clones while preserving root-mounted and SSH clone forms. Host matching now compares non-default ports consistently.
|
||||
- REST transport failures, non-201 writes, malformed/missing created IDs, non-200 read-backs, and read-back mismatches all fail closed.
|
||||
- Existing approve/request-changes behavior remains covered.
|
||||
- Independent exact-head re-review remains coordinator-owned.
|
||||
|
||||
## Final verification evidence
|
||||
|
||||
- URL-portability regression was RED before remediation at the new `http://git.mosaicstack.dev` case and GREEN afterward.
|
||||
- Round-3 genuine subpath regression was RED against round-2 head `1b190201` and GREEN after the fix: `https://git.example/gitea/owner/repo.git` maps to API repository `owner/repo` under configured base `/gitea`.
|
||||
- Regression coverage verifies POST and read-back GET for root-mounted HTTP(S), path-prefixed HTTP(S), non-default HTTP port, scp-style SSH, and `ssh://` clone forms.
|
||||
- Focused shell checks, all git-wrapper harnesses, and full repository test/typecheck/lint/format gates passed after remediation.
|
||||
- Branch will be force-pushed with lease for coordinator re-verification; no PR opened.
|
||||
@@ -1,112 +0,0 @@
|
||||
# Issue #824 — Mosaic skill CLI and Claude bridge auto-sync
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver `mosaic skill register|unregister|list` plus install/upgrade reconciliation of every canonical `~/.config/mosaic/skills/*` entry into `~/.claude/skills/`, without clobbering runtime-owned files or directories.
|
||||
|
||||
## Scope and constraints
|
||||
|
||||
- Issue: mosaicstack/stack#824
|
||||
- Branch: `feat/824-mosaic-skill-cli`
|
||||
- M1 runtime: Claude Code only.
|
||||
- Pi/Codex parity is documentation-only; no non-Claude bridge implementation.
|
||||
- Do not author the downstream `mosaic-context-refresh` skill.
|
||||
- Workers do not modify `docs/TASKS.md`, merge, close #824, or touch `main`.
|
||||
- TDD is mandatory and red-first; filesystem tests use temporary directories only.
|
||||
- Budget: no explicit token cap supplied; use a focused single-worker implementation with no new dependencies.
|
||||
|
||||
## Requirements mapping
|
||||
|
||||
1. Register creates the canonical Claude symlink and is idempotent.
|
||||
2. Names are untrusted: reject empty/escaping/absolute/separator/`..`/leading-dash names before filesystem mutation, with clear CLI stderr and nonzero status.
|
||||
3. Register repairs only Mosaic-owned dangling symlinks and refuses foreign files, directories, and symlinks.
|
||||
4. Unregister removes only symlinks pointing inside the canonical Mosaic skills root and is idempotent when absent.
|
||||
5. List reports registered, dangling, foreign, and canonical-but-unregistered skills.
|
||||
6. Install and upgrade generically reconcile all canonical skills after framework sync/re-seed, continuing past foreign conflicts without clobbering them.
|
||||
7. User/developer documentation describes commands, status meanings, security boundaries, and Claude-only M1 scope.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add co-located failing Vitest coverage for all filesystem behaviors and auto-sync.
|
||||
2. Run the focused spec and record the expected RED failure.
|
||||
3. Commit the red contract as `test(#824): ...`.
|
||||
4. Implement the skill bridge and Commander command registration.
|
||||
5. Wire reconciliation into wizard finalize and `mosaic update` re-seed, preserving non-clobber behavior.
|
||||
6. Update canonical docs and sitemap if navigation changes.
|
||||
7. Run focused tests, package tests, typecheck, lint, and formatting.
|
||||
8. Commit implementation/docs as `feat(#824): ...`, queue-guard, push, open PR with `Closes #824.`, fire completion event, and notify the coordinator.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-07-17: Loaded mission/delivery/TDD/documentation rails, issue #824, active mission state, and relevant installer/update paths.
|
||||
- 2026-07-17: Confirmed `mosaic update` invokes `framework/install.sh` with `MOSAIC_SYNC_ONLY=1`; that path exits before existing post-install skill linking, leaving newly present canonical skills unregistered.
|
||||
- 2026-07-17: Coordinator addendum classified the user-supplied skill name and runtime symlink target as a path-traversal/symlink-injection surface. Expanded the initial red contract to reject traversal before mutation, preserve every foreign entry, and unregister Mosaic-owned links only.
|
||||
- 2026-07-17: Implemented the Commander command group and secure generic bridge; wired wizard finalize and successful framework re-seed reconciliation; updated user/developer/installed/root docs and sitemap.
|
||||
- 2026-07-17: Focused, package-wide, repository baseline, temp-home situational, and independent review gates completed. Ready for scoped feature commit, queue guard, push, and PR handoff.
|
||||
|
||||
## Tests and evidence
|
||||
|
||||
### TDD evidence
|
||||
|
||||
- RED environment attempt: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/skill.spec.ts` initially could not locate Vitest because this fresh worktree had no dependencies.
|
||||
- Dependency setup: `pnpm install --frozen-lockfile --store-dir /home/hermes/.local/share/pnpm/store` succeeded. The explicit store was required because machine pnpm config incorrectly resolves the default store under `/root`.
|
||||
- RED behavior: focused Vitest failed with `Failed to load url ./skill.js ... Does the file exist?`, proving the bridge API was absent.
|
||||
- RED integration: finalize/update specs failed because no Claude links or `skillSync` result existed.
|
||||
- RED symlink injection: symlinked Claude/canonical root tests failed because the initial implementation followed ancestor links.
|
||||
- GREEN after review remediation: `skill.spec.ts` 36/36, `finalize-skills.spec.ts` 6/6, and `update-checker.reseed.spec.ts` 30/30.
|
||||
|
||||
### Baseline gates
|
||||
|
||||
- `pnpm --filter '@mosaicstack/mosaic...' run build` — pass (fresh-worktree dependency outputs built).
|
||||
- `pnpm --filter @mosaicstack/mosaic run typecheck` — pass.
|
||||
- `pnpm --filter @mosaicstack/mosaic run lint` — pass.
|
||||
- `pnpm --filter @mosaicstack/mosaic test` — pass: 69 files, 1,325 Vitest tests plus framework shell suite.
|
||||
- `pnpm typecheck` — pass: 42/42 Turbo tasks.
|
||||
- `pnpm lint` — pass: 23/23 Turbo tasks.
|
||||
- `pnpm format:check` — pass.
|
||||
|
||||
### Situational evidence
|
||||
|
||||
A built-CLI temp-home smoke test (no real `~/.claude` or Mosaic config touched) proved:
|
||||
|
||||
- register creates the exact link and a second run reports `already registered`;
|
||||
- list reports registered and unregistered canonical skills;
|
||||
- `../../etc` exits 1 with `Invalid skill name` and creates no escaped path;
|
||||
- unregister removes the managed link and a second run reports `already unregistered`;
|
||||
- a fake successful framework re-seed generically registered both `added-after-setup` and `second-skill` from runtime directory enumeration.
|
||||
|
||||
### Review evidence
|
||||
|
||||
- Initial uncommitted Codex code/security review described name validation/clobber protection as strong; its only finding was the harness-owned, unrelated `.mosaic/orchestrator/session.lock`, which is excluded from all commits and the PR.
|
||||
- Exact branch review then identified two remediations: preserve successful framework re-seed status when bridge-wide reconciliation fails, and reject/escape control-character names to prevent terminal/log injection.
|
||||
- Both findings were reproduced red-first and remediated. A subsequent exact review identified one finalize failure-isolation blocker; a root-wide bridge error now warns and allows wizard doctor/summary/next-steps completion, with a red-first regression.
|
||||
- All remediations passed the full package and repository gates. Final exact-head review is rerun after amending the feature commit.
|
||||
|
||||
### Acceptance mapping
|
||||
|
||||
| Acceptance criterion | Evidence |
|
||||
| --- | --- |
|
||||
| register/unregister/list, idempotent | `skill.spec.ts` and built-CLI temp-home smoke |
|
||||
| traversal/symlink-injection protection | invalid-name matrix, foreign file/dir/link tests, symlinked-root tests |
|
||||
| list flags dangling and foreign entries | deterministic list status test |
|
||||
| install and upgrade auto-sync every canonical directory | finalize + framework re-seed integration specs; two-skill built-module smoke |
|
||||
| newly added skill becomes discoverable without manual link | `added-after-setup` auto-sync creates exact Claude link; Claude can rescan with `/reload-skills` or a new session |
|
||||
| Pi/Codex parity captured as scope note | user guide, developer guide, installed framework README |
|
||||
| documentation gate | root README, user guide, developer guide, framework README, sitemap |
|
||||
|
||||
## Risks
|
||||
|
||||
- Symlink replacement uses `lstat` semantics so dangling links are detectable without following them.
|
||||
- Link ownership is determined lexically against the canonical skills root, and existing symlink ancestors in either managed root are rejected before mutation.
|
||||
- Auto-sync continues across per-skill conflicts while never deleting real files/directories or foreign symlinks.
|
||||
- Claude Code discovers filesystem skills at session launch/reload boundaries; bridge creation makes a later `/reload-skills` or new session able to discover the skill, but cannot mutate an already-cached in-process registry by itself.
|
||||
- Pi does not need this Claude bridge because its Mosaic launcher can consume the canonical root. Codex lifecycle parity remains explicitly deferred.
|
||||
- No deployment surface is affected.
|
||||
|
||||
## PR #826 review remediation
|
||||
|
||||
- 2026-07-17: Exact-head RoR requested changes for two ownership bugs: installer pruning deleted foreign-name links under `MOSAIC_HOME` outside canonical skills, and unregister deleted a same-root link targeting a different skill. It also requested trailing-dot rejection and executable coverage support.
|
||||
- RED evidence: focused regression run failed 4 tests: register/unregister accepted `safe.`, misdirected unregister did not throw, and the install linker deleted the foreign-name link.
|
||||
- GREEN evidence: `skill.spec.ts` passes 43/43, including live and dangling foreign-name links in a temp HOME/MOSAIC_HOME and the misdirected unregister invariant.
|
||||
- Coverage: `vitest run src/commands/skill.spec.ts --coverage` passes configured 85% thresholds for `skill.ts`: 91.05% statements/lines, 86.27% branches, 95.23% functions.
|
||||
- Full gates: package build passed; package tests passed 69 files / 1,332 tests plus framework shell suite; repository typecheck 42/42, lint 23/23, and format check passed.
|
||||
@@ -1,86 +0,0 @@
|
||||
# WI-1 Scratchpad — Authenticated external lease broker
|
||||
|
||||
- **Issue:** Gitea #828
|
||||
- **Milestone:** 188 — Compaction-Refresh Mechanism (M1: Claude + Pi)
|
||||
- **Branch:** `feat/828-lease-broker`
|
||||
- **Starting HEAD:** `d801d6c4c8a984d6a95033c49714210018d3d9a8`
|
||||
- **Session role:** Orchestrator coordinating implementation; Mos retains merge authority.
|
||||
|
||||
## Objective
|
||||
|
||||
Implement the ratified WI-1 product lease broker under `packages/mosaic/`: Linux `SO_PEERCRED` identity, broker-minted logical session IDs, `(pid,starttime)` launcher anchors with per-hop `/proc` starttime revalidation, sibling-substitution rejection, same-PID runtime-generation revocation, crypto-RNG single-use token persistence, and protected Unix-socket posture.
|
||||
|
||||
## Authority verification
|
||||
|
||||
Verified before code on session start; all exact SHA-256 values matched:
|
||||
|
||||
- BUILD-BRIEF: `89fdbc27ed0e5050dc7b52f3ef2ddaea691edf17fd89d51b15e26fb5ed47171b`
|
||||
- SPEC-v5: `a6d07ade835758e8488ca10d3b0631caf0beb93ea3a6733631f151b0c2f01433`
|
||||
- Ratification: `bac58319c9c4028b5b40e1129e0033cdb5a6b7b02033c25f06f4cb77d7779c67`
|
||||
- P6 planner ruling: `b7bbb6ea6e8d9a5c3366993642ab4e4f65b961af04936dcac20bfbcdcbaf1a09`
|
||||
- WI-0 Gate0 evidence: `5d418306fcc597fd514e500bee40d1509f0bf467e46ee13fc5c280ed8274759d`
|
||||
|
||||
## Locked constraints
|
||||
|
||||
- Build against the ratified design; do not re-derive it.
|
||||
- Product code only in `packages/mosaic`; Gate0 Python probes are reference prototypes and are not shipped.
|
||||
- Caller-supplied/asserted `session_id` is refused.
|
||||
- Tokens use the operating-system CSPRNG via Python `secrets`; never `Math.random` or model output.
|
||||
- Socket parent directory mode `0700`, socket mode `0600` minimum; document distinct-principal deployment as the stronger T-C-closing posture.
|
||||
- Red-first TDD for six named cases; new-code coverage >=85%.
|
||||
- No merge. PR must say `closes #828`; exact 40-character head handed to Mos for Opus-SECREV and independent review.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Load security/testing/docs guidance and inspect existing `packages/mosaic` architecture.
|
||||
2. Write the six required tests first and capture RED evidence.
|
||||
3. Implement minimal broker modules and CLI/runtime integration necessary for product use.
|
||||
4. Run focused tests with coverage, package gates, then full repository gates/suite.
|
||||
5. Run author-side review/remediation, commit `closes #828`, queue guard, push, and open PR through Mosaic wrappers.
|
||||
6. Send PR number + exact head SHA to `web1:mosaic-100`; stop without merging.
|
||||
|
||||
## Risks / boundaries
|
||||
|
||||
- Same-UID counterfeit socket replacement remains the disclosed T-C residual unless broker runs under a distinct principal; filesystem modes alone are minimum hardening, not a complete authenticity proof.
|
||||
- `.mosaic/orchestrator/mission.json` and `.mosaic/orchestrator/session.lock` were already modified at session start and must not be included in this PR.
|
||||
- Repository Woodpecker pipelines exist; CI is the canonical build path. No manual image build/deploy is in scope.
|
||||
|
||||
## Progress / evidence
|
||||
|
||||
- 2026-07-18 session start: mandatory mission files and orchestration guides loaded.
|
||||
- STEP 0: all four authority hashes matched; artifacts read in full.
|
||||
- Branch/HEAD confirmed; issue #828 open; Gate0 evidence hash confirmed.
|
||||
- Initial RED: focused Vitest acceptance suite failed 11/11 because the product daemon did not exist; the expected missing-product failure was observed before implementation.
|
||||
- Review-remediation RED: partial/zero-progress state writes, nested corrupt state, symlink state, canonical starttime, and duplicate-anchor generation behavior failed before their fixes. Real socket RED/GREEN runs were executed by the unrestricted parent harness because the delegated worker sandbox denies `AF_UNIX.bind()`.
|
||||
- Product implementation added at `packages/mosaic/framework/tools/lease-broker/daemon.py`; Gate0 probe scripts were read as references but not copied or shipped.
|
||||
- Independent Codex code review round 1 found 2 blockers + 1 should-fix (connection stall/crash, partial writes, packet-dependent framing); all were remediated with tests.
|
||||
- Independent Codex code review round 2 found 2 blockers + 1 relevant should-fix (half-close contract ambiguity, incomplete persisted-state validation, symlink/non-regular state); all were remediated with tests and documentation. Pre-existing `.mosaic/*` session dirt remains excluded from the PR.
|
||||
- Unrestricted focused situational suite: `35/35` GREEN.
|
||||
- New Python product module coverage: `90%` (`356` statements, `36` missed), above the user-required 85%.
|
||||
- Root typecheck: `42/42` Turbo tasks GREEN.
|
||||
- Root lint: `23/23` Turbo tasks GREEN.
|
||||
- Root format check: GREEN.
|
||||
- Package build + suite: `71/71` files and `1,369/1,369` tests GREEN, including framework shell tests.
|
||||
- Full root suite: `43/43` Turbo tasks GREEN after the oversized-frame production race fix.
|
||||
- Focused acceptance suite: `35/35` GREEN in three consecutive unrestricted runs; exact-head instrumented run also `35/35` GREEN.
|
||||
- Exact-head Python product coverage: `90%` (`365` statements, `37` missed), above the required 85%.
|
||||
- Review-triggered oversized-frame race was fixed in production by bounded drain-to-EOF; tests were not changed.
|
||||
- Commits banked in red/green cadence: `d61c5441` (RED contract), `deb11df7` (GREEN implementation/docs), `57770e34` (oversized-frame production fix).
|
||||
- Final-review blocker remediated: added a 256-token pending-state cap, deletion on consume/generation revocation, pre-open serialized-size enforcement, and request-wide in-memory rollback for every broker mutation/commit failure while retaining the v1 live-token schema.
|
||||
- Distinct-principal docs now state built-in `0700`/`0600` is same-principal only; WI-1 does not provide the external identity-preserving proxy/ACL/service boundary needed for the stronger deployment.
|
||||
- Exact Python unit suite: `8/8` GREEN. Unrestricted focused acceptance: `35/35` GREEN.
|
||||
- Exact-head package build/suite: `71/71` files and `1,369/1,369` tests GREEN.
|
||||
- Exact-head Python product coverage: `90%` (`376` statements, `36` missed), above required 85%.
|
||||
- Root typecheck: `42/42` GREEN. Root lint: `23/23` GREEN. Root format check and `git diff --check`: GREEN.
|
||||
- Final exact-head rereview found two persistence blockers: post-rename directory-fsync uncertainty and acceptance of impossible persisted token records. RED was captured as three invariant failures plus one missing fail-stop error; commits `a94b1220` (RED) and `d05465e5` (GREEN) remediate both without weakening tests.
|
||||
- Post-remediation evidence: Python unit suite `10/10`, focused real-socket acceptance `35/35`, full root suite `43/43` Turbo tasks, broker coverage `90%` (`395` statements, `38` missed), lint `23/23`, typecheck `42/42`, format check and `git diff --check` GREEN.
|
||||
- Independent Codex review of remediation commit `d05465e54736c4966294c4af8fbd6a4ad8fe81aa`: APPROVE, confidence `0.94`, zero findings. Reviewer sandbox could not allocate temp directories; unrestricted parent test evidence above is canonical.
|
||||
|
||||
- Remediation session: terra review comment `18072` reproduced a SERIAL-ACCEPT DoS; scope is RED regressions plus bounded concurrent connection handling on PR #836, preserving all existing broker security properties.
|
||||
- RED evidence against reviewed daemon: four silent peers delayed registration `3920 ms` beyond the `1500 ms` bound; 16 silent peers were not reaped within `2500 ms`. The first bounded implementation then exposed slot exhaustion by rejecting the valid queued caller with `EPIPE`; admission was corrected to wait for a reclaimed bounded slot. GREEN evidence: queued-peer test `211 ms`; strengthened cap/reap/reclaim test `1118 ms`; complete real-socket acceptance `37/37` and Python persistence suite `10/10`.
|
||||
|
||||
## Coordinator handoff requirements
|
||||
|
||||
1. Mandatory Opus-SECREV on the exact PR head; no GPT/terra substitute.
|
||||
2. Independent exact-head code review and exact-head RoR before Mos-authorized merge.
|
||||
3. Mos retains merge authority; this WI author stops after PR + full 40-character head handoff.
|
||||
@@ -1,130 +0,0 @@
|
||||
# WI-2 Scratchpad — Whole mutator-class gate
|
||||
|
||||
- **Issue:** Gitea #829
|
||||
- **Branch:** `feat/829-mutator-gate`
|
||||
- **Base HEAD:** `8ec67a1126adb0dcd4c3a2bf5525f3e239c0b201`
|
||||
- **Role:** sol author/build lane only; terra code review and Opus security review are coordinator-owned.
|
||||
|
||||
## Mission prompt
|
||||
|
||||
Implement BUILD-BRIEF Deliverable 2 as a framework-native whole mutator-class gate under `packages/mosaic/`, building against the merged WI-1 lease broker. No consequential mutator may succeed while UNVERIFIED after a compaction observer fires or after TTL. Carry the T-B compromised-tool acceptance criteria. Enforce revoke-first and promote-last structurally. A receipt is only a promotion prerequisite; the mutator-class gate remains the safety mechanism. M1 is Claude + Pi only.
|
||||
|
||||
## Authority verification
|
||||
|
||||
Verified exact SHA-256 before design/code:
|
||||
|
||||
- BUILD-BRIEF: `89fdbc27ed0e5050dc7b52f3ef2ddaea691edf17fd89d51b15e26fb5ed47171b`
|
||||
- SPEC-v5: `a6d07ade835758e8488ca10d3b0631caf0beb93ea3a6733631f151b0c2f01433`
|
||||
- Ratification: `bac58319c9c4028b5b40e1129e0033cdb5a6b7b02033c25f06f4cb77d7779c67`
|
||||
- sol final red-team: `3da326a4ea91767b731e128a93b13194e8002358101e30de3fcb8ca2f8f54faa`
|
||||
|
||||
Carried authority chain also verified/read for the locked T-B gate contract: SPEC-v4 `a5e9c261…`, v4 sol `1e76ee59…`, SPEC-v3 `e0830ba0…`, v3 sol `9f321ade…`.
|
||||
|
||||
## Plan
|
||||
|
||||
1. RED real-socket acceptance tests for default-deny whole classes, T-B raw-tool bypass, observer/TTL revocation, and structural revoke-first/promote-last.
|
||||
2. Extend the merged WI-1 broker as the sole lease authority; authenticate every transition through existing peercred/ancestry/session logic and consume WI-1 single-use cycle tokens atomically before promotion.
|
||||
3. Add one broker-backed runtime gate executable and wire it across all Claude `PreToolUse` tools and Pi `tool_call`; unknown/custom tools deny by default.
|
||||
4. Add proportional protocol/security/operations documentation and requirements-to-evidence mapping.
|
||||
5. Run focused coverage, package/full suites, lint/typecheck/format, then queue-guard, push, open an unmerged PR with `closes #829`, and hand off the exact head.
|
||||
|
||||
## Risks and bounds
|
||||
|
||||
- Receipt parsing/builders and compaction observers are later WIs; WI-2 exposes the promotion prerequisite boundary but does not treat a receipt as safety authority.
|
||||
- Broker restart intentionally loses volatile VERIFIED leases and therefore restarts UNVERIFIED; persistent WI-1 identity/token state remains unchanged.
|
||||
- The gate is whole-class and does not parse shell command strings. T-C extension/hook absence and same-UID broker replacement remain outside the client guarantee and server branch protection remains the backstop.
|
||||
- Initial lease TTL is capped at ratified 300 seconds; callers may only shorten it.
|
||||
- Working budget assumption: 35K tokens; reduce documentation/refactor breadth before touching locked scope if pressure rises.
|
||||
|
||||
## Progress and verification
|
||||
|
||||
- RED #1: all 5 initial real-socket contract tests failed on WI-1 with `UNKNOWN_ACTION` or missing adapter behavior.
|
||||
- RED #2: register-before-exec runtime test failed because `launch-runtime.py` did not exist.
|
||||
- GREEN: broker-owned volatile lease state, 300-second maximum monotonic TTL, WI-1 token-backed promotion, all-tools runtime gate, Claude/Pi wiring, and register-before-exec launcher delivered without changing WI-1 peercred/ancestry authority.
|
||||
- Focused broker + gate acceptance: `43/43` GREEN.
|
||||
- Instrumented Python coverage: `88%` total — daemon `89%`, register/exec launcher `86%`, runtime gate `86%`.
|
||||
- Full repository suite: `43/43` Turbo tasks GREEN; `@mosaicstack/mosaic` `72/72` files and `1,377/1,377` tests GREEN.
|
||||
- Root typecheck: `42/42`; lint: `23/23`; format check and `git diff --check`: GREEN.
|
||||
- No author self-review was run. Exact-head terra CODE and Opus SECREV remain coordinator-owned gates.
|
||||
|
||||
## Acceptance mapping
|
||||
|
||||
| Acceptance criterion | Evidence |
|
||||
| --- | --- |
|
||||
| No consequential mutator succeeds while UNVERIFIED after observer revoke or TTL | `observer revocation and monotonic TTL expiry deny the next mutator` real-socket acceptance test |
|
||||
| T-B compromised-tool bypass is covered by the whole gate | `T-B raw and custom mutator tools are default-denied without shell parsing` across Claude/Pi built-ins, raw Bash class, MCP/custom/unknown tools |
|
||||
| Revoke-first / promote-last is structural | `revoke-first and promote-last structurally bracket mutator authority`; direct promotion rejected, pending remains denied, token consumption commits before VERIFIED |
|
||||
| Consume WI-1 auth/lease substrate | All transitions and decisions traverse merged peercred/ancestry authentication; promotion consumes the exact WI-1 CSPRNG cycle token |
|
||||
| M1 Claude + Pi | Claude `.*` PreToolUse and Pi `tool_call` invoke the same broker gate; register-before-exec test proves broker-minted parent identity reaches runtime descendants |
|
||||
|
||||
## Locked discipline
|
||||
|
||||
- Re-verify and read the four authority artifacts before design or code.
|
||||
- RED-first tests must cover unverified mutation refusal, T-B compromised-tool refusal, and revoke-first/promote-last ordering.
|
||||
- Consume WI-1 VERIFIED-lease state; do not re-derive kernel identity, ancestry, sessions, or token authentication.
|
||||
- Minimum 85% new-code coverage; full suite, lint, typecheck, and format checks green.
|
||||
- Build only: no self-review and no merge. Open a PR containing `closes #829`, report its exact 40-character head, then exit.
|
||||
|
||||
## Remediation — terra CODE comment 18091
|
||||
|
||||
- Coordinator correction: terra returned REQUEST CHANGES at head `77b137ccc04b5be035cac5ca21bbbf3df8b94f97`; Opus SECREV was GO and CI green, but no evidence transfers to the remediated head.
|
||||
- BLOCKER 1 verified: first-class Claude/Pi route through `execLeaseGatedRuntime`, while the supported Claudex path preserves isolation but directly invokes `claude`; it therefore registers no anchor, injects no lease session, and the isolated config has no guaranteed all-tools gate hook.
|
||||
- BLOCKER 2 accepted: prior 88% was aggregate evidence. Remediation must produce independently measured branch coverage of at least 85% for each new executable (`launch-runtime.py`, `mutator-gate.py`, and daemon delta evidence), including successful exec-boundary collection and validation/error branches.
|
||||
- Remediation discipline: RED tests first; preserve the reviewed-good broker lock/state-transition ordering; update PR #837 on the same branch; no self-review or merge.
|
||||
|
||||
### Remediation evidence
|
||||
|
||||
- RED commit `046896c6`: both `mosaic claudex` and `mosaic yolo claudex` behavioral probes exited 1 because the direct path supplied neither a broker session nor the isolated all-tools hook; branch-focused Python tests failed on the absent injectable boundaries. Fresh WI-2 daemon-delta instrumentation also failed the ≥85% branch gate at 75%.
|
||||
- GREEN: Claudex now exposes only `execLeaseGated`, passes the preserved isolated proxy environment through the shared register-before-exec wrapper, and merges the exact `.*` mutator hook into isolated `settings.json` with mode `0600`. Missing broker/identity, malformed or symlinked settings, and an unverified consequential tool all fail closed. The broker transition/lock implementation was not changed.
|
||||
- Behavioral regression: normal and YOLO Claudex both receive a 64-hex broker session, retain their mode-specific arguments, observe the exact all-tools hook, and receive status 2 for unverified `Bash`.
|
||||
- Independent branch coverage: `launch-runtime.py` 16/18 = **89%** (statements 98%); `mutator-gate.py` 21/22 = **95%** (statements 99%); `daemon.py` WI-2 delta 35/40 = **88%** (whole-file branch 80%, statements 90%).
|
||||
- Fresh focused real-socket coverage run: WI-1 + WI-2 acceptance `46/46`; persistence `10/10`; branch unit suite `10/10`.
|
||||
- Fresh full repository suite: `43/43` Turbo tasks; `@mosaicstack/mosaic` `72/72` files and `1,381/1,381` tests.
|
||||
- Fresh root gates: typecheck `42/42`; lint `23/23`; format and `git diff --check` GREEN.
|
||||
- PR #837 remains open and unmerged. Terra CODE and Opus SECREV must both rerun from zero on the exact remediated head before coordinator-owned merge authorization.
|
||||
|
||||
## Remediation round 3 — terra CODE comment 18099 + binding upgrade
|
||||
|
||||
- Locked-good surfaces: Claudex gating and B2 per-executable coverage are verified; do not regress them. Broker state-transition/lock ordering remains untouched.
|
||||
- Mechanical repository sweep found direct executing Claude entries in PRDY init, PRDY update, QA remediation, and `@mosaicstack/coord` task launch. It also found a direct Claude command rendered into the QA report template and documentation examples. Existing Mosaic CLI Claude/Pi/Claudex, orchestrator session-run, and fleet starts already reach the gated boundary.
|
||||
- Elevated hard requirements: ship a permanent suite/CI guard that scans production source and fails on any direct Claude/Pi launch; route every executing entry through one common gated wrapper; add real-broker RED/GREEN tests for PRDY init/update and QA; preserve each environment and denial behavior; independently measure all new executable coverage at ≥85%.
|
||||
- Round-3 plan: first commit RED behavioral and scanner-contract tests; then add one framework `launch-runtime.sh` choke-point over `launch-runtime.py`, make Mosaic CLI and shell launchers use it, make coord route through `mosaic`, and wire the permanent guard into package tests. Update all discovered operator-facing direct-launch examples so the scanner inventory remains complete.
|
||||
|
||||
### Round-3 outcome
|
||||
|
||||
- RED commit `7f3418fa`: PRDY init, PRDY update, and QA remediation all reached the fake Claude binary without a broker session even when the configured socket did not exist; the permanent-guard contract initially failed because its executable was absent, then failed against the five discovered direct entries (four executing plus the QA command template).
|
||||
- Choke-point decision: a new shell layer was unnecessary. Every executing repository entry now converges directly or through `mosaic`/`execLeaseGatedRuntime` on the existing single `launch-runtime.py` register-then-exec wrapper. PRDY and QA preserve their working directories, prompts, flags, logging pipe, and environment. Coord rewrites direct Claude commands to `mosaic claude` and rejects unknown custom Claude launchers fail-closed.
|
||||
- Permanent guard: `packages/mosaic/framework/tools/lease-broker/check-runtime-launches.py`, invoked by `packages/mosaic/package.json` `test:framework-shell` and therefore root `pnpm test`/CI. It scans production code under `packages/`, `apps/`, `plugins/`, and `tools/` and rejects literal, absolute-path, process-API, command-array, and dynamic Claude/Pi launch forms. Synthetic bypass tests are permanent at `runtime_launch_guard_unittest.py`.
|
||||
- Mechanical inventory: **14 gated / 14 total** — coord 2, fleet 1, QA 2, orchestrator 3, PRDY 2, Mosaic Claude/Pi/Claudex adapter/boundary 4. No verification-layer fallback or follow-up issue is needed because the single code-level wrapper was achieved.
|
||||
- Real-socket behavioral evidence: PRDY init, PRDY update, and QA remediation each fail before runtime execution when the broker is absent; with the broker present they receive a broker-minted 64-hex session and the unverified `Bash` authorization exits 2. Claudex normal/YOLO and the broker state machine remain GREEN.
|
||||
- Fresh branch coverage: `launch-runtime.py` **18/18 = 100%**; `mutator-gate.py` **22/22 = 100%**; permanent guard **36/38 = 95%**; `daemon.py` WI-2 delta **35/40 = 87.5%**. All attributable executable statement coverage is at least 98%.
|
||||
- Fresh focused suites: broker + mutator real-socket acceptance `49/49`; persistence `10/10`; launcher/gate branch suite `13/13`; permanent guard suite `7/7`; coord `19/19`.
|
||||
- Fresh full repository suite: `43/43` Turbo tasks; `@mosaicstack/mosaic` `72/72` files and `1,384/1,384` tests. Root typecheck `42/42`, lint `23/23`, format, and diff checks GREEN.
|
||||
- PR #837 remains open and unmerged. Terra CODE and Opus SECREV must both rerun from zero on the exact round-3 head before coordinator-owned merge authorization.
|
||||
|
||||
## Remediation round 4 — terra CODE comment 18104
|
||||
|
||||
- Locked-good surfaces: the 14/14 launch inventory, single `launch-runtime.py` choke-point, real-socket launcher behavior, coverage, Claudex gating, and broker state machine must not change.
|
||||
- Reproduced RIDER E exactly at head `1792b7934dda7eff64a207b8b0edb9c460d4164b`: a temporary production file containing `exec claude --dangerously-skip-permissions "terra-r3" # launch-runtime.py` made the guard exit 0 and report `1 gated/1 total`.
|
||||
- Root cause: classification searched the unparsed physical line, and the broad gated regex treated any `launch-runtime.py` substring—including comments and inert arguments—as an invocation before the direct-launch finding was evaluated.
|
||||
- Round-4 plan: add permanent RED cases for the exact comment evasion plus string-argument, echo, and unrelated-variable marker evasions; tokenize/strip comments by launcher syntax; recognize only command-position wrapper invocations with `--runtime` and the gated command separator; retain 14/14 real inventory; rerun guard coverage and all gates fresh.
|
||||
- Mos Rider A/B decision: adopt **both** defenses. Command-position parsing remains necessary because a normal `claude -p` launch is consequential even without the dangerous flag. The primitive-location invariant is more mechanically robust for dangerous mode because it does not need to recognize a wrapper marker at all. Move the sole raw `--dangerously-skip-permissions` literal into `launch-runtime.py`; any occurrence in another production file is independently RED.
|
||||
- Rider-A RED matrix adds heredoc body, backslash continuation, non-first `;`/`&&`/pipe commands, command substitution, `eval`, and variable-execution indirection in addition to the six marker/comment evasions. Before the augmented implementation, primitive ownership, command substitution, `eval`, variable execution, and the preserved 14-site inventory all fail.
|
||||
- Round-4 GREEN uses both defenses. Quote-aware comment stripping removes shell/Python `#` and JS/TS line/block comments; shell command prefixes are segmented with `shlex`; validated wrappers require `launch-runtime.py` in command position, `--runtime`, and the `--` command separator; multiline TypeScript wrapper calls are validated as complete invocations. Direct command syntax wins over markers, while tracked runtime assignments plus `eval`/variable execution, command substitution, chained commands, heredocs, continuations, and `env`/`command`/`nohup` prefixes are rejected.
|
||||
- Primitive ownership is independently load-bearing: `launch-runtime.py` is the sole production owner of the raw Claude dangerous flag. Mosaic, Claudex, and PRDY request semantic `--dangerous`; the wrapper validates Claude and injects the primitive immediately before register/exec. This preserves actual YOLO argv behavior while making any raw primitive elsewhere fail without relying on wrapper-name recognition.
|
||||
- Permanent guard suite now has 10 tests and 31 direct-launch forms, including 18 new round-4 marker/comment/indirection/prefix evasions plus harmless-marker and multiline-wrapper controls. Terra's exact add-ungated source is exercised through the CLI effectiveness test. Repository inventory remains exactly **14 gated / 14 total**.
|
||||
- Fresh round-4 coverage: guard **97%** branch-aware aggregate (241 statements, 110 branches); `launch-runtime.py` **100%**; `mutator-gate.py` **100%**. The daemon is byte-unchanged from the round-3 head whose WI-2 delta is **87.5%**.
|
||||
- Fresh round-4 gates: real-socket acceptance **49/49**; persistence **10/10**; launcher/gate **14/14**; guard **10/10**; coord **19/19**; Mosaic **1384/1384**; root **43/43**; typecheck **42/42**; lint **23/23**; format and diff checks green.
|
||||
|
||||
## Remediation round 5 — terra 18116 + Opus 18114
|
||||
|
||||
- Both independent gates converged on one guard-only completeness gap at round-4 head `1eb77c17f3147d4fa9944f77f1826243135b9cc0`; all round-4 primitive anchoring, command-position parsing, 14/14 inventory, broker ordering, and coverage remain locked-good.
|
||||
- Reproduced exactly: a temporary production source containing `launcher=claude` followed by `exec "$launcher" -p x` exits 0 with `0 gated / 0 total`. The literal command resolver skips prefixes but cannot resolve a tracked variable; the variable resolver handles only bare/eval references and cannot skip prefixes.
|
||||
- Round-5 plan: add 10 permanent RED forms (quoted/unquoted `exec`, `command`, `nohup`, and `env` with assignment, each multiline and same-line), then unify shell command-position resolution so literal and tracked-variable terminal tokens traverse the same prefix parser. Retain an independent variable-reference backstop, the 14/14 inventory, and every round-4 regression.
|
||||
- Mos stopping-criterion augment: command parsing is explicitly best-effort rather than a complete shell interpreter. Add B1 proving a parser-exotic alias launch with the raw dangerous flag is still RED by primitive anchoring, and B2 proving a parser-missed non-dangerous alias launch reaches the global `.*` hook and fails closed with `GATE_UNAVAILABLE` when no lease session exists. Document A (realistic parser matrix) + B (robust residual backstops); fresh reviewers supply criterion C (no new non-overlapping finding).
|
||||
- RED commit `91a4a983`: all 10 prefix×variable cases failed as expected before the fix—quoted/unquoted `exec`, `command`, `nohup`, and `env A=1`, each in multiline and same-line assignment shapes.
|
||||
- GREEN structural resolution: `shell_command_tokens()` now owns command-position prefix skipping for both literal and variable callers, including nested `exec`/`command`/`nohup`/`env` ordering. `runtime_variables` is threaded into `is_shell_direct_invocation()` and the same terminal-token resolver backs `executes_runtime_variable()`; exact `$v` and `${v}` references are resolved after `shlex` removes quoting. Same-line runtime assignment delimiters include shell operators.
|
||||
- Residual backstops: B1 proves alias-indirected dangerous mode is classified `dangerous-primitive` even though the parser does not resolve the alias. B2 proves a non-dangerous alias residual remains parser-missed, then verifies the shipped global `.*` Claude hook and status-2 `GATE_UNAVAILABLE` denial for representative read, mutator, and custom/MCP tools without a lease session.
|
||||
- Stopping-criterion evidence A+B is committed in tests and architecture docs; C remains the fresh exact-head terra/Opus determination. Repository inventory remains exactly **14 gated / 14 total**.
|
||||
- Fresh round-5 coverage: permanent guard remains **97%** branch-aware aggregate (251 statements, 112 branches). Locked-good launcher and mutator-gate executables remain unchanged at their round-4 **100% / 100%** evidence.
|
||||
- Fresh round-5 gates: real-socket acceptance **50/50**; persistence **10/10**; launcher/gate **14/14**; guard **12/12**; coord **19/19**; Mosaic **1385/1385**; root **43/43**; typecheck **42/42**; lint **23/23**; format and diff checks green.
|
||||
@@ -1,95 +0,0 @@
|
||||
# WI-3 Scratchpad — Compaction revocation and runtime-generation rollover
|
||||
|
||||
- **Issue:** Gitea #830
|
||||
- **Branch:** `feat/830-compaction-revoke`
|
||||
- **Base HEAD:** `abd2791f59b3f06f46dd08e55298ced72f6aa7c2`
|
||||
- **Role:** sol author/build lane only; terra CODE and Opus SECREV are coordinator-owned.
|
||||
|
||||
## Mission prompt
|
||||
|
||||
Implement BUILD-BRIEF Deliverable 3.3 and D4 on merged WI-1/WI-2 under `packages/mosaic/`. Claude `PreCompact` and `SessionStart(matcher=compact)` plus Pi `session_before_compact`/`context` equivalents must revoke the active lease through the existing broker state machine. Any `runtime_generation` bump—including same-PID reload/resume/fork—must auto-revoke the prior incarnation so the new generation inherits no prior lease. M1 is Claude + Pi only.
|
||||
|
||||
Honor amended D2-v5 exactly: hard fail-closure when at least one observer fires or after lease expiry; both observers missing within TTL is an explicitly named bounded residual stale window (maximum 300 seconds, soak-tighten only), with no claim that the mutator gate bounds actions inside that window; total gate-hook miss is T-C. T12b/T30 must report both the within-TTL ALLOWED outcome and after-TTL DENIED outcome.
|
||||
|
||||
## Session start verification
|
||||
|
||||
- Worktree is clean on `feat/830-compaction-revoke` at exact required base `abd2791f59b3f06f46dd08e55298ced72f6aa7c2`; `origin/main` is the same SHA and includes merged WI-2 atop WI-1.
|
||||
- Authority SHA-256 verified:
|
||||
- BUILD-BRIEF: `89fdbc27ed0e5050dc7b52f3ef2ddaea691edf17fd89d51b15e26fb5ed47171b`
|
||||
- SPEC-v5: `a6d07ade835758e8488ca10d3b0631caf0beb93ea3a6733631f151b0c2f01433`
|
||||
- Ratification: `bac58319c9c4028b5b40e1129e0033cdb5a6b7b02033c25f06f4cb77d7779c67`
|
||||
- sol red-team: `3da326a4ea91767b731e128a93b13194e8002358101e30de3fcb8ca2f8f54faa`
|
||||
- WI-0 evidence pack SHA-256 `5d418306fcc597fd514e500bee40d1509f0bf467e46ee13fc5c280ed8274759d` read directly. Probe P3 is **PASS**: real Pi retained the same PID/starttime through reload/fork/new/resume while generations advanced and a prior VERIFIED generation was revoked.
|
||||
- P6 planner-return ruling SHA-256 `b7bbb6ea6e8d9a5c3366993642ab4e4f65b961af04936dcac20bfbcdcbaf1a09` read directly: feature WI admission is GO with the exact-delivery empirical compatibility fact and disclosed T-C middle-drop residual; no receipt redesign.
|
||||
|
||||
## Plan and budget
|
||||
|
||||
1. RED real-socket acceptance for T12b/T30, each Claude observer, same-PID generation rollover, Claude/Claudex hook wiring, and Pi lifecycle wiring.
|
||||
2. Add one broker client executable for observer revocation plus a private monotonic generation-file helper shared by launcher, gate, and revoker.
|
||||
3. Wire Claude `PreCompact`, `SessionStart(compact)`, and resume/clear generation rollover; merge equivalent mandatory hooks into isolated Claudex settings.
|
||||
4. Wire Pi pre/post compaction observers and reload/new/resume/fork generation rollover with local fail-closed tool blocking if lifecycle revocation fails.
|
||||
5. Document the D2-v5 bounded stale window without claiming the mutator gate bounds within-TTL actions; update protocol/security/operations/sitemap/checklist.
|
||||
6. Run focused real tests, independently measured executable coverage ≥85%, full repository gates, commit/push, open an unmerged `closes #830` PR, and hand off for terra CODE + mandatory Opus SECREV.
|
||||
|
||||
Working estimate: **35K tokens**. No explicit hard cap was supplied; reduce refactor breadth before touching locked broker authority/state-machine semantics.
|
||||
|
||||
## RED evidence
|
||||
|
||||
- New T12b/T30 test already reports the inherited primitive honestly: within-TTL **ALLOWED**, after-TTL **DENIED**. The complete AC remains RED because the mandatory threat-contract document is absent.
|
||||
- Focused real-socket suite is RED with 7 expected failures: missing revoker executable (both Claude observers + generation bump), missing Claude/Pi wiring, missing isolated Claudex observers, and missing D2-v5 disclosure.
|
||||
- Branch-focused Python suite is RED on the wished generation initializer/resolver interfaces and missing `lease_generation.py` / `revoke-lease.py`.
|
||||
- Pi lifecycle suite is RED because the wished standalone `lease-lifecycle.ts` observer/generation module does not exist.
|
||||
|
||||
## Locked discipline
|
||||
|
||||
- RED-first T12b/T30 and observer/generation tests; test commit precedes implementation.
|
||||
- Reuse broker `revoke_lease`; do not fork identity, lease, or transition authority.
|
||||
- Preserve revoke-first/promote-last and WI-1/WI-2 reviewed state machine.
|
||||
- ≥85% attributable executable coverage with real tests.
|
||||
- No author self-review, no merge, no `--no-verify`.
|
||||
|
||||
## Local implementation complete (push held)
|
||||
|
||||
Implemented on the WI-3 base `abd2791f59b3f06f46dd08e55298ced72f6aa7c2` without changing the reviewed broker state machine:
|
||||
|
||||
- Added `revoke-lease.py`, which authenticates through the existing broker session/generation and invokes `revoke_lease`. A fired observer that cannot confirm broker revocation advances the private generation as a local fence before returning non-zero.
|
||||
- Added `lease_generation.py`: owner/type/mode/size validation, no-follow opens, exclusive bump lock, monotonic `int64` generation, write-all + `fsync`, and fail-closed exhaustion/corruption handling.
|
||||
- `launch-runtime.py` creates `generation-<broker-session>.state` mode `0600` beside the socket before `exec`; `mutator-gate.py` resolves that current file value on every tool check.
|
||||
- Claude settings and isolated Claudex settings now preserve/install `PreCompact`, `SessionStart(compact)`, and resume/clear rollover hooks in addition to the global all-tools gate.
|
||||
- Pi now registers tested `session_before_compact`, `session_compact`→first `context`, and `session_start(reload|new|resume|fork)` handlers. Failed pre-compact revocation cancels compaction; failed post-compact/rollover revocation latches local all-tool denial.
|
||||
- Added PRD requirements, architecture/security/protocol/operations updates, sitemap entry, and the ignored-by-default documentation checklist (force-add required at commit).
|
||||
|
||||
### Acceptance and coverage evidence
|
||||
|
||||
- Focused acceptance: `19/19`; T12b/T30 prints within-TTL **ALLOWED** and after-TTL **DENIED**.
|
||||
- Pi lifecycle: `8/8`, with **100% statements/branches/functions/lines** attributable coverage.
|
||||
- New Python generation/revoker: `24/24`, **99% branch-aware aggregate coverage** (`lease_generation.py` 98%, `revoke-lease.py` 100%).
|
||||
- Mosaic package: `1399/1399`; framework shell Python `24/24`, launch guard `12/12`, permanent launch inventory `14 gated/14 total`.
|
||||
- Existing lease-broker real-socket acceptance: `37/37` within the package run.
|
||||
- Full repository: `43/43` Turbo tasks green; gateway `628 passed / 12 skipped`; Mosaic `1399/1399`.
|
||||
- Root typecheck: `42/42`; lint: `23/23`; format and `git diff --check` green.
|
||||
- Initial direct package test without first building the package reproduced the known missing-`dist/cli.js` harness condition; the canonical root Turbo test (which schedules `@mosaicstack/mosaic#build`) and explicit package build+test are green. No test was weakened.
|
||||
|
||||
### Review evidence
|
||||
|
||||
- Codex uncommitted code review: **APPROVE**, confidence `0.88`, zero findings. Its read-only sandbox could not rerun Vitest, but the author-side focused and full suites above were green.
|
||||
- Codex uncommitted security review: risk **none**, confidence `0.91`, zero findings.
|
||||
- Coordinator-mandated fresh exact-head terra CODE and Opus SECREV remain pending after rebase/push clearance; these local reviews do not replace that final gate.
|
||||
|
||||
### Hold and residuals
|
||||
|
||||
- **DO NOT PUSH OR OPEN A PR YET.** Coordinator requires flake-fix #838 to land, then WI-3 must rebase onto deterministic-green `main` before push.
|
||||
- Merge remains gated on #838, #827 Probe 3, and combined GO.
|
||||
- Named residual retained verbatim: when both observers are entirely missed, within-TTL consequential actions remain allowed; only lease expiry denies after the bounded stale window. No within-window mutator-action bound is claimed.
|
||||
|
||||
## Deterministic-main rebase evidence
|
||||
|
||||
- Fetched and confirmed `origin/main` at `8dfcf1903e385f977121069f798f476eb671fffc` (`#838` bounded broker deadlines, empty-read fail-closure, and de-flaked acceptance client).
|
||||
- Linear rebase completed. The only content conflict was `packages/mosaic/src/mutator-gate/runtime_tools_unittest.py`; resolution retained #838's `subprocess`/`threading` deadline regressions and WI-3's `stat` generation-state coverage. No authority/state-machine choice was ambiguous.
|
||||
- `packages/mosaic/src/mutator-gate/mutator-gate.acceptance.spec.ts` auto-merged on top of #838's shared `requestBrokerReply` helper. No inline socket/`JSON.parse` client was resurrected.
|
||||
- Verified WI-3 has zero diff from `origin/main` for #838-owned `daemon.py`, `broker-test-client.ts`, `lease-broker.acceptance.spec.ts`, `vitest.config.ts`, and `packages/mosaic/package.json`; bounded deadlines and the de-flaked harness are preserved byte-for-byte.
|
||||
- Required verbose acceptance command: **2 files / 56 tests green**. T12b/T30 still prints within-TTL **ALLOWED** and after-TTL **DENIED**.
|
||||
- Full Mosaic package after explicit build: **74 files / 1408 tests green**; deadline unit `2/2`, runtime tools `25/25`, launch guard `12/12`, inventory `14/14`.
|
||||
- Full repository: **43/43 Turbo tasks green**. Root typecheck `42/42`, lint `23/23`, format and diff checks green.
|
||||
- Attributable coverage remains Python **99%** branch-aware and Pi lifecycle **100%** statements/branches/functions/lines.
|
||||
- Push and PR remain held pending combined GO and all WI-3 merge gates. The coordinator-owned promote-lease-lost-ACK SPEC amendment/backstop is acknowledged as a future merge prerequisite and was not retro-expanded into this core rebase/build.
|
||||
@@ -1,13 +0,0 @@
|
||||
# #832 Receipt-challenge protocol — build scratchpad
|
||||
|
||||
- **Objective:** Deliver WI-5 receipt-challenge protocol ACs T25, T26, T28, and T29 only.
|
||||
- **Authority:** BUILD-BRIEF, SPEC-v5, ratification, and red-team hashes verified in STEP-0.
|
||||
- **Base:** `e522b22fa4492861b0fcd4a956a8795c54eb9bfe` (`origin/main`).
|
||||
- **Constraints:** Byte-build only: no live broker/socket/systemd/tmux mutation. No PR, self-review, or probe fire. T27/T30 are out of scope.
|
||||
- **Plan:**
|
||||
1. Add red-first deterministic T26/T29 in-build tests that call shipped normative construction and broker path.
|
||||
2. Add an unexecuted, isolated P5 out-of-process replay harness that drives the shipped daemon and asserts consume-before-promote for T25/T28.
|
||||
3. Implement the broker-minted receipt challenge and exact receipt observation/consume/promote path.
|
||||
4. Run unit, framework-shell, compile, lint, and type checks; push after the required queue guard; report to `mosaic-100`.
|
||||
- **Risks:** The standalone harness must drive the real daemon without a divergent fixture. If that is impossible, stop and flag Mos.
|
||||
- **Evidence:** Initial RED recorded in `/home/hermes/agent-work/reviews/832-wi5-red-receipt-challenge.log`; initial green checks passed. Remediation RED recorded in `/home/hermes/agent-work/reviews/832-wi5-remediation-red.log` before observer/payload implementation; remediation green passed. Remediation-2 RED recorded in `/home/hermes/agent-work/reviews/832-wi5-remediation2-red.log`: each rejected begin restored prior VERIFIED authority. Remediation-2 GREEN: receipt unittest (5: all `INVALID_CONSTRUCTION`, `PAYLOAD_CONSTRUCTION_REFUSED`, and `PAYLOAD_BINDING_MISMATCH` cases preserve UNVERIFIED and deny the next mutator), normative-fragments unittest (5), state-store regression (10), full mutator-gate acceptance (20, including the real begin → observer → consume → promote path), `py_compile`, Mosaic package lint/typecheck, and targeted Prettier check. The P5 harness remains unfired. Coverage tooling remains unavailable (`python3 -m coverage`: module not installed). Push pending.
|
||||
@@ -1,15 +0,0 @@
|
||||
# #833 constrained recovery command — build scratchpad
|
||||
|
||||
- **Objective:** Deliver WI-6 plus Mos-ruled B1/B2 and R2 Claude-only literal-argv repair: no shell-active recovery mapping bypass, unchanged Pi gate/B2 observer, AC-1/C4 preservation, and an unfired P6 probe.
|
||||
- **Authority:** STEP-0 SHA-256 verified 4/4 against the supplied BUILD-BRIEF, SPEC-v5, ratification, and red-team records.
|
||||
- **Base:** exact `07553ead337a70a9241f826d27571650262b289c`; new branch `feat/833-constrained-recovery-command`; merge-base assertion passed before any commit.
|
||||
- **Constraints:** No rebase/pull during build; no live install/symlink or live broker/socket/tmux/systemd/model-stream activation; no self-review, PR, merge, push, or P6 fire. `docs/TASKS.md` is orchestrator-owned and will not be modified.
|
||||
- **Plan:**
|
||||
1. Add red-first unit tests against the recovery broker entrypoint for fresh recovery challenge, normal-receipt replay refusal, observable partial-delivery refusal, and the explicit middle-drop negative capability; commit the RED test and preserve its command output.
|
||||
2. Implement the recovery command as a thin driver over shared WI-5 broker transitions and the trusted observer seam; it never accepts caller receipt text.
|
||||
3. Add the source-resident skill under `packages/mosaic/framework/skills/`, plus a tmp-only #824 bridge projection test.
|
||||
4. Build an unfired, default-3-run P6 standalone real-socket driver; it is not added to package scripts and will not be run.
|
||||
5. Run targeted broker/mutator/receipt suites, lint, and format check; report head to `mosaic-100` and stop.
|
||||
- **Risks:** The observer can only represent an exact latest message. Tail-preserving middle-drop is intentionally not claimed receipt-detectable (T-C residual deferred to WI-7 server evidence).
|
||||
- **Evidence:** Original RED test committed at `3b5513bd6efad0c06b599fc759a66cff4286db04`; expected `UNKNOWN_ACTION` is logged in `/home/hermes/agent-work/reviews/833-wi6-red.log`. B1/B2 repair RED is `f4beedc3e7ac2e142dcbdeefb0e5ee40c20d9b86` in `/home/hermes/agent-work/reviews/833-wi6-repair-red.log`. R2 adversarial RED is committed at `65e2bd71cf360b6f45c86eec0b06ae24494832d8` in `/home/hermes/agent-work/reviews/833-wi6-repair-R2-red.log` before the literal-only gate source: the private real-gate/real-daemon battery covers every argv position (executable, path, phase, each flag, each value) for command substitution, backticks, parameter/arithmetic expansion, brace/tilde, process substitution, glob, redirects, control operations, embedded newline, and quotes. P6 remains rebuilt and unfired. The ordinary package Vitest/lint/typecheck/root-format commands cannot resolve their executables in this intentionally dependency-free fresh worktree (`node_modules` absent); no install/symlink workaround was used.
|
||||
- **Budget:** No explicit task token cap was supplied; scope is fixed to WI-6 and no unrelated behavior will be added.
|
||||
@@ -1,44 +0,0 @@
|
||||
# Issue #838 — Broker acceptance socket flake
|
||||
|
||||
## Objective
|
||||
|
||||
Eliminate high-contention uncaught JSON parse failures in lease-broker and mutator-gate acceptance helpers without laundering malformed/empty replies into passing assertions.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Branch: `fix/838-broker-acceptance-flake` in `/home/hermes/agent-work/stack-838-flakefix`.
|
||||
- Red-first TDD with a forced empty/truncated reply path and deterministic rejection or documented retry.
|
||||
- Read newline-framed replies completely; reject malformed broker replies with byte length/content context.
|
||||
- Determine RIDER2 branch before finalizing: test-harness-only `(a)` or daemon write truncation `(b)`.
|
||||
- If product-side, prove the real Claude/Pi adapter read path fails closed; fix any allow-risk.
|
||||
- Coverage >=85% per changed executable through real tests.
|
||||
- Full suite and repository gates green; independent exact-head review required.
|
||||
- Push and open a PR containing `closes #838`; do not merge.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-07-17: Reclaimed from #824. Confirmed clean worktree on `fix/838-broker-acceptance-flake` at main base `abd2791f59b3f06f46dd08e55298ced72f6aa7c2`.
|
||||
- RED evidence: after dependency setup, `broker-test-client.spec.ts` failed to load the intentionally absent shared client module. Its contract forces empty-close retry, repeated truncated-close rejection with byte context, and newline-terminated malformed-reply rejection.
|
||||
- RIDER2 verdict: branch **(b)**. `daemon.py` starts one connection deadline before request reading, then may spend that budget waiting for `broker_lock`; after handling, `remaining <= 0` returns without writing. A timed `sendall` failure can likewise close after a partial write. A deterministic socketpair probe held the lock past `CONNECTION_DEADLINE_SECONDS` and observed `deadline_probe_reply_length=0`.
|
||||
- Adapter tripwire: real subprocess executions of `mutator-gate.py` for both `--runtime claude` and `--runtime pi` against actual Unix servers returning empty and truncated replies all exited 2 with `GATE_UNAVAILABLE`. Adapter fail-close is proven; there is no ALLOW risk.
|
||||
- Residual: production broker reply loss remains an availability-denial path under extreme contention, but cannot grant mutator authority. The acceptance-only client retries early closes and otherwise rejects with response byte length, escaped bytes, and hex; malformed newline-framed replies are never retried or converted to reply objects.
|
||||
- Shared client now owns newline framing and parsing for both acceptance suites. Focused suites pass 60 tests, including the real adapter tripwire.
|
||||
- Coverage gate: changed helper is 100% statements/lines/functions and 90% branches; existing `skill.ts` remains above 85% per-file thresholds.
|
||||
|
||||
## Scope corrections and bounded product repair
|
||||
|
||||
- Coordinator correction superseded the initial push/PR and retry language: this lane is BUILD-ONLY, and early-close retries are forbidden because they can mask a committed broker transaction. Nothing may be pushed or opened until explicitly cleared.
|
||||
- Revised RED evidence: the no-retry empty/truncated tests failed because the first failed exchange was retried into `{ ok: true }`; the daemon regression failed because a slow completed `broker.handle()` produced `b''` instead of a newline-framed reply.
|
||||
- Client repair: both former duplicated helpers use one shared reader. Empty, truncated, malformed, oversized, timed-out, and socket-error replies reject `BrokerTransportError` with a typed `kind`, attempt count fixed at one, response length, escaped bytes, and hex. No retry and no catch-to-reply conversion exists.
|
||||
- Product repair: `daemon.py` now has independent bounded read, broker-lock queue, and send budgets. Lock queue exhaustion returns explicit `BROKER_BUSY` before `broker.handle()` can mutate state. Once handling starts it finishes atomically, and its reply always receives a fresh send timeout instead of being skipped because read/lock/fsync consumed a shared deadline.
|
||||
- Product GREEN evidence: deterministic socketpair tests prove lock saturation returns framed `BROKER_BUSY` without invoking `handle()`, and a handle that completes after the former one-second shared deadline still returns its complete framed reply.
|
||||
- RIDER2b remains **fail-closed**: real Claude and Pi `mutator-gate.py` subprocesses against empty and truncated Unix-socket replies exit 2 with `GATE_UNAVAILABLE`; no malformed/default ALLOW was observed.
|
||||
- Residual/tripwire: an unavoidable peer disconnect or send failure can still lose acknowledgement after a valid transaction commits. The affected adapter call fails closed. A valid `promote_lease` may nevertheless remain VERIFIED after its acknowledgement is lost; that is authority-observability divergence requiring WI-3/Opus security review rather than expansion of #838. #838 does not add retries or attempt a protocol redesign.
|
||||
- Final package evidence: recursive Mosaic dependency build passed; 73 Vitest files / 1,392 tests passed; deadline unit tests 2/2, real runtime tool tests 15/15, launch guard tests 12/12, inventory 14/14, and shell regressions passed.
|
||||
- Final coverage: `broker-test-client.ts` 99.24% statements/lines, 86.11% branches, 100% functions under per-file >=85% thresholds. Repository typecheck 42/42, lint 23/23, and format check passed.
|
||||
- Independent Codex exact-head review requested one framing fix: a valid frame followed by trailing bytes in a later socket chunk could resolve before the garbage arrived. Security review also flagged complete token-bearing reply bodies in diagnostic properties/logs.
|
||||
- Review RED evidence: delayed cross-chunk garbage resolved `{ ok: true }` instead of rejecting, and a truncated `promotion_token` remained in the typed error. The tests use separate timed writes to prevent kernel/event-loop coalescing.
|
||||
- Review remediation: the shared client now accumulates through EOF, requires exactly one terminal newline, then parses inside a rejecting error boundary. Diagnostic bodies are capped at 256 bytes, sensitive broker fields are fully redacted, and a SHA-256 digest preserves correlation without credential disclosure.
|
||||
- Post-review coverage: `broker-test-client.ts` 99.35% statements/lines, 86.66% branches, 100% functions. Final full suite is 73 files / 1,394 tests plus all Python/shell gates; recursive build, typecheck, lint, and format are green.
|
||||
- Fresh exact-head Codex security review: risk `none`, no findings. Fresh code review found only that the real-adapter subprocess proof lacked a timeout; it now has a five-second bound and fails with runtime/wire context while closing the fake server. The focused Python suite remains 15/15 green.
|
||||
- Mandatory Opus SECREV remains coordinator-owned and pending before any push/PR decision; this build is intentionally local-only.
|
||||
@@ -1,82 +0,0 @@
|
||||
# B1 / @next Durable Publish Pipeline — Design
|
||||
|
||||
## Objective
|
||||
|
||||
Make `next` a durable integration line that publishes the artifacts required by downstream federation boot tests without manual builds.
|
||||
|
||||
Every merge to `next` publishes:
|
||||
|
||||
1. **npm prerelease packages** to the Gitea npm registry with dist-tag `next`.
|
||||
2. **Gateway container image** tagged only as `gateway:sha-<short>`.
|
||||
|
||||
The existing stable release behavior remains isolated to `main` / tags.
|
||||
|
||||
## Registry verification
|
||||
|
||||
Target registry: `https://git.mosaicstack.dev/api/packages/mosaicstack/npm/`.
|
||||
|
||||
Pre-implementation checks:
|
||||
|
||||
- `npm view @mosaicstack/mosaic dist-tags --registry https://git.mosaicstack.dev/api/packages/mosaicstack/npm/ --json` returned a dist-tags object (`latest: 0.0.48`).
|
||||
- `npm view @mosaicstack/mosaic@latest version --registry https://git.mosaicstack.dev/api/packages/mosaicstack/npm/` resolved `0.0.48`.
|
||||
- `@next` currently returns 404 because no `next` dist-tag exists yet; this is expected before the first next prerelease publish.
|
||||
|
||||
Pipeline design includes a post-publish verification that `npm view @mosaicstack/mosaic@next version` resolves to the exact CI-computed prerelease version. If Gitea fails to honor the `next` dist-tag, the pipeline fails closed.
|
||||
|
||||
## Version scheme
|
||||
|
||||
The prerelease version is computed at publish time only; no `package.json` version changes are committed.
|
||||
|
||||
For each non-private `@mosaicstack/*` package:
|
||||
|
||||
```text
|
||||
<target-stable>-next.<CI_PIPELINE_NUMBER>
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `CI_PIPELINE_NUMBER` is Woodpecker's monotonic pipeline number.
|
||||
- `target-stable` is the package's current committed stable version with the patch component incremented.
|
||||
- Example: `@mosaicstack/mosaic` `0.0.48` publishes as `0.0.49-next.1626`.
|
||||
- Example: `@mosaicstack/gateway` `0.0.6` publishes as `0.0.7-next.1626`.
|
||||
|
||||
Rationale:
|
||||
|
||||
- npm semver sorts `0.0.49-next.1627` above `0.0.49-next.1626`.
|
||||
- The prerelease does not overtake the future stable `0.0.49`.
|
||||
- The monotonic pipeline number avoids conflicts across repeated `next` merges.
|
||||
|
||||
## Branch and tag guardrails
|
||||
|
||||
| Pipeline path | Branch/event | Publishes | Forbidden |
|
||||
| --------------------- | ------------------------------ | ------------------------------------------------------- | ---------------------- |
|
||||
| stable npm publish | `main` push/manual or tag | package versions already committed in package manifests | `@next` dist-tag |
|
||||
| next npm publish | `next` push/manual only | CI-computed prereleases with `--tag next` | `latest` dist-tag |
|
||||
| gateway image | `main` push/manual or tag | `sha-<short>` + `latest` on main + tag on tag events | next prerelease npm |
|
||||
| gateway image | `next` push/manual only | `sha-<short>` only | `latest` |
|
||||
| appservice/web images | `main` push/manual or tag only | existing stable image behavior | next image publication |
|
||||
|
||||
The pipeline has explicit branch checks inside the publish commands as a second fail-closed layer beyond Woodpecker `when` clauses.
|
||||
|
||||
## Implementation plan
|
||||
|
||||
1. Widen `.woodpecker/publish.yml` top-level `when` to include `next` so the publish pipeline runs on next merges.
|
||||
2. Keep existing `publish-npm` on `main` / tags only.
|
||||
3. Add `publish-next-npm` for `next` push/manual only:
|
||||
- configure Gitea npm auth from existing `gitea_token` secret as `NPM_TOKEN`;
|
||||
- preflight registry dist-tag metadata;
|
||||
- compute prerelease versions in CI by temporarily editing package manifests in the workspace;
|
||||
- run `pnpm publish ... --tag next` against non-private `@mosaicstack/*` packages;
|
||||
- verify `@mosaicstack/mosaic@next` resolves to the computed version.
|
||||
4. Split image `when` anchors:
|
||||
- `image_build_when` includes `next` and is used by `build-gateway`;
|
||||
- `main_image_build_when` keeps appservice/web on main/tags only.
|
||||
5. Keep gateway next image destinations to `sha-<short>` only; no `latest` on next.
|
||||
|
||||
## Risk controls
|
||||
|
||||
- Auth/registry failures are fatal.
|
||||
- No manual image build/push path is introduced.
|
||||
- No production `latest` tags are touched from `next`.
|
||||
- No `@latest` npm dist-tags are touched from `next`.
|
||||
- All changes live in CI config and docs; no runtime source behavior changes.
|
||||
@@ -1,34 +0,0 @@
|
||||
# B2 — Fresh-install skills sync path
|
||||
|
||||
## Problem
|
||||
|
||||
Greenfield wizard on `next` reported:
|
||||
|
||||
```text
|
||||
Skills sync script not found at ~/.config/mosaic/bin/mosaic-sync-skills
|
||||
Skills: install failed
|
||||
```
|
||||
|
||||
## Diagnosis
|
||||
|
||||
The framework install migration removed the legacy `~/.config/mosaic/bin/` directory and now installs framework helper scripts under:
|
||||
|
||||
```text
|
||||
~/.config/mosaic/tools/_scripts/
|
||||
```
|
||||
|
||||
`packages/mosaic/src/stages/finalize.ts` still resolved wizard helper scripts from `mosaicHome/bin`, so wizard-selected skills failed even though `mosaic-sync-skills` was present in the current framework layout.
|
||||
|
||||
## Fix
|
||||
|
||||
- Resolve framework helper scripts through `tools/_scripts/<name>` first.
|
||||
- Keep a legacy `bin/<name>` fallback for pre-migration installs.
|
||||
- Point missing-script warnings at the current `tools/_scripts` layout.
|
||||
- Update the finalize skills test fixture to model the fresh framework layout.
|
||||
- Update framework README examples from legacy `bin/` helper paths to `tools/_scripts/`.
|
||||
|
||||
## Verification
|
||||
|
||||
- Unit: `pnpm --filter @mosaicstack/mosaic test -- finalize-skills`
|
||||
- Gates: `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, `pnpm build`
|
||||
- Fresh path: ran `packages/mosaic/framework/install.sh` with a temp `MOSAIC_HOME` and `MOSAIC_SYNC_ONLY=1`; verified `tools/_scripts/mosaic-sync-skills` exists, legacy `bin/mosaic-sync-skills` does not, and the script installs a selected fake `lint` skill into Mosaic + Pi runtime skill directories.
|
||||
@@ -1,36 +0,0 @@
|
||||
# B3 — Wizard completion ordering
|
||||
|
||||
## Problem
|
||||
|
||||
The wizard printed the success summary / `Mosaic is ready.` during `finalizeStage`, before the gateway configuration stage had completed its daemon health check. If the gateway health gate later failed, the user could see a success claim followed by a gateway failure.
|
||||
|
||||
## Diagnosis
|
||||
|
||||
`finalizeStage` handled both mutation work and terminal success messaging. Wizard paths then ran `gatewayConfigStage` and `gatewayBootstrapStage` afterward:
|
||||
|
||||
1. finalize writes config, links runtime assets, syncs skills, runs doctor;
|
||||
2. finalize prints `Installation Summary` + `Mosaic is ready.`;
|
||||
3. gateway config starts/waits for daemon health;
|
||||
4. gateway bootstrap runs.
|
||||
|
||||
The summary needed to be deferred until after the gateway readiness gates.
|
||||
|
||||
## Fix
|
||||
|
||||
- `finalizeStage` now returns a `showSummary()` callback and supports `deferSummary`.
|
||||
- Wizard/quick-start paths call finalize with `deferSummary: true`.
|
||||
- `showSummary()` is called only after gateway config reports ready and bootstrap completes, or immediately when the caller explicitly skips gateway setup.
|
||||
- If gateway health/config reports not ready, the wizard returns/aborts without printing the success summary.
|
||||
- Folded in adjacent runtime install hint fix for Pi: `curl -fsSL https://pi.dev/install.sh | sh`.
|
||||
|
||||
## Verification
|
||||
|
||||
- Added unified-wizard coverage for summary-after-health and no-summary-on-health-failure.
|
||||
- Targeted: `pnpm --filter @mosaicstack/mosaic test -- unified-wizard finalize-skills`
|
||||
- `pnpm format:check`
|
||||
- `pnpm typecheck`
|
||||
- `pnpm lint`
|
||||
- `pnpm build`
|
||||
- `pnpm test`
|
||||
- Codex code review: approve.
|
||||
- Codex security review: one low finding on the requested Pi `curl | sh` install hint; no security finding in the wizard completion-ordering change.
|
||||
@@ -1,36 +0,0 @@
|
||||
# B4 — Wizard step deduplication
|
||||
|
||||
## Problem
|
||||
|
||||
Greenfield wizard testing showed completed wizard steps could be executed again after the menu marked them `[done]`. In practice this made the Providers/API-key flow and Skills flow appear twice in one wizard run.
|
||||
|
||||
There was a second related API-key duplication path: when the Providers step was completed with no key, `gatewayConfigStage` still prompted for `ANTHROPIC_API_KEY` during Finish because it only skipped the gateway API-key prompt when `providerKey` was non-empty.
|
||||
|
||||
## Diagnosis
|
||||
|
||||
- `runMenuLoop` labeled completed sections with `[done]`, but still dispatched the selected step again if the user selected that row.
|
||||
- Quick Start ran Providers and Skills but did not mark those sections complete in `completedSections`.
|
||||
- `runFinishPath`/`quickStartPath` defaulted `providerType` to `none` for gateway config, which made it impossible for `gatewayConfigStage` to distinguish:
|
||||
- provider step completed and user intentionally skipped the key, vs.
|
||||
- provider step was never run.
|
||||
|
||||
## Fix
|
||||
|
||||
- Added a shared menu section key helper and a completed-step guard in `runMenuLoop`.
|
||||
- Completed menu steps now log a skip message instead of re-running their stage.
|
||||
- Quick Start marks Providers and Skills complete after running them.
|
||||
- Finish/Quick Start now pass `state.providerType` as-is to gateway config instead of defaulting to `none`.
|
||||
- `gatewayConfigStage` treats `providerType: 'none'` as an explicit completed provider setup with no key and skips the second gateway API-key prompt.
|
||||
|
||||
## Verification
|
||||
|
||||
- Added unified wizard regression coverage asserting repeated Providers/Skills menu selections only execute each stage once.
|
||||
- Added gateway config coverage asserting `providerType: 'none'` does not prompt for a gateway API key and writes no API key env var.
|
||||
- Targeted: `pnpm --filter @mosaicstack/mosaic test -- unified-wizard gateway-config`
|
||||
- `pnpm format:check`
|
||||
- `pnpm typecheck`
|
||||
- `pnpm lint`
|
||||
- `pnpm build`
|
||||
- `pnpm test`
|
||||
- Codex code review: approve.
|
||||
- Codex security review: no findings.
|
||||
@@ -1,47 +0,0 @@
|
||||
# BUG-CLI Scratchpad
|
||||
|
||||
## Objective
|
||||
|
||||
Fix 4 CLI/TUI polish bugs in a single PR (issues #192, #193, #194, #199).
|
||||
|
||||
## Issues
|
||||
|
||||
- #192: Ctrl+T leaks 't' into input
|
||||
- #193: Duplicate React keys in CommandAutocomplete
|
||||
- #194: /provider login false clipboard claim
|
||||
- #199: TUI shows hardcoded version "0.0.0"
|
||||
|
||||
## Plan and Fixes
|
||||
|
||||
### Bug #192 — Ctrl+T character leak
|
||||
|
||||
- Location: `packages/cli/src/tui/app.tsx`
|
||||
- Fix: Added `ctrlJustFired` ref. Set synchronously in Ctrl+T/L/N/K handlers, cleared via microtask.
|
||||
In the `onChange` wrapper passed to `InputBar`, if `ctrlJustFired.current` is true, suppress the
|
||||
leaked character and return early.
|
||||
|
||||
### Bug #193 — Duplicate React keys
|
||||
|
||||
- Location: `packages/cli/src/tui/components/command-autocomplete.tsx`
|
||||
- Fix: Changed `key={cmd.name}` to `key={`${cmd.execution}-${cmd.name}`}` for uniqueness.
|
||||
- Also: `packages/cli/src/tui/commands/registry.ts` — `getAll()` now deduplicates gateway commands
|
||||
that share a name with local commands. Local commands take precedence.
|
||||
|
||||
### Bug #194 — False clipboard claim
|
||||
|
||||
- Location: `apps/gateway/src/commands/command-executor.service.ts`
|
||||
- Fix: Removed the `\n\n(URL copied to clipboard)` suffix from the provider login message.
|
||||
|
||||
### Bug #199 — Hardcoded version "0.0.0"
|
||||
|
||||
- Location: `packages/cli/src/cli.ts` + `packages/cli/src/tui/app.tsx`
|
||||
- Fix: `cli.ts` reads version from `../package.json` via `createRequire`. Passes `version: CLI_VERSION`
|
||||
to TuiApp in both render calls. TuiApp has new optional `version` prop (defaults to '0.0.0'),
|
||||
passes it to TopBar instead of hardcoded `"0.0.0"`.
|
||||
|
||||
## Quality Gates
|
||||
|
||||
- CLI typecheck: PASSED
|
||||
- CLI lint: PASSED
|
||||
- Prettier format:check: PASSED
|
||||
- Gateway lint: PASSED
|
||||
@@ -0,0 +1,54 @@
|
||||
# DOCS-IA-001 — Documentation Information Architecture
|
||||
|
||||
- **Task:** DOCS-IA-001
|
||||
- **Internal reference:** `TASKS:DOCS-IA-001`
|
||||
- **Objective:** Codify the canonical `docs/` structure and authoring rules in `docs/README.md` before moving or rewriting existing documentation.
|
||||
- **Scope:** README contract only; no document migration in this slice.
|
||||
- **Approved design:** `docs/plans/2026-08-10-docs-information-architecture-design.md`
|
||||
- **Implementation plan:** `docs/plans/2026-08-10-docs-structure-readme.md`
|
||||
|
||||
## Plan
|
||||
|
||||
1. Replace the starter `docs/README.md` with the approved target tree and placement policy.
|
||||
2. Document source-of-truth, audience-book, artifact, migration, and Obsidian link rules.
|
||||
3. Run focused formatting, whitespace, structure, link, and scope checks.
|
||||
4. Commit only `docs/README.md`; preserve unrelated staged and untracked changes.
|
||||
|
||||
## Progress
|
||||
|
||||
- [x] Context inventory completed.
|
||||
- [x] Design approved by user.
|
||||
- [x] Design committed as `205cc0d`.
|
||||
- [x] Implementation plan written.
|
||||
- [x] Scratchpad created.
|
||||
- [x] README updated.
|
||||
- [x] Focused verification completed.
|
||||
- [x] Scoped documentation commit created (`docs: codify documentation structure`).
|
||||
|
||||
## Tests and verification
|
||||
|
||||
| Check | Result |
|
||||
| --- | --- |
|
||||
| Markdown formatting | PASS — `pnpm exec prettier --check docs/README.md docs/plans/2026-08-10-docs-structure-readme.md docs/scratchpads/DOCS-IA-001.md` |
|
||||
| Whitespace validation | PASS — `git diff --no-index --check` for all new Markdown files |
|
||||
| Required structure anchors | PASS — root controls, books, artifact directories, Obsidian, and retired `mosaic-stack` boundary found |
|
||||
| README-only scope check | PASS — the scoped documentation commit contains only this task's README, plan, and scratchpad; unrelated changes remain outside the commit |
|
||||
|
||||
## Risks and blockers
|
||||
|
||||
- Existing documentation remains under `docs/_old_structure/`; this slice does not migrate it.
|
||||
- Existing source/tests reference legacy paths such as `docs/fleet/` and `docs/federation/`; those references require a later migration slice.
|
||||
- `docs/TASKS.md` has a single-writer orchestrator policy and is intentionally not modified here.
|
||||
- `docs/GETTING_STARTED.md` is an unrelated pre-staged deletion and must remain outside this task commit.
|
||||
- `docs/.obsidian/` is pre-existing untracked vault metadata and must not be modified or committed here.
|
||||
|
||||
## Final evidence
|
||||
|
||||
- `docs/README.md` now defines the complete target tree, placement matrix, source-of-truth policy, authoring workflow, migration policy, and Obsidian/Git link conventions.
|
||||
- `pnpm exec prettier --check docs/README.md docs/plans/2026-08-10-docs-structure-readme.md docs/scratchpads/DOCS-IA-001.md` passed.
|
||||
- `git diff HEAD^ HEAD --check` and the staged-index whitespace check passed.
|
||||
- Focused structure and retired-boundary checks passed.
|
||||
- All three relative Markdown links in the README resolve.
|
||||
- The scoped documentation commit contains only the README, plan, and scratchpad.
|
||||
- The pre-existing staged deletion of `docs/GETTING_STARTED.md`, modified `.mosaic/orchestrator/*` files, and untracked `docs/.obsidian/` metadata remain outside the documentation commit.
|
||||
- Content migration, sitemap refresh, and legacy source/test path updates remain explicitly deferred to later slices.
|
||||
@@ -0,0 +1,197 @@
|
||||
# DOCS-IA-002 — Documentation Catalog and Truth Audit
|
||||
|
||||
- **Task:** DOCS-IA-002
|
||||
- **Internal reference:** `TASKS:DOCS-IA-002`
|
||||
- **Plan:** `docs/plans/2026-08-10-docs-catalog-audit.md`
|
||||
- **Objective:** Catalog all documentation and audit validity/truthfulness before migration.
|
||||
- **Mode:** Read-only discovery; coordinator reconciles findings.
|
||||
|
||||
## Parallel Pi audit lanes — 2026-08-10
|
||||
|
||||
All lanes used `pi --model openai-codex/gpt-5.6-luna:max` in detached worktrees with only `read` and `bash` tools. No lane edited files, staged changes, committed, or started services.
|
||||
|
||||
| Lane | Assignment | Outcome |
|
||||
| -------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `docs-prd` | Audit `docs/PRD.md`, linked workstream documents, requirements claims, and package/source alignment. | Completed. PRD remains draft/normative; broken fleet/Kanban links and held/contradicted claims require human disposition before promotion. |
|
||||
| `docs-api` | Compare `docs/openapi-tess.yaml` with gateway controllers, routes, DTOs, auth guards, and tests. | Completed. Tess contract is scoped and incomplete for the gateway; API migration requires a full route/schema/auth/error inventory and human scope decision. |
|
||||
| `docs-control` | Audit `docs/MISSION-MANIFEST.md` and `docs/TASKS.md` without changing orchestrator-owned state. | Completed. Active versus historical MVP/workstream status is unresolved; status, archive/rehome, and control-plane repairs remain orchestrator/human-owned. |
|
||||
| `docs-source` | Map live consumers of `docs/fleet`, `docs/federation`, `docs/architecture`, `docs/tess`, and `docs/native-kanban-sot`. | Completed. Legacy roots are absent from current `docs/`; architecture/fleet have source/test consumers, while Tess/Kanban are primarily control-plane/navigation dependencies. Recommended order starts with authority decisions, then architecture security, fleet consumers, and API/Tess migration. |
|
||||
|
||||
The four isolated worktrees were clean and removed after report collection.
|
||||
|
||||
## Autonomous finish-line orchestration — 2026-08-10
|
||||
|
||||
- **Coordinator session:** `019fed44-977c-73b9-b14a-58de29c0cb51`
|
||||
- **Recovery anchor:** Resume from this section and `git log`; completed slices are immutable scoped commits, while active lane reports are advisory until reconciled here.
|
||||
- **Worker policy:** Isolated worktrees, read-only evidence collection, no services, no database access, no edits to `docs/TASKS.md`, `docs/MISSION-MANIFEST.md`, `docs/PRD.md`, or `.mosaic/orchestrator/*`.
|
||||
- **Decision policy:** Migrate only evidence-backed current contracts or clearly historical artifacts. Queue product/control-plane/API-authority decisions for humans.
|
||||
|
||||
| Lane | Assignment | State |
|
||||
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `docs-channel` | Verify the archived channel protocol against shared DTOs, gateway/Discord implementation, and tests; identify safe canonical destination and contradictions. | Complete — rewrite required; shared DTO and Discord baseline are current, while registry, Telegram parity, Matrix, identity linking, and multiplexing claims are draft or contradicted. |
|
||||
| `docs-runtime` | Classify the remaining runtime-portability ADR and M1 architecture pages against source/tests and live references. | Complete — egress ADR remains a draft RFC; M1 lease/fencing is an implemented decision requiring precision corrections and a held operations companion. |
|
||||
| `docs-reports` | Classify archived reports/checklists into exact evidence/archive destinations and identify references that must move with them. | Complete — 13 evidence artifacts classified; the byte-identical #756 batch was selected and migrated. |
|
||||
| `docs-guides` | Identify the next safe user/admin/developer guide slices, verifying commands and held PostgreSQL/runtime boundaries. | Complete after automatic compaction — upgrade/recovery is the next safe rewrite; deployment, tier migration, Gateway/Web activation, and PostgreSQL remain held. |
|
||||
|
||||
### Implementation lanes
|
||||
|
||||
| Lane | Branch | Owned slice | State |
|
||||
| ------------------- | --------------------------------- | ------------------------------------------------------ | ------------------------------------- |
|
||||
| `docs-channel-impl` | `docs/channel-protocol-migration` | Rewritten current channel architecture page only. | Complete; cherry-picked as `00bdf8b`. |
|
||||
| `docs-runtime-impl` | `docs/runtime-m1-migration` | M1 decision and held connector-lease operations guide. | Complete; cherry-picked as `631567d`. |
|
||||
| `docs-upgrade-impl` | `docs/upgrade-recovery-migration` | Verified local upgrade/recovery administrator guide. | Complete; cherry-picked as `39987a5`. |
|
||||
| `docs-reports-impl` | `docs/report-evidence-migration` | Four byte-identical historical evidence moves. | Complete; cherry-picked as `9f74187`. |
|
||||
|
||||
Shared indexes, navigation, audit records, integration review, and final commits remain coordinator-owned.
|
||||
|
||||
### Implementation wave 2
|
||||
|
||||
| Lane | Branch | Owned slice | State |
|
||||
| ---------------------- | --------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
||||
| `docs-channel-guides` | `docs/channel-audience-guides` | Discord admin, user workflow, and adapter-authoring pages. | Complete; cherry-picked as `f4faa3f`. |
|
||||
| `docs-lease-ops` | `docs/lease-operations-migration` | Current/held lease-broker operational boundary. | Complete; cherry-picked as `6b3ebce`, then placed under the canonical testing chapter. |
|
||||
| `docs-egress-rfc` | `docs/egress-rfc-migration` | Explicitly draft optional egress gateway RFC. | Complete; cherry-picked as `0692d99`. |
|
||||
| `docs-dashboard-guide` | `docs/dashboard-guide-migration` | Verified current web-dashboard user page. | Complete; cherry-picked as `7fa0f65`. |
|
||||
|
||||
### Final review lanes
|
||||
|
||||
| Lane | Assignment | State |
|
||||
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `docs-nav-review` | Independently audit current-page ownership, reachability, relative links, lifecycle labels, and sitemap accuracy. | Complete — findings remediated: artifact indexes added, quarantine links removed, stale sitemap copy corrected, mission label no longer overrides control state. |
|
||||
| `docs-safety-review` | Independently review new current/held pages against source/tests and database/runtime safety constraints. | Complete — Discord durability blocker found; all affected pages now limit claims to live routing/delivery and disclose missing route-to-UUID persistence evidence. |
|
||||
| `docs-stop-review` | Confirm that remaining unmigrated groups require authority decisions or coupled source/test migrations, and identify any missed safe slice. | Complete — historical mission bundle migrated; remaining Fleet, Federation, Kanban, Tess/API, and deployment groups are authority- or source/test-coupled. |
|
||||
|
||||
## Progress
|
||||
|
||||
- [x] Confirmed external fleet sessions are standing down; no shared agent session was repurposed.
|
||||
- [x] Established parallel read-only discovery lanes.
|
||||
- [x] Counted current and archived documentation files.
|
||||
- [x] Ran initial link audit.
|
||||
- [x] Complete corrected code-surface audit.
|
||||
- [x] Complete truth triage probes.
|
||||
- [x] Write human-readable catalog/audit report.
|
||||
- [x] Verify report formatting and scope.
|
||||
- [x] Commit audit artifacts without unrelated working-tree changes.
|
||||
- [x] Scaffold audience, architecture, and API indexes without moving legacy content.
|
||||
- [x] Add current scaffold entry points to `SITEMAP.md` without rewriting its legacy sections.
|
||||
- [x] Select the P8-003 performance report as the first low-risk migration slice.
|
||||
- [x] Archive the contradicted TUI PRD/task pair with unchanged content and an explicit archive index.
|
||||
- [x] Create and promote the verified user quickstart from the empty root placeholder.
|
||||
- [x] Rewrite and promote the SSO administrator runbook from current auth/web source evidence.
|
||||
- [x] Promote the lease-broker protocol, security, mutator-gate, and compaction-revocation contracts with their navigation and acceptance-test consumers.
|
||||
- [x] Remove the blanket `docs/reports/` ignore rule so canonical evidence can be staged and linted normally.
|
||||
- [x] Migrate the three-file #756 Discord evidence batch byte-identically and add a reports index.
|
||||
- [x] Complete and integrate the four implementation-agent slices after independent scope and evidence review.
|
||||
- [x] Complete wave 2 audience, testing, RFC, and dashboard migrations and connect every page to its owning index and sitemap.
|
||||
- [x] Replace the stale sitemap link inventory with fully resolvable current navigation and an authority-gated backlog summary.
|
||||
- [x] Complete independent navigation, safety, and stop-condition reviews; remediate every autonomous finding.
|
||||
- [x] Migrate the bounded historical mission archive and repair its two broken sibling links.
|
||||
- [x] Archive the unreferenced five-file monorepo-consolidation planning bundle byte-identically with explicit historical boundaries.
|
||||
- [x] Archive ten unreferenced legacy plans/deferred stubs byte-identically; retain the live-test-coupled Agent Reflection PRD and authority-gated WebUI/Fleet draft in quarantine.
|
||||
- [x] Archive 94 unreferenced historical scratchpads byte-identically; retain 17 records coupled to control docs, tests/fixtures, mission/evidence records, or KBN-101.
|
||||
- [x] Archive the two unreferenced Matrix/MACP RFCs byte-identically as historical drafts, cross-referenced to the canonical unimplemented-Matrix boundary.
|
||||
- [x] Archive two unreferenced standalone designs byte-identically; retain the coupled #791 design and normative framework constitution in quarantine.
|
||||
- [x] Migrate three #751 Native Kanban review reports byte-identically to their already-referenced canonical evidence paths; retain KBN-101 and Fleet reports with gated workstreams.
|
||||
- [x] Reconcile PR #1210 with current `next`: restore the complete Fleet executable book, active Native Kanban/KBN SSOT, KBN-101 reports, and eight protected #1187 hold sites byte-exactly from provider base `216cd722`.
|
||||
|
||||
## PR #1210 integration reconciliation
|
||||
|
||||
CI pipeline 2405 proved that `docs/fleet/**` is an executable contract: Fleet tests and CLI projections fail when the book, north-star YAML/Markdown, example roster, or JSON schema is moved. Fred approved restoration and required the active KBN SSOT plus the eight #1187 hold-site documents to remain canonical. Scrappy supplied and will re-review the protected-path census.
|
||||
|
||||
All protected files were restored from `origin/next@216cd722`, not rewritten. The protected developer guide's Fleet-canary dependency was also restored; its sole stale upgrade-guide link was reconciled to the current administrator-guide destination. Scrappy corrected an initial provenance-pin instruction: `docs/native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md` is provider-base blob `2bb6209909004b74490565d5def9956aba6d83ca`; the void `45e4…` pin belongs to a later unmerged KBN RED-branch preimage and is intentionally absent from PR #1210.
|
||||
|
||||
No documentation-only relocation of these surfaces is authorized. A future move requires explicit Fleet consumer migration or Fred/Task-18 KBN authority reconciliation.
|
||||
|
||||
## Initial findings
|
||||
|
||||
- Baseline inventory: 283 documentation artifacts — 11 current root files, 269 archived files, two prior plans, and one prior scratchpad; current audit artifacts are listed separately.
|
||||
- Archived inventory: 269 files under `docs/_old_structure/`, moved unchanged by commit `cd4409a`.
|
||||
- Initial link scan: 219 internal relative links/wikilinks, 98 unresolved under the baseline checkout; 83 current legacy links remain after excluding two intentional README blueprint links, and 12 archive links are unresolved.
|
||||
- 31 source/test/framework files reference legacy documentation roots such as `docs/fleet/`, `docs/federation/`, or `docs/architecture/`.
|
||||
- `docs/QUICKSTART.md` is empty; `docs/SITEMAP.md` has 66 broken current links; `docs/PRD.md`, `docs/TASKS.md`, and `docs/MISSION-MANIFEST.md` retain broken pre-archive references.
|
||||
- SSO provider environment names and partial-config behavior align with `packages/auth`, but the documented `NEXT_PUBLIC_*_ENABLED` web flow is stale against dynamic `/api/sso/providers` discovery.
|
||||
- TUI documents reference missing `packages/cli` and a missing historical worktree; current TUI code is under `packages/mosaic`.
|
||||
- `docs/openapi-tess.yaml` parses as OpenAPI 3.1 with 17 paths, but remains a legacy root-level Tess-scoped contract rather than the full API SSOT.
|
||||
- The baseline `.gitignore` ignored `docs/reports/`, conflicting with the new documentation contract and lint-staged. The blanket rule is now removed so canonical evidence can be tracked normally.
|
||||
- The scaffold slice adds `USER-GUIDE/README.md`, `ADMIN-GUIDE/README.md`, `ADMIN-GUIDE/security/README.md`, `DEVELOPER-GUIDE/README.md`, `DEVELOPER-GUIDE/architecture/README.md`, and `API/README.md`; legacy pages remain unchanged.
|
||||
- `SITEMAP.md` links the protected Fleet and KBN authority surfaces at their canonical paths. Remaining authority-gated Federation, Kanban task-state, Tess/API, and deployment groups are summarized without presenting quarantine paths as current navigation.
|
||||
- `docs/PERFORMANCE.md` had no live source/test dependency or internal links; it moved unchanged to `docs/reports/qa/p8-003-performance-optimization.md`. The admin index and current sitemap now classify it as historical evidence, not an operator runbook.
|
||||
- `PRD-TUI_Improvements.md` and `TASKS-TUI_Improvements.md` had no live source/test dependencies beyond their internal relative link; both moved unchanged to `docs/archive/tui/`, and `docs/archive/README.md` labels them historical.
|
||||
- The empty `docs/QUICKSTART.md` placeholder was replaced by `docs/USER-GUIDE/getting-started/quickstart.md`, based on verified versioned-package, wizard, CLI, and runtime-safety behavior. The page holds mutable remote-script installation, pins and checks the published top-level package artifact, discloses that the transitive dependency closure is not independently immutable, and excludes held PostgreSQL/source-checkout routes.
|
||||
- The SSO guide now documents Authentik/WorkOS/Keycloak discovery, OIDC callbacks, Keycloak SAML fallback, partial-config failures, and the absence of frontend feature flags. The root guide and stale `.env.example` flags were removed.
|
||||
- The lease-broker acceptance suites directly consumed two quarantined `docs/architecture/` paths; promoting the protocol, security, mutator-gate, and compaction-revocation contracts to `DEVELOPER-GUIDE/architecture/` and updating those consumers restored the intended contract family without changing runtime behavior.
|
||||
- The #756 Discord code-review, security-review, and documentation-checklist reports had no source/test consumers and moved byte-identically to their canonical report categories. `docs/reports/README.md` labels their historical evidence boundary.
|
||||
- Independent safety review found that Discord external route strings are not proven to map to UUID conversation rows. Current pages now promise live routing/delivery only, disclose that persistence can fail while dispatch continues, and require pre-enrollment for privileged durable-session controls.
|
||||
- The monorepo-consolidation brief, board review, and three work-package specifications had no live consumers or internal links. They moved byte-identically to `archive/planning/`; current package existence supports historical classification but does not prove every old acceptance criterion.
|
||||
- Ten additional unreferenced implementation plans, setup records, and deferred stubs moved byte-identically to `archive/planning/legacy/`. `agent-reflection-loop-PRD.md` was excluded because a MACP test names its intended canonical path; the WebUI/Fleet bridge draft was excluded because it remains authority-gated.
|
||||
- Of 111 quarantined scratchpads, 94 had no current path/name consumers and no coupled local Markdown links; they moved byte-identically to `archive/work-records/`. Seventeen remain quarantined with their control-document, source/test fixture, mission/evidence, or KBN-101 dependencies.
|
||||
- The two Matrix/MACP RFCs were explicitly draft, unreferenced, and link-free. They moved byte-identically under `archive/planning/matrix-macp/`; the archive index points to the canonical channel page that records Matrix as unimplemented.
|
||||
- The npm prerelease-lane and storage-abstraction designs had no current consumers or local links. They moved byte-identically under `archive/planning/designs/` with explicit source/test verification boundaries.
|
||||
- Three #751 Native Kanban review reports moved byte-identically to `reports/native-kanban-sot/`, matching paths already named by the archived #751 scratchpad. Their historical GO verdicts do not decide current authority or KBN-101 execution.
|
||||
|
||||
## Method
|
||||
|
||||
- Resolve relative Markdown links from the source page directory.
|
||||
- Resolve wikilinks from the `docs/` vault root.
|
||||
- Compare document claims to current source, package manifests, tests, configuration, and executable paths.
|
||||
- Treat normative PRDs and plans as intent, not shipped behavior.
|
||||
- Treat archived material as historical unless current source/tests demonstrate it remains operative.
|
||||
|
||||
## Risks and blockers
|
||||
|
||||
- Fleet source/test consumers are satisfied by retaining the executable book at `docs/fleet/`. Fred authorized the PR #1210 C2 disposition: five control-document destinations without a different canonical post-restructure home were restored byte-identically from quarantine to their canonical paths; no task or mission status semantics changed.
|
||||
- Historical documents may contain commands or security claims that are unsafe if resurfaced as current guidance.
|
||||
- Truth audit is static unless a claim can be verified without starting held services or violating database/runtime safety rules.
|
||||
- `docs/TASKS.md` remains single-writer orchestrator state. Fred authorized link-only C2 repair; restoration of the exact linked destinations resolved the defect without editing its payload.
|
||||
- After restoring active Fleet/KBN/#1187 surfaces, the Fleet-canary dependency, and five authorized control-document destinations, 60 quarantine files remain. Every remaining group is authority-, source/test-consumer-, safety-, or path-coupled; the Mos-gated compaction probes additionally hard-code their present repository-relative location and must not be moved or run independently.
|
||||
- The pre-existing `9a1cc63` commit removed `docs/GETTING_STARTED.md` and added the `.obsidian` ignore rule before this audit commit; that state is not attributed to this task.
|
||||
|
||||
## Verification log
|
||||
|
||||
| Check | Result |
|
||||
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| File inventory | PASS — 11 root files, 269 archived files, plus task artifacts |
|
||||
| Initial link audit | FINDING — 219 links, 98 unresolved |
|
||||
| Code-surface audit | PASS — corrected manifest/script and legacy-reference scans; first attempt was discarded due to a `require()` path bug |
|
||||
| Truth probes | PASS — root docs, SSO, performance, TUI, OpenAPI, and source-path evidence triaged |
|
||||
| Final report | Written — `docs/reports/documentation/2026-08-10-docs-catalog-audit.md` |
|
||||
| Scoped commit | PASS — audit plan, report, and scratchpad committed together; `.mosaic/orchestrator/*` remains outside the commit |
|
||||
| Report formatting and scope | PASS — `pnpm exec prettier --ignore-path /dev/null --check` passed; baseline ignored-path conflict was identified and later resolved |
|
||||
| Commit hook behavior | RESOLVED — lint-staged exposed the blanket `docs/reports/` ignore conflict; the rule was removed and report paths can now be staged normally |
|
||||
| Index scaffold | PASS — six indexes formatted, all new Markdown/wikilinks resolve, and target directories exist; legacy pages were not changed |
|
||||
| Sitemap scaffold | PASS — additive current section is formatted, all seven links resolve, and legacy sections are unchanged |
|
||||
| First migration selection | PASS — P8-003 report selected as a no-rewrite evidence migration; live references identified before move |
|
||||
| P8-003 migration | PASS — destination is byte-identical, live references were updated, formatting and navigation checks pass, and only the scoped migration files are pending commit |
|
||||
| TUI archive migration | PASS — both pages are byte-identical, internal links and archive navigation resolve, formatting passes, and only the scoped archive files are pending commit |
|
||||
| Quickstart migration | PASS — exact `@mosaicstack/[email protected]` artifact and published SHA-512 integrity are pinned; mutable remote scripts and immutable-closure overclaims are held |
|
||||
| SSO migration | PASS — auth/gateway/web SSO tests pass (15+2+2), source claims and navigation resolve, obsolete env flags are removed, and the root guide is retired |
|
||||
| Parallel Pi audits | PASS — four requested `openai-codex/gpt-5.6-luna:max` read-only lanes completed in clean isolated worktrees; no agent changes were imported |
|
||||
| Lease-broker architecture | PASS — four contract pages promoted, two source/test consumers and navigation updated, 20/20 Vitest acceptance tests passed, and the 3-test Python portability suite passed |
|
||||
| #756 evidence migration | PASS — three reports moved byte-identically by SHA-256, no source/test consumers found, reports index and sitemap updated |
|
||||
| Implementation agents | PASS — four isolated Luna lanes committed disjoint owned slices; coordinator reviewed and cherry-picked each commit |
|
||||
| Second report batch | PASS — four historical evidence files moved byte-identically and added to the reports index |
|
||||
| Channel architecture | PASS — verified DTO/Discord behavior is separated from draft Telegram, Matrix, registry, identity, and multiplexing work |
|
||||
| Runtime portability M1 | PASS — current decision precision corrected; companion operations page is explicitly held/non-operative |
|
||||
| Upgrade/recovery guide | PASS — installed-CLI/local-PGlite route only; PostgreSQL, Compose, migration, and Gateway/Web activation remain held |
|
||||
| Implementation wave 2 | PASS — four isolated Luna lanes produced scoped commits; coordinator reviewed, cherry-picked, and integrated each page |
|
||||
| Channel audience guides | PASS — Discord admin/user/developer pages align to shared source/tests and explicitly deny Telegram/Matrix parity claims |
|
||||
| Lease-broker verification | PASS — safe static/test workflow is current; startup, recovery, mutation, service management, and cleanup remain held |
|
||||
| Optional egress RFC | PASS — proposal remains draft/non-operative; model and runtime-provider boundaries are separated and candidates are not integrated |
|
||||
| Web dashboard guide | PASS — current routes, views, chat persistence, and absent project/task creation controls are documented from source/tests |
|
||||
| Sitemap refresh | PASS — 54/54 relative links resolve after PR #1210 protected-surface reconciliation |
|
||||
| Canonical link audit | PASS AFTER AUTHORIZED C2 REPAIR — 443 relative links scanned, 0 unresolved; all ten control-doc links resolve through five byte-identical canonical destination restores |
|
||||
| C1 anti-masking control | PASS — executable Vitest control scans the explicit current-installation page set and observed-red fixtures prove pipe-to-shell, process substitution, and mutable branches fail |
|
||||
| C2 anti-masking control | PASS — all ten original `TASKS.md`/`MISSION-MANIFEST.md` uses resolve; restored destination blobs match their quarantine sources and the sitemap claim is owner-neutral |
|
||||
| Navigation review | PASS AFTER REMEDIATION — plan/scratchpad indexes added, current quarantine links removed, lifecycle/status copy aligned |
|
||||
| Safety review | PASS AFTER REMEDIATION — Discord pages no longer claim unproven ordinary persistence or restart continuity |
|
||||
| Stop-condition review | AUTONOMOUS COMPLETE — historical mission bundle migrated; remaining groups require authority or coupled source/test work |
|
||||
| Repository pre-push checks | PASS — `pnpm preflight`, `pnpm typecheck`, `pnpm lint`, and `pnpm format:check` with `DATABASE_URL` unset |
|
||||
| Root test suite | PR #1210 CI pipeline 2405 failed because the migration removed executable `docs/fleet/` contracts; provider-base restoration is the required amendment. |
|
||||
| Fleet contract restoration | PASS LOCALLY — focused north-star, Fleet documentation, and roster-schema suites pass 77/77 after exact provider-base restoration. |
|
||||
| Focused final tests | PASS — types 71, Discord 44, web 33, focused gateway 32, and lease-broker/mutator acceptance 57; `DATABASE_URL` unset, no services started |
|
||||
| Historical mission archive | PASS — 11 completed/superseded records moved under `archive/missions/`, indexed, and two broken sibling links repaired |
|
||||
| Historical planning archive | PASS — five consolidation records plus ten legacy plans/stubs moved byte-identically under `archive/planning/`; hashes and zero-consumer scans verified |
|
||||
| Historical work records | PASS — 94 unreferenced scratchpads moved byte-identically under `archive/work-records/`; 17 coupled records deliberately retained in quarantine |
|
||||
| Matrix/MACP draft RFCs | PASS — two unreferenced, link-free drafts moved byte-identically under `archive/planning/matrix-macp/`; canonical Matrix limitation linked |
|
||||
| Standalone design archive | PASS — prerelease-lane and storage-abstraction designs moved byte-identically under `archive/planning/designs/`; coupled/normative designs excluded |
|
||||
| #751 Kanban review evidence | PASS — initial NO-GO, re-review GO, and final GO moved byte-identically under `reports/native-kanban-sot/`; existing evidence paths now resolve |
|
||||
@@ -1,52 +0,0 @@
|
||||
# FED-M3-05 — Federation List Verb Scratchpad
|
||||
|
||||
## Objective
|
||||
|
||||
Implement `POST /api/federation/v1/list/:resource`.
|
||||
|
||||
## Scope
|
||||
|
||||
- Wire `FederationAuthGuard` → `FederationScopeService` → read-only list query layer.
|
||||
- Apply `max_rows_per_query` row cap and return pagination metadata when truncated.
|
||||
- Tag returned rows with `_source: "local"`.
|
||||
- Keep audit writes deferred to M4.
|
||||
- No request/response body persistence.
|
||||
|
||||
## Base / branch
|
||||
|
||||
- Branch: `feat/federation-m3-verb-list`
|
||||
- Base: `main` after M3-04 scope service merged via PR #672 (`c739256a`).
|
||||
|
||||
## Implementation notes
|
||||
|
||||
- Added `ListController` under `apps/gateway/src/federation/server/verbs/`.
|
||||
- Added `FederationListQueryService` as the read-only query layer and native RBAC evaluator.
|
||||
- Query resources supported in M3 list path:
|
||||
- `tasks`: project/mission scoped tasks visible through personal/team project access.
|
||||
- `notes`: non-empty `mission_tasks.notes` rows visible through personal/team mission access.
|
||||
- `memory`: user-owned `insights` and `preferences` rows.
|
||||
- `credentials` / `api_keys`: denied by native RBAC in M3 even if present in scope; sensitive-resource implementation is not part of FED-M3-05.
|
||||
- Cursor pagination uses an opaque base64url keyset cursor over `(createdAt, id)`; DB reads fetch at most `limit + 1` rows per resource query.
|
||||
- Reviewer isolation fix: `mission_tasks.notes` rows are always constrained by `missionTasks.userId = subjectUserId` and accessible mission IDs; team scope narrows missions but never widens to other users' mission task notes.
|
||||
- Follow-up review fix: memory listing now uses deterministic table-block pagination (`insights` first, then `preferences`) with cursor source metadata, so one table's cursor is never applied to the other.
|
||||
- Follow-up hardening: missing auth-guard context returns a structured federation `unauthorized` envelope; unsupported resources and non-encodable truncated cursors throw instead of silently crashing/truncating.
|
||||
|
||||
## Tests
|
||||
|
||||
- `pnpm --filter @mosaicstack/gateway test -- list.controller.spec.ts list-query.service.spec.ts` — PASS (16 tests, including PGlite regression coverage for team-scoped notes isolation, unauthorized mission notes exclusion, `includePersonal: false`, deterministic memory pagination, missing context envelope, unsupported resource, and cursor encode failure).
|
||||
- `pnpm --filter @mosaicstack/gateway typecheck` — PASS.
|
||||
- `pnpm --filter @mosaicstack/gateway lint` — PASS.
|
||||
- `pnpm format:check` — PASS.
|
||||
- `pnpm typecheck` — PASS (41/41 turbo tasks).
|
||||
- `pnpm lint` — PASS (23/23 turbo tasks).
|
||||
- `pnpm --filter @mosaicstack/gateway test` — FAIL in pre-existing/live-DB integration suite: `apps/gateway/src/__tests__/cross-user-isolation.test.ts` cleanup cannot connect to local PostgreSQL on `localhost:5433`. New list tests pass; failure is outside FED-M3-05.
|
||||
|
||||
## Review evidence
|
||||
|
||||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — PASS after follow-up remediation; approve, no findings.
|
||||
- `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted` — PASS after follow-up remediation; risk level none, no findings.
|
||||
- Security-review note: read-path audit logging remains intentionally deferred to M4 per orchestrator clarification and FED-M3-05 scope.
|
||||
|
||||
## Risks / follow-up
|
||||
|
||||
- Read-path audit logging remains intentionally deferred to M4.
|
||||
@@ -1,65 +0,0 @@
|
||||
# FED-M3-07 — Capabilities Verb Scratchpad
|
||||
|
||||
## Objective
|
||||
|
||||
Implement `GET /api/federation/v1/capabilities` in `apps/gateway/src/federation/server/verbs/capabilities.controller.ts`.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add read-only capabilities controller under federation server verbs.
|
||||
- Use `FederationAuthGuard` only; active grant is sufficient and no native RBAC/scope-service eval runs.
|
||||
- Response shape: `{ resources, excluded_resources, max_rows_per_query, supported_verbs }` derived from grant scope.
|
||||
- Register controller in `FederationModule`.
|
||||
- Unit-test happy path, defaults, no-context guard seam, and invalid scope handling.
|
||||
|
||||
## Constraints / assumptions
|
||||
|
||||
- Issue: #462.
|
||||
- Branch: `feat/federation-m3-verb-capabilities` from `origin/main` (`3eeed04e`).
|
||||
- Depends on M3-03 auth guard; guard attaches `request.federationContext.scope` after active-grant validation.
|
||||
- ASSUMPTION: `supported_verbs` is the M3 verb set from `@mosaicstack/types` (`list`, `get`, `capabilities`).
|
||||
- ASSUMPTION: `filters`/`rate_limit` are intentionally omitted for FED-M3-07 because the card’s response shape lists only the four required fields.
|
||||
- Budget: no explicit hard cap from orchestrator; working cap ~4K-8K tokens for card implementation + tests + PR cycle.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Write controller unit tests first.
|
||||
2. Implement controller and module registration.
|
||||
3. Run scoped tests + typecheck/lint/format.
|
||||
4. Run Codex code/security review and remediate.
|
||||
5. Commit, queue guard, push, PR via wrapper.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-06-24: Intake complete; fresh worktree created from origin/main.
|
||||
- 2026-06-24: Added `CapabilitiesController`, registered it in `FederationModule`, and added 5 unit tests.
|
||||
- 2026-06-24: Code/security reviews passed with no findings.
|
||||
|
||||
## Tests run
|
||||
|
||||
- `pnpm --filter @mosaicstack/gateway test -- capabilities.controller.spec.ts` — PASS (5 tests).
|
||||
- `pnpm --filter @mosaicstack/gateway typecheck` — PASS.
|
||||
- `pnpm --filter @mosaicstack/gateway lint` — PASS.
|
||||
- `pnpm format:check` — PASS.
|
||||
- `pnpm typecheck` — PASS (41/41 turbo tasks).
|
||||
- `pnpm lint` — PASS (23/23 turbo tasks).
|
||||
- `pnpm test` — FAIL in pre-existing/live-DB integration suite: `apps/gateway/src/__tests__/cross-user-isolation.test.ts` cleanup hit PostgreSQL connection/schema state for the `messages` table. Changed capabilities tests passed; failure is outside FED-M3-07 surface. No `fleet-personas.spec` flake encountered.
|
||||
|
||||
## Review evidence
|
||||
|
||||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — PASS/approve, no findings.
|
||||
- `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted` — PASS, risk level none, no findings.
|
||||
|
||||
## Risks / blockers
|
||||
|
||||
- Full repo `pnpm test` may hit known `fleet-personas.spec` flake per orchestrator; ignore that specific flake if encountered.
|
||||
- Previous card saw local DB schema issue in `cross-user-isolation.test.ts`; scoped capabilities tests should be authoritative for this surface.
|
||||
|
||||
## Acceptance evidence mapping
|
||||
|
||||
| Acceptance criterion | Evidence |
|
||||
| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
||||
| GET `/api/federation/v1/capabilities` exists | Route metadata test in `capabilities.controller.spec.ts`; scoped test PASS |
|
||||
| Uses active-grant auth guard and no RBAC eval | Guard metadata test confirms only `FederationAuthGuard`; controller has no service injections/RBAC calls; scoped test PASS |
|
||||
| Response enumerates resources/excluded/max rows/supported verbs from scope | Happy-path/default scope tests + response schema parse; scoped test PASS |
|
||||
| Read-only/no persistence side effects | Controller only parses request `federationContext.scope` and returns a DTO; no DB/service dependency; code review PASS |
|
||||
@@ -1,67 +0,0 @@
|
||||
# FED-M3-09 — Query Source Service Scratchpad
|
||||
|
||||
## Objective
|
||||
|
||||
Implement `apps/gateway/src/federation/client/query-source.service.ts` for `source: "local" | "federated:<host>" | "all"` routing.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add QuerySourceService in gateway federation client layer.
|
||||
- Unit-test local-only, single federated peer, all-source fan-out/merge, and per-peer partial failures.
|
||||
- Keep `docs/federation/TASKS.md` read-only per project agent guidance.
|
||||
|
||||
## Constraints / assumptions
|
||||
|
||||
- Issue: #462.
|
||||
- Branch: `feat/federation-m3-query-source` from `origin/main` (`e0e7be70`).
|
||||
- ASSUMPTION: `federated:<host>` should match active outbound peers by `commonName` first and by `endpointUrl` host/hostname as compatibility fallback; source tags use `peer.commonName` per `@mosaicstack/types` source-tag docs.
|
||||
- ASSUMPTION: QuerySourceService provides list/fan-out behavior; get/source routing can be layered later because card acceptance says merge rows.
|
||||
- ASSUMPTION: `source: "all"` cannot safely return a single continuation cursor for multiple sub-sources; any subquery cursor marks the merged response `_partial: true` + `_truncated: true` while omitting `nextCursor`.
|
||||
- Budget: no explicit hard cap from orchestrator; working cap ~8K-12K tokens for card 1 implementation + tests + PR cycle.
|
||||
- OpenBrain unavailable: credential loader failed with missing `/home/jarvis/.config/mosaic/credentials.json`; not blocking code delivery.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Review federation client/types/db patterns.
|
||||
2. Write unit tests for source behavior.
|
||||
3. Implement QuerySourceService and export/register it in FederationModule.
|
||||
4. Run scoped tests, typecheck, lint, format.
|
||||
5. Run codex uncommitted review and remediate.
|
||||
6. Commit, queue guard, push, PR via wrapper.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-06-24: Intake complete; using isolated worktree to avoid dirty orchestrator files in original checkout.
|
||||
- 2026-06-24: Added QuerySourceService, module export, barrel export, and 7 unit tests.
|
||||
- 2026-06-24: First Codex review found pagination and port-host matching issues; both remediated with tests.
|
||||
|
||||
## Tests run
|
||||
|
||||
- `pnpm --filter @mosaicstack/gateway test -- query-source.service.spec.ts` — PASS (7 tests).
|
||||
- `pnpm --filter @mosaicstack/gateway typecheck` — PASS.
|
||||
- `pnpm --filter @mosaicstack/gateway lint` — PASS.
|
||||
- `pnpm format:check` — PASS.
|
||||
- `pnpm typecheck` — PASS (41/41 turbo tasks).
|
||||
- `pnpm lint` — PASS (23/23 turbo tasks).
|
||||
- `pnpm test` — FAIL in pre-existing/live-DB integration suite: `apps/gateway/src/__tests__/cross-user-isolation.test.ts` cleanup hit `relation "messages" does not exist` against local PostgreSQL. Changed QuerySource unit tests passed; failure is outside FED-M3-09 surface and appears tied to local DB schema state.
|
||||
|
||||
## Review evidence
|
||||
|
||||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — first pass request-changes, 2 should-fix findings (all-source cursor handling; endpoint port host matching).
|
||||
- Remediation: `_partial` + `_truncated` when any all-source subquery has `nextCursor`; endpoint match accepts URL `host` and `hostname`; added tests for both.
|
||||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — PASS/approve, no findings.
|
||||
- `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted` — PASS, risk level none, no findings.
|
||||
|
||||
## Risks / blockers
|
||||
|
||||
- Federation query layer is not yet wired; service API needs to be stable and easy to compose.
|
||||
- Must avoid hard-failing `source: all` on remote peer failures.
|
||||
|
||||
## Acceptance evidence mapping
|
||||
|
||||
| Acceptance criterion | Evidence |
|
||||
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
||||
| local source returns local rows tagged `_source: local` | `query-source.service.spec.ts` local test; scoped test PASS |
|
||||
| `federated:<host>` queries selected peer and tags rows with peer source | `query-source.service.spec.ts` commonName/endpoint-host tests; scoped test PASS |
|
||||
| `all` fans out local + active outbound peers in parallel and merges tagged rows | `query-source.service.spec.ts` all-source call-order/merge test; scoped test PASS |
|
||||
| per-peer failure on `all` returns `_partial: true`, not throw | `query-source.service.spec.ts` peer failure test; scoped test PASS |
|
||||
@@ -1,60 +0,0 @@
|
||||
# FED-M3-10 — Federation M3 Integration Tests
|
||||
|
||||
## Objective
|
||||
|
||||
Add single-gateway gateway integration tests for M3 acceptance #6 and #7.
|
||||
|
||||
## Branch / base
|
||||
|
||||
- Branch: `feat/federation-m3-integration`
|
||||
- Base: `origin/next` (`838701bd` after M3-06/#683 merge)
|
||||
- PR base when unblocked: `next`
|
||||
|
||||
## Scope
|
||||
|
||||
- Real PostgreSQL via `@mosaicstack/db`.
|
||||
- Mocked TLS context / Fastify request shim for `FederationAuthGuard`.
|
||||
- Direct controller calls using the real M3 route contract: `POST /api/federation/v1/list/:resource` with body `{ limit?, cursor? }`.
|
||||
- Gated by `FEDERATED_INTEGRATION=1`.
|
||||
- No federation harness dependency.
|
||||
|
||||
## Fixture notes
|
||||
|
||||
Aligned with the B2 seed design vocabulary:
|
||||
|
||||
- `tasks` visibility uses personal `projects` + `missions` chain.
|
||||
- `notes` are `mission_tasks.notes`; the integration suite asserts subject-only note visibility on an authorized mission.
|
||||
- Seed includes a second user and unauthorized team/project tasks to prove exclusion from the max-row-cap list result.
|
||||
- Grants/peers are direct DB fixtures; cert auth still runs through `FederationAuthGuard` using real X.509 certs generated by existing test helpers.
|
||||
|
||||
## Current implementation
|
||||
|
||||
Added `apps/gateway/src/__tests__/integration/federation-m3-list.integration.test.ts` covering:
|
||||
|
||||
1. M3 #6 — cert missing Mosaic OIDs returns 401 federation `unauthorized` envelope.
|
||||
2. M3 #6 — valid cert whose grant row is `revoked` returns 403 federation `forbidden` envelope.
|
||||
3. M3 #7 — active grant with `max_rows_per_query: 2` caps `list tasks`, returns `_truncated` + `nextCursor`, source-tags rows, and excludes other-user / unauthorized-team tasks.
|
||||
4. Cross-user notes invariant — subject can list their own `mission_tasks.notes` row while another user's note on the same authorized mission is excluded.
|
||||
5. Unsupported-resource invariant — `list widgets` fails closed with a federation `scope_violation` envelope.
|
||||
|
||||
## Verification
|
||||
|
||||
- `pnpm --filter @mosaicstack/types build` — PASS.
|
||||
- `pnpm --filter @mosaicstack/db build` — PASS.
|
||||
- `pnpm --filter @mosaicstack/storage build` — PASS.
|
||||
- `pnpm --filter @mosaicstack/brain build` — PASS.
|
||||
- `pnpm --filter @mosaicstack/queue build` — PASS.
|
||||
- `pnpm --filter @mosaicstack/config build` — PASS.
|
||||
- `pnpm --filter @mosaicstack/auth build` — PASS.
|
||||
- `pnpm --filter @mosaicstack/gateway test -- src/__tests__/integration/federation-m3-list.integration.test.ts` — PASS skipped when `FEDERATED_INTEGRATION` unset (5 skipped).
|
||||
- `FEDERATED_INTEGRATION=1 pnpm --filter @mosaicstack/gateway test -- src/__tests__/integration/federation-m3-list.integration.test.ts` — PASS (5 tests) after local `docker compose up -d postgres` + `pnpm --filter @mosaicstack/db db:push`.
|
||||
- `pnpm --filter @mosaicstack/gateway typecheck` — PASS.
|
||||
- `pnpm --filter @mosaicstack/gateway lint` — PASS.
|
||||
- `pnpm format:check` — PASS.
|
||||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — PASS; approve, no findings.
|
||||
- `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted` — PASS; risk level none, no findings.
|
||||
|
||||
## Push / PR
|
||||
|
||||
- #683 landed in `next`; branch rebased onto `origin/next` before push.
|
||||
- CI is serialized; run queue guard before push.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Documentation Scratchpads
|
||||
|
||||
> **Status:** Current artifact index. Scratchpads are working memory and verification records, not product requirements or command authority.
|
||||
|
||||
## Documentation migration records
|
||||
|
||||
- [DOCS-IA-001 — information architecture](DOCS-IA-001.md) — completed structure-design and documentation-contract record.
|
||||
- [DOCS-IA-002 — catalog audit and migration](DOCS-IA-002-catalog-audit.md) — active coordinator progress, autonomous lane state, verification evidence, and authority blockers.
|
||||
|
||||
Completed scratchpads may remain here when they provide useful delivery provenance. Their conclusions must be reflected in the owning canonical page before the scratchpad is treated as complete.
|
||||
|
||||
## Related
|
||||
|
||||
- [[README|Documentation contract]]
|
||||
- [[SITEMAP|Documentation sitemap]]
|
||||
- [[plans/README|Documentation plans]]
|
||||
@@ -1,37 +0,0 @@
|
||||
# BUG-196: Admin Page Redirect Issue
|
||||
|
||||
## Problem
|
||||
|
||||
Admin page redirects to /chat for users with admin role because role check fails.
|
||||
|
||||
## Root Cause
|
||||
|
||||
The `role` field is defined as an `additionalField` in better-auth's user configuration, but
|
||||
better-auth v1.5.5 does not automatically include additionalFields in the session response from
|
||||
the `getSession()` API. This causes the admin role check to fail:
|
||||
|
||||
- Frontend: `AdminRoleGuard` checks `user?.role !== 'admin'`
|
||||
- Backend: `AdminGuard` checks `user.role !== 'admin'`
|
||||
- When `role` is `undefined`, both checks treat the user as non-admin and deny access
|
||||
|
||||
## Solution
|
||||
|
||||
Implemented a defensive check in the backend `AdminGuard` that:
|
||||
|
||||
1. First tries to use the `role` field from the session (if better-auth includes it)
|
||||
2. Falls back to fetching the role directly from the database if it's missing
|
||||
3. Defaults to 'member' if the user has no role set
|
||||
|
||||
This ensures that admin users can always access the admin panel, and also protects against
|
||||
the case where better-auth doesn't include the additionalField in future versions.
|
||||
|
||||
## Files Changed
|
||||
|
||||
1. `/apps/gateway/src/admin/admin.guard.ts` - Added fallback role lookup
|
||||
2. `/packages/auth/src/auth.ts` - No changes needed (better-auth config is correct)
|
||||
|
||||
## Verification
|
||||
|
||||
- All three quality gates pass: `typecheck`, `lint`, `format:check`
|
||||
- Backend admin guard now explicitly handles missing role field
|
||||
- Frontend admin guard remains unchanged (will work once role is available)
|
||||
@@ -1,30 +0,0 @@
|
||||
# Scratchpad: CI Docker Publish (2026-03-30)
|
||||
|
||||
- Objective: Add Woodpecker Docker build+push steps for gateway and web images on `main` pushes.
|
||||
- Scope: `.woodpecker/ci.yml`.
|
||||
- Constraints:
|
||||
- Use existing Dockerfiles at `docker/gateway.Dockerfile` and `docker/web.Dockerfile`.
|
||||
- Publish to `git.mosaicstack.dev` with `from_secret` credentials.
|
||||
- Tag both `latest` and `${CI_COMMIT_SHA}`.
|
||||
- Do not run publish steps on pull requests.
|
||||
- ASSUMPTION: Publishing `latest` is required by the task for registry convenience, even though immutable tags remain the safer deployment reference.
|
||||
- Findings:
|
||||
- Existing pipeline already has `build` after `lint`, `format`, and `test`.
|
||||
- `apps/gateway/package.json` uses `tsc` for `build`; no Prisma dependency or `prisma generate` hook is present.
|
||||
- Plan:
|
||||
1. Patch `.woodpecker/ci.yml` to keep `build` as the quality gate successor and add `publish-gateway` plus `publish-web`.
|
||||
2. Validate YAML and run repo quality gates relevant to the change.
|
||||
3. Review the diff, then commit/push/PR if validation passes.
|
||||
- Verification:
|
||||
- `python3 -c "import yaml; yaml.safe_load(open('.woodpecker/ci.yml'))" && echo "YAML valid"`
|
||||
- `pnpm lint`
|
||||
- `pnpm typecheck`
|
||||
- `pnpm format:check`
|
||||
- `docker compose up -d`
|
||||
- `pnpm --filter @mosaicstack/db db:push`
|
||||
- `pnpm test`
|
||||
- `pnpm build`
|
||||
- Manual review of `.woodpecker/ci.yml` diff: publish steps are main-only, depend on `build`, and use secret-backed registry auth plus dual tags.
|
||||
- Risks:
|
||||
- Pipeline behavior beyond YAML validation cannot be fully proven locally; remote Woodpecker execution will be the final situational check after push.
|
||||
- Repo baseline required two existing `plugins/macp` files to be reformatted before `pnpm format:check` would pass.
|
||||
@@ -1,250 +0,0 @@
|
||||
# Mission Scratchpad — CLI Unification & E2E First-Run
|
||||
|
||||
> Append-only log. NEVER delete entries. NEVER overwrite sections.
|
||||
> This is the orchestrator's working memory across sessions.
|
||||
|
||||
**Mission ID:** cli-unification-20260404
|
||||
**Started:** 2026-04-04
|
||||
**Related PRDs:** `docs/PRD.md` (v0.1.0 long-term target)
|
||||
|
||||
## Original Mission Prompt
|
||||
|
||||
Original user framing (2026-04-04):
|
||||
|
||||
> We are off the reservation right now. Working on getting the system to work via cli first, then working on the webUI. The missions are likely all wrong. The PRDs might have valid info.
|
||||
>
|
||||
> E2E install to functional, with Mosaic Forge working. `mosaic gateway` config is broken — no token is created. Unable to configure. Installation doesn't really configure, it just installs and launches the gateway. Multiple `mosaic` commands are missing that should be included. Unified installer experience is not ready. UX is bad.
|
||||
>
|
||||
> The various mosaic packages will need to be available within the mosaic cli: `mosaic auth`, `mosaic brain`, `mosaic forge`, `mosaic log`, `mosaic macp`, `mosaic memory`, `mosaic queue`, `mosaic storage`.
|
||||
>
|
||||
> The list of commands in `mosaic --help` also need to be alphabetized for readability.
|
||||
>
|
||||
> `mosaic telemetry` should also exist. Local OTEL for wide-event logging / post-mortems. Remote upload opt-in via `@mosaicstack/telemetry-client-js` (https://git.mosaicstack.dev/mosaicstack/telemetry-client-js) — the telemetry server will be part of the main mosaicstack.dev website. Python counterpart at https://git.mosaicstack.dev/mosaicstack/telemetry-client-py.
|
||||
|
||||
## Planning Decisions
|
||||
|
||||
### 2026-04-04 — State discovery + prep PR
|
||||
|
||||
**Critical finding:** Two CLI packages both owned `bin.mosaic` — `@mosaicstack/mosaic` (0.0.21) and `@mosaicstack/cli` (0.0.17). Their `src/cli.ts` files were near-verbatim duplicates (424 vs 422 lines) and their `src/commands/` directories overlapped, with some files silently diverging (notably `gateway/install.ts`, the version responsible for the broken install UX). Whichever package was linked last won the `mosaic` symlink.
|
||||
|
||||
**Decision:** `@mosaicstack/cli` dies. `@mosaicstack/mosaic` is the single CLI + TUI package. This was confirmed with user ("The @mosaicstack/cli package is no longer a package. Its features were moved to @mosaicstack/mosaic instead."). Prep PR #398 executed the removal.
|
||||
|
||||
**Decision:** CLI registration pattern = `register<Name>Command(parent: Command)` exported by each sub-package, co-located with the library code. Proven by `@mosaicstack/quality-rails` → `registerQualityRails(program)`. Avoids cross-package commander version mismatches.
|
||||
|
||||
**Decision:** Stale mission state (harness-20260321 manifest, storage-abstraction TASKS.md, PRD-Harness_Foundation.md) gets archived under `docs/archive/missions/`. Scratchpads for completed sub-missions are left in `docs/scratchpads/` as historical record — they're append-only by design and valuable as breadcrumbs.
|
||||
|
||||
### 2026-04-04 — Gateway bootstrap token bug root cause
|
||||
|
||||
`apps/gateway/src/admin/bootstrap.controller.ts`:
|
||||
|
||||
- `GET /api/bootstrap/status` returns `needsSetup: true` **only** when `users` table count is zero
|
||||
- `POST /api/bootstrap/setup` throws `ForbiddenException` if any user exists
|
||||
|
||||
`packages/mosaic/src/commands/gateway/install.ts` — `runInstall()` "explicit reinstall" branch (lines ~87–98):
|
||||
|
||||
1. Clears `meta.adminToken` from meta.json (line 175 — `preserveToken = false` when `regeneratedConfig = true`)
|
||||
2. Calls `bootstrapFirstUser()`
|
||||
3. Status endpoint returns `needsSetup: false` because users row still exists
|
||||
4. `bootstrapFirstUser` prints _"Admin user already exists — skipping setup. (No admin token on file — sign in via the web UI to manage tokens.)"_ and returns
|
||||
5. Install "succeeds" with NO token, NO CLI path to generate one, and chicken-and-egg on `/api/admin/tokens` which requires auth
|
||||
|
||||
**Recovery design options (to decide in CU-03-01):**
|
||||
|
||||
- Filesystem-signed nonce file written by the installer; recovery endpoint checks it
|
||||
- Accept a valid BetterAuth admin session cookie → mint new admin token via authenticated API call (leans on existing auth; `mosaic gateway login` becomes the recovery entry point)
|
||||
- Gateway daemon accepts `--rescue` flag that mints a one-shot recovery token, prints it, then exits
|
||||
|
||||
Current lean: option 2 (BetterAuth cookie) because it reuses existing auth and gives us `mosaic gateway login` as a useful command regardless. But the design spike in CU-03-01 should evaluate all three against: security, complexity, headless-environment friendliness, and disaster-recovery scenarios.
|
||||
|
||||
### 2026-04-04 — Telemetry architecture
|
||||
|
||||
- `@mosaicstack/telemetry-client-js` + `@mosaicstack/telemetry-client-py` are separate repos on Gitea — **not** currently consumed anywhere in this monorepo (verified via grep)
|
||||
- Telemetry server will be combined with the main mosaicstack.dev website (not built yet)
|
||||
- Local OTEL stays — `apps/gateway/src/tracing.ts` already wires it up for wide-event logging and post-mortem traces
|
||||
- `mosaic telemetry` is a thin wrapper that:
|
||||
- `mosaic telemetry local {status,tail,jaeger}` → local OTEL state, Jaeger links
|
||||
- `mosaic telemetry {status,opt-in,opt-out,test,upload}` → remote upload path via telemetry-client-js
|
||||
- Remote disabled by default; opt-in requires explicit consent
|
||||
- `test`/`upload` ship with dry-run mode until the server endpoint is live
|
||||
|
||||
### 2026-04-04 — Open-question decisions (session 1)
|
||||
|
||||
Jason answered the four planning questions:
|
||||
|
||||
1. **Recovery endpoint design (CU-03-01):** BetterAuth cookie. `mosaic gateway login` becomes the recovery entry point. The spike in CU-03-01 can be compressed — design is locked; task becomes implementation planning rather than evaluation.
|
||||
2. **Sub-package command surface (M5):** The current CU-05-01..08 scope is acceptable for this mission. Deeper command surfaces can be follow-up work.
|
||||
3. **Telemetry server:** Ship `mosaic telemetry upload` and `mosaic telemetry test` in dry-run-only mode until the mosaicstack.dev server endpoint is live. Capture intended payload shape and print/log instead of POSTing. Real upload path gets wired in as follow-up once the server is ready.
|
||||
4. **Top-level `mosaic config`:** Required. Add to M4 (CLI structure milestone) since it lives alongside help-shape work and uses the existing `packages/mosaic/src/config/config-service.ts` machinery. Separate concern from `mosaic gateway config` (which manages gateway .env + meta.json).
|
||||
|
||||
## Session Log
|
||||
|
||||
| Session | Date | Milestone | Tasks Done | Outcome |
|
||||
| ------- | ---------- | ------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------- |
|
||||
| 1 | 2026-04-04 | cu-m01 Kill legacy CLI | CU-01-01 | PR #398 merged to main as `c39433c3`. 48 files deleted, 6685 LOC removed. CI green (pipeline 702). |
|
||||
| 1 | 2026-04-04 | cu-m02 Archive + scaffold | CU-02-01, CU-02-02, CU-02-03 | PR #399 merged to main as `6f15a84c`. Mission manifest + TASKS.md + scratchpad live. |
|
||||
| 1 | 2026-04-04 | Planning | 4 open questions resolved | See decisions block above. Ready to start M3/M4/M5. |
|
||||
|
||||
## Corrections / Course Changes
|
||||
|
||||
_(append here as they happen)_
|
||||
|
||||
## Handoff — end of Session 1 (2026-04-04)
|
||||
|
||||
**Session 1 agent:** claude-opus-4-6[1m]
|
||||
**Reason for handoff:** context budget (~80% used after bootstrap + two PRs + decision capture). Main is clean, no in-flight branches, no dirty state.
|
||||
|
||||
### What Session 2 should read first
|
||||
|
||||
1. `docs/MISSION-MANIFEST.md` — phase, progress, milestone table
|
||||
2. `docs/TASKS.md` — task state, dependencies, agent assignments
|
||||
3. This scratchpad — decisions, bug analysis, open risks, gotchas
|
||||
4. `git log --oneline -5` — confirm #398 and #399 are on main
|
||||
|
||||
### State of the world
|
||||
|
||||
- **Main branch HEAD:** `6f15a84c docs: archive stale mission, scaffold CLI unification mission (#399)`
|
||||
- **Working tree:** clean (no uncommitted changes after this handoff PR merges)
|
||||
- **Open PRs:** none (both M1 and M2 PRs merged)
|
||||
- **Deleted branches:** `chore/remove-cli-package-duplicate`, `docs/mission-cli-unification` (both local + remote)
|
||||
- **Milestones done:** cu-m01, cu-m02 (2 / 8)
|
||||
- **Milestones unblocked for parallel start:** cu-m03, cu-m04, cu-m05 (everything except M5.CU-05-06 which waits on M3.CU-03-03 for gateway login)
|
||||
|
||||
### Decisions locked (do not re-debate)
|
||||
|
||||
1. `@mosaicstack/cli` is dead; `@mosaicstack/mosaic` is the sole CLI package
|
||||
2. Sub-package CLI pattern: each package exports `register<Name>Command(parent: Command)`, wired into `packages/mosaic/src/cli.ts` (copy the `registerQualityRails` pattern)
|
||||
3. Gateway recovery uses **BetterAuth cookie** — `mosaic gateway login` + `mosaic gateway config rotate-token` via authenticated `POST /api/admin/tokens`
|
||||
4. Telemetry: `mosaic telemetry` wraps `@mosaicstack/telemetry-client-js`; remote upload is dry-run only until the mosaicstack.dev server endpoint is live
|
||||
5. Top-level `mosaic config` command is required (separate from `mosaic gateway config`) — wraps `packages/mosaic/src/config/config-service.ts`; added as CU-04-04
|
||||
|
||||
### Known gotchas for Session 2
|
||||
|
||||
- **pr-create.sh eval bug:** `~/.config/mosaic/tools/git/pr-create.sh` line 158 uses `eval "$CMD"`. Backticks and `$()` in PR bodies get shell-evaluated. **Workaround:** strip backticks from PR bodies OR use `tea pr create --repo mosaicstack/mosaic-stack --login mosaicstack --title ... --description ... --head <branch>` directly. Captured in openbrain.
|
||||
- **ci-queue-wait.sh unknown state:** The wrapper reports `state=unknown` and returns immediately instead of waiting. Poll the PR pipeline manually with `~/.config/mosaic/tools/woodpecker/pipeline-list.sh` and grep for the PR branch.
|
||||
- **pr-merge.sh branch delete:** `-d` flag is accepted but warns "branch deletion may need to be done separately". Delete via the Gitea API: `curl -X DELETE -H "Authorization: token $TOKEN" "https://git.mosaicstack.dev/api/v1/repos/mosaicstack/mosaic-stack/branches/<url-encoded-branch>"`.
|
||||
- **Tea login not default:** `tea login list` shows `mosaicstack` with DEFAULT=false. Pass `--login mosaicstack` explicitly on every `tea` call.
|
||||
- **`.mosaic/orchestrator/session.lock`:** auto-rewritten on every session launch. Shows up as dirty working tree on branch switch. Safe to `git checkout` the file before branching.
|
||||
- **Dual install.ts files no longer exist:** M1 removed `packages/cli/src/commands/gateway/install.ts`. The canonical (and only) one is `packages/mosaic/src/commands/gateway/install.ts`. The "user exists, no token" bug (CU-03-06) is in this file around lines 388-394 (`bootstrapFirstUser`). The server-side gate is in `apps/gateway/src/admin/bootstrap.controller.ts` lines 28 and 35.
|
||||
|
||||
### Suggested starting task for Session 2
|
||||
|
||||
Pick based on what the user wants shipped first:
|
||||
|
||||
- **Highest user-impact:** M3 — fixes the install bug that made the user "off the reservation" in the first place. Start with CU-03-01 (implementation plan, opus-tier, 4K) → CU-03-02 (server endpoint, sonnet).
|
||||
- **Quickest win:** M4.CU-04-01 — one-line `configureHelp({ sortSubcommands: true })`. 3K estimate. Good warm-up.
|
||||
- **User priority stated in session 1:** M5.CU-05-01 — `mosaic forge`. Larger scope (18K), but user flagged Forge specifically as part of "E2E install to functional, with Mosaic Forge working".
|
||||
|
||||
Session 2 orchestrator should pick one, update TASKS.md status to `in-progress`, follow the standard cycle: plan → code → test → review → remediate → commit → push → PR → queue guard → merge. Mosaic hard gates apply.
|
||||
|
||||
### Files added / modified in Session 1
|
||||
|
||||
Session 1 touched only these files across PRs #398 and #399 plus this handoff PR:
|
||||
|
||||
- Deleted: `packages/cli/` (entire directory, 48 files)
|
||||
- Archived: `docs/archive/missions/harness-20260321/MISSION-MANIFEST.md`, `docs/archive/missions/harness-20260321/PRD.md`, `docs/archive/missions/storage-abstraction/TASKS.md`
|
||||
- Modified: `pnpm-workspace.yaml`, `tools/install.sh`, `AGENTS.md`, `CLAUDE.md`, `README.md`, `docs/guides/user-guide.md`, `packages/mosaic/framework/defaults/README.md`
|
||||
- Created: `docs/MISSION-MANIFEST.md`, `docs/TASKS.md`, `docs/scratchpads/cli-unification-20260404.md` (this file)
|
||||
|
||||
No code changes to `apps/`, `packages/mosaic/`, or any other runtime package. Session 2 starts fresh on the runtime code.
|
||||
|
||||
## Open Risks
|
||||
|
||||
- **Telemetry server not live:** CU-06-03 (`mosaic telemetry upload`) may need a dry-run stub until the server endpoint exists on mosaicstack.dev. Not blocking for this mission, but ships with reduced validation until then.
|
||||
- **`mosaic auth` depends on gateway login:** CU-05-06 is gated by CU-03-03 (`mosaic gateway login`). Sequencing matters — do not start CU-05-06 until M3 is done or significantly underway.
|
||||
- **pr-create.sh wrapper bug:** Discovered during M1 — `~/.config/mosaic/tools/git/pr-create.sh` line 158 uses `eval "$CMD"`, which shell-evaluates any backticks / `$(…)` / `${…}` in PR bodies. Workaround: strip backticks from PR bodies (use bold / italic / plain text instead), or use `tea pr create` directly. Captured in openbrain as gotcha. Should be fixed upstream in Mosaic tools repo at some point, but out of scope for this mission.
|
||||
- **Mosaic coord / orchestrator session lock drift:** `.mosaic/orchestrator/session.lock` gets re-written every session launch and shows up as a dirty working tree on branch switch. Not blocking — just noise to ignore.
|
||||
|
||||
## Session 2 Log (2026-04-05)
|
||||
|
||||
**Session 2 agent:** claude-opus-4-6[1m]
|
||||
**Mode:** parallel orchestration across worktrees
|
||||
|
||||
### Wave 1 — M3 (gateway token recovery)
|
||||
|
||||
- CU-03-01 plan landed as PR #401 → `docs/plans/gateway-token-recovery.md`. Confirmed no server changes needed — AdminGuard already accepts BetterAuth cookies, `POST /api/admin/tokens` is the existing mint endpoint.
|
||||
- CU-03-02..07 implemented as PR #411: `mosaic gateway login` (interactive BetterAuth sign-in, session persisted), `mosaic gateway config rotate-token`, `mosaic gateway config recover-token`, fix for `bootstrapFirstUser` "user exists, no token" dead-end, 22 new unit tests. New files: `commands/gateway/login.ts`, `commands/gateway/token-ops.ts`.
|
||||
- CU-03-08 independent code review surfaced 2 BLOCKER findings (session.json world-readable, password echoed during prompt) + 3 important findings (trimmed password, cross-gateway token persistence, unsafe `--password` flag). Remediated in PR #414: `saveSession` writes mode 0o600, new `promptSecret()` uses TTY raw mode, persistence target now matches `--gateway` host, `--password` marked UNSAFE with warning.
|
||||
|
||||
### Wave 2 — M4 (help ergonomics + mosaic config)
|
||||
|
||||
- CU-04-01..03 landed as PR #402: `configureHelp({ sortSubcommands: true })` on root + gateway subgroup, plus an `addHelpText('after', …)` grouped-reference section (Commander 13 has no native command-group API).
|
||||
- CU-04-04/05 landed as PR #408: top-level `mosaic config` with `show|get|set|edit|path`, extends `config/config-service.ts` with `readAll`, `getValue`, `setValue`, `getConfigPath`, `isInitialized` + `ConfigSection`/`ResolvedConfig` types. Additive only.
|
||||
|
||||
### Wave 3 — M5 (sub-package CLI surface, 8 commands + integration)
|
||||
|
||||
Parallel-dispatched in isolated worktrees. All merged:
|
||||
|
||||
- PR #403 `mosaic brain`, PR #404 `mosaic queue`, PR #405 `mosaic storage`, PR #406 `mosaic memory`, PR #407 `mosaic log`, PR #410 `mosaic macp`, PR #412 `mosaic forge`, PR #413 `mosaic auth`.
|
||||
- Every package exports `register<Name>Command(parent: Command)` co-located with library code, following `@mosaicstack/quality-rails` pattern. Each wired into `packages/mosaic/src/cli.ts` with alphabetized `register…Command(program)` calls.
|
||||
- PR #415 landed CU-05-10 integration smoke test (`packages/mosaic/src/cli-smoke.spec.ts`, 19 tests covering all 9 registrars) PLUS a pre-existing exports bug fix in `packages/macp/package.json` (`default` pointed at `./src/index.ts` instead of `./dist/index.js`, breaking ERR_MODULE_NOT_FOUND when compiled mosaic CLI tried to load macp at runtime). Caught by empirical `node packages/mosaic/dist/cli.js --help` test before merge.
|
||||
|
||||
### New gotchas captured in Session 2
|
||||
|
||||
- **`pr-create.sh` "Remote repository required" failure:** wrapper can't detect origin in multi-remote contexts. Fallback used throughout: direct Gitea API `curl -X POST …/api/v1/repos/mosaicstack/mosaic-stack/pulls` with body JSON.
|
||||
- **`publish` workflow killed on post-merge pushes:** pipelines 735, 742, 747, 750, 758, 767 all show the Docker build step killed after `ci` workflow succeeded. Pre-existing infrastructure issue (observed on #714/#715 pre-mission). The `ci` workflow is the authoritative gate; `publish` killing is noise.
|
||||
- **macp exports.default misaligned:** latent bug from original monorepo consolidation — every other package already pointed at `dist/`. Only exposed when compiled CLI started loading macp at runtime.
|
||||
- **Commander 13 grouping:** no native command-group API; workaround is `addHelpText('after', groupedReferenceString)` + alphabetized flat list via `sortSubcommands: true`.
|
||||
|
||||
### Wave 4 — M6 + M7 (parallel)
|
||||
|
||||
- M6 `mosaic telemetry` landed as PR #417 (merge `a531029c`). Full scope CU-06-01..05: `@mosaicstack/telemetry-client-js` shim, `telemetry local {status,tail,jaeger}`, top-level `telemetry {status,opt-in,opt-out,test,upload}` with dry-run default, persistent consent state. New files: `packages/mosaic/src/commands/telemetry.ts`, `src/telemetry/client-shim.ts`, `src/telemetry/consent-store.ts`, plus `telemetry.spec.ts`.
|
||||
- M7 unified first-run UX landed as PR #418 (merge `872c1245`). Full scope CU-07-01..04: `install.sh` `--yes`/`--no-auto-launch` flags + auto-handoff to wizard + gateway install, wizard/gateway-install coordination via transient state file, `mosaic gateway verify` post-install healthcheck, Docker-based `tools/e2e-install-test.sh`.
|
||||
|
||||
### Wave 5 — M8 (release)
|
||||
|
||||
- PR #419 (merge `b9d464de`) — CLI unification release v0.1.0. Single cohesive docs + release PR:
|
||||
- README.md: unified command tree, new install UX, `mosaic gateway` and `mosaic config` sections, removed stale `@mosaicstack/cli` refs.
|
||||
- docs/guides/user-guide.md: new "Sub-package Commands" + "Telemetry" sections covering all 11 top-level commands.
|
||||
- `packages/mosaic/package.json`: bumped 0.0.21 → 0.1.0 (CI publishes on merge).
|
||||
- Git tag: `mosaic-v0.1.0` (scoped to avoid collision with existing `v0.1.0` repo tag) — pushed to origin on merge sha.
|
||||
- Gitea release: https://git.mosaicstack.dev/mosaicstack/mosaic-stack/releases/tag/mosaic-v0.1.0 — "@mosaicstack/mosaic v0.1.0 — CLI Unification".
|
||||
|
||||
### Wave 6 — M8 correction (version regression)
|
||||
|
||||
PR #419 bumped `@mosaicstack/mosaic` 0.0.21 → 0.1.0 and released as `mosaic-v0.1.0`. This was wrong on two counts:
|
||||
|
||||
1. **Versioning policy violation.** The project stays in `0.0.x` alpha until GA. Minor bump to `0.1.0` jumped out of alpha without authorization.
|
||||
2. **macp exports fix never reached the registry.** PR #415 fixed `packages/macp/package.json` `exports.default` pointing at `./src/index.ts`, but did NOT bump macp's version. When the post-merge publish workflow ran on #419, it published `@mosaicstack/[email protected]` but `@mosaicstack/[email protected]` was "already published" so the fix was silently skipped. Result: users running `mosaic update` got mosaic 0.1.0 which depends on macp and resolves to the still-broken registry copy of macp@0.0.2, failing with `ERR_MODULE_NOT_FOUND` on `./src/index.ts` at CLI startup.
|
||||
|
||||
Correction PR:
|
||||
|
||||
- `@mosaicstack/mosaic` 0.1.0 → `0.0.22` (stay in alpha)
|
||||
- `@mosaicstack/macp` 0.0.2 → `0.0.3` (force republish with the exports fix)
|
||||
- Delete Gitea tag `mosaic-v0.1.0` + release
|
||||
- Delete `@mosaicstack/[email protected]` from the Gitea npm registry so `latest` reverts to the highest remaining version
|
||||
- Create tag `mosaic-v0.0.22` + Gitea release
|
||||
|
||||
**Lesson captured:** every package whose _source_ changes must also have its _version_ bumped, because the publish workflow silently skips "already published" versions. `@mosaicstack/[email protected]` had the bad exports in the registry from day one; the in-repo fix in #415 was invisible to installed-from-registry consumers until the version bumped.
|
||||
|
||||
### Wave 7 — Waves 2 & 3 correction (same systemic bug)
|
||||
|
||||
After Wave 6's correction (PR #421) landed `mosaic-v0.0.22`, a clean global install still crashed with `Named export 'registerBrainCommand' not found` — and after fixing brain/forge/log in PR #422, the next clean install crashed with `registerMemoryCommand` not found. Same root cause: M5 (PR #416) added `registerXCommand` exports to memory, queue, storage, brain, forge, log, and config but only bumped a subset of versions. The publish workflow silently skipped every unchanged-version package, leaving the M5 exports absent from the registry.
|
||||
|
||||
Three cascaded correction PRs were required because each attempt only surfaced the next stale package at runtime:
|
||||
|
||||
- **PR #421** — macp 0.0.2 → 0.0.3, mosaic 0.1.0 → 0.0.22, delete `mosaic-v0.1.0` tag/release/registry version
|
||||
- **PR #422** — brain/forge/log 0.0.2 → 0.0.3, mosaic 0.0.22 → 0.0.23
|
||||
- **PR #423** — memory/queue/storage 0.0.3 → 0.0.4, mosaic 0.0.23 → 0.0.24
|
||||
|
||||
**First clean end-to-end verification** after PR #423:
|
||||
|
||||
```
|
||||
$ npm i -g @mosaicstack/mosaic@latest # installs 0.0.24
|
||||
$ mosaic --help # exits 0, prints full alphabetized command list
|
||||
```
|
||||
|
||||
**Systemic fix (follow-up):** The publish workflow's "already published, skipping" tolerance is dangerous when source changes without version bumps. Options to prevent recurrence: (a) fail publish if any workspace package's dist files differ from registry content at the same version, or (b) CI lint check that any `packages/*/src/**` change in a PR also modifies `packages/*/package.json` version.
|
||||
|
||||
### Mission outcome
|
||||
|
||||
All 8 milestones, all 8 success criteria met in-repo. Released as `mosaic-v0.0.24` (alpha) after three cascaded correction PRs (#421, #422, #423) fixing the same systemic publish-skip bug across macp, brain, forge, log, memory, queue, and storage. First version where `npm i -g @mosaicstack/mosaic@latest && mosaic --help` works end-to-end from a clean global install.
|
||||
|
||||
## Verification Evidence
|
||||
|
||||
### CU-01-01 (PR #398)
|
||||
|
||||
- Branch: `chore/remove-cli-package-duplicate`
|
||||
- Commit: `7206b9411d96`
|
||||
- Merge commit on main: `c39433c3`
|
||||
- CI pipeline: #702 (`pull_request` event, all 6 steps green: postgres, install, typecheck, lint, format, test)
|
||||
- Quality gates (pre-push): typecheck 38/38, lint 21/21, format clean, test 38/38
|
||||
@@ -1,29 +0,0 @@
|
||||
# F3-m3 — `mosaic update` re-seeds framework + relaunches agents (R13)
|
||||
|
||||
- **Issue:** #609 · **Branch:** `feat/f3-m3-update-reseed`
|
||||
|
||||
## Gap (found in 0.0.39 production validation)
|
||||
|
||||
`mosaic update` installs the new npm CLI but never re-seeds `~/.config/mosaic/` from the package's
|
||||
bundled `framework/`. So the shipped custom Pi harness (agent-name export + native HB, 0.0.39) stays
|
||||
DORMANT until a re-seed — operators get the new CLI on a stale framework.
|
||||
|
||||
## Implementation
|
||||
|
||||
- `update-checker.ts`: `resolveBundledFrameworkRoot()`, `buildReseedCommand()` (install.sh in
|
||||
`MOSAIC_SYNC_ONLY=1 MOSAIC_INSTALL_MODE=keep` — the P4 data-safe reconcile), `runFrameworkReseed()`,
|
||||
`readRosterAgentNames()`, `buildRelaunchCommands()` (systemctl --user restart per agent).
|
||||
- `cli.ts` `update`: after a successful CLI install that includes `@mosaicstack/mosaic`, re-seed the
|
||||
framework (default-on; `--no-reseed` to skip). Then either `--relaunch` (restart rostered agents) or
|
||||
print clear guidance to run `mosaic update --relaunch` / `mosaic fleet restart`.
|
||||
|
||||
## Flow
|
||||
|
||||
`update CLI → re-seed framework (data-safe) → relaunch agents (opt-in)` — closes R13, activates the
|
||||
native harness for every operator.
|
||||
|
||||
## Verification
|
||||
|
||||
- 6 new unit tests (reseed command/env, relaunch commands, roster parse, missing-installer guard).
|
||||
- 19 runtime + 26 launch tests still green; tsc/eslint/prettier clean.
|
||||
- Data-safety of the sync is already proven (P4 5-fixture matrix + live dragon-lin validation).
|
||||
@@ -1,30 +0,0 @@
|
||||
# F4 — Orchestrator chat connector + Matrix (#616)
|
||||
|
||||
- **Issue:** #616 · **Branch:** `feat/f4-matrix-connector` (off main; independent of #615) · **Doctrine:** north-star #613.
|
||||
|
||||
## Phase 1 (this PR) — abstraction + scaffold
|
||||
|
||||
- `src/fleet/connectors/types.ts`: `OrchestratorConnector` (send/subscribe/health) + message/config types; thread-aware via optional `threadId`; `DEFAULT_CONNECTOR_KIND=tmux`.
|
||||
- `src/fleet/connectors/registry.ts`: extensible factory registry; `resolveConnectorKind` (defaults tmux, back-compat); `createConnector` throws `ConnectorNotImplementedError` until Phase 2 registers factories.
|
||||
- `roster.schema.json`: optional `connector` block (tmux|discord|matrix; matrix homeserver/user/room; secrets via env, never roster).
|
||||
- Design doc `docs/fleet/f4-matrix-connector.md`: interface, config, Matrix CS-API mapping, Conduit-default infra, phasing.
|
||||
- **No fleet.ts changes** → self-contained, zero conflict with stacked #615.
|
||||
|
||||
## Verification
|
||||
|
||||
- 7 connector tests green; tsc/eslint/prettier/sanitize clean; schema valid JSON.
|
||||
|
||||
## Phase 2+ (follow-ups, in the doc)
|
||||
|
||||
Matrix CS-API client (fetch send/sync/health) + factory; init/configure connector-selection UX + roster-parse wiring; systemd launch wiring; Conduit deploy guide; first-party Mosaic Discord (threads) as a connector.
|
||||
|
||||
## Phase 2a (feat/f4-matrix-client, stacked on #617) — Matrix CS-API client
|
||||
|
||||
- `src/fleet/connectors/matrix.ts`: `MatrixConnector implements OrchestratorConnector` over the Matrix
|
||||
client-server API (injectable fetch, no SDK). `send` → PUT m.room.message (thread-aware); `subscribe`
|
||||
→ /sync long-poll loop using the pure `parseSyncResponse`; `health` → /versions + /whoami.
|
||||
`registerMatrixConnector(env)` registers the factory (token from MATRIX_ACCESS_TOKEN, never roster).
|
||||
- Pure helpers `buildMessageBody` + `parseSyncResponse` make send/receive unit-testable.
|
||||
- 13 Matrix tests + 7 registry = 20 connector tests green; tsc/eslint/prettier clean.
|
||||
- Remaining Phase 2: init/configure connector-selection UX + roster-parse wiring (touches fleet.ts —
|
||||
after #615); systemd launch wiring; Conduit deploy guide.
|
||||
@@ -1,110 +0,0 @@
|
||||
# FCM-M2-001 — Generated Environment Boundary
|
||||
|
||||
- **Issue/card:** #758 / FCM-M2-001
|
||||
- **Branch/base:** `feat/758-generated-env-boundary` from `origin/main` `e9c4aa3e8b3780719cd5a43c0ef3f37fc70de666`
|
||||
- **Budget assumption:** 30K-card budget; implement only the deterministic generated/local environment boundary and its launch-chain/docs/tests.
|
||||
|
||||
## Objective
|
||||
|
||||
Replace the generic fleet agent `.env` authority/merge path with a deterministic roster-derived `<agent>.env.generated` projection and strict, data-only `<agent>.env.local`. The roster remains the desired-state authority. Reject bad input before the launcher creates a tmux session; never print sensitive or privileged-command values.
|
||||
|
||||
## Scope and non-goals
|
||||
|
||||
- In scope: deterministic render/write, strict generated/local parse rules, legacy `.env` disposition/quarantine, systemd/launcher boundary, permission/path checks, focused fail-closed tests, operator/reference documentation, USC interface evidence.
|
||||
- Excluded: roster CRUD/mutation, v2 roster schema changes, lifecycle/reconcile/apply behavior, migration/canary rollout, connectors, remote surfaces, live-fleet actions, and M2-002.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add red tests for generated-key shadowing, malformed/duplicate/unknown/command/sensitive input, no-value diagnostics, deterministic/idempotent projection, secure file modes, and legacy disposition.
|
||||
2. Implement a pure strict environment contract plus atomic projection/quarantine helper.
|
||||
3. Replace the generic `.env` writer/merge path and systemd reference with `.env.generated` + `.env.local` ownership.
|
||||
4. Make the shell launcher parse the files without `source`/`eval`, reject unsafe input before tmux creation, and construct only the roster-derived runtime command.
|
||||
5. Add operator/reference documentation with the requested USC M1 interface evidence and M2–M4 gate statement.
|
||||
6. Run focused/package/root gates and audit the USC interface packet. Per continuation scope, stop before review, commit, push, PR, or live mutation.
|
||||
|
||||
## Initial evidence
|
||||
|
||||
- No existing owner: target worktree path absent; no target local/remote branch; `pr-list.sh -s open` returned no open PRs.
|
||||
- M1 compiler/API/docs and executable disposition evidence are present at the assigned base.
|
||||
- Existing launch chain writes `fleet/agents/<agent>.env`, preserves arbitrary legacy lines via `mergeAgentEnv`, sources `MOSAIC_AGENT_COMMAND`, and executes it through `bash -c`; all are M2 remediation targets.
|
||||
- `~/.config/mosaic/guides/SECURITY.md` is absent. Read the available security-review role contract and the vault/secrets guide instead.
|
||||
|
||||
## Verification log
|
||||
|
||||
### Continuation (2026-07-14)
|
||||
|
||||
- Preserved the inherited 14-file delta; no reset, stash, rebase, roster mutation, lifecycle action,
|
||||
live-fleet action, commit, push, or PR action was performed.
|
||||
- Focused gates passed:
|
||||
- `pnpm --dir packages/mosaic test -- src/fleet/generated-env-boundary.spec.ts` — 1 file, 10 tests passed.
|
||||
- `bash packages/mosaic/framework/tools/fleet/test-start-agent-session.sh` — passed.
|
||||
- `bash packages/mosaic/framework/systemd/user/test-fleet-units.sh` — passed.
|
||||
- `pnpm --dir packages/mosaic test -- src/commands/fleet.spec.ts` — 1 file, 192 tests passed.
|
||||
- Package gates passed before final documentation/format follow-up:
|
||||
- `pnpm --dir packages/mosaic typecheck` — passed.
|
||||
- `pnpm --dir packages/mosaic lint` — passed.
|
||||
- `pnpm --dir packages/mosaic test` — 52 files, 752 tests passed.
|
||||
- `pnpm format:check` initially failed only for the new boundary reference and generated-boundary
|
||||
TypeScript files; targeted Prettier normalization was applied. A final `pnpm format:check` passed.
|
||||
- USC packet audit: the M1 structural compiler is `parseRosterV2` with roster `version: 2`; the
|
||||
semantic resolver is `validateRosterV2Semantics`; disposition artifacts retain `version: 1` fixture
|
||||
evidence. `docs/TASKS.md` records M1-001 done, M1-002 in-progress, and M1-003 not-started; no
|
||||
product release version is claimed. The packet now distinguishes these statuses from checkout
|
||||
artifact presence and states the M2 → M3 → M4 downstream gates.
|
||||
|
||||
## Review remediation (2026-07-14)
|
||||
|
||||
- **Blocker 1 red-first:** Added a launcher reproducer with a `0777` `fleet/agents` parent and a private generated file. Before implementation, `bash packages/mosaic/framework/tools/fleet/test-start-agent-session.sh` failed: `FAIL: generated file under a world-writable parent was accepted`. The failure occurred after the launch path reached fake tmux, proving the parent was not validated.
|
||||
- **Blocker 2 red-first:** Added a `symlink()` projection-directory reproducer that preloads generated/local/quarantine/legacy target files and asserts no target mutation. Before implementation, `pnpm --dir packages/mosaic test -- src/fleet/generated-env-boundary.spec.ts` failed the new test because the existing writer followed the `agentEnvDir` symlink and parsed its target legacy input (`expected /unsafe-directory/i`, received `code=malformed-line`). The initial test-only missing `mkdir` import was corrected before recording this behavior failure.
|
||||
- **Blocker 3 red-first:** Added fresh/stale/absent native-heartbeat regression coverage. Before implementation, an isolated fake-tmux launcher reproducer with a fresh `<agent>.hb.native` marker failed `FAIL: fresh native heartbeat was overwritten`; the existing sidecar immediately replaced native `status=busy`/`model` content.
|
||||
- **Remediation result:** The launcher now rejects a group/world-accessible or symlinked `fleet/agents` parent before an environment read or tmux call. The projection writer uses `lstat` before chmod/write processing and rejects a symlinked directory without creating generated/local/quarantine files or deleting legacy input. The heartbeat sidecar defers to a fresh non-symlink native marker and falls back when stale/absent. Focused green evidence before independent review: `bash packages/mosaic/framework/tools/fleet/test-start-agent-session.sh` and `pnpm --dir packages/mosaic test -- src/fleet/generated-env-boundary.spec.ts` (11 tests) passed.
|
||||
- **Independent-review follow-up red-first:** Codex code review returned one blocker and security review one medium CWE-732 finding: the writer repaired an already `0777` directory with `chmod` before trusting its contents. Added a reproducer with a safe local file beneath an existing `0777` directory. Before the follow-up fix, `pnpm --dir packages/mosaic test -- src/fleet/generated-env-boundary.spec.ts` failed because the promise resolved and wrote `coder0.env.generated` instead of rejecting.
|
||||
- **Independent-review remediation:** Existing directories now pass non-following private-directory validation before any read or chmod; only a directory created in this call is normalized to `0700`. The fleet-add test fixture now creates its simulated trusted `fleet/agents` boundary at `0700`; this corrects fixture setup to match the new required contract rather than weakening the rejection assertion. Focused reruns passed: generated-boundary 12 tests, launcher boundary suite, and fleet suite 192 tests.
|
||||
- **Final verification before re-review:** Launcher + systemd suites passed; package suite passed (52 files, 754 tests); package lint/typecheck, root typecheck (42 tasks), format check, and diff check passed. The rerun code review still reports a tmux command-arity blocker, and the security rerun reports systemd `EnvironmentFile` pre-validation injection findings for both agent units. These were discovered after the specified three-remediation scope; no additional source changes were made. Independent review therefore remains `REQUEST CHANGES` despite the requested three fixes passing their behavioral suites.
|
||||
|
||||
## Systemd pre-validation remediation (2026-07-14)
|
||||
|
||||
- **Red-first:** Updated the fleet unit contract to reject any `EnvironmentFile=` projection preload, require a cleared bootstrap environment, and require a validated exact-stop path. Before implementation, `bash packages/mosaic/framework/systemd/user/test-fleet-units.sh` failed: `FAIL: agent units must not preload projections before strict parsing`.
|
||||
- **Red-first parser/stop coverage:** Added interaction-wrapper and exact-stop cases to the launcher boundary suite. Before implementation, `bash packages/mosaic/framework/tools/fleet/test-start-agent-session.sh` failed: `FAIL: interaction did not use shared strict parser first`, because the interaction wrapper consumed inherited environment before projection validation.
|
||||
- **Focused green:** Both unit templates now use `env -i` with fixed `HOME`, agent instance, and PATH; neither has `Environment=`/`EnvironmentFile=`. The interaction wrapper delegates to `start-agent-session.sh --interaction`, so strict generated/local parsing precedes pinned Pi profile checks. `--stop` reuses the strict generated parser before exact `=<agent>` socket/session termination. Passed: systemd unit suite, launcher boundary suite (including malformed interaction, pinned profile, and ambient-socket stop cases), and 210 focused TypeScript tests.
|
||||
- **Final verification:** `pnpm --dir packages/mosaic test` passed (52 files, 754 tests); package lint/typecheck, root typecheck (42 tasks), format/diff, and shell syntax checks passed. Security review passed with no findings. Code review repeated the previously refuted tmux argv concern and a pre-existing Claude trust-lock suggestion; per the assigned narrow follow-up, no tmux or unrelated trust-path change was made.
|
||||
|
||||
## Risks and next review
|
||||
|
||||
- This card is uncommitted and unreleased. The canonical tracker still records its dependencies as
|
||||
M1-002 in progress and M1-003 not started; this continuation does not reinterpret those task states.
|
||||
- Final post-documentation checks passed: `pnpm --dir packages/mosaic typecheck`,
|
||||
`pnpm --dir packages/mosaic lint`, `pnpm --dir packages/mosaic test` (52 files, 752 tests),
|
||||
`pnpm typecheck` (42 Turbo tasks), and `pnpm format:check`.
|
||||
- Obtain independent code and security review of the complete delta next. Do not run commit, push,
|
||||
PR, or live-fleet commands in this continuation.
|
||||
|
||||
## Fresh-install directory remediation (2026-07-14)
|
||||
|
||||
- **Objective:** Remediate only the fresh-install path where `installFleet` created `fleet/agents`
|
||||
with host-umask permissions before the boundary writer correctly rejected it.
|
||||
- **Plan:** Add a real `fleet install --no-enable` integration reproducer; prove red; let the
|
||||
existing boundary writer own directory creation; run focused and full gates. No commit, push,
|
||||
PR, review disposition, or live-fleet action.
|
||||
- **Red evidence:** Before the one-line remediation,
|
||||
`pnpm --dir packages/mosaic test -- src/commands/fleet.spec.ts` failed the new test with
|
||||
`AgentEnvBoundaryError: code=unsafe-permissions` at `ensurePrivateProjectionDirectory`, after
|
||||
`installFleet` pre-created the directory.
|
||||
- **Change:** Removed only the recursive `mkdir(activePaths.agentEnvDir)` in `installFleet`.
|
||||
`writeAgentEnvironmentProjection` remains the sole creator and retains its existing `lstat`,
|
||||
private-directory, symlink, and existing-unsafe-directory fail-closed checks.
|
||||
- **Focused green:** `pnpm --dir packages/mosaic test -- src/commands/fleet.spec.ts` — 193 tests
|
||||
passed. The new integration executes a fresh `fleet install --no-enable`, asserts a real
|
||||
non-symlink `0700` directory and a `0600` generated projection. Existing unsafe-directory
|
||||
coverage remains in `generated-env-boundary.spec.ts` and asserts no chmod repair/no generated
|
||||
file write.
|
||||
- **Full gates green:** generated-boundary 12 tests; launcher and systemd suites; package
|
||||
typecheck/lint and 52 files / 755 tests; root typecheck (42 tasks), lint, format, diff check,
|
||||
and root test (42 tasks) all passed.
|
||||
- **Independent review:** The complete inherited uncommitted delta still has Codex `REQUEST CHANGES`
|
||||
findings outside this narrow fix (tmux command arity and Claude trust-lock regression), plus a
|
||||
security-review medium finding on unvalidated writable ancestor directories. No out-of-scope
|
||||
source changes were made.
|
||||
- **Risk:** The writer's existing create-then-validate sequence is relied on for the creation
|
||||
boundary; a concurrent substitution causes fail-closed validation rather than repair. The
|
||||
review findings above remain residual risks for the complete card delta.
|
||||
@@ -1,85 +0,0 @@
|
||||
# FCM-M5-001 — Fleet configuration operator documentation
|
||||
|
||||
- Task: `FCM-M5-001`
|
||||
- Issue: `#758`
|
||||
- Branch: `docs/758-fleet-config-operator-docs`
|
||||
- Exact base: `9745bc3f29c26b021a478b7ad03cfb494f6c9de3` (tree `4da210da9a71b035130d4160a4a2e691bdfde2da`)
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver the accepted fleet documentation information architecture, operator workflows, operations and migration references, comprehensive contract documentation, and deterministic link/example validation without live fleet action or product mutation.
|
||||
|
||||
## Scope and constraints
|
||||
|
||||
- Documentation, examples, documentation validation, and tracking only.
|
||||
- `roster.yaml` remains the sole writable desired-state authority; generated state is derived/observed.
|
||||
- No M4-002 implementation or execution; no canary, migration, rollback, deployment, systemd/tmux/session, generated projection, or product mutation.
|
||||
- `mos-comms` is temporary and is not permanent architecture.
|
||||
- Parent issue `#758` remains open through M5.
|
||||
- No credentials, sensitive values, or privileged command content.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Update tracking first with exact M4-001 evidence and mark M5-001 in progress.
|
||||
2. Map the M0 checklist and current implementation behavior to documentation pages.
|
||||
3. Author operator, operations, migration, schema/reference, recovery, troubleshooting, and security/authority docs.
|
||||
4. Add or extend deterministic documentation/link/example validation if required, red-first.
|
||||
5. Run repository documentation, link, example, and relevant package checks; review and remediate.
|
||||
6. Commit, queue-guard, push one branch, and open one wrapper-created PR; stop for independent review.
|
||||
|
||||
## Budget
|
||||
|
||||
- Task estimate: `24K`.
|
||||
- Working cap: stay within the card estimate by parallelizing read-only discovery and limiting edits to checklist-required artifacts.
|
||||
|
||||
## Progress checkpoints
|
||||
|
||||
- [x] Loaded repository/global delivery and documentation contracts.
|
||||
- [x] Verified `origin/main` is exact required base and created isolated worktree.
|
||||
- [x] Tracking updated first.
|
||||
- [x] Checklist mapped and docs authored.
|
||||
- [x] Validation green.
|
||||
- [x] Review/remediation complete.
|
||||
- [x] Commit, queue guard, push, PR #789.
|
||||
- [x] Rejected exact-head RoR findings repaired on a new descendant commit candidate.
|
||||
- [ ] New exact-head review and CI after repair push.
|
||||
|
||||
## Tests and verification
|
||||
|
||||
- Red-first documentation validator initially failed for the absent fleet entry point and canonical
|
||||
example, then passed after the IA and example were added.
|
||||
- `pnpm --filter @mosaicstack/mosaic exec vitest run src/fleet/roster-v2.spec.ts src/fleet/example-profile-dispositions.spec.ts src/fleet/fleet-documentation.spec.ts src/fleet/v1-v2-migration.spec.ts src/fleet/generated-env-boundary.spec.ts src/fleet/fleet-agent-crud.spec.ts src/fleet/fleet-reconciler.spec.ts` — 7 files, 195 tests passed after building workspace dependencies.
|
||||
- `pnpm format:check` — passed.
|
||||
- `pnpm lint` — 23 tasks passed.
|
||||
- `pnpm typecheck` — 42 tasks passed.
|
||||
- `pnpm test` — 43 tasks passed; `@mosaicstack/mosaic` contributed 61 files and 1,045 tests.
|
||||
- `bash packages/mosaic/framework/tools/quality/scripts/verify-sanitized.sh` — passed.
|
||||
- `bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh` — passed.
|
||||
- `git diff --check` — passed before final review.
|
||||
- Independent staged-snapshot review identified four documentation/validation blockers: reboot safety,
|
||||
heartbeat observation, migration failure envelope, and example-scan coverage. All were remediated;
|
||||
focused rereview approved the staged remediations with no blockers. Exact committed-head review remains
|
||||
a post-PR gate.
|
||||
- Post-remediation `@mosaicstack/mosaic` lint/typecheck passed; package test passed 61 files / 1,045
|
||||
tests; sanitization and resident-budget gates passed again.
|
||||
|
||||
- Post-PR exact-head RoR on rejected head `0aee2c09819fd06e28f927384ea56fa2ef374edf`
|
||||
identified five blockers: update-lifecycle overclaim, missing explicit `fleet validate` gap,
|
||||
fragment-blind link validation, unsupported checklist-evidence claim, and insufficient example safety
|
||||
validation. Red-first regressions failed before implementation for missing-heading, privileged-command,
|
||||
and credential-format fixtures. Repairs now preserve/document implementation truth, validate heading
|
||||
fragments, narrow checklist claims, and scan fenced/canonical examples for common credential formats
|
||||
and privileged commands without printing fixture values.
|
||||
- Repair-focused fleet contracts: 7 files, 192 tests passed after review remediation; documentation
|
||||
validator contributed 11 tests. Full gates passed: format; lint 23/23; typecheck 42/42; test 43/43
|
||||
tasks with `@mosaicstack/mosaic` 61 files / 1,052 tests; sanitization; resident budget; and
|
||||
`git diff --check`. New exact-head review/CI remain pending until the repair commit is pushed.
|
||||
|
||||
## Risks/blockers
|
||||
|
||||
- Checklist may include behavior intentionally deferred to M4-002/M5-002; such items must be recorded as approved-existing holds rather than claimed delivered.
|
||||
- Commands/examples must remain non-live and avoid privileged/sensitive content.
|
||||
|
||||
## Final evidence
|
||||
|
||||
- Pending.
|
||||
@@ -1,20 +0,0 @@
|
||||
# Scratchpad — fix-ci-migrations-20260330
|
||||
|
||||
## Objective
|
||||
|
||||
- Fix Drizzle migration journal ordering so fresh Postgres instances apply all schema migrations in CI.
|
||||
|
||||
## Plan
|
||||
|
||||
- Inspect migration SQL, journal, and snapshot chain.
|
||||
- Patch metadata consistently.
|
||||
- Run full test suite.
|
||||
- Record result and risks.
|
||||
|
||||
## Progress
|
||||
|
||||
- Inspected migration files and confirmed 0001_cynical_ultimatum.sql is missing from journal while 0002 depends on it.
|
||||
- Patched `packages/db/drizzle/meta/_journal.json` to insert `0001_cynical_ultimatum` at idx 1 and shift later entries to idx 2-7.
|
||||
- Verified snapshot content is already semantically aligned with the fixed ordering: the missing tables exist in `0001_snapshot.json`, and `mutable` appears in later snapshots.
|
||||
- Installed workspace dependencies in this worktree to make the requested test command runnable.
|
||||
- Ran `pnpm test` successfully; gateway reported `347 passed (347)` and Turbo finished with `35 successful, 35 total`.
|
||||
@@ -1,41 +0,0 @@
|
||||
# Task Scratchpad — Turbo DATABASE_URL passthrough
|
||||
|
||||
## Objective
|
||||
|
||||
- Fix CI test execution under Turborepo by passing DB-related environment variables through the `test` task.
|
||||
- Preserve the repo's documented local Postgres fallback on host port `5433`.
|
||||
|
||||
## Scope
|
||||
|
||||
- Edit `turbo.json`
|
||||
- Run baseline checks requested by the user and repo rules where feasible
|
||||
- Publish branch and open PR if checks are acceptable
|
||||
|
||||
## Assumptions
|
||||
|
||||
- ASSUMPTION: No PRD update is required because this is a narrow CI/config bug fix that does not change product requirements.
|
||||
- ASSUMPTION: `docs/TASKS.md` remains untouched because project guidance marks it orchestrator-only.
|
||||
- ASSUMPTION: Local Postgres-backed tests are not runnable in this worktree, so baseline verification will rely on static gates unless the environment already provides DB access.
|
||||
|
||||
## Plan
|
||||
|
||||
- Record current repo state and avoid touching `.mosaic/orchestrator/session.lock`
|
||||
- Add Turbo DB env declarations for test execution and cache invalidation
|
||||
- Run `pnpm format:check`, `pnpm typecheck`, and `pnpm lint`
|
||||
- Review the diff, then commit/push/PR via provider-appropriate flow
|
||||
|
||||
## Verification Log
|
||||
|
||||
- `pnpm install` completed in this worktree so repo tooling is available
|
||||
- `pnpm format:check` initially failed on `turbo.json`; fixed by formatting the file
|
||||
- `pnpm format:check` passed after formatting
|
||||
- `pnpm typecheck` passed
|
||||
- `pnpm lint` passed
|
||||
- Independent review flagged two important adjustments:
|
||||
- keep `DEFAULT_DATABASE_URL` on `5433` because local Docker Compose maps host `5433 -> container 5432`
|
||||
- prefer Turbo `env` over `passThroughEnv` so DB config changes also affect the test cache key
|
||||
|
||||
## Risks
|
||||
|
||||
- Existing mission/orchestrator files are dirty in the worktree and must be excluded from the scoped change.
|
||||
- Local tests were not run because no Postgres service is available in this worktree; CI remains the primary situational validation for the test-task behavior.
|
||||
@@ -1,54 +0,0 @@
|
||||
# Fleet CLI Local Canary Review Fixes
|
||||
|
||||
## Objective
|
||||
|
||||
Fix only the two should-fix code review findings:
|
||||
|
||||
1. Ensure `@mosaicstack/mosaic` declares `yaml` and lockfile state is current.
|
||||
2. Validate `mosaic agent status [agent]` against the fleet roster before constructing/running the tmux target.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Do not modify `docs/TASKS.md`.
|
||||
- Leave changes uncommitted.
|
||||
- Run requested formatting and quality gates.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Inspect manifest/lockfile state for `yaml`.
|
||||
2. Add failing regression test for `mosaic agent status typo`.
|
||||
3. Patch `registerFleetAgentCommands` status validation.
|
||||
4. Format touched files.
|
||||
5. Run requested tests, typecheck, and lint.
|
||||
6. Review final diff.
|
||||
|
||||
## Progress
|
||||
|
||||
- Loaded required repo/global/runtime instructions.
|
||||
- Confirmed `packages/mosaic/package.json` already declares `yaml`.
|
||||
- Confirmed `pnpm-lock.yaml` already has `packages/mosaic` importer entry for `yaml`.
|
||||
- Found `registerFleetAgentCommands` status path does not validate agent before building tmux target.
|
||||
|
||||
## Verification
|
||||
|
||||
- TDD red check: `pnpm --filter @mosaicstack/mosaic test -- src/commands/fleet.spec.ts`
|
||||
failed before the production fix because `mosaic agent status typo` resolved instead of
|
||||
rejecting.
|
||||
- Focused green check: `pnpm --filter @mosaicstack/mosaic test -- src/commands/fleet.spec.ts`
|
||||
passed after adding roster validation.
|
||||
- Formatting: `pnpm exec prettier --write packages/mosaic/src/commands/fleet.ts packages/mosaic/src/commands/fleet.spec.ts docs/scratchpads/fleet-cli-local-canary-review-fixes.md`
|
||||
completed with all files unchanged.
|
||||
- Requested tests: `pnpm --filter @mosaicstack/mosaic test -- src/commands/fleet.spec.ts src/cli-smoke.spec.ts`
|
||||
passed with 36 tests.
|
||||
- Baseline typecheck: `pnpm typecheck` passed.
|
||||
- Baseline lint: `pnpm lint` passed.
|
||||
- Independent review: `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted`
|
||||
returned approve with 0 findings. Note: reviewer reported broader context inspection was limited
|
||||
by its read-only sandbox, so review was based on the supplied diff.
|
||||
- `docs/TASKS.md` has no diff.
|
||||
|
||||
## Risks
|
||||
|
||||
- `docs/TASKS.md` intentionally untouched per user instruction.
|
||||
- Review finding 1 required no file edit: `packages/mosaic/package.json` already declares
|
||||
`yaml`, and the `packages/mosaic` importer in `pnpm-lock.yaml` already includes `yaml`.
|
||||
@@ -1,31 +0,0 @@
|
||||
# Fleet onboarding-injection — comms cheat-sheet + peer roster (#620)
|
||||
|
||||
- **Issue:** #620 · **Branch:** `feat/fleet-comms-onboarding` (off main). Root cause of Mos's failed first send.
|
||||
|
||||
## What
|
||||
|
||||
Inject a `# Fleet Comms` block into each spawned fleet agent's system prompt (via composeContract — the
|
||||
runtime-agnostic path every `mosaic yolo <runtime>` agent hits), so it boots knowing how to reach peers.
|
||||
|
||||
- `src/fleet/comms-onboarding.ts` (standalone, no fleet.ts coupling):
|
||||
- `parseRosterAgents` (name/class/host/ssh, lenient), `renderPeerReach` (same-host `-s` vs cross-host
|
||||
`-H <ssh> -s`), `buildFleetCommsBlock` (self [host:session] identity + agent-send path + peer table +
|
||||
FLIP-to-reply + `agent send --verify`=ACCEPTED), `readFleetCommsBlock` (reads roster.yaml; '' if not a member).
|
||||
- `composeContract` appends it only when MOSAIC_AGENT_NAME is set + the agent is in the roster.
|
||||
- `roster.schema.json`: optional per-agent `host` + `ssh` (cross-host addresses; manual = pre-federation
|
||||
stopgap, federation/W1 auto-discovers later).
|
||||
|
||||
## Acceptance criteria (Mos) — all covered
|
||||
|
||||
1. own [host:session] + agent-send path + peer roster ✓
|
||||
2. cross-host correctness: local→`-s` (no -H); remote→`-H <ssh> -s` ✓ (concrete coder0-0@dragon-lin)
|
||||
3. FLIP-the-preamble reply rule ✓
|
||||
4. `agent send --verify` = ACCEPTED ✓
|
||||
5. no `-L` (default socket); matches live tooling ✓
|
||||
|
||||
## Verification
|
||||
|
||||
- 10 onboarding unit tests (parse, render local/remote/fallback/equal-host, build, situational read) +
|
||||
2 composeContract situational tests (injects for fleet agent w/ correct cross-host addr; no-op when
|
||||
MOSAIC_AGENT_NAME unset). tsc/eslint/prettier/sanitize clean.
|
||||
- Post-merge validation: Mos spawns a real w-jarvis agent → first-try reach to coder0-0@dragon-lin + a local peer.
|
||||
@@ -1,26 +0,0 @@
|
||||
# Fleet enhancer role + two-agent floor (#614)
|
||||
|
||||
- **Issue:** #614 · **Branch:** `feat/fleet-enhancer-floor` (stacked on #612 `feat/fleet-polish-bundle`)
|
||||
- **Doctrine:** `docs/fleet/north-star.md` (PR #613) — every fleet = orchestrator + enhancer minimum.
|
||||
|
||||
## Changes
|
||||
|
||||
- **Presets** (general, coding, research, hybrid): add `enhancer` (claude, `class: enhancer`,
|
||||
`persistent_persona: true`) as a core always-on agent alongside the orchestrator. minimal/local-canary
|
||||
unchanged.
|
||||
- **fleet.ts**: `countEnhancers` helper; init guarantee extended — non-minimal profiles must yield
|
||||
exactly 1 orchestrator AND >=1 enhancer (hard-fail otherwise); `removeAgentFromRoster` refuses to drop
|
||||
the sole enhancer (symmetric with the sole-orchestrator guard) so the floor holds at runtime, not just init.
|
||||
- **Role doc**: `framework/fleet/roles/enhancer.md` — the enhancer mandate (monitor → analyze → plan →
|
||||
upgrade tools/skills/harness WITH orchestrator → file Mosaic Stack bug reports) + boundaries (does NOT
|
||||
code or review).
|
||||
|
||||
## Verification
|
||||
|
||||
- 155 fleet tests green (new: countEnhancers; remove-sole-enhancer guard; remove-allows-when-another;
|
||||
init two-agent-floor; every-non-minimal-preset-has-enhancer; updated preset rosters). tsc/eslint/
|
||||
prettier/sanitize clean. TDD on the init guarantee + remove protection.
|
||||
|
||||
## Stacking
|
||||
|
||||
Built on #612's init-R5 code. PR shows #612 + enhancer until #612 merges; then rebase onto main → clean.
|
||||
@@ -1,100 +0,0 @@
|
||||
# Scratchpad — Fleet Phase 2: Observability (W-FLEET)
|
||||
|
||||
> Append-only. Mission `mvp-20260312` / workstream W-FLEET.
|
||||
> Lead: Jarvis (Claude) at `W-jarvis:mos-claude-18`. Coordinating with `jwoltje@dragon-lin:coder0-0`.
|
||||
|
||||
## Mission prompt (2026-06-20)
|
||||
|
||||
Establish the north star for the Mosaic Fleet feature and prepare Phase-2 observability
|
||||
for delivery. The USC tmux PoC is the proven base. Jason granted lead authority:
|
||||
"The fleet is a great way to actually build the MVP — we are building the system that
|
||||
builds the system." Dogfood actual agent construction + ad-hoc deployment; coordinate
|
||||
with a second agent on `dragon-lin`.
|
||||
|
||||
## Decisions of record (with Jason, 2026-06-20)
|
||||
|
||||
- Agent model: config defines, session runs (gateway = definition/identity/auth; tmux = runtime).
|
||||
- Tenancy: multi-tenant from the start; isolation = per-tenant Linux uid.
|
||||
- Health: heartbeat required; dogfood stub implements protocol now.
|
||||
- Lifecycle: hybrid (core always-on + ephemeral workers).
|
||||
- Observation: read-only default, opt-in takeover.
|
||||
- Multi-host: designed-for day one; control plane rides federation (W1), not a bespoke broker.
|
||||
- Delivery: CLI-first, dogfood on the live stub fleet; webUI deferred to Phase 5.
|
||||
- Fleet is dual-role: product AND means of production (bootstrapping the MVP).
|
||||
- Code review = **dual-engine**: Claude **and** gpt-5.5/Codex, run together (Jason: the
|
||||
combination produces the best results). Launch reviewers via `mosaic yolo pi` / `codex`
|
||||
(proven path) or `~/.config/mosaic/tools/codex/codex-code-review.sh`. Applies to all
|
||||
code-review gates incl. FLEET-OBS-008. Per Jason 2026-06-20.
|
||||
- Worktree discipline: do fleet work in `~/src/mosaicstack-stack-worktrees/<branch>`, NOT
|
||||
the shared main checkout — concurrent processes mutate `main` there (learned 2026-06-20).
|
||||
|
||||
## Environment facts (verified 2026-06-20)
|
||||
|
||||
- Fleet is live on `W-jarvis` (uid 1000, `jarvis`, `Linger=yes`) on tmux socket
|
||||
`mosaic-fleet`: `_holder`, `canary-pi`, `dogfood-coder`, `dogfood-orchestrator`,
|
||||
`dogfood-reviewer`. All panes run `~/.config/mosaic/fleet/dogfood-agent.py` (stub),
|
||||
including `canary-pi` (roster says runtime=pi → **drift**).
|
||||
- Holder + `mosaic-agent@*` units are `active (exited)` but `UnitFileState=disabled`
|
||||
(reboot loses fleet → boot-enable gap to surface).
|
||||
- Observation blocked by: isolated socket (hidden from default `tmux ls`), `capture-pane`
|
||||
blank for TUIs, `attach` being read-write + resizing.
|
||||
- Second agent: `jwoltje@dragon-lin`, session `coder0-0` (group `coder0`), running `node`,
|
||||
default socket. ssh forward reach confirmed.
|
||||
|
||||
## Governance / collision-safety
|
||||
|
||||
- `mosaicstack-stack` has active mission `mvp-20260312` with single-writer locks on
|
||||
`docs/MISSION-MANIFEST.md`, `docs/TASKS.md`, `docs/scratchpads/mvp-20260312.md`.
|
||||
- This workstream touches NONE of those. All Fleet docs scoped under `docs/fleet/` +
|
||||
this scratchpad. Rollup row proposed, not written.
|
||||
|
||||
## Session log
|
||||
|
||||
- 2026-06-20: Researched AI guide + fleet code + live state. Established north star with
|
||||
Jason (8 forks decided). Branched `feat/fleet-observability`. Persisted
|
||||
`docs/fleet/{north-star.md,PRD.md,TASKS.md}` + this scratchpad. Next: establish comms
|
||||
with dragon-lin coder, commit docs, begin Phase-2 delivery (heartbeat + `fleet ps`).
|
||||
- 2026-06-20 (session 2): Built Phase-2 CLI via worker (commit ab47831): `fleet ps`,
|
||||
`agent watch`, `agent send --verify`, 62 tests. LIVE-verified `fleet ps` on
|
||||
mosaic-fleet — correctly flagged canary-pi DRIFT + BOOT-ENABLE, tenant_id+host in JSON.
|
||||
Heartbeat responder added to dogfood-agent.py (FLEET-OBS-002) — `fleet ps` HB now
|
||||
`healthy` for all 4 agents.
|
||||
- Coordination: dual-engine-reviewed (Claude+Codex) and merged framework PRs #572
|
||||
(sanitization gate) + #575 (CONSTITUTION extraction) as Lead. Codex caught an Alpine
|
||||
blocker on #572 (refuted by CI); Claude caught a CI-breaking format failure on #575.
|
||||
- **FINDINGS (north-star / Phase-3 blockers):**
|
||||
1. Ad-hoc `mosaic yolo {codex,pi}` via `start-agent-session.sh` DIE immediately in a
|
||||
detached tmux pane (codex: "stdin is not a terminal"; pi: same). Only the python stub
|
||||
survives. => Real runtimes have NEVER run durably in the fleet. Launch path (PATH/TTY
|
||||
in the detached shell) must be fixed before Phase-3 real-runtime swap. `fleet ps`
|
||||
caught both dead panes instantly (tool validated).
|
||||
2. `MOSAIC_AGENT_NAME` (set in systemd EnvironmentFile) is NOT propagated into tmux's
|
||||
global env, so agents defaulted to `unknown`. Worked around in dogfood-agent.py via
|
||||
tmux session-name fallback; the systemd/tmux env handoff needs a real fix.
|
||||
- Next: rebase on merged main, open Phase-2 PR, dual-engine review, merge, close
|
||||
`fleet-observability-1`. Defer launch-path + env-propagation fixes to Phase 3.
|
||||
- 2026-06-21 (session 3): Phase-2 PR #579 merged (3 dual-engine rounds hardened
|
||||
verify+watch). Then closed the launch-path question with Jason's input — CORRECTING
|
||||
earlier findings:
|
||||
- The ad-hoc launch deaths were NOT a fundamental TTY blocker: (a) codex was a stale
|
||||
version (Jason updated it); (b) pi was misconfigured to Claude auth (Jason removed it;
|
||||
default is now Codex). The REAL durable-launch bug is **PATH**: the detached tmux
|
||||
launch shell is login+non-interactive, so it misses `~/.npm-global/bin` (added only in
|
||||
`~/.bashrc`) -> `mosaic: command not found` (127) -> pane dies. tmux panes inherit the
|
||||
tmux _server_ env, so PATH must be baked into the pane command.
|
||||
- **Durable real-agent recipe (validated live on gpt-5.5, Claude-free):**
|
||||
`mosaic yolo pi --model openai-codex/gpt-5.5:high` — pi tolerates detached tmux; a raw
|
||||
interactive TUI (codex CLI) exits without an attached client. Status line confirmed
|
||||
`(openai-codex) gpt-5.5 • high`.
|
||||
- PATH fix landed in `start-agent-session.sh` (commit 32efc13, branch
|
||||
feat/fleet-launch-path): derive runtime-bin prefix (MOSAIC_RUNTIME_BIN | npm prefix |
|
||||
~/.npm-global/bin | ~/.local/bin), bake `export PATH=...; exec <cmd>` into the pane;
|
||||
`exec` also fixes the drift false-positive. Live-tested under stripped PATH -> durable.
|
||||
- Boot-survival: Jason ran `systemctl --user enable` (+ linger). TODO: auto-enable in
|
||||
**fleet init** so operators never have to remember it (agentic-enhancement cycle).
|
||||
- Future custom Pi harness build: pi cannot self-report its model (track
|
||||
runtime/model/effort as fleet metadata); drift detection should recognize `node` as
|
||||
pi's pane command (a node-wrapped pane can currently read as drift).
|
||||
- Findings recorded in AI Guide playbooks/tmux-fleet.md (aiguide PR #7, merged).
|
||||
- Policy: avoid Claude outside Claude Code (API pricing for alt-harness use) — fleet
|
||||
runtimes default to Codex / pi-on-Codex; Claude stays in Claude Code only.
|
||||
@@ -1,20 +0,0 @@
|
||||
# Fleet-polish bundle — boot-survival symmetry (#611)
|
||||
|
||||
- **Issue:** #611 · **Branch:** `feat/fleet-polish-bundle` · From the Lead's Codex symmetry-gap finding.
|
||||
|
||||
## Three fixes
|
||||
|
||||
1. **disable-on-remove (BUG, TDD).** `fleet remove` stopped + deleted roster/env/heartbeat but never
|
||||
`systemctl --user disable [email protected]` → a removed-but-enabled unit could resurrect on
|
||||
reboot pointing at deleted config. Fix: `buildSystemdDisableCommand` + disable in `remove`
|
||||
(best-effort, gated on !--keep-files).
|
||||
2. **add-enable.** `fleet add` now enables the new agent's unit for boot-survival (best-effort,
|
||||
independent of --start) — symmetry with disable-on-remove.
|
||||
3. **init-R5 guarantee.** `fleet init --write` now FAILS HARD when a non-minimal profile doesn't yield
|
||||
exactly one orchestrator (was a soft warning). `minimal` (sanctioned no-orchestrator) still allowed.
|
||||
|
||||
## Verification
|
||||
|
||||
- 4 new tests (disable builder; remove-invokes-disable; add-invokes-enable; init general → exactly 1
|
||||
orchestrator) + 147 existing fleet tests green (151 total). tsc/eslint/prettier clean.
|
||||
- TDD on the disable bug per contract.
|
||||
@@ -1,28 +0,0 @@
|
||||
# Fleet stand-up fixes — model_hint→--model + socket-default trap (#626)
|
||||
|
||||
- **Issue:** #626 · **Branch:** `feat/fleet-standup-fixes` (off main). PoC-blocking, before doctrine doc.
|
||||
|
||||
## FIX 1 — model_hint consumed
|
||||
|
||||
- generateAgentEnv emits `MOSAIC_AGENT_MODEL=<modelHint>` (bare empty when unset).
|
||||
- start-agent-session.sh default command → `mosaic yolo $RUNTIME ${MOSAIC_AGENT_MODEL:+--model $MOSAIC_AGENT_MODEL}`.
|
||||
→ pi workers launch with `--model openai-codex/gpt-5.5:high`.
|
||||
|
||||
## FIX 2 — socket default trap (absent ⇒ literal default socket, no -L everywhere)
|
||||
|
||||
- THE TRAP (3 sites): parseRosterText fallback was DEFAULT_SOCKET_NAME; systemd unit had
|
||||
`Environment=MOSAIC_TMUX_SOCKET=mosaic-fleet` + `ExecStop ${…:-mosaic-fleet}`; start-agent-session
|
||||
defaulted `:-mosaic-fleet`. All fixed → absent socket = '' = default tmux socket (no -L).
|
||||
- `socketArgs(name)` helper → `name ? ['-L', name] : []`; replaced all ~15 -L render sites in fleet.ts.
|
||||
- shellEnvValue('') now emits a **bare** `VAR=` (not `''`) — unambiguous empty in systemd EnvironmentFile
|
||||
(a quoted '' could become a literal socket named "''").
|
||||
- start-agent-session.sh: `_tmux` wrapper passes -L only when socket set; [email protected]: dropped the
|
||||
socket default + conditional ExecStop. So spawn == observe == onboarding cheat-sheet.
|
||||
- CONTAINMENT: all 6 shipped presets set socket_name: mosaic-fleet explicitly → unaffected; only
|
||||
socket-less rosters (the PoC) get default-socket behavior. DEFAULT_SOCKET_NAME exported for explicit use.
|
||||
|
||||
## Verification
|
||||
|
||||
- 158 fleet + 201 fleet-adjacent tests green; new: socketArgs none/named, model_hint→env, explicit-socket
|
||||
renders -L, socket-less env bare. tsc/eslint/prettier/sanitize clean. Shell bash -n + end-to-end sim
|
||||
(socket-less→no -L, model→--model).
|
||||
@@ -1,47 +0,0 @@
|
||||
# Gateway Install UX Fixes — 2026-04-04
|
||||
|
||||
## Context
|
||||
|
||||
User hit two publish-drift bugs on `mosaic gateway install` (fixed in #386 and
|
||||
#389). On top of those, the install UX itself has three concrete problems:
|
||||
|
||||
1. Admin API token is generated by the bootstrap step and saved to
|
||||
`~/.config/mosaic/gateway/meta.json`, but never shown to the user. There is
|
||||
no way to retrieve it without reading the file or running `mosaic gateway
|
||||
config` afterward.
|
||||
2. When install crashes mid-way (e.g. daemon fails to become healthy), the
|
||||
next run of `mosaic gateway install` prompts "Reinstall? [y/N]". Saying N
|
||||
aborts, leaving the user with a half-configured install and no clear path
|
||||
forward. There is no resume path.
|
||||
3. Health-check failure only prints "Check logs: mosaic gateway logs" — forcing
|
||||
the user to run another command to see the actual error.
|
||||
|
||||
## Goal
|
||||
|
||||
Make `mosaic gateway install` a single end-to-end, resumable command that shows
|
||||
the admin token on creation and surfaces errors inline.
|
||||
|
||||
## Plan
|
||||
|
||||
- `install.ts`: detect partial state (meta exists, no admin token, daemon not
|
||||
running) and skip already-completed phases instead of aborting.
|
||||
- `install.ts`: add a prominent "Admin API Token" banner printed right after
|
||||
bootstrap succeeds. Include copy-now warning.
|
||||
- `install.ts`: on health-check timeout, read the tail of `LOG_FILE` and print
|
||||
the last ~30 non-empty lines before returning.
|
||||
- Keep `mosaic gateway config` as-is (view/edit env vars); this is not the
|
||||
setup wizard.
|
||||
- No new commands. No new flags yet.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Readline/stdin piping fragility (pre-existing, not related to user complaint).
|
||||
- Refactor to a phased state machine (overkill for three targeted fixes).
|
||||
|
||||
## Verification
|
||||
|
||||
- Typecheck, lint, format (mandatory gates).
|
||||
- Manual end-to-end: fresh install → confirm token displayed.
|
||||
- Manual resume: delete daemon.pid mid-install → re-run → confirm it resumes.
|
||||
- Manual failure: point ENV_FILE port to a used port → re-run → confirm log
|
||||
tail is printed.
|
||||
@@ -1,68 +0,0 @@
|
||||
# Gateway Security Hardening Scratchpad
|
||||
|
||||
## Metadata
|
||||
|
||||
- Date: 2026-03-13
|
||||
- Worktree: `/home/jwoltje/src/mosaic-mono-v1-worktrees/sec-remediation`
|
||||
- Branch: `fix/gateway-security`
|
||||
- Scope: Finish 7 requested gateway security fixes without switching branches or worktrees
|
||||
- Related tracker: worker task only; `docs/TASKS.md` is orchestrator-owned and left unchanged
|
||||
- Budget assumption: no explicit token cap; keep scope limited to requested gateway/auth/validation hardening
|
||||
|
||||
## Objective
|
||||
|
||||
Complete the remaining gateway security hardening work:
|
||||
|
||||
1. Chat HTTP auth guard enforcement
|
||||
2. Chat WebSocket session validation
|
||||
3. Ownership checks on by-id CRUD routes
|
||||
4. Global validation pipe and DTO enforcement
|
||||
5. Rate limiting
|
||||
6. Helmet security headers
|
||||
7. Body limit and env validation
|
||||
|
||||
## Plan
|
||||
|
||||
1. Reconcile current worktree state against requested fixes.
|
||||
2. Patch or extend tests first for DTO/auth behavior mismatches.
|
||||
3. Implement minimal code changes to satisfy tests and requested behavior.
|
||||
4. Run targeted gateway tests.
|
||||
5. Run baseline gates: `pnpm typecheck`, `pnpm lint`.
|
||||
6. Perform manual code review and record findings.
|
||||
7. Commit, push branch, open PR, send OpenClaw event, remove worktree.
|
||||
|
||||
## Progress Log
|
||||
|
||||
### 2026-03-13T00:00 local
|
||||
|
||||
- Loaded required Mosaic/global/runtime instructions and applicable skills.
|
||||
- Confirmed active worktree is `sec-remediation` and branch is already dirty with prior session changes.
|
||||
- Identified remaining gaps: DTO validation mismatch and non-requested socket auth helper typing/behavior drift.
|
||||
|
||||
## TDD Notes
|
||||
|
||||
- Required: yes. This is security/auth/permission logic.
|
||||
- Approach: update targeted unit tests first, verify failure, then patch code minimally.
|
||||
|
||||
## Verification Log
|
||||
|
||||
- `pnpm --filter @mosaicstack/gateway test -- src/chat/__tests__/chat-security.test.ts src/__tests__/resource-ownership.test.ts`
|
||||
- Red: failed on socket session reshaping and DTO role/length mismatches.
|
||||
- Green: passed with 3 test files and 20 tests passing.
|
||||
- `pnpm typecheck`
|
||||
- Pass on 2026-03-13 with 18/18 package typecheck tasks successful.
|
||||
- `pnpm lint`
|
||||
- Pass on 2026-03-13 with 18/18 package lint tasks successful.
|
||||
- `pnpm format:check`
|
||||
- Pass on 2026-03-13 with `All matched files use Prettier code style!`
|
||||
|
||||
## Review Log
|
||||
|
||||
- Manual review completed against auth, authorization, validation, and runtime hardening requirements.
|
||||
- No blocker findings remained after remediation.
|
||||
|
||||
## Risks / Blockers
|
||||
|
||||
- Repository instructions conflict on PR merge behavior; user explicitly instructed PR-only, no merge. Follow user instruction.
|
||||
- Existing worktree contains prior-session modifications; do not revert unrelated changes.
|
||||
- `missions` and `tasks` currently depend on project ownership because the schema does not carry a direct user owner column.
|
||||
@@ -1,33 +0,0 @@
|
||||
# Git Wrapper Rollup — 2026-05-26
|
||||
|
||||
## Objective
|
||||
|
||||
Consolidate pending Mosaic wrapper fixes after `mosaic update` reported the local framework package was already current (`@mosaicstack/mosaic 0.0.30`) but the installed `~/.config/mosaic/tools` wrappers still lacked the open Gitea/Woodpecker wrapper patches.
|
||||
|
||||
## Scope
|
||||
|
||||
Roll up the open wrapper-related Gitea PR branches into one integration branch:
|
||||
|
||||
- PR #513: `pr-ci-wait.sh` stdin collision fix.
|
||||
- PR #518: Gitea PR metadata/merge preflight hardening.
|
||||
- PR #521: Gitea merge fallback + unsafe PR-number rejection.
|
||||
- PR #522: Woodpecker credential/pagination fixes and CI Postgres service collision fix.
|
||||
- PR #523: explicit Gitea repo/login args and `eval` removal for PR/issue creation.
|
||||
|
||||
## Conflict resolutions
|
||||
|
||||
- Kept array-based command construction where possible instead of reintroducing `eval`.
|
||||
- Kept explicit `--repo OWNER/REPO --login mosaicstack` Gitea arguments for `tea` calls.
|
||||
- Combined PR merge API fallback behavior from metadata hardening and empty-identity fallback branches.
|
||||
- Preserved numeric PR-number validation for `pr-merge.sh`.
|
||||
|
||||
## Verification checklist
|
||||
|
||||
- `bash -n` on changed shell scripts.
|
||||
- Wrapper smoke checks from a clean worktree.
|
||||
- Gitea PR verification after push.
|
||||
- CI status checked through Gitea/Woodpecker.
|
||||
|
||||
## Notes
|
||||
|
||||
`mosaic update` did not install these fixes because the package registry still reports `@mosaicstack/mosaic 0.0.30` as current. The source patches must merge/release before normal framework update will carry them.
|
||||
@@ -1,66 +0,0 @@
|
||||
# H1 — heartbeat readiness detection
|
||||
|
||||
## Objective
|
||||
|
||||
Add runtime-agnostic readiness classification to `mosaic fleet ps` so an agent can be reported as working/idle/stuck/stale/dead/unknown instead of treating pane liveness as progress.
|
||||
|
||||
## Scope
|
||||
|
||||
- `packages/mosaic/src/commands/fleet.ts`
|
||||
- exported readiness state/types/default thresholds/helpers/classifier
|
||||
- `AgentPsRow.readiness` additive JSON field
|
||||
- table HB column and IDLE/STUCK flags
|
||||
- `packages/mosaic/src/commands/fleet.spec.ts`
|
||||
- pure classifier branch/boundary coverage
|
||||
- threshold helper coverage
|
||||
- legitimate render/JSON assertion updates for new HB text
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Branches covered: dead, unknown, stale, busy working, null-idle working, stuck boundary, idle boundary, working below idle.
|
||||
- Threshold env helpers default to 300s/900s and honor positive integer env values.
|
||||
- `fleet ps` rows populate `readiness` for roster and unmanaged socket sessions.
|
||||
- Table HB text becomes `<age>s/<readiness>` when heartbeat age exists; remains `unknown` when absent.
|
||||
- Flags include `IDLE`/`STUCK` for matching readiness.
|
||||
- Local gates green: `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, fleet vitest.
|
||||
- Pre-push queue guard passes; PR opened off `origin/main`; no merge by worker.
|
||||
|
||||
## Constraints / Assumptions
|
||||
|
||||
- Source branch: `origin/main` @ `e3adc6a`.
|
||||
- No scope creep beyond readiness detection.
|
||||
- `docs/TASKS.md` and `docs/fleet/TASKS.md` are orchestrator-owned; worker will not modify them.
|
||||
- PRD alignment source: `docs/fleet/PRD.md` Phase 2 observability; this is a refinement of heartbeat observability, preserving existing unknown/stale behavior.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Install dependencies with requested PNPM environment.
|
||||
2. Add readiness types/helpers/classifier near heartbeat constants.
|
||||
3. Add `readiness` to `AgentPsRow` and populate both row paths.
|
||||
4. Update table render and flags.
|
||||
5. Add unit tests and update affected ps render/JSON assertions.
|
||||
6. Run build precheck + required gates.
|
||||
7. Run automated independent review, remediate findings.
|
||||
8. Queue guard, push, open PR.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-06-24: Branch created from `origin/main` @ `e3adc6a`.
|
||||
- 2026-06-24: Implemented readiness thresholds/classifier, JSON row field, HB column label, and IDLE/STUCK flags.
|
||||
- 2026-06-24: Added classifier branch/boundary tests, threshold helper tests, JSON shape assertions, and readiness table rendering assertions.
|
||||
|
||||
## Verification Evidence
|
||||
|
||||
- `pnpm install --store-dir "$HOME/.pnpm-store"` — pass.
|
||||
- `npx turbo build --filter=@mosaicstack/mosaic^...` — pass, 12/12 tasks successful.
|
||||
- `pnpm typecheck` — pass, 41/41 tasks successful.
|
||||
- `pnpm lint` — pass, 23/23 tasks successful.
|
||||
- `pnpm format:check` — pass, all matched files use Prettier style.
|
||||
- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts` — pass, 171 tests.
|
||||
- `pnpm --filter @mosaicstack/mosaic test` — pass, 39 files / 547 tests; `fleet.spec.ts` 171 tests.
|
||||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — approve, 0 findings (reviewed supplied diff; sandbox file-inspection limitation noted by tool).
|
||||
|
||||
## Risks / Blockers
|
||||
|
||||
- No current blocker.
|
||||
- Review tool could not inspect repo files directly due sandbox wrapper limitation, but it reviewed the supplied diff and approved with no findings.
|
||||
@@ -1,53 +0,0 @@
|
||||
# H1b — tmux pane idle signal wiring
|
||||
|
||||
## Objective
|
||||
|
||||
Feed `classifyReadiness()` a real idle signal on tmux 3.4 by deriving `idleSeconds` from the first available tmux timestamp source: pane activity, then window activity, then session activity.
|
||||
|
||||
## Scope
|
||||
|
||||
- `packages/mosaic/src/commands/fleet.ts`
|
||||
- Extend `buildTmuxListPanesCommand()` format to include `#{window_activity}` and `#{session_activity}` after the existing fields.
|
||||
- Update `parseTmuxListPanes()` to choose the first non-empty finite positive timestamp and clamp future idle values to 0.
|
||||
- `packages/mosaic/src/commands/fleet.spec.ts`
|
||||
- Cover pane/window/session activity parsing behavior, empty-field index alignment, null idle, future clamping, math correctness, and exact tmux format.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- No changes to `classifyReadiness()`, thresholds, `AgentPsRow`, or `fleet ps` rendering.
|
||||
- No merge by worker; orchestrator routes review/merge.
|
||||
- Workers do not modify `docs/TASKS.md`.
|
||||
|
||||
## PRD Alignment
|
||||
|
||||
Aligned with `docs/fleet/PRD.md` FR-1 and acceptance criteria for truthful `mosaic fleet ps` pane/pid/idle observability.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Sync branch from latest `origin/main` and install dependencies with required pnpm env.
|
||||
2. Add/confirm reproducer tests for tmux 3.4 empty `pane_activity` and new fallback behavior.
|
||||
3. Implement the focused parser/format change only.
|
||||
4. Run required build, baseline gates, fleet vitest, and independent review.
|
||||
5. Run pre-push queue guard, push branch, and open PR to `main` with Mosaic wrapper.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-06-24: Branch `fix/fleet-pane-idle-activity` created from `origin/main` @ `ec8dd7c` after fetching.
|
||||
- 2026-06-24: Session-start generated local `.mosaic/orchestrator/*` changes on the previous release branch; stashed as `coder1 session-start state before H1b` to keep this branch clean.
|
||||
- 2026-06-24: Added TDD coverage for the tmux 3.4 production case (`pane_activity` empty, `window_activity` populated), exact new list-panes format, null/future/multiple-source behavior.
|
||||
- 2026-06-24: Implemented parser fallback without changing readiness classifier thresholds or render shape.
|
||||
|
||||
## Verification Evidence
|
||||
|
||||
- `pnpm install --store-dir "$HOME/.pnpm-store"` — pass.
|
||||
- Reproducer before implementation: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts` — failed as expected (old format, no fallback, negative future idle).
|
||||
- `npx turbo build --filter=@mosaicstack/mosaic^...` — pass, 12/12 tasks successful.
|
||||
- `pnpm typecheck` — pass, 41/41 tasks successful.
|
||||
- `pnpm lint` — pass, 23/23 tasks successful.
|
||||
- `pnpm format:check` — pass, all matched files use Prettier style.
|
||||
- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts` — pass, 176 tests.
|
||||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — approve, 0 findings (reviewed supplied diff; sandbox file-inspection limitation noted by tool).
|
||||
|
||||
## Risks / Blockers
|
||||
|
||||
- No current blocker.
|
||||
@@ -1,70 +0,0 @@
|
||||
# H2 — readiness semantics: available, not stuck
|
||||
|
||||
## Objective
|
||||
|
||||
Correct fleet readiness semantics so a healthy long-idle agent is reported as `available` (good/assignable) instead of `stuck` (fault). Reserve `stuck` in the type/JSON value space for future positive block evidence.
|
||||
|
||||
## Scope
|
||||
|
||||
- `packages/mosaic/src/commands/fleet.ts`
|
||||
- replace `idle` readiness state with `available`
|
||||
- keep `stuck` in the union but stop emitting it from idle-only heuristics
|
||||
- remove stuck threshold helper/env handling
|
||||
- remove IDLE/STUCK alarm flags from table rendering
|
||||
- `packages/mosaic/src/commands/fleet.spec.ts`
|
||||
- update classifier branch/boundary tests
|
||||
- assert very long idle maps to `available`, not `stuck`
|
||||
- update table/JSON assertions for available with no alarm flags
|
||||
- remove stuck threshold helper tests
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `classifyReadiness()` remains pure/total/never-throw and maps:
|
||||
- dead/stale/unknown unchanged
|
||||
- busy/null/undefined/non-finite idle to `working`
|
||||
- idle >= activity threshold to `available`
|
||||
- idle < activity threshold to `working`
|
||||
- No idle-derived path emits `stuck`.
|
||||
- `MOSAIC_HEARTBEAT_IDLE_THRESHOLD` remains backward compatible as the working→available activity threshold.
|
||||
- `MOSAIC_HEARTBEAT_STUCK_THRESHOLD` and helper/default are removed.
|
||||
- `fleet ps` keeps the idle-seconds column header `IDLE`, renders `available` in HB label, and does not add IDLE/STUCK warning flags.
|
||||
- Local gates green: build precheck, typecheck, lint, format:check, fleet vitest.
|
||||
- PR opened against `main`; no merge by worker.
|
||||
|
||||
## Constraints / Assumptions
|
||||
|
||||
- Source branch: `origin/main` @ `1020cfa`.
|
||||
- `docs/TASKS.md` is orchestrator-owned; worker will not modify it.
|
||||
- Documentation impact is captured in this scratchpad and PR description; no user/admin guide behavior beyond CLI readiness label semantics.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Install dependencies with requested PNPM environment.
|
||||
2. Inspect current H1/H1b readiness implementation and tests.
|
||||
3. Update classifier types/helpers/rendering.
|
||||
4. Update focused tests.
|
||||
5. Run build precheck + required gates.
|
||||
6. Run automated code review, remediate any findings.
|
||||
7. Queue guard, push, open PR.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-06-24: Branch created from `origin/main` @ `1020cfa`.
|
||||
- 2026-06-24: Replaced idle-derived `idle`/`stuck` outputs with `available`; retained `stuck` in type union for future positive block evidence.
|
||||
- 2026-06-24: Removed stuck threshold env/helper plumbing and IDLE/STUCK alarm flags.
|
||||
- 2026-06-24: Updated classifier and table-render tests for available semantics.
|
||||
|
||||
## Verification Evidence
|
||||
|
||||
- `pnpm install --store-dir "$HOME/.pnpm-store"` — pass.
|
||||
- `npx turbo build --filter=@mosaicstack/mosaic^...` — pass, 12/12 tasks successful.
|
||||
- `pnpm typecheck` — pass, 41/41 tasks successful.
|
||||
- `pnpm lint` — pass, 23/23 tasks successful.
|
||||
- `pnpm format:check` — pass, all matched files use Prettier style.
|
||||
- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts` — pass, 177 tests.
|
||||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — approve, 0 findings (reviewed supplied diff; sandbox file-inspection limitation noted by tool).
|
||||
|
||||
## Risks / Blockers
|
||||
|
||||
- No current blocker.
|
||||
- Review tool could not inspect repo files directly due sandbox wrapper limitation, but it reviewed the supplied diff and approved with no findings.
|
||||
@@ -1,60 +0,0 @@
|
||||
# Mission Scratchpad — Harness Foundation
|
||||
|
||||
> Append-only log. NEVER delete entries. NEVER overwrite sections.
|
||||
> This is the orchestrator's working memory across sessions.
|
||||
|
||||
## Original Mission Prompt
|
||||
|
||||
```
|
||||
Jason wants to get the gateway and TUI working as a real daily-driver harness.
|
||||
The system needs: multi-provider LLM access, task-aware agent routing, conversation persistence,
|
||||
security isolation, session hardening, job queue foundation, and channel protocol design for
|
||||
future Matrix/remote integration.
|
||||
|
||||
Provider decisions: Anthropic (Sonnet 4.6, Opus 4.6), OpenAI (Codex gpt-5.4), Z.ai (GLM-5),
|
||||
OpenRouter, Ollama. Embeddings via Ollama local models.
|
||||
|
||||
Pi SDK stays as agent runtime. Build with Matrix integration in mind but foundation first.
|
||||
Agent routing per task with granular specification is required.
|
||||
```
|
||||
|
||||
## Planning Decisions
|
||||
|
||||
### 2026-03-21 — Phase 9 PRD and mission setup
|
||||
|
||||
- PRD created as `docs/PRD-Harness_Foundation.md` with canonical Mosaic template format
|
||||
- 7 milestones, 71 tasks total
|
||||
- Milestone order: M1 (persistence) → M2 (security) → M3 (providers) → M4 (routing) → M5 (sessions) → M6 (jobs) → M7 (channel design)
|
||||
- M1 and M2 are hard prerequisites — no provider or routing work until conversations persist and data is user-scoped
|
||||
- Pi SDK kept as agent runtime; providers plug in via adapter pattern underneath
|
||||
- Embeddings migrated from OpenAI to Ollama local (nomic-embed-text or mxbai-embed-large)
|
||||
- BullMQ chosen for job queue (Valkey-compatible, TypeScript-native)
|
||||
- Channel protocol is design-only in this phase; Matrix implementation deferred to Phase 10
|
||||
- Models confirmed: Claude Sonnet 4.6, Opus 4.6, Haiku 4.5, Codex gpt-5.4, GLM-5, Ollama locals
|
||||
- Routing engine: rule-based classification first, LLM-assisted later
|
||||
- Default routing: coding-complex→Opus, coding-moderate→Sonnet, coding-simple→Codex, research→Codex, summarization→GLM-5, conversation→Sonnet, cheap/general→Haiku, offline→Ollama
|
||||
|
||||
### Architecture decisions
|
||||
|
||||
- Provider adapter pattern: each provider implements IProviderAdapter, registered in Pi SDK's provider registry
|
||||
- Routing flow: classify message → match rules by priority → check provider health → fallback chain → dispatch
|
||||
- Context window management: summarize older messages when history exceeds 80% of model context
|
||||
- OAuth pattern: URL-display + clipboard + Valkey poll token (same as P8-012 design)
|
||||
- Embedding dimension: migration from 1536 (OpenAI) to 768/1024 (Ollama) — may require re-embedding existing insights
|
||||
|
||||
## Session Log
|
||||
|
||||
| Session | Date | Milestone | Tasks Done | Outcome |
|
||||
| ------- | ---------- | --------- | -------------------------------- | ---------------------------------------------- |
|
||||
| 1 | 2026-03-21 | Planning | PRD, manifest, tasks, scratchpad | Mission initialized, planning gate in progress |
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. Z.ai GLM-5 API format — OpenAI-compatible or custom? (Research in M3-005)
|
||||
2. Which Ollama embedding model: nomic-embed-text (768-dim) vs mxbai-embed-large (1024-dim)? (Test in M3-009)
|
||||
3. Provider credentials: env vars for system defaults + DB for per-user overrides? (ASSUMPTION: hybrid)
|
||||
4. Pi SDK provider adapter support — needs verification in M3-001 before committing to adapter pattern
|
||||
|
||||
## Corrections
|
||||
|
||||
<!-- Record any corrections to earlier decisions or assumptions. -->
|
||||
@@ -1,330 +0,0 @@
|
||||
# Install UX Hardening — IUH-M01 Session Notes
|
||||
|
||||
## Session: 2026-04-05 (agent-ad6b6696)
|
||||
|
||||
### Plan
|
||||
|
||||
**Manifest schema decision:**
|
||||
|
||||
- Version 1 JSON at `~/.config/mosaic/.install-manifest.json` (mode 0600)
|
||||
- Written by `tools/install.sh` after successful install
|
||||
- Fields: version, installedAt, cliVersion, frameworkVersion, mutations{directories, npmGlobalPackages, npmrcLines, shellProfileEdits, runtimeAssetCopies}
|
||||
- Uninstall reads it; if missing → heuristic mode (warn user)
|
||||
|
||||
**File list:**
|
||||
|
||||
- NEW: `packages/mosaic/src/runtime/install-manifest.ts` — read/write helpers + types
|
||||
- NEW: `packages/mosaic/src/runtime/install-manifest.spec.ts` — unit tests
|
||||
- NEW: `packages/mosaic/src/commands/uninstall.ts` — command implementation
|
||||
- NEW: `packages/mosaic/src/commands/uninstall.spec.ts` — unit tests
|
||||
- MOD: `packages/mosaic/src/cli.ts` — register `uninstall` command
|
||||
- MOD: `tools/install.sh` — write manifest on success + add `--uninstall` path
|
||||
|
||||
**Runtime asset list (from mosaic-link-runtime-assets / framework/install.sh):**
|
||||
|
||||
- `~/.claude/CLAUDE.md` (source: `$MOSAIC_HOME/runtime/claude/CLAUDE.md`)
|
||||
- `~/.claude/settings.json` (source: `$MOSAIC_HOME/runtime/claude/settings.json`)
|
||||
- `~/.claude/hooks-config.json` (source: `$MOSAIC_HOME/runtime/claude/hooks-config.json`)
|
||||
- `~/.claude/context7-integration.md` (source: `$MOSAIC_HOME/runtime/claude/context7-integration.md`)
|
||||
- `~/.config/opencode/AGENTS.md` (source: `$MOSAIC_HOME/runtime/opencode/AGENTS.md`)
|
||||
- `~/.codex/instructions.md` (source: `$MOSAIC_HOME/runtime/codex/instructions.md`)
|
||||
|
||||
**Reversal logic:**
|
||||
|
||||
1. If `.mosaic-bak-<stamp>` exists for a file → restore it
|
||||
2. Else if managed copy exists → remove it
|
||||
3. Never touch files not in the known list
|
||||
|
||||
**npmrc reversal:**
|
||||
|
||||
- Only remove line `@mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/`
|
||||
- If manifest has the line, use that as authoritative; else check heuristically
|
||||
|
||||
**PATH reversal:**
|
||||
|
||||
- Check install.sh: it does NOT add PATH entries to shell profiles (framework/install.sh migration removes old `$MOSAIC_HOME/bin` PATH entries in v0/v1→v2 migration, but new install does NOT add PATH)
|
||||
- ASSUMPTION: No PATH edits in current install (v0.0.24+). Shell profiles not modified by current install.
|
||||
- The `$PREFIX/bin` is mentioned in a warning but NOT added to shell profiles by install.sh.
|
||||
- shellProfileEdits array will be empty for new installs; heuristic mode also skips it.
|
||||
|
||||
**Test strategy:**
|
||||
|
||||
- Unit test manifest read/write with temp dir mocking
|
||||
- Unit test command registration
|
||||
- Unit test dry-run flag (no actual fs mutations)
|
||||
- Unit test --keep-data skips protected paths
|
||||
- Unit test heuristic mode warning
|
||||
|
||||
**Implementation order:**
|
||||
|
||||
1. install-manifest.ts helpers
|
||||
2. install-manifest.spec.ts tests
|
||||
3. uninstall.ts command
|
||||
4. uninstall.spec.ts tests
|
||||
5. cli.ts registration
|
||||
6. tools/install.sh manifest writing + --uninstall path
|
||||
|
||||
ASSUMPTION: No PATH modifications in current install.sh (v0.0.24). Framework v0/v1→v2 migration cleaned old PATH entries but current install does not add new ones.
|
||||
ASSUMPTION: `--uninstall` in install.sh handles framework + cli + npmrc only; gateway teardown deferred to `mosaic gateway uninstall`.
|
||||
ASSUMPTION: Pi settings.json edits (skills paths) added by framework/install.sh are NOT reversed in this iteration — too risky to touch user Pi config without manifest evidence. Noted as follow-up.
|
||||
|
||||
---
|
||||
|
||||
## Session 2 — 2026-04-05 (orchestrator resume)
|
||||
|
||||
### IUH-M01 completion summary
|
||||
|
||||
- **PR:** #429 merged as `25cada77`
|
||||
- **CI:** green (Woodpecker)
|
||||
- **Issue:** #425 closed
|
||||
- **Files:** +1205 lines across 4 new + 2 modified + 1 docs
|
||||
- **Tests:** 14 new, 170 total passing
|
||||
|
||||
### Follow-ups captured from worker report
|
||||
|
||||
1. **Pi settings.json reversal deferred** — worker flagged as too risky without manifest evidence. Future IUH task should add manifest entries for Pi settings mutations. Not blocking M02/M03.
|
||||
2. **Pre-existing `cli-smoke.spec.ts` failure** — `@mosaicstack/brain` package entry resolution fails in Vitest. Unrelated to IUH-M01. Worth a separate issue later.
|
||||
3. **`pr-create.sh` wrapper bug with multiline bodies** — wrapper evals body args as shell when they contain newlines/paths. Worker fell back to Gitea REST API. Same class of bug I hit earlier with `issue-create.sh`. Worth a tooling-team issue to fix both wrappers.
|
||||
|
||||
### Mission doc sync
|
||||
|
||||
cli-unification docs that were archived before the M01 subagent ran did not travel into the M01 PR (they were local, stashed before pull). Re-applying now:
|
||||
|
||||
- `docs/archive/missions/cli-unification-20260404/` (the old manifest + tasks)
|
||||
- `docs/MISSION-MANIFEST.md` (new install-ux-hardening content)
|
||||
- `docs/TASKS.md` (new install-ux-hardening content)
|
||||
|
||||
Committing as `docs: scaffold install-ux-hardening mission + archive cli-unification`.
|
||||
|
||||
### Next action
|
||||
|
||||
Delegate IUH-M02 to a sonnet subagent in an isolated worktree.
|
||||
|
||||
---
|
||||
|
||||
## Session 3: 2026-04-05 (agent-a6ff34a5) — IUH-M02 Wizard Remediation
|
||||
|
||||
### Plan
|
||||
|
||||
**AC-3: Password masking + confirmation**
|
||||
|
||||
- New `packages/mosaic/src/prompter/masked-prompt.ts` — raw-mode stdin reader that suppresses echo, handles backspace/Ctrl+C/Enter.
|
||||
- `bootstrapFirstUser` in `packages/mosaic/src/commands/gateway/install.ts`: replace `rl.question('Admin password...')` with `promptMaskedPassword()`, require confirm pass, keep min-8 validation.
|
||||
- Headless path: when `MOSAIC_ASSUME_YES=1` or `!process.stdin.isTTY`, read `MOSAIC_ADMIN_PASSWORD` env var directly.
|
||||
|
||||
**AC-4a: Hooks preview stage**
|
||||
|
||||
- New `packages/mosaic/src/stages/hooks-preview.ts` — reads `hooks-config.json` from `state.sourceDir` or `state.mosaicHome`, displays each top-level hook category with name/trigger/command preview, prompts "Install these hooks? [Y/n]", stores result in `state.hooks`.
|
||||
- `packages/mosaic/src/types.ts` — add `hooks?: { accepted: boolean; acceptedAt?: string }` to `WizardState`.
|
||||
- `packages/mosaic/src/wizard.ts` — insert `hooksPreviewStage` between `runtimeSetupStage` and `skillsSelectStage`; skip if no claude runtime detected.
|
||||
|
||||
**AC-4b: `mosaic config hooks` subcommands**
|
||||
|
||||
- Add `hooks` subcommand group to `packages/mosaic/src/commands/config.ts`:
|
||||
- `list`: reads `~/.claude/hooks-config.json`, shows hook names and enabled/disabled status
|
||||
- `disable <name>`: prefixes matching hook key with `_disabled_` in the JSON
|
||||
- `enable <name>`: removes `_disabled_` prefix if present
|
||||
|
||||
**AC-5: Headless install path**
|
||||
|
||||
- `runConfigWizard`: detect headless mode (`MOSAIC_ASSUME_YES=1` or `!process.stdin.isTTY`), read env vars with defaults, validate required vars, skip prompts entirely.
|
||||
- `bootstrapFirstUser`: detect headless mode, read `MOSAIC_ADMIN_NAME/EMAIL/PASSWORD`, validate, proceed without prompts.
|
||||
- Document env vars in `packages/mosaic/README.md` (create if absent).
|
||||
|
||||
### File list
|
||||
|
||||
NEW:
|
||||
|
||||
- `packages/mosaic/src/prompter/masked-prompt.ts`
|
||||
- `packages/mosaic/src/prompter/masked-prompt.spec.ts`
|
||||
- `packages/mosaic/src/stages/hooks-preview.ts`
|
||||
- `packages/mosaic/src/stages/hooks-preview.spec.ts`
|
||||
|
||||
MODIFIED:
|
||||
|
||||
- `packages/mosaic/src/types.ts` — extend WizardState
|
||||
- `packages/mosaic/src/wizard.ts` — wire hooksPreviewStage
|
||||
- `packages/mosaic/src/commands/gateway/install.ts` — masked password + headless path
|
||||
- `packages/mosaic/src/commands/config.ts` — add hooks subcommands
|
||||
- `packages/mosaic/src/commands/config.spec.ts` — extend tests
|
||||
- `packages/mosaic/README.md` — document env vars
|
||||
|
||||
### Assumptions
|
||||
|
||||
ASSUMPTION: `hooks-config.json` location is `<sourceDir>/framework/runtime/claude/hooks-config.json` during wizard (sourceDir is package root). Fall back to `<mosaicHome>/runtime/claude/hooks-config.json` for installed config.
|
||||
ASSUMPTION: The `hooks` subcommands under `config` operate on `~/.claude/hooks-config.json` (the installed copy), not the package source.
|
||||
ASSUMPTION: For the hooks preview stage, the "name" field displayed per hook entry is the top-level event key (e.g. "PostToolUse") plus the matcher from nested hooks array. This is the most user-readable representation given the hooks-config.json structure.
|
||||
ASSUMPTION: `config hooks list/enable/disable` use `CLAUDE_HOME` env or `~/.claude` as the target directory for hooks files.
|
||||
ASSUMPTION: The headless TTY detection (`!process.stdin.isTTY`) is sufficient; `MOSAIC_ASSUME_YES=1` is an explicit override for cases where stdin is a TTY but the user still wants non-interactive (e.g., scripted installs with piped terminal).
|
||||
|
||||
---
|
||||
|
||||
## Session 4 — 2026-04-05 (orchestrator resume) — IUH-M02 closed, delegating IUH-M03
|
||||
|
||||
### IUH-M02 completion summary
|
||||
|
||||
- **PR:** #431 merged as `cd8b1f66`
|
||||
- **CI:** green (Woodpecker)
|
||||
- **Issue:** #426 closed
|
||||
- **Acceptance criteria:** AC-3 (password mask), AC-4 (hooks visibility — consent recorded), AC-5 (headless path) all satisfied
|
||||
- **New files:** `prompter/masked-prompt.ts`, `stages/hooks-preview.ts` (+ specs)
|
||||
- **Modified:** `wizard.ts`, `types.ts` (`state.hooks`), `commands/gateway/install.ts`, `commands/config.ts`
|
||||
|
||||
### Follow-up captured from M02 agent
|
||||
|
||||
**Hooks consent is recorded but not enforced.** The `hooks-preview` stage sets `state.hooks.accepted` when the user confirms, but the finalize stage still unconditionally runs `mosaic-link-runtime-assets`, which copies `hooks-config.json` into `~/.claude/` regardless of consent. This is a soft gap — the user sees the prompt and can decline, but declining currently has no effect downstream.
|
||||
|
||||
Options for addressing:
|
||||
|
||||
- Fold into IUH-M03 (since M03 touches the finalize/install convergence path anyway)
|
||||
- Spin a separate small follow-up issue after M03 lands
|
||||
|
||||
Leaning toward folding into M03 — the unified first-run flow naturally reworks the finalize→gateway handoff where this gating belongs.
|
||||
|
||||
### IUH-M03 delegation
|
||||
|
||||
Now delegating to an **opus** subagent in an isolated worktree. Scope from `/tmp/iuh-m03-body.md`:
|
||||
|
||||
- Extract `runConfigWizard` → `stages/gateway-config.ts`
|
||||
- Extract `bootstrapFirstUser` → `stages/gateway-bootstrap.ts`
|
||||
- `runWizard` invokes gateway stages as final stages
|
||||
- Drop the 10-minute `$XDG_RUNTIME_DIR/mosaic-install-state.json` session bridge
|
||||
- `mosaic gateway install` becomes a thin standalone wrapper for backward-compat
|
||||
- `tools/install.sh` single auto-launch entry point
|
||||
- **Bonus if scoped:** honor `state.hooks.accepted` in finalize stage so declining hooks actually skips hook install
|
||||
|
||||
Known tooling caveats to pass to worker:
|
||||
|
||||
- `issue-create.sh` / `pr-create.sh` wrappers eval multiline bodies as shell — use Gitea REST API fallback with `load_credentials gitea-mosaicstack`
|
||||
- Protected `main`: PR-only, squash merge
|
||||
- Must run `ci-queue-wait.sh --purpose push|merge` before push/merge
|
||||
|
||||
---
|
||||
|
||||
## Session 5: 2026-04-05 (agent-a7875fbd) — IUH-M03 Unified First-Run
|
||||
|
||||
### Problem recap
|
||||
|
||||
`mosaic wizard` and `mosaic gateway install` currently run as two separate phases bridged by a fragile 10-minute session file at `$XDG_RUNTIME_DIR/mosaic-install-state.json`. `tools/install.sh` auto-launches both sequentially so the user perceives two wizards stitched together; state is not shared, prompts are duplicated, and if the user walks away the bridge expires.
|
||||
|
||||
### Design decision — Option A: gateway install becomes terminal stages of `runWizard`
|
||||
|
||||
Two options on the table:
|
||||
|
||||
- (A) Extract `runConfigWizard` and `bootstrapFirstUser` into `stages/gateway-config.ts` and `stages/gateway-bootstrap.ts`, append them to `runWizard` as final stages, and make `mosaic gateway install` a thin wrapper that runs the same stages with an ephemeral state seeded from existing config.
|
||||
- (B) Introduce a new top-level orchestrator that composes the wizard and gateway install as siblings.
|
||||
|
||||
**Chosen: Option A.** Rationale:
|
||||
|
||||
1. The wizard already owns a `WizardState` that threads state across stages — gateway config/bootstrap fit naturally as additional stages without a new orchestration layer.
|
||||
2. `mosaic gateway install` as standalone entry point stays idempotent by seeding a minimal `WizardState` and running only the gateway stages, reusing the same functions.
|
||||
3. Avoids a parallel state object and keeps the call graph linear; easier to test and to reason about the "one cohesive flow" UX goal.
|
||||
4. Option B would leave `runWizard` and the gateway install as siblings that still need to share a state object — equivalent complexity without the narrative simplification.
|
||||
|
||||
### Scope
|
||||
|
||||
1. Extend `WizardState` with optional `gateway` slice: `{ tier, port, databaseUrl?, valkeyUrl?, anthropicKey?, corsOrigin, admin?: { name, email, password } }`. The admin password is held in memory only — never persisted to disk as part of the state object.
|
||||
2. New `packages/mosaic/src/stages/gateway-config.ts` — pure stage that:
|
||||
- Reads existing `.env`/`mosaic.config.json` if present (resume path) and sets state.
|
||||
- Otherwise prompts via `WizardPrompter` (interactive) or reads env vars (headless).
|
||||
- Writes `.env` and `mosaic.config.json`, starts the daemon, waits for health.
|
||||
3. New `packages/mosaic/src/stages/gateway-bootstrap.ts` — pure stage that:
|
||||
- Checks `/api/bootstrap/status`.
|
||||
- If needsSetup, prompts for admin name/email/password (uses `promptMaskedConfirmed`) or reads env vars (headless); calls `/api/bootstrap/setup`; persists token in meta.
|
||||
- If already setup, handles inline token recovery exactly as today.
|
||||
4. `packages/mosaic/src/wizard.ts` — append gateway-config and gateway-bootstrap as stages 11 and 12. Remove `writeInstallState` and the `INSTALL_STATE_FILE` constant entirely.
|
||||
5. `packages/mosaic/src/commands/gateway/install.ts` — becomes a thin wrapper that builds a minimal `WizardState` with a `ClackPrompter`, then calls `runGatewayConfigStage(...)` and `runGatewayBootstrapStage(...)` directly. Remove the session-file readers/writers. Headless detection is delegated to the stage itself. The wrapper still exposes the `runInstall({host, port, skipInstall})` API so `gateway.ts` command registration is unchanged.
|
||||
6. `tools/install.sh` — drop the second `mosaic gateway install` call; `mosaic wizard` now covers end-to-end. Leave `gateway install` guidance for non-auto-launch path so users still know the standalone entry point exists.
|
||||
7. **Hooks gating (bonus — folded in):** `finalize.ts` already runs `mosaic-link-runtime-assets`. When `state.hooks?.accepted === false`, set `MOSAIC_SKIP_CLAUDE_HOOKS=1` in the env for the subprocess; teach the script to skip copying `hooks-config.json` when that env var is set. Other runtime assets (CLAUDE.md, settings.json, context7) still get linked.
|
||||
|
||||
### Files
|
||||
|
||||
NEW:
|
||||
|
||||
- `packages/mosaic/src/stages/gateway-config.ts` (+ `.spec.ts`)
|
||||
- `packages/mosaic/src/stages/gateway-bootstrap.ts` (+ `.spec.ts`)
|
||||
|
||||
MODIFIED:
|
||||
|
||||
- `packages/mosaic/src/types.ts` — extend WizardState with `gateway?:` slice
|
||||
- `packages/mosaic/src/wizard.ts` — append gateway stages, remove session-file bridge
|
||||
- `packages/mosaic/src/commands/gateway/install.ts` — thin wrapper over stages, remove 10-min bridge
|
||||
- `packages/mosaic/src/stages/finalize.ts` — honor `state.hooks.accepted === false` by setting `MOSAIC_SKIP_CLAUDE_HOOKS=1`
|
||||
- `packages/mosaic/framework/tools/_scripts/mosaic-link-runtime-assets` — honor `MOSAIC_SKIP_CLAUDE_HOOKS=1`
|
||||
- `tools/install.sh` — single unified auto-launch
|
||||
|
||||
### Assumptions
|
||||
|
||||
ASSUMPTION: Gateway stages must run **after** `finalizeStage` because finalize writes identity files and links runtime assets that the gateway admin UX may later display — reversed ordering would leave Claude runtime linkage incomplete when the admin token banner prints.
|
||||
ASSUMPTION: Standalone `mosaic gateway install` uses a `ClackPrompter` (interactive) by default; the headless path is still triggered by `MOSAIC_ASSUME_YES=1` or non-TTY stdin, and the stage functions detect this internally.
|
||||
ASSUMPTION: When `runWizard` reaches the gateway stages, `state.mosaicHome` is authoritative for GATEWAY_HOME resolution if it differs from the default — we set `process.env.MOSAIC_GATEWAY_HOME` before importing gateway modules so the constants resolve correctly.
|
||||
ASSUMPTION: Keeping backwards compatibility for `runInstall({host, port, skipInstall})` is enough — no other internal caller exists.
|
||||
ASSUMPTION: Removing the session file is safe because the old bridge is at most a 10-minute window; there is no on-disk migration to do.
|
||||
|
||||
### Test plan
|
||||
|
||||
- `gateway-config.spec.ts`: fresh install writes .env + mosaic.config.json (mock fs + prompter); resume path reuses existing BETTER_AUTH_SECRET; headless path respects MOSAIC_STORAGE_TIER/MOSAIC_GATEWAY_PORT/etc.
|
||||
- `gateway-bootstrap.spec.ts`: calls `/api/bootstrap/setup` with collected creds (mock fetch); handles "already setup" branch; honors headless env vars; persists token via `writeMeta`.
|
||||
- Extend existing passing tests — no regressions in `login.spec`, `recover-token.spec`, `rotate-token.spec`.
|
||||
- Unified flow integration is covered at the stage-level; no new e2e test infra required.
|
||||
|
||||
### Delivery cycle
|
||||
|
||||
plan (this entry) → code → typecheck/lint/format → test → codex review (`~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted`) → remediate → commit → ci-queue-wait push → push → PR → CI green → merge → close #427.
|
||||
|
||||
### Remediation log (codex review rounds)
|
||||
|
||||
- **Round 1** — hooks opt-out did not remove an existing managed file; port override ignored on resume; headless errors swallowed. Fixed: hooks cleanup, `portOverride` honored, errors re-thrown.
|
||||
- **Round 2** — headless stage failures exited 0; port override on decline-rerun mismatched; no default-path integration test. Fixed: `process.exit(1)` in headless, revert portOverride on decline, add `unified-wizard.test.ts`.
|
||||
- **Round 3** — hooks removal too broad (would touch user-owned files); port override written to meta but not .env (drift); wizard swallowed errors. Fixed: `cmp -s` managed-file check, force regeneration when portOverride differs from saved port, re-throw unexpected errors.
|
||||
- **Round 4** — port-override regeneration tripped the corrupt-partial-state guard (blocker); headless already-bootstrapped-with-no-local-token path reported failure instead of no-op; hooks byte-equality fragile across template updates. Fixed: introduce `forcePortRegen` flag bypassing the guard (with a dedicated spec test), headless rerun of already-bootstrapped gateway now returns `{ completed: true }` (with spec coverage), hooks cleanup now checks for a stable `"mosaic-managed": true` marker embedded in the template (byte-equality remains as a fallback for legacy installs).
|
||||
- Round 5 codex review attempted but blocked by upstream usage limit (quota). Rerun after quota refresh if further findings appear; all round-4 findings are code-covered.
|
||||
|
||||
---
|
||||
|
||||
## Session 6 — 2026-04-05 (orchestrator close-out) — MISSION COMPLETE
|
||||
|
||||
### IUH-M03 completion summary (reported by opus delivery agent)
|
||||
|
||||
- **PR:** #433 merged as `732f8a49`
|
||||
- **CI:** Woodpecker green on final rebased commit `f3d5ef8d`
|
||||
- **Issue:** #427 closed with summary comment
|
||||
- **Tests:** 219 passing (+15 net new), 24 files
|
||||
- **Codex review:** 4 rounds applied and remediated; round 5 blocked by upstream quota — no known outstanding findings
|
||||
|
||||
### What shipped in M03
|
||||
|
||||
- NEW stages: `stages/gateway-config.ts`, `stages/gateway-bootstrap.ts` (extracted from the old monolithic `gateway/install.ts`)
|
||||
- NEW integration test: `__tests__/integration/unified-wizard.test.ts`
|
||||
- `runWizard` now has 12 stages — gateway config + bootstrap are terminal stages 11 & 12
|
||||
- 10-minute `$XDG_RUNTIME_DIR/mosaic-install-state.json` session-file bridge **deleted**
|
||||
- `mosaic gateway install` rewritten as a thin standalone wrapper invoking the same two stages — backward-compat preserved
|
||||
- `WizardState.gateway?` slice carries host/port/tier/admin/adminTokenIssued across stages
|
||||
- `tools/install.sh` single unified `mosaic wizard` call — no more two-phase launch
|
||||
- **Bonus scoped in:** finalize stage honors `state.hooks.accepted === false` via `MOSAIC_SKIP_CLAUDE_HOOKS=1`; `mosaic-link-runtime-assets` honors the flag; Mosaic-managed detection now uses a stable `"mosaic-managed": true` marker in `hooks-config.json` with byte-equality fallback for legacy installs. **Closes the M02 follow-up.**
|
||||
|
||||
### Mission status — ALL DONE
|
||||
|
||||
| AC | Status | PR |
|
||||
| ---- | ------ | ---------------------------------------------------- |
|
||||
| AC-1 | ✓ | #429 |
|
||||
| AC-2 | ✓ | #429 |
|
||||
| AC-3 | ✓ | #431 |
|
||||
| AC-4 | ✓ | #431 + #433 (gating) |
|
||||
| AC-5 | ✓ | #431 |
|
||||
| AC-6 | ✓ | #433 |
|
||||
| AC-7 | ✓ | #429, #431, #433 all merged, CI green, issues closed |
|
||||
|
||||
### Follow-ups for future work (not blocking mission close)
|
||||
|
||||
1. **`pr-ci-wait.sh` vs Woodpecker**: wrapper reports `state=unknown` because Woodpecker doesn't publish to Gitea's combined-status endpoint. Worker used `tea pr` CI glyphs as authoritative. Pre-existing tooling gap — worth a separate tooling-team issue.
|
||||
2. **`issue-create.sh` / `pr-create.sh` wrapper `eval` bug with multiline bodies** — hit by M01, M02, M03 workers. All fell back to Gitea REST API. Needs wrapper fix.
|
||||
3. **Codex review round 5** — attempted but blocked by upstream quota. Rerun after quota resets to confirm nothing else surfaces.
|
||||
4. **Pi settings.json reversal** — deferred from M01; install manifest schema should be extended to track Pi settings mutations for reversal.
|
||||
5. **`cli-smoke.spec.ts` pre-existing failure** — `@mosaicstack/brain` resolution in Vitest. Unrelated. Worth a separate issue.
|
||||
|
||||
### Next steps (orchestrator)
|
||||
|
||||
1. This scratchpad + MISSION-MANIFEST.md + TASKS.md updates → final docs PR
|
||||
2. After merge: create release tag per framework rule (milestone/mission completion = release tag + repository release)
|
||||
3. Archive mission docs under `docs/archive/missions/install-ux-hardening-20260405/` once the tag is published
|
||||
@@ -1,40 +0,0 @@
|
||||
# Installer `--next` fast npm lane — 2026-06-25
|
||||
|
||||
## Scope
|
||||
|
||||
Flip `tools/install.sh --next` from source-build-first to fast npm `@next` first, with source fallback.
|
||||
|
||||
## Registry reality check
|
||||
|
||||
Gitea npm registry: `https://git.mosaicstack.dev/api/packages/mosaicstack/npm/`
|
||||
|
||||
Verified before implementation:
|
||||
|
||||
- `@mosaicstack/mosaic@next` resolves to `0.0.49-next.1633`.
|
||||
- `@mosaicstack/gateway@next` resolves to `0.0.7-next.1633`.
|
||||
- `@mosaicstack/gateway` dist-tags include `latest: 0.0.6` and `next: 0.0.7-next.1633`.
|
||||
- `apps/gateway/package.json` is non-private and has Gitea npm `publishConfig`.
|
||||
|
||||
Conclusion: the installer can fast-install both CLI and gateway npm packages for `--next`. The gateway Docker `gateway:sha-<short>` remains the deployment/harness artifact; the npm gateway package is valid for the installer global package path.
|
||||
|
||||
## Behavior
|
||||
|
||||
- `--next` with no explicit ref:
|
||||
1. framework archive from `next`;
|
||||
2. resolve `@mosaicstack/gateway@next` and `@mosaicstack/mosaic@next`;
|
||||
3. require both resolved versions to share the same `next.<pipeline>` suffix;
|
||||
4. install the exact resolved package versions;
|
||||
5. set `MOSAIC_GATEWAY_SKIP_NPM_INSTALL=1` so wizard does not overwrite the prerelease gateway;
|
||||
6. if either package is missing/unreachable/mismatched/fails, fall back to existing source build at `next`.
|
||||
- `--dev` remains pure source build.
|
||||
- explicit `--ref` / `MOSAIC_REF` still wins over `--next` and uses the source path for that exact ref.
|
||||
|
||||
## Install detail
|
||||
|
||||
The installer writes the scoped npmrc mapping (`@mosaicstack:registry=...`) and then runs npm install without overriding npm's default registry. Passing `--registry=<gitea>` to `npm install` forces public transitive dependencies (for example `@anthropic-ai/sdk`) to resolve from Gitea and breaks the fast path; the scoped npmrc mapping is the correct split-registry behavior.
|
||||
|
||||
## Verification notes
|
||||
|
||||
- Added `tools/install-next-lane.test.sh` with a fake npm/source harness for exact-version fast install, registry failure source fallback, explicit-ref precedence, and mismatched suffix warning.
|
||||
- Wired the installer harness into `pnpm test` via `pnpm run test:installer`.
|
||||
- Real temp-prefix fast install succeeded with `@mosaicstack/[email protected]` and `@mosaicstack/[email protected]`.
|
||||
@@ -1,35 +0,0 @@
|
||||
# Scratchpad — installer `--next` lane
|
||||
|
||||
## Objective
|
||||
|
||||
Add a prerelease installer lane for the permanent `next` integration branch.
|
||||
|
||||
## Scope
|
||||
|
||||
- `tools/install.sh`
|
||||
- README/install documentation
|
||||
- Follow-up design note for future npm `@next` prerelease publishing
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add `--next` and `MOSAIC_NEXT=1` as source-build shorthand for `next`.
|
||||
2. Preserve explicit ref precedence: `MOSAIC_REF` and `--ref` win over `--next`.
|
||||
3. Update installer source display/help text.
|
||||
4. Document three lanes:
|
||||
- stable npm `@latest`
|
||||
- prerelease `--next`
|
||||
- contributor `--dev --ref X`
|
||||
5. Run shell and repo gates locally, then hold before push/PR until runner serialization greenlight.
|
||||
|
||||
## Verification
|
||||
|
||||
- `bash -n tools/install.sh` — pass.
|
||||
- `docker run --rm -v "$PWD:/mnt" -w /mnt koalaman/shellcheck:stable tools/install.sh` — pass.
|
||||
- `bash tools/install.sh --check --framework --next` — source display shows `ref: next, --next prerelease lane`.
|
||||
- `bash tools/install.sh --check --cli --next --ref feature-x` — source display shows explicit ref wins.
|
||||
- `MOSAIC_NEXT=1 MOSAIC_REF=feature-env bash tools/install.sh --check --cli` — source display shows explicit env ref wins.
|
||||
- `pnpm install --frozen-lockfile --prefer-offline --store-dir /home/jarvis/.local/share/pnpm/store` — pass (local override for repo `.npmrc` CI store path).
|
||||
- `pnpm typecheck` — pass (41 successful tasks).
|
||||
- `pnpm lint` — pass (23 successful tasks).
|
||||
- `pnpm format:check` — pass.
|
||||
- `bash tools/e2e-install-test.sh` — attempted; current baseline fails during gateway health after stable registry install because Valkey is unavailable in the clean container. The `tools/install.sh --yes --no-auto-launch` stage itself completed before the downstream gateway verification failure.
|
||||
@@ -1,80 +0,0 @@
|
||||
# Issue 766 — exact cross-harness fleet comms targeting
|
||||
|
||||
- **Issue:** #766
|
||||
- **Branch:** `fix/766-exact-fleet-comms`
|
||||
- **Worktree:** `/home/jarvis/src/stack-issue-766`
|
||||
- **Delivery boundary:** source/tests/docs only; no live tmux, session, or fleet actions; leave uncommitted for independent review.
|
||||
|
||||
## Objective
|
||||
|
||||
Replace inference-prone fleet onboarding guidance with one roster-resolved contract that gives Claude Code, Codex, OpenCode, and Pi the same authoritative local identity and exact executable command for every known peer.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add issue-specific normative requirements to `docs/PRD.md` before source changes; do not modify orchestrator-owned `docs/TASKS.md`.
|
||||
2. Extract the existing v1 roster parsing/normalization into one lightweight shared resolver used by both fleet commands and runtime comms composition.
|
||||
3. Write failing contract tests for explicit SSH-only cross-host targeting, global/default socket authority, authoritative identity, unknown-peer failure, no operational metavariables, and four-harness parity.
|
||||
4. Make source `TOOLS.md` non-operational and marker-versioned; prove fresh installation preserves that exact contract and composition detects a stale installed copy without rewriting it.
|
||||
5. Render a deterministic comms generation and document comparison/relaunch handling; never rewrite an active session.
|
||||
6. Run focused Vitest and shell exact-target tests, then package/repository typecheck, lint, format, test, and build gates as relevant.
|
||||
7. Reconstruct the exact uncommitted tree, including untracked files, for independent review and remediate findings without committing.
|
||||
|
||||
## Contract decisions
|
||||
|
||||
- `tmux.socket_name` is the one supported socket authority for every local fleet session. A per-agent `socket`, when present for compatibility, must equal that global value; independent per-agent sockets fail closed because the runtime does not provision them. A named socket renders `-L`, while the empty literal default renders no `-L`.
|
||||
- A peer is same-host only when its resolved host equals the current roster member's resolved host. Every host-omitted member resolves against the stable local fleet-host baseline, never against the viewer's explicit host. Same-host rows never render `-H`.
|
||||
- A cross-host row requires that peer's explicit roster `ssh`; absence is a contract error. Never substitute `host` as an SSH target.
|
||||
- The current member's explicit roster `host` wins; otherwise the local machine's short hostname is the baseline for host-omitted local members.
|
||||
- Unknown members/peers return a deterministic error listing exact known names and an exact self-scoped discovery command. No fuzzy session lookup.
|
||||
- Exact command fields are structurally constrained to safe targeting grammars and shell-rendered as individual arguments. Unsafe host/SSH/socket values fail roster normalization rather than entering executable guidance.
|
||||
- Existing installed `TOOLS.md` remains user-owned during ordinary keep-mode updates. Currency requires the expected source and installed marker/version plus bounded SHA-256 byte identity. Explicit `mosaic update --repair-tools` is the supported current-version recovery path: it makes a digest-qualified no-clobber backup, restores the contract and regular executable helper, and does not rewrite active context.
|
||||
- The v1 resolver preserves and validates `tmux`, `discord`, and `matrix` connector blocks in YAML and JSON; conflicting snake/camel aliases fail closed unless their values are identical.
|
||||
- JSON roster fallback occurs only when `roster.yaml` is absent. Keep-mode reseed preserves both formats, and relaunch discovery uses the same canonical resolver.
|
||||
- The helper is inspected without following symlinks and must be a regular executable file. Missing, directory, symlink, and non-executable installations fail closed with deterministic repair guidance.
|
||||
- Active contexts carry a deterministic comms generation. Operators compare it to `mosaic agent comms-block <exact-agent>` output; mismatch means stale and requires an explicit exact-agent relaunch.
|
||||
|
||||
## Risks
|
||||
|
||||
- Import cycles if runtime composition imports the command-heavy `fleet.ts`; mitigate with a lightweight shared roster module and re-export compatibility.
|
||||
- Existing schema prose allowed independent per-agent sockets even though runtime provisioning used one global socket; constrain compatibility declarations to the global value and preserve empty-global default behavior.
|
||||
- Remote inventory may be incomplete. Fail composition closed for an unreachable cross-host row rather than generating a guessed command.
|
||||
- `TOOLS.md` is user-seeded and intentionally preserved. Detect/report drift instead of overwriting custom content.
|
||||
|
||||
## Planned evidence
|
||||
|
||||
- `comms-onboarding.spec.ts`: resolver/renderer/failure/generation contracts.
|
||||
- `compose-contract.spec.ts`: identical authoritative comms section for all four harnesses and stale installed-contract reporting without mutation.
|
||||
- `file-adapter.test.ts`: source-to-fresh-install byte equality and preservation of customized installed `TOOLS.md`.
|
||||
- Existing `agent-send.test.sh`, socket isolation, and tmux runtime transport tests.
|
||||
- Repository quality gates and independent uncommitted-tree review.
|
||||
|
||||
## Evidence log
|
||||
|
||||
- Preflight collision scan: no issue-766 local/remote branch, worktree, or open PR collision before branch creation.
|
||||
- Isolated branch created from fetched `origin/main` at `4990905`; original checkout not edited.
|
||||
- One strict v1 resolver now serves fleet commands and communications composition; roster writes preserve `host`, `ssh`, and `socket`.
|
||||
- Exact renderer covers authoritative self identity, global/default socket authority, rejected independent sockets, stable hostless-peer resolution, same-host omission of `-H`, explicit-SSH-only cross-host rows, shell-safe argv rendering, deterministic generations, and fail-closed unknown/missing targets.
|
||||
- Real framework `defaults/TOOLS.md` is tested byte-equal through a fresh `FileConfigAdapter` install, the installed helper is executable, and the final Pi contract contains the same source contract plus exact generated command; separate parity coverage proves byte-equivalent comms sections for Claude Code, Codex, OpenCode, and Pi.
|
||||
- Second review remediation adds strict connector/alias coverage, full-semantic generation coverage, ENOENT-only fallback, no-follow helper validation, unconditional current-version repair, digest-qualified no-clobber backups, and marker/version-gated currency.
|
||||
- The helper, roster, installed TOOLS, and framework source files are read with canonical containment, every existing ancestor and target rejected if symlinked, `O_NOFOLLOW` descriptor reads, inode stability checks, and effective-identity execute access. Read-only TOOLS status treats source/installed symlinks as unavailable without following or rewriting them.
|
||||
- Explicit repair validates both bundled inputs before destination creation, stages backup/TOOLS/helper plus exact-mode rollback files before any persistent file commit, revalidates destination identity at each commit boundary, installs the digest backup without clobber, and removes or exactly rolls back every committed output on injected failure. `changed: false` is returned only after full cleanup; cleanup/rollback failure is reported as `changed: true`.
|
||||
- Connector schema and runtime normalization require kind-matching settings and reject inactive connector blocks. Keep-mode installers preserve only exact `roster.yaml`, `roster.json`, `agents/`, and `run/` paths while refreshing framework `roster.schema.json`; shell evidence covers byte preservation and schema refresh.
|
||||
- Solo contracts render normalized role/class plus explicit no-peer/no-remote authority boundaries; composed-contract evidence keeps role Mandate/Boundaries before Fleet Comms.
|
||||
- Operational documentation and CLI metavariable now use `mosaic agent comms-block <exact-member>`; historical issue-633 scratchpad text remains historical.
|
||||
- The latest independent review rejected synthetic tree `556ae4ea04f2715a4e9d381f3cafaf4c8b991b2e` on three mandatory findings: installed `TOOLS.md` could be read through target/ancestor symlinks before unsafe status was reported; ambient class/tool-policy state could split identity authority from the canonical roster member; and the connector schema admitted empty or whitespace-only Discord/Matrix strings rejected by runtime parsing.
|
||||
- Red-first reproduction proved all three findings with 20 failures and 79 passes. Remediation routes installed `TOOLS.md` through the bounded secure regular-file reader before composition, resolves one exact canonical fleet identity for persona/tool policy/normalized class/Fleet Comms, rejects canonicalized ambient class mismatches, canonicalizes compatibility classes during roster parsing, and aligns parser/schema non-whitespace requirements.
|
||||
- Four-runtime coverage proves unsafe target and ancestor symlink content is omitted without mutation, while Claude Code, Codex, OpenCode, and Pi all project the same canonical member authority. Connector parser/schema coverage includes empty and whitespace-only Discord `channel_id` and Matrix `homeserver_url`, `user_id`, and `room_id` values.
|
||||
- Remediated focused gates passed: 99/99 across the two finding-focused suites plus connector schema regression PASS; the six changed-suite matrix passed 341/341; secure-file/transaction coverage remains green, including 28/28 transactional repair tests; installer migration passed 21/21.
|
||||
- Mosaic package suite passed 906/906. Shell/runtime regressions passed: `agent-send.test.sh` `PASS=11 FAIL=0`; named-socket isolation; matrix/tmux transport 12/12 (Matrix 5/5, tmux 7/7).
|
||||
- Final repository gates passed: format check; typecheck 42/42 tasks; lint 23/23; tests 42/42 tasks (Mosaic 906/906, gateway 628 passed/12 skipped); build 23/23.
|
||||
- A subsequent immutable review of tree `aa6414123643a504145fce6ac1d66f0b535feb5e` found one roster-authority blocker: a canonical member with omitted `tool_policy` inherited ambient `MOSAIC_AGENT_TOOL_POLICY`. Red-first four-runtime coverage failed 4/39 specifically on the leaked operator-interaction policy. Composition now branches on canonical membership: fleet launches use only `canonicalMember.toolPolicy` (including canonical absence), while genuinely non-fleet launches retain ambient fallback.
|
||||
- Final remediated gates passed: four-runtime regression 39/39; six changed-suite matrix 345/345; connector schema regression PASS; Mosaic package 910/910; installer migration 21/21; `agent-send.test.sh` 11/11; named-socket isolation PASS; Matrix/tmux transport 12/12; repository format PASS; typecheck 42/42 tasks; lint 23/23 tasks; tests 42/42 tasks; build 23/23 tasks.
|
||||
- No live tmux/session/fleet mutation, commit, push, PR mutation, issue mutation, context mutation, or reviewer launch performed.
|
||||
- Exact synthetic-tree reconstruction and frozen evidence are included in the coordinator handoff.
|
||||
- Sole-remediation preflight reverified the clean committed checkout at head `0dc47cac92c93a3ffd39ba9dd6685ac4165f6361`, tree `538de6ccce1f8c44ba288a7493286e63a3413e75`, branch `fix/766-exact-fleet-comms`; issue and PR state were read only through Mosaic wrappers.
|
||||
- Deterministic red-first ancestor substitution swapped validated `root/tools` for an external symlink immediately after `lstat`; current head returned `external marker` (`1 failed, 4 passed`) before implementation.
|
||||
- Secure reads now hold `/` and every root/descendant directory descriptor, traverse appended components through Linux `/proc/self/fd` with `O_DIRECTORY|O_NOFOLLOW`, and read plus effective-identity execute-check the same final descriptor. Non-Linux or unavailable proc-fd capability fails closed; stable errors redact managed paths while retaining Node `code` compatibility for missing/non-executable repair behavior.
|
||||
- Added deterministic root-selection, descendant-ancestor, and final-target substitution coverage. All return trusted descriptor-bound bytes after rename/symlink replacement; the race suite passed 50/50 repeated runs.
|
||||
- Isolated CLI verification drove `mosaic agent --mosaic-home <fixture> comms-block self` while repeatedly swapping `fleet/` with an external symlink: `trusted=2 fail_closed=10 external_marker=0`; a persistent symlink ancestor exited 1 with a redacted unsafe-ancestor error. No live fleet state was used or mutated.
|
||||
- Remediation gates: focused secure-file/comms/launch/tmux/Matrix `110/110`; full `@mosaicstack/mosaic` `914/914`; package and repository typecheck pass (`42/42` repository tasks); package and repository lint pass (`23/23` repository tasks); repository format check and `git diff --check` pass.
|
||||
- Independent review found one production hardening blocker (nonblocking final open), one redacted-error blocker, and a deterministic ancestor-test gap. Remediation added `O_NONBLOCK`, normalized execute errors while preserving errno, proved the ancestor hook fires, and added final-target substitution coverage; post-remediation review evidence is clean on the production invariant.
|
||||
@@ -1,55 +0,0 @@
|
||||
# M3-001 Provider Adapter Pattern — Scratchpad
|
||||
|
||||
## Objective
|
||||
|
||||
Refactor ProviderService into an IProviderAdapter pattern without breaking existing Ollama flow.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add `IProviderAdapter` interface and supporting types to `@mosaicstack/types` provider package
|
||||
2. Create `apps/gateway/src/agent/adapters/` directory with:
|
||||
- `provider-adapter.interface.ts` — IProviderAdapter + ProviderHealth + CompletionParams + CompletionEvent
|
||||
- `ollama.adapter.ts` — extract existing Ollama logic
|
||||
3. Refactor ProviderService:
|
||||
- Accept `IProviderAdapter[]` (injected via DI token)
|
||||
- `registerAll()` / `listModels()` aggregates from all adapters
|
||||
- `getAdapter(name)` — lookup by name
|
||||
- `healthCheckAll()` — check all adapters
|
||||
- Keep Pi ModelRegistry wiring (required by AgentService)
|
||||
4. Wire up in AgentModule
|
||||
|
||||
## Key Findings
|
||||
|
||||
### Pi SDK Compatibility
|
||||
|
||||
- Pi SDK uses `ModelRegistry` as central registry; ProviderService wraps it
|
||||
- `ModelRegistry.registerProvider()` is the integration point — adapters call this
|
||||
- Pi doesn't have a native "IProviderAdapter" concept — adapters are a Mosaic abstraction on top
|
||||
- The `createAgentSession()` call in AgentService uses `modelRegistry: this.providerService.getRegistry()`
|
||||
- OllamaAdapter should call `registry.registerProvider('ollama', {...})` same as today
|
||||
- CompletionParams/CompletionEvent: Pi SDK streams via `AgentSession.prompt()`, not raw completion
|
||||
— IProviderAdapter.createCompletion() is for future direct use; for now stub or leave as interface-only
|
||||
— ASSUMPTION: createCompletion is reserved for future M3+ work; Pi SDK owns the actual streaming
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- ESM: use `.js` extensions in all imports
|
||||
- NestJS: use `@Inject()` explicitly
|
||||
- Keep RoutingService working — it only uses `providerService.listAvailableModels()`
|
||||
- Keep AgentService working — it uses `providerService.getRegistry()`, `findModel()`, `getDefaultModel()`, `listAvailableModels()`
|
||||
|
||||
## Progress
|
||||
|
||||
- [ ] Add types to @mosaicstack/types
|
||||
- [ ] Create adapters/ directory
|
||||
- [ ] Create IProviderAdapter interface file
|
||||
- [ ] Create OllamaAdapter
|
||||
- [ ] Refactor ProviderService
|
||||
- [ ] Update AgentModule
|
||||
- [ ] Run tests
|
||||
- [ ] Run quality gates
|
||||
|
||||
## Risks
|
||||
|
||||
- Pi SDK doesn't natively support IProviderAdapter — adapters are a layer on top
|
||||
- createCompletion() is architecturally sound but requires Pi session bypass (future work)
|
||||
@@ -1,16 +0,0 @@
|
||||
# Scratchpad: MACP OC Bridge (2026-03-30)
|
||||
|
||||
- Objective: Replace the OpenClaw MACP plugin's Pi-direct `runTurn` with the MACP controller queue bridge.
|
||||
- Scope: `plugins/macp/src/macp-runtime.ts`, `plugins/macp/src/index.ts`, `plugins/macp/openclaw.plugin.json`, `plugins/macp/README.md`.
|
||||
- Plan:
|
||||
1. Read controller/dispatcher/plugin docs and confirm queue/result contract.
|
||||
2. Queue tasks through `.mosaic/orchestrator/tasks.json` using a brief file and controller trigger.
|
||||
3. Poll result JSON, stream output back to ACP, then validate with typecheck/format checks.
|
||||
- Risks:
|
||||
- The repo orchestrator must be enabled in `.mosaic/orchestrator/config.json`.
|
||||
- Result JSON does not always embed worker output, so the runtime falls back to metadata-linked output files or a formatted result summary.
|
||||
- Verification:
|
||||
- `npx tsc --noEmit --target es2022 --module nodenext --moduleResolution nodenext --skipLibCheck plugins/macp/src/macp-runtime.ts plugins/macp/src/index.ts`
|
||||
- `pnpm prettier --write "plugins/macp/**/*.{ts,json,md}"`
|
||||
- `pnpm format:check`
|
||||
- `npx tsc --noEmit -p plugins/macp/tsconfig.json` still fails in this branch because `plugins/macp/tsconfig.json` extends a missing `packages/config/typescript/library.json` file and also pulls in pre-existing external OpenClaw type noise.
|
||||
@@ -1,38 +0,0 @@
|
||||
# ms-792 — Fleet roster error handling and installer heading
|
||||
|
||||
## Objective
|
||||
|
||||
Make expected missing or malformed fleet roster configuration fail with an actionable message and nonzero exit instead of a raw Node stack trace. Ensure the installer preserves the `@mosaicstack/mosaic` heading.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add failing coverage for missing and malformed roster input.
|
||||
2. Centralize roster-file read and parse error translation; add the CLI async error boundary.
|
||||
3. Sweep fleet command read paths that bypass the roster loader.
|
||||
4. Replace the installer heading output with format-safe rendering and test it.
|
||||
5. Run focused and repository quality checks; request independent review.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-07-16: Confirmed issue #792 and branch base `9745bc3f`.
|
||||
- 2026-07-16: Installed locked workspace dependencies using a worktree-local pnpm store; no `.mosaic/` files were changed intentionally.
|
||||
- 2026-07-16: Added a shared roster read/parse guard and routed v1 fleet commands plus v1/v2 selection through Commander’s actionable nonzero error path. V2 command modules already return structured nonzero JSON errors for their guarded reads.
|
||||
- 2026-07-16: Replaced installer heading `echo` with format-safe `printf`; added a regression check for the scoped package heading.
|
||||
- 2026-07-16: Rebuilt CLI and manually verified `fleet ps` with no roster prints the initialization hint, exits 1, and has no stack trace.
|
||||
- 2026-07-17: Rebased #818 onto `origin/main` at `9ddc6fbd` (#791 PR3). The added `fleet regen` command had a canonical roster read in its sibling module; it now uses the same missing-roster guard and Commander exit path. Internal NORTH_STAR, preset, and post-write invariant reads remain intentionally unguarded.
|
||||
- 2026-07-17: RoR found that semantically invalid v1 documents still escaped as plain `Error` values. `normalizeFleetRosterV1` now preserves each validation message while converting it to `FleetRosterConfigurationError`, so its command callers use the actionable nonzero Commander path.
|
||||
|
||||
## Verification
|
||||
|
||||
- `pnpm --filter @mosaicstack/mosaic test` — PASS (61 files, 1,046 tests; executed outside sandbox because CLI smoke tests spawn Node)
|
||||
- `pnpm typecheck` — PASS
|
||||
- `pnpm lint` — PASS
|
||||
- `pnpm format:check` — PASS
|
||||
- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts src/commands/install-heading.spec.ts` — PASS (209 tests)
|
||||
- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet-regen-command.spec.ts` — PASS (27 tests, including missing canonical roster)
|
||||
- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts -t "semantically invalid v1 roster"` — RED then PASS; verifies duplicate agent names are reported as `fleet.roster` exit 1 without a stack trace.
|
||||
- Instrumented Vitest coverage is unavailable because `@vitest/coverage-v8` is not declared in this repository. Each branch added in the roster guard has direct unit coverage.
|
||||
|
||||
## Risks / blockers
|
||||
|
||||
- Dependency installation is required before executing Vitest, TypeScript, lint, and formatting gates.
|
||||
@@ -1,19 +0,0 @@
|
||||
# north-star doctrine consolidation (#620-adjacent doc PR)
|
||||
|
||||
- **Branch:** `feat/north-star-doctrine` (off main). Source: Mos's consolidated handoff + 2 drafts (budgeting/200k/delegation + control-plane). ONE conflict-free PR per the merge-map.
|
||||
|
||||
## Applied (merge-map, in order)
|
||||
|
||||
1. Stack table: +2 rows (Central register, Budget/spend governance) after Control plane + PoC-socket-hygiene note.
|
||||
2. `## Budget & token governance` after Invariants (even-spread pacing [Jason override], hard-cap ladder, multi-sub auto-routing, historical learning, #558 CLI UX) + TTY OPS INVARIANT note.
|
||||
3. `## Control plane & central register` after Observation model (Postgres fleet schema, gateway-API access, dispatcher = forge pipeline engine + forge-exec adapter [NOT a daemon], register backs forge, board = forge BOD).
|
||||
4. Phased roadmap Phase 4/5 annotated (fleet schema migration + forge-exec; central register live).
|
||||
5. Decisions of record (2026-06-22): doctrine §1(c) bullets (200k cap, worker bound #8, delegation, budget, spend mandate, unified identity Fleet, role-based session naming) + control-plane 6c `### Control plane & central register` subgroup.
|
||||
6. Future enhancements: Matrix-future-transport (#10, F4 IS Matrix) + tmux security hardening (§5).
|
||||
7. Assumptions: doctrine §1(d) (3) + control-plane 6e (1) + release-procedure note + tracked-separately note.
|
||||
|
||||
## Conflict checklist: all ✓
|
||||
|
||||
1 Decisions-2026-06-22; order Invariants→Budget→Observation→Control plane→Roadmap; 2 stack rows; even-spread (no opportunistic/HOLD); control-plane UNHELD; forge-exec = tracked #628 post-PoC; §7 drift re-captures all present (#8/#10/#558/TTY/release).
|
||||
|
||||
## Out of scope (cited in doc + PR): #622 (spend template std), #623 (telemetry product), #625 (tenant_id schema), #628 (forge-exec adapter). Doctrine only — no implementation.
|
||||
@@ -1,50 +0,0 @@
|
||||
# Scratchpad — P5-003 Telegram Plugin
|
||||
|
||||
## Objective
|
||||
|
||||
Implement `@mosaicstack/telegram-plugin` by matching the established Discord plugin pattern with Telegraf + socket.io-client, add package docs, and pass package typecheck/lint.
|
||||
|
||||
## Requirements Source
|
||||
|
||||
- docs/PRD.md: Phase 5 remote control / Telegram plugin
|
||||
- docs/TASKS.md: P5-003
|
||||
- User task brief dated 2026-03-13
|
||||
|
||||
## Plan
|
||||
|
||||
1. Inspect Discord plugin behavior and package conventions
|
||||
2. Add Telegram runtime dependencies if missing
|
||||
3. Implement Telegram plugin with matching gateway event flow
|
||||
4. Add README usage documentation
|
||||
5. Run package typecheck and lint
|
||||
6. Run code review and remediate findings
|
||||
7. Commit, push, open PR, notify, remove worktree
|
||||
|
||||
## TDD Rationale
|
||||
|
||||
ASSUMPTION: No existing telegram package test harness or fixture coverage makes package-level TDD
|
||||
disproportionate for this plugin scaffold task. Validation will rely on typecheck, lint, and
|
||||
manual structural parity with the Discord plugin.
|
||||
|
||||
## Risks
|
||||
|
||||
- Telegram API typings may differ from Discord’s event shapes and require narrower guards.
|
||||
- Socket event payloads may already include `role` in shared gateway expectations.
|
||||
|
||||
## Progress Log
|
||||
|
||||
- 2026-03-13: Loaded Mosaic/global/repo guidance, mission files, Discord reference implementation, and Telegram package scaffold.
|
||||
- 2026-03-13: Added `telegraf` and `socket.io-client` to `@mosaicstack/telegram-plugin`.
|
||||
- 2026-03-13: Implemented Telegram message forwarding, gateway streaming accumulation, response chunking, and package README.
|
||||
|
||||
## Verification Evidence
|
||||
|
||||
- `pnpm --filter @mosaicstack/telegram-plugin typecheck` → pass
|
||||
- `pnpm --filter @mosaicstack/telegram-plugin lint` → pass
|
||||
- `pnpm typecheck` → pass
|
||||
- `pnpm lint` → pass
|
||||
|
||||
## Review
|
||||
|
||||
- Automated uncommitted review wrapper was invoked for the current delta.
|
||||
- Manual review completed against Discord parity, gateway event contracts, and package docs; no additional blockers found.
|
||||
@@ -1,44 +0,0 @@
|
||||
# P5-004 Scratchpad
|
||||
|
||||
- Objective: Add optional Authentik OIDC SSO adapter via Better Auth genericOAuth.
|
||||
- Task ref: P5-004
|
||||
- Issue ref: #96
|
||||
- Plan:
|
||||
1. Inspect auth/gateway surfaces and Better Auth plugin shape.
|
||||
2. Add failing coverage for auth config/startup validation where feasible.
|
||||
3. Implement adapter, docs, and warnings.
|
||||
4. Run targeted typechecks, lint, and review.
|
||||
|
||||
- TDD note: no low-friction auth plugin or bootstrap-env test seam exists for `packages/auth/src/auth.ts` or `apps/gateway/src/main.ts`. This change is configuration-oriented and does not alter an existing behavioral contract with a current test harness. I skipped new tests for this pass and relied on exact typecheck/lint/test commands plus manual review.
|
||||
|
||||
- Changes:
|
||||
1. Added conditional Better Auth `genericOAuth` plugin registration for the `authentik` provider in `packages/auth/src/auth.ts`.
|
||||
2. Added a soft startup warning in `apps/gateway/src/main.ts` for incomplete Authentik env configuration.
|
||||
3. Added `docs/plans/authentik-sso-setup.md` with env, redirect URI, and test-flow guidance.
|
||||
4. Confirmed `packages/auth/src/index.ts` already exports `AuthConfig`; no change required there.
|
||||
|
||||
- Verification:
|
||||
1. `pnpm --filter @mosaicstack/db build`
|
||||
2. `pnpm --filter @mosaicstack/auth typecheck`
|
||||
3. `pnpm --filter @mosaicstack/gateway typecheck`
|
||||
4. `pnpm lint`
|
||||
5. `pnpm format:check`
|
||||
6. `pnpm --filter @mosaicstack/auth test`
|
||||
7. `pnpm --filter @mosaicstack/gateway test`
|
||||
|
||||
- Results:
|
||||
1. `@mosaicstack/auth` typecheck passed after replacing the non-existent `enabled` field with conditional plugin registration.
|
||||
2. `@mosaicstack/gateway` typecheck passed.
|
||||
3. Repo lint passed.
|
||||
4. Prettier check passed after formatting `apps/gateway/src/main.ts`.
|
||||
5. `@mosaicstack/auth` tests reported `No test files found, exiting with code 0`.
|
||||
6. `@mosaicstack/gateway` tests passed: `3` files, `20` tests.
|
||||
|
||||
- Review:
|
||||
1. Manual review of the diff found no blocker issues.
|
||||
2. External `codex-code-review.sh --uncommitted` was attempted but did not return a usable verdict in-session; no automated review findings were available from that run.
|
||||
|
||||
- Situational evidence:
|
||||
1. Provider activation is env-gated by `AUTHENTIK_CLIENT_ID`.
|
||||
2. Misconfigured optional SSO surfaces a warning instead of crashing gateway startup.
|
||||
3. Setup doc records the expected redirect path: `{BETTER_AUTH_URL}/api/auth/callback/authentik`.
|
||||
@@ -1,43 +0,0 @@
|
||||
# P5 — Overlay composer + cross-harness (compose-contract)
|
||||
|
||||
- **Issue:** #604 · **Branch:** `feat/p5-overlay-composer` · **Lineage:** #542 → constitution alpha
|
||||
- **Requirements:** R7 (compose-contract) + R8 (cross-harness) + R9 (composer test)
|
||||
- **Design of record:** `docs/design/framework-constitution/{DESIGN.md §3.2, PRD.md §4}` (on `feat/framework-constitution-alpha`)
|
||||
|
||||
## Locked design (sequential-thinking)
|
||||
|
||||
Current `launch.ts` assembly (`buildComposedPrompt`) injects by value: mission + PRD + hard-gate +
|
||||
CONSTITUTION + AGENTS + USER + TOOLS + runtime. It does **not** inject SOUL or STANDARDS (those are
|
||||
read-on-demand per the gutted AGENTS dispatcher), and has no `.local` overlay support.
|
||||
|
||||
**Decision (ASSUMPTION — recorded for the PR):** overlays are injected as **deltas by value** under
|
||||
labeled sections; base files keep their existing residency.
|
||||
|
||||
- `USER.local.md` → appended directly under the `# User Profile` block (USER is injected).
|
||||
- `SOUL.local.md` + `STANDARDS.local.md` → a trailing `# Operator Overlays` section (their bases are
|
||||
load-on-demand, so only the small delta is injected — not the full base prose).
|
||||
- **Why:** honors DESIGN §3.2 ("model gets one pre-merged blob, no read-merge ritual") while preserving
|
||||
the P3 byte-budget tiering (don't re-inject large SOUL/STANDARDS prose). Precedence order kept: base
|
||||
layers first, operator overlays at recency.
|
||||
- Base-only is automatic when a `.local` file is absent (`readOptional`).
|
||||
|
||||
## Plan
|
||||
|
||||
| # | Task | File |
|
||||
| --- | ------------------------------------------------------------------------------------------------------ | --------------------------------------- |
|
||||
| 1 | Extract `composeContract({harness, mosaicHome})` pure fn; `buildComposedPrompt` delegates | `src/commands/launch.ts` |
|
||||
| 2 | Overlay logic (USER.local under profile; SOUL/STANDARDS.local in `# Operator Overlays`) | `src/commands/launch.ts` |
|
||||
| 3 | `mosaic compose-contract <harness>` command → prints blob to stdout | `src/commands/launch.ts` |
|
||||
| 4 | Bare-launch overlay nudge in self-load fallback | `framework/defaults/AGENTS.md` |
|
||||
| 5 | `compose-contract.spec.ts`: per-tier anchor, Tier-3 byte-equality, overlay present/absent, per-harness | `src/commands/compose-contract.spec.ts` |
|
||||
|
||||
## Deferred to P6
|
||||
|
||||
CONTRIBUTING.md + harness×gate compliance matrix; resident line-count CI ceiling; `aiguide` reconcile;
|
||||
alpha tag `mosaic-vX.Y.Z-alpha`.
|
||||
|
||||
## Status
|
||||
|
||||
- [x] Phase scaffold (branch, issue #604, scratchpad, TASKS)
|
||||
- [ ] Implementation (tasks 1–5)
|
||||
- [ ] prettier + vitest green; PR via wrapper → Lead (rides 0.0.39; 0.0.38 mid-cut)
|
||||
@@ -1,29 +0,0 @@
|
||||
# P6 — Docs, compliance matrix, alpha tag (constitution capstone)
|
||||
|
||||
- **Issue:** #606 · **Branch:** `feat/p6-docs-compliance-alpha` · **Lineage:** #542
|
||||
- **Requirements:** R9 (resident line-count ceiling) + R10 (CONTRIBUTING + compliance matrix + aiguide) + alpha tag
|
||||
|
||||
## Delivered (in-repo)
|
||||
|
||||
- `framework/CONTRIBUTING.md` — layer model, operator-hygiene/PII prohibition, dedup rule, resident
|
||||
budget, **dual-installer parity rule**, adding-a-harness, re-contamination rule, **harness×gate
|
||||
compliance matrix** (hook-parity gap marked ⚠️ tracked-v2), known-limitations (§9 residuals), PR checklist.
|
||||
- `framework/tools/quality/scripts/check-resident-budget.sh` — line-count ceiling over framework-owned
|
||||
resident files (CONSTITUTION + AGENTS + each runtime/\*/RUNTIME.md); `--self-test`; replaces the crude
|
||||
inline ci.yml loop. Wired blocking in `.woodpecker/ci.yml`.
|
||||
- Composer unit test (R9) already runs via `pnpm test`; `verify-sanitized.sh` (P1) already wired.
|
||||
|
||||
## Verification
|
||||
|
||||
- Sanitization gate green (CONTRIBUTING is operator-neutral). Resident-budget self-test + real run green.
|
||||
- prettier clean. Current resident counts: CONSTITUTION 96, AGENTS 83, RUNTIME max 75 — all < ceiling.
|
||||
|
||||
## Remaining
|
||||
|
||||
- [ ] `aiguide` reconcile (separate repo `~/src/aiguide` / mosaicstack/aiguide) — consistency pass vs Constitution.
|
||||
- [ ] Alpha tag `mosaic-vX.Y.Z-alpha` — propose version; Lead cuts after full DoD §8 green + all phases merged.
|
||||
|
||||
## Notes
|
||||
|
||||
- Alpha DoD (DESIGN §8): all phases P0–P6 merged + CI green. P5 (#605) pending merge after 0.0.38 publish.
|
||||
- Hook parity (codex/opencode/pi) = tracked v2 gap, documented in the matrix, not closed here.
|
||||
@@ -1,65 +0,0 @@
|
||||
# P8-001 — WorkOS + Keycloak SSO Providers
|
||||
|
||||
**Branch:** feat/p8-001-sso-providers
|
||||
**Started:** 2026-03-18
|
||||
**Mode:** Delivery
|
||||
|
||||
## Objective
|
||||
|
||||
Add WorkOS and Keycloak as optional SSO providers to the BetterAuth configuration, following the existing Authentik pattern.
|
||||
|
||||
## Scope
|
||||
|
||||
| Surface | Change |
|
||||
| ---------------------------------------- | ----------------------------------------------------------------------- |
|
||||
| `packages/auth/src/auth.ts` | Refactor provider array, add WorkOS + Keycloak conditional registration |
|
||||
| `apps/web/src/lib/auth-client.ts` | Add `genericOAuthClient()` plugin |
|
||||
| `apps/web/src/app/(auth)/login/page.tsx` | WorkOS + Keycloak SSO buttons gated by `NEXT_PUBLIC_*` env vars |
|
||||
| `.env.example` | Document WorkOS + Keycloak env vars |
|
||||
| `packages/auth/src/auth.test.ts` | Unit tests verifying env-var gating |
|
||||
|
||||
## Plan
|
||||
|
||||
1. ✅ Refactor `createAuth` to build `oauthProviders[]` conditionally
|
||||
2. ✅ Add WorkOS provider (explicit URLs, no discovery)
|
||||
3. ✅ Add Keycloak provider (discoveryUrl pattern)
|
||||
4. ✅ Add `genericOAuthClient()` to auth-client.ts
|
||||
5. ✅ Add SSO buttons to login page gated by `NEXT_PUBLIC_WORKOS_ENABLED` / `NEXT_PUBLIC_KEYCLOAK_ENABLED`
|
||||
6. ✅ Update `.env.example`
|
||||
7. ⏳ Write `auth.test.ts` with env-var gating tests
|
||||
8. ⏳ Quality gates: typecheck + lint + format:check + test
|
||||
9. ⏳ Commit + push + PR
|
||||
|
||||
## Decisions
|
||||
|
||||
- **WorkOS**: Uses explicit `authorizationUrl`, `tokenUrl`, `userInfoUrl` (no discovery endpoint available)
|
||||
- **Keycloak**: Uses `discoveryUrl` pattern (`{URL}/realms/{REALM}/.well-known/openid-configuration`)
|
||||
- **UI gating**: Login page uses `NEXT_PUBLIC_WORKOS_ENABLED` / `NEXT_PUBLIC_KEYCLOAK_ENABLED` feature flags (safer than exposing secret env var names client-side)
|
||||
- **Refactor**: Authentik moved into same `oauthProviders[]` array pattern — cleaner, more extensible
|
||||
- **Feature flag design**: `NEXT_PUBLIC_*` flags are opt-in alongside credentials (prevents accidental button render when creds not set)
|
||||
|
||||
## Assumptions
|
||||
|
||||
- `ASSUMPTION:` WorkOS OIDC discovery URL is not publicly documented; using direct URL pattern from WorkOS SSO docs.
|
||||
- `ASSUMPTION:` `NEXT_PUBLIC_WORKOS_ENABLED=true` must be explicitly set — this is intentional (credential presence alone doesn't enable the button since NEXT_PUBLIC vars are baked at build time).
|
||||
|
||||
## Tests
|
||||
|
||||
- `auth.test.ts`: Mocks betterAuth stack, verifies WorkOS included/excluded based on env var
|
||||
- `auth.test.ts`: Verifies Keycloak discoveryUrl constructed correctly
|
||||
|
||||
## Quality Gate Results
|
||||
|
||||
| Gate | Status |
|
||||
| ------------------------ | -------------------------------------------- |
|
||||
| typecheck | ✅ 32/32 cached green |
|
||||
| lint | ✅ 18/18 cached green |
|
||||
| format:check | ✅ All matched files use Prettier code style |
|
||||
| test (@mosaicstack/auth) | ✅ 8/8 tests passed |
|
||||
|
||||
## Verification Evidence
|
||||
|
||||
- `pnpm typecheck` — FULL TURBO, 32 tasks successful
|
||||
- `pnpm lint` — FULL TURBO, 18 tasks successful
|
||||
- `pnpm format:check` — All matched files use Prettier code style!
|
||||
- `pnpm --filter=@mosaicstack/auth test` — 8 tests passed, 0 failed
|
||||
@@ -1,40 +0,0 @@
|
||||
# P8-009: TUI Phase 1 — Slash Command Parsing
|
||||
|
||||
## Task Reference
|
||||
|
||||
- Issue: #162
|
||||
- Branch: feat/p8-009-tui-slash-commands
|
||||
|
||||
## Scope
|
||||
|
||||
- New files: parse.ts, registry.ts, local/help.ts, local/status.ts, commands/index.ts
|
||||
- Modified files: use-socket.ts, input-bar.tsx, message-list.tsx, app.tsx
|
||||
|
||||
## Key Observations
|
||||
|
||||
- CommandDef in @mosaicstack/types does NOT have `category` field — will omit from LOCAL_COMMANDS
|
||||
- CommandDef.args is `CommandArgDef[] | undefined`, not `{ usage: string }` — help.ts args rendering needs adjustment
|
||||
- Message role union currently: 'user' | 'assistant' | 'thinking' | 'tool' — adding 'system'
|
||||
- InputBar currently takes `onSubmit: (value: string) => void` — need to add slash command interception
|
||||
- app.tsx passes `onSubmit={socket.sendMessage}` directly — needs command-aware handler
|
||||
|
||||
## Assumptions
|
||||
|
||||
- ASSUMPTION: `category` field not in CommandDef type — will skip category grouping in help output, or add it only to registry (not to CommandDef type)
|
||||
- ASSUMPTION: For the `args` field display in help, will use `CommandArgDef.name` and `CommandArgDef.description`
|
||||
- ASSUMPTION: `commands:manifest` event type may not be in ServerToClientEvents — will handle via socket.on with casting if needed
|
||||
|
||||
## Status
|
||||
|
||||
- [ ] Create commands directory structure
|
||||
- [ ] Implement parse.ts
|
||||
- [ ] Implement registry.ts
|
||||
- [ ] Implement local/help.ts
|
||||
- [ ] Implement local/status.ts
|
||||
- [ ] Implement commands/index.ts
|
||||
- [ ] Modify use-socket.ts
|
||||
- [ ] Modify input-bar.tsx
|
||||
- [ ] Modify message-list.tsx
|
||||
- [ ] Modify app.tsx
|
||||
- [ ] Run quality gates
|
||||
- [ ] Commit + Push + PR + CI
|
||||
@@ -1,72 +0,0 @@
|
||||
# P8-010 Scratchpad — Gateway Phase 2: CommandRegistryService + CommandExecutorService
|
||||
|
||||
## Objective
|
||||
|
||||
Implement gateway-side command registry system:
|
||||
|
||||
- `CommandRegistryService` — owns canonical command manifest, broadcasts on connect
|
||||
- `CommandExecutorService` — routes `command:execute` socket events
|
||||
- `CommandsModule` — NestJS wiring
|
||||
- Wire into `ChatGateway` and `AppModule`
|
||||
- Register core commands
|
||||
- Tests for CommandRegistryService
|
||||
|
||||
## Key Findings from Codebase
|
||||
|
||||
### CommandDef shape (from packages/types/src/commands/index.ts)
|
||||
|
||||
- `scope: 'core' | 'agent' | 'skill' | 'plugin' | 'admin'` (NOT `category`)
|
||||
- `args?: CommandArgDef[]` — array of arg defs, each with `name`, `type`, `optional`, `values?`, `description?`
|
||||
- No `aliases` required (it's listed but optional-ish... wait, it IS in the interface)
|
||||
- `aliases: string[]` — IS present
|
||||
|
||||
### SlashCommandResultPayload requires `conversationId`
|
||||
|
||||
- The task spec shows `{ command, success, error }` without `conversationId` but actual type requires it
|
||||
- Must include `conversationId` in all return values
|
||||
|
||||
### CommandManifest has `skills: SkillCommandDef[]`
|
||||
|
||||
- Must include `skills` array in manifest
|
||||
|
||||
### userId extraction in ChatGateway
|
||||
|
||||
- `client.data.user` holds the user object (set in `handleConnection`)
|
||||
- `client.data.user.id` or similar for userId
|
||||
|
||||
### AgentModule not imported in ChatModule
|
||||
|
||||
- ChatGateway imports AgentService via DI
|
||||
- ChatModule doesn't declare imports — AgentModule must be global or imported
|
||||
|
||||
### Worktree branch
|
||||
|
||||
- Branch: `feat/p8-010-command-registry`
|
||||
- Working in: `/home/jwoltje/src/mosaic-mono-v1/.claude/worktrees/agent-ac85b3b2`
|
||||
|
||||
## Plan
|
||||
|
||||
1. Create `apps/gateway/src/commands/command-registry.service.ts`
|
||||
2. Create `apps/gateway/src/commands/command-executor.service.ts`
|
||||
3. Create `apps/gateway/src/commands/commands.module.ts`
|
||||
4. Modify `apps/gateway/src/app.module.ts` — add CommandsModule
|
||||
5. Modify `apps/gateway/src/chat/chat.module.ts` — import CommandsModule
|
||||
6. Modify `apps/gateway/src/chat/chat.gateway.ts` — inject services, add handler, emit manifest
|
||||
7. Create `apps/gateway/src/commands/command-registry.service.spec.ts`
|
||||
|
||||
## Progress
|
||||
|
||||
- [ ] Create CommandRegistryService
|
||||
- [ ] Create CommandExecutorService
|
||||
- [ ] Create CommandsModule
|
||||
- [ ] Update AppModule
|
||||
- [ ] Update ChatModule
|
||||
- [ ] Update ChatGateway
|
||||
- [ ] Write tests
|
||||
- [ ] Run quality gates
|
||||
- [ ] Commit + push + PR
|
||||
|
||||
## Risks
|
||||
|
||||
- CommandDef `args` shape mismatch from task spec — must use actual type
|
||||
- `SlashCommandResultPayload.conversationId` is required — handle missing conversationId
|
||||
@@ -1,44 +0,0 @@
|
||||
# P8-012 Scratchpad — Gateway /agent, /provider, /mission, /prdy, /tools Commands
|
||||
|
||||
## Objective
|
||||
|
||||
Add gateway-executed commands: `/agent`, `/provider`, `/mission`, `/prdy`, `/tools`.
|
||||
Key feature: `/provider login` OAuth flow with Valkey poll token.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Read all relevant files (done)
|
||||
2. Update `command-registry.service.ts` — add 5 new command registrations
|
||||
3. Update `commands.module.ts` — wire Redis injection for executor
|
||||
4. Update `command-executor.service.ts` — add 5 new command handlers + Redis injection
|
||||
5. Write spec file for new commands
|
||||
6. Run quality gates (typecheck, lint, format:check, test)
|
||||
7. Commit and push
|
||||
|
||||
## Key Decisions
|
||||
|
||||
- Redis pattern: same as GCModule — use `REDIS` token injected from a QueueHandle factory
|
||||
- `CommandDef` type fields: `scope: 'core'|'agent'|'skill'|'plugin'|'admin'`, `args?: CommandArgDef[]`, `execution: 'local'|'socket'|'rest'|'hybrid'`
|
||||
- No `category` or `usage` fields — instruction spec was wrong on that
|
||||
- `SlashCommandResultPayload.conversationId` is typed as `string` (not `string | undefined`) per the type
|
||||
- Provider commands are `scope: 'agent'` since they relate to agent configuration
|
||||
- Redis injection: add a `COMMANDS_REDIS` token in commands module, inject via factory pattern same as GCModule
|
||||
|
||||
## Progress
|
||||
|
||||
- [ ] command-registry.service.ts updated
|
||||
- [ ] commands.module.ts updated (add Redis provider)
|
||||
- [ ] command-executor.service.ts updated (add Redis injection + handlers)
|
||||
- [ ] spec file written
|
||||
- [ ] quality gates pass
|
||||
- [ ] commit + push + PR
|
||||
|
||||
## Risks
|
||||
|
||||
- `conversationId` typing: `SlashCommandResultPayload.conversationId` is `string`, but some handler calls pass `undefined`. Need to check if it's optional.
|
||||
|
||||
After reviewing types: `conversationId: string` in `SlashCommandResultPayload` — not optional. Must pass empty string or actual ID. Looking at existing code: `message: 'Start a new conversation...'` returns `{ command, conversationId, ... }` where conversationId comes from payload which is always a string per `SlashCommandPayload`. For provider commands that don't have a conversationId, pass empty string `''` or the payload's conversationId.
|
||||
|
||||
Actually looking at the spec more carefully: `handleProvider` returns `conversationId: undefined`. But the type says `string`. This would be a TypeScript error. I'll use `''` as a fallback or adjust. Let me re-examine...
|
||||
|
||||
The `SlashCommandResultPayload` interface says `conversationId: string` — not optional. But the spec says `conversationId: undefined`. I'll use `payload.conversationId` (passing it through) since it comes from the payload.
|
||||
@@ -1,55 +0,0 @@
|
||||
# P8-016: Security — Tool Path Hardening + Sandbox Escape Prevention
|
||||
|
||||
## Status: in-progress
|
||||
|
||||
## Branch: feat/p8-016-tool-hardening
|
||||
|
||||
## Issue: #169
|
||||
|
||||
## Scope
|
||||
|
||||
Harden file, git, and shell tool factories so no path operation escapes `sandboxDir`.
|
||||
|
||||
## Files to Create
|
||||
|
||||
- `apps/gateway/src/agent/tools/path-guard.ts` (new)
|
||||
- `apps/gateway/src/agent/tools/path-guard.test.ts` (new)
|
||||
|
||||
## Files to Modify
|
||||
|
||||
- `apps/gateway/src/agent/tools/file-tools.ts`
|
||||
- `apps/gateway/src/agent/tools/git-tools.ts`
|
||||
- `apps/gateway/src/agent/tools/shell-tools.ts`
|
||||
|
||||
## Analysis
|
||||
|
||||
### file-tools.ts
|
||||
|
||||
- Has existing `resolveSafe()` function but uses weak containment check (relative path)
|
||||
- Replace with `guardPath` (for reads/lists on existing paths) and `guardPathUnsafe` (for writes)
|
||||
- Error pattern: return `{ content: [{ type: 'text', text: 'Error: ...' }], details: undefined }`
|
||||
|
||||
### git-tools.ts
|
||||
|
||||
- Has `clampCwd()` that silently falls back to sandbox root on escape attempt
|
||||
- Replace with strict `guardPath` that throws SandboxEscapeError, caught and returned as error
|
||||
- Also need to guard the `path` parameter in `git_diff`
|
||||
|
||||
### shell-tools.ts
|
||||
|
||||
- Has `clampCwd()` same silent-fallback approach
|
||||
- Replace with strict `guardPath` that throws SandboxEscapeError
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
- `guardPath`: uses `realpathSync.native` to resolve symlinks, requires path to exist
|
||||
- `guardPathUnsafe`: lexical only (`path.resolve`), for paths that may not exist yet
|
||||
- Both throw `SandboxEscapeError` on escape attempt
|
||||
- Callers catch and return error result
|
||||
|
||||
## Verification
|
||||
|
||||
- pnpm typecheck
|
||||
- pnpm lint
|
||||
- pnpm format:check
|
||||
- pnpm test
|
||||
@@ -1,103 +0,0 @@
|
||||
# P8-019 Verification — Phase 8 Platform Architecture
|
||||
|
||||
**Date:** 2026-03-15
|
||||
**Status:** complete
|
||||
**Branch:** feat/p8-019-verify
|
||||
**PR:** #185
|
||||
**Issue:** #172
|
||||
|
||||
## Test Results
|
||||
|
||||
- Unit tests (baseline, pre-P8-019): 101 passing across 9 gateway test files + 1 CLI file
|
||||
- Integration tests added: 2 new spec files (68 new tests)
|
||||
- `apps/gateway/src/commands/commands.integration.spec.ts` — 42 tests
|
||||
- `packages/cli/src/tui/commands/commands.integration.spec.ts` — 26 tests
|
||||
- Total after P8-019: 160 passing tests across 12 test files
|
||||
- Quality gates: typecheck ✓ lint ✓ format:check ✓ test ✓
|
||||
|
||||
## Components Verified
|
||||
|
||||
### Command System
|
||||
|
||||
- `CommandRegistryService.getManifest()` returns 19 core commands (>= 12 requirement met)
|
||||
- All commands have correct `execution` type:
|
||||
- `socket`: model, thinking, new, clear, compact, retry, system, gc, agent, mission, prdy, tools, reload
|
||||
- `rest`: rename, history, export, preferences
|
||||
- `hybrid`: provider, status (gateway), (status overridden to local in TUI)
|
||||
- `local`: help (gateway); help, stop, cost, status, clear (TUI local)
|
||||
- All aliases verified: m→model, t→thinking, n→new, a→agent, s→status, h→help, pref→preferences
|
||||
- `parseSlashCommand()` correctly extracts command + args for all forms
|
||||
- Unknown commands return `success: false` with descriptive message
|
||||
|
||||
### Preferences + System Override
|
||||
|
||||
- `PreferencesService.getEffective()` applies platform defaults when no user overrides
|
||||
- Immutable keys (`limits.maxThinkingLevel`, `limits.rateLimit`) cannot be overridden — enforcement always wins
|
||||
- `set()` returns error for immutable keys with "platform enforcement" message
|
||||
- `SystemOverrideService.set()` stores to Valkey with 5-minute TTL; verified via mock
|
||||
- `/system` command calls `SystemOverrideService.set()` with exact text arg
|
||||
- `/system` with no args calls `SystemOverrideService.clear()`
|
||||
|
||||
### Session GC
|
||||
|
||||
- `collect(sessionId)` deletes all `mosaic:session:<id>:*` Valkey keys
|
||||
- `fullCollect()` clears all `mosaic:session:*` keys on cold start
|
||||
- `sweepOrphans()` extracts unique session IDs from keys and collects each
|
||||
- GC result includes `duration` and `orphanedSessions` count
|
||||
- `/gc` command invokes `sweepOrphans(userId)` and returns count in response
|
||||
|
||||
### Tool Security (path-guard)
|
||||
|
||||
- `guardPath` rejects `../` traversal → throws `SandboxEscapeError`
|
||||
- `guardPath` rejects absolute paths outside sandbox → throws `SandboxEscapeError`
|
||||
- `guardPathUnsafe` rejects sibling-named directories (e.g. `/tmp/test-sandbox-evil/`)
|
||||
- All 12 path-guard tests pass; `SandboxEscapeError` message includes path and sandbox in text
|
||||
|
||||
### Workspace
|
||||
|
||||
- `WorkspaceService.resolvePath()` returns user path for solo projects:
|
||||
`$MOSAIC_ROOT/.workspaces/users/<userId>/<projectId>`
|
||||
- `WorkspaceService.resolvePath()` returns team path for team projects:
|
||||
`$MOSAIC_ROOT/.workspaces/teams/<teamId>/<projectId>`
|
||||
- Path resolution is deterministic (same inputs → same output)
|
||||
- `exists()`, `createUserRoot()`, `createTeamRoot()` all tested
|
||||
|
||||
### TUI Autocomplete
|
||||
|
||||
- `filterCommands(commands, query)` filters by name, aliases, and description
|
||||
- Empty query returns all commands
|
||||
- Prefix matching works: "mo" → model, "mi" → mission
|
||||
- Alias matching: "h" matches help (alias)
|
||||
- Description keyword matching: "switch" → model
|
||||
- Unknown query returns empty array
|
||||
- `useInputHistory` ring buffer caps at 50 entries
|
||||
- Up-arrow recall returns most recent entry
|
||||
- Down-arrow after up restores saved input
|
||||
- Duplicate consecutive entries are deduplicated
|
||||
- Reset navigation works correctly
|
||||
|
||||
### Hot Reload
|
||||
|
||||
- `ReloadService` registers plugins via `registerPlugin()`
|
||||
- `reload()` iterates plugins, calls their `reload()` method
|
||||
- Plugin errors are counted but don't prevent other plugins from reloading
|
||||
- Non-MosaicPlugin objects are skipped gracefully
|
||||
- SIGHUP trigger verified via reload trigger = 'sighup'
|
||||
|
||||
## Gaps / Known Limitations
|
||||
|
||||
1. `SystemOverrideService` creates its own Valkey connection in constructor (not injected) — functional but harder to test in isolation without mocking `createQueue`. Current tests mock it at the executor level.
|
||||
2. `/status` command has `execution: 'hybrid'` in the gateway registry but `execution: 'local'` in the TUI local registry — TUI local takes precedence, which is the intended behavior.
|
||||
3. `SessionGCService.fullCollect()` runs on `onModuleInit` (cold start) — this is intentional but means tests must mock redis.keys to avoid real Valkey calls.
|
||||
4. `ProjectBootstrapService` and `TeamsService` in workspace module have no dedicated tests — they are thin wrappers over Drizzle that delegate to WorkspaceService (which is tested).
|
||||
5. GC cron schedule (`SESSION_GC_CRON` env var) is configured at module level — not unit tested here; covered by NestJS cron integration.
|
||||
6. `filterCommands` in `CommandAutocomplete` is not exported — replicated in integration test to verify behavior.
|
||||
|
||||
## CI Evidence
|
||||
|
||||
Pipeline: TBD after push — all 4 local quality gates green:
|
||||
|
||||
- pnpm typecheck: 32 tasks, all cached/green
|
||||
- pnpm lint: 18 tasks, all green
|
||||
- pnpm format:check: all files match Prettier style
|
||||
- pnpm test: 32 tasks, 160 tests passing
|
||||
@@ -1,58 +0,0 @@
|
||||
# RM-01 — Reproducible checkout
|
||||
|
||||
- Task/ref: RM-01 (`docs/remediation/TASKS.md`, internal mission tracking)
|
||||
- Objective: make checkout/install/typecheck hooks fail on code rather than environmental residue, for root CI and non-root seats.
|
||||
- Scope: pnpm store configuration, transactional Husky installation, dependency/generated-state preflight, checkout regression tests, developer documentation.
|
||||
- Constraints: isolated worktree; no skip-switch fixes; no writes under `/root` or `/tmp`; workers do not edit `docs/remediation/TASKS.md`; author does not review or merge.
|
||||
- Acceptance: AC1–AC8 from the orchestrator dispatch/addendum.
|
||||
- Plan:
|
||||
1. Add RED-first tests for missing dependencies, stale/foreign `.next`, and interrupted hook installation.
|
||||
2. Implement environment-overridable HOME-based pnpm store defaults, deterministic preflight, and transactional hook installation.
|
||||
3. Run focused tests, install/build/baseline gates, and explicit AC negative controls.
|
||||
4. Obtain independent review, push after queue guard, open PR, and send evidence to `mos-remediation`.
|
||||
- Budget: orchestrator estimate 6K/60K; no explicit hard token cap. Keep scope to RM-01 and avoid unrelated cleanup.
|
||||
- Risks: 97%-full shared `/tmp`; native dependency install size; root-owned fixtures may require Docker for realistic verification.
|
||||
|
||||
## Progress / evidence
|
||||
|
||||
- Worktree created at `/home/hermes/agent-work/rm-01` from `origin/main` `06e0d403`.
|
||||
- `/tmp` baseline: 28G used, 889M available (97%); worktree and planned store are on `/home`.
|
||||
- Root causes confirmed from source: committed `.npmrc` pins `/root`; `prepare` invokes Husky directly; web typecheck includes generated `.next` types without validating ownership/freshness.
|
||||
|
||||
## Checkpoint evidence (c45e5e19)
|
||||
|
||||
- AC1 IN PROGRESS: non-root `pnpm install --frozen-lockfile --store-dir "$HOME/.local/share/pnpm/store"` exited 0; `pnpm exec turbo run typecheck --force` exited 0 (45/45 uncached). Clean CI-container run not performed.
|
||||
- AC2 DONE: with `node_modules` absent, `pnpm preflight` exited 42 with `MOSAIC_PREFLIGHT_MISSING_DEPS` and `run pnpm install`; after install it exited 0.
|
||||
- AC3 DONE: appending `export const x: number = "s"` to `packages/types/src/index.ts` made `pnpm -w typecheck` exit 2 with TS2322; reverting made it exit 0.
|
||||
- AC4 IN PROGRESS: local `pnpm -w build` exited 0 and `git status --porcelain` showed no generated residue beyond the intended RM-01 source changes. Fresh-clone proof not performed.
|
||||
- AC5 DONE: non-root install exited 0; `pnpm store path` resolved `/home/hermes/.local/share/pnpm/store/v10`; no `/root` write was attempted.
|
||||
- AC6 IN PROGRESS: focused failure/rollback tests passed, but final review found a concurrent-install race. Two installers can both observe `.husky/_` absent; after one installs successfully, the losing install's catch path can quarantine the winner's active hooks and restore stale Git config (`scripts/install-hooks.mjs`, activation/catch transaction). A RED regression is committed after the checkpoint.
|
||||
- AC7 DONE: install/store/worktree were on `/home`; full `pnpm -w build` exited 0; `/tmp` usage changed by 4096 bytes during the build (23,805,173,760 → 23,805,177,856 bytes), not materially.
|
||||
- AC8 DONE for the implemented path: store resolves under `$HOME`; test/quarantine/build state resolves under the worktree; no implemented component requires a writable path outside `$HOME` or the worktree.
|
||||
|
||||
## Continuation evidence
|
||||
|
||||
- AC6 DONE: the committed race reproducer was observed RED (`node --test --test-name-pattern='a competing successful installer is not removed by the losing process' scripts/install-hooks.test.mjs`, exit 1/ENOENT), then passed after cleanup became ownership-safe. The losing installer never removes an active hook set or restores Git configuration it did not activate. `pnpm test:checkout` passes 21/21, exit 0, including the original race and a post-rename peer-replacement regression.
|
||||
- Generated-state remediation: replaced mtime inference with a source/build-input fingerprint, written only after a serialized successful Next build with unchanged inputs. Failed/interrupted/overlapping builds leave no trusted marker. The fingerprint uses Next's own environment loader, covers resolved `NEXT_PUBLIC_*` values, inherited TypeScript configuration, lock/workspace inputs, and rejects symlink inputs.
|
||||
- Baseline: `pnpm typecheck`, `pnpm lint`, and `pnpm format:check` each exit 0. Local `pnpm test` still exits 97 only at the pre-existing Bash `BASH_LINENO` convention guard (#973/#1003), after checkout tests and package tests pass; this is not reported as a green full-suite result.
|
||||
- Automated review remediation: resolved findings for peer-hook ownership, stale/failed build markers, build-input changes, expanded environment inputs, inherited TypeScript config, symlink inputs, and overlapping build serialization. Independent PR review remains assigned to rev-974.
|
||||
- AC1 DONE at `0f706119`: a clean clone created inside `git.mosaicstack.dev/mosaicstack/stack/ci-base:latest` ran the exact acceptance sequence `pnpm install --frozen-lockfile && pnpm -w typecheck`; exit 0 with 45/45 uncached typecheck tasks successful. An earlier bind-mounted clone attempt exited 1 because root in the container rejected the host-owned Git directory; that failed attempt is not counted as evidence.
|
||||
- AC4 DONE at `0f706119`: in that same fresh clone and CI image, `pnpm -w build` completed 25/25 tasks and the immediately following `git status --porcelain` was empty; combined assertion exit 0.
|
||||
- Push BLOCKED after the required queue guard: `git push origin fix/rm-01-reproducible-checkout` was rejected by Gitea with `User permission denied for writing` / `pre-receive hook declined`, despite `MOSAIC_GIT_IDENTITY=f10-coder` resolving username `f10-coder` from the provisioned `gitea-mosaicstack-f10-coder.token`.
|
||||
|
||||
## Review remediation — restated AC2
|
||||
|
||||
- Independent review correctly found that an added symlink under a successfully built `.next` tree passed preflight. The exact reviewer control, `ln -s /etc/hosts apps/web/.next/reviewer-symlink && pnpm preflight`, was observed passing before remediation.
|
||||
- The original blanket symlink wording conflicts with AC4 because canonical Next `output: 'standalone'` emits legitimate pnpm dependency symlinks. The coordinator independently verified 42 such links and approved the operative restatement: `.next` itself must not be a symlink; descendant symlinks must exactly match the successful build's certified manifest.
|
||||
- RED-first controls were observed failing together against the prior implementation (exit 1): `.next` root, added, removed, retargeted, tampered-manifest, and canonical-style certified-link cases. The build now publishes the manifest atomically before the existing source certification commit marker; that marker binds the manifest SHA-256. Missing/partial/modified manifests remain untrusted.
|
||||
- GREEN evidence: the six-case symlink control passes; the exact reviewer-added link exits 43; removing it restores preflight exit 0. The added RED-first build-publication control also proves a symlinked `.next` cannot redirect certification writes outside the checkout. `pnpm test:checkout` passes 23 top-level tests / 29 including subtests. Canonical `pnpm --filter @mosaicstack/web build` and the following `pnpm preflight` both exit 0.
|
||||
- Threat-model ruling: the manifest detects accidental, independent, stale, and foreign-residue mutation—the class exposed by the five-month-stale `.next` that produced 19 phantom TS2307 errors. It does not defend against a same-UID actor able to rewrite both manifest and marker consistently (CWE-345); no local worktree construction can without an external trust anchor. RM-59 tracks the residual: executor/spine-side attestation outside worktree authority, dependent on RM-12, RM-21, and RM-25.
|
||||
- AC8 concrete proof at `df7530ae`: a clean clone ran in `ci-base:latest` with Docker `--read-only`; its only writable mounts were `/workspace` (the worktree) and `/home/ci` (`HOME`, with `NPM_CONFIG_STORE_DIR=/home/ci/store`). `pnpm install --frozen-lockfile && pnpm -w typecheck` exited 0 with 45/45 uncached tasks. This proves the implemented checkout path requires no writable location outside `$HOME` and the worktree. An initial fixture attempt failed only because Git required `/workspace` safe-directory setup; it is not counted as evidence.
|
||||
|
||||
## Handoff
|
||||
|
||||
1. Keep the newly committed RED tests red until implementing: (a) source-fingerprint marker support for valid incremental `.next` output, and (b) ownership-safe concurrent hook activation.
|
||||
2. The latest automated review rejected oldest-generated-file mtime as a false positive for valid incremental Next output. Use a source-content fingerprint marker written only after successful `next build`; do not continue tuning mtimes.
|
||||
3. For Husky, generation in an isolated temporary Git repo avoids mutating real `core.hooksPath` during staging. Preserve that design. Fix the losing concurrent process so it never removes a peer's completed hook set or restores stale config.
|
||||
4. Codex review runs in a read-only sandbox, so its attempts to run the fixture-writing Node tests report opaque test-file failures. The same tests run normally in the worktree.
|
||||
5. Full `pnpm test` is not green on this host: it exits 97 at the pre-existing Bash `BASH_LINENO` convention guard (#1003), after the changed checkout tests and package tests pass. Do not weaken that gate.
|
||||
@@ -1,120 +0,0 @@
|
||||
# RM-03 — CI Queue Guard Repair
|
||||
|
||||
- **Task:** RM-03
|
||||
- **Issue:** #1019
|
||||
- **Branch:** `fix/rm-03-queue-guard`
|
||||
- **Owner:** coder-mos1
|
||||
- **Reviewer:** rev-974 (independent; author != reviewer)
|
||||
- **Started:** 2026-08-01
|
||||
|
||||
## Objective
|
||||
|
||||
Repair the mandatory CI queue guard so it reads provider payloads, blocks asserted non-green CI, distinguishes provider unavailability from a real non-green result, and inspects the branch actually being pushed or merged.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Worktree only: `/home/hermes/agent-work/rm-03`; never mutate `/src/mosaic-stack`.
|
||||
- JSON payload travels through stdin; never argv. Large payload must remain below no ARG_MAX dependency.
|
||||
- TDD is mandatory. Every behavior case must be observed red before implementation.
|
||||
- No bypass flags or hook suppression.
|
||||
- Do not cite the existing guard's green as evidence; D-23 establishes it is zero-information.
|
||||
- Gate-ready is a frozen exact head. Any push after a merge-gate verdict voids that verdict.
|
||||
- No merge: coordinator holds the merge hand pending Jason.
|
||||
|
||||
## Design
|
||||
|
||||
1. Feed JSON to `python3 -c` on stdin, including pending-context rendering.
|
||||
2. Classify valid green as `READY`; pending/failure/no-status/malformed/mixed as `ASSERTED_NOT_READY`; provider/credential/transport inability as `CANNOT_ASSERT`.
|
||||
3. `ASSERTED_NOT_READY` exits nonzero. `CANNOT_ASSERT` emits a loud diagnostic and appends a local JSONL audit record. Push degrades to exit 0; merge holds with distinct retryable exit 75 until provider recovery, then self-clears without manual reset. Inability to write the audit exits nonzero.
|
||||
4. Derive the current branch when `-B` is omitted. The merge wrapper passes the exact PR head branch, repository, and full commit SHA—not its `main` base—so fork PRs cannot resolve against an adjacent base-repository branch.
|
||||
|
||||
## Test matrix
|
||||
|
||||
| Case | Required outcome |
|
||||
| --- | --- |
|
||||
| success | exit 0; terminal-success |
|
||||
| pending | nonzero after bounded timeout |
|
||||
| failure | nonzero |
|
||||
| no-status | nonzero |
|
||||
| malformed | nonzero |
|
||||
| >=150 KiB payload | unchanged classification; never rc126 |
|
||||
| provider unreachable on push | loud audited CANNOT_ASSERT; degraded exit 0 |
|
||||
| provider unreachable on merge | loud audited CANNOT_ASSERT; retryable exit 75/HOLD |
|
||||
| audit unavailable | nonzero |
|
||||
| implicit push branch | provider URL uses checked-out feature branch |
|
||||
| merge wrapper | queue guard receives exact PR head branch/repository/full SHA |
|
||||
|
||||
## RED-first evidence
|
||||
|
||||
Observed against the unmodified `origin/main` implementation before source edits:
|
||||
|
||||
- `bash packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh` → rc 1 with 15 failed assertions.
|
||||
- Success payload was reported `state=unknown`.
|
||||
- Pending, failure, no-status, and malformed payloads each exited 0 and omitted `ASSERTED_NOT_READY`.
|
||||
- The 160 KiB payload produced rc 141 because Python never consumed the pipe; it did not classify success.
|
||||
- Provider-unreachable exited 7 with no `CANNOT_ASSERT` audit record.
|
||||
- Implicit push queried `/branches/main`, not `/branches/fix/rm-03-fixture`.
|
||||
- Audit-unavailable emitted no audit diagnostic.
|
||||
- A credential-resolution hard-block mutant was then run before trusting that added case: `credential-unresolvable` returned rc 1 and omitted `CANNOT_ASSERT`; the matrix returned rc 1 with two named assertion failures.
|
||||
- Review-blocker controls were observed red: structurally invalid `statuses` string and null-entry payloads each exited 0 as `terminal-success`; unsupported-platform discovery exited 1 without diagnostic or audit (seven named assertion failures total).
|
||||
- After the push/merge asymmetry ruling, merge-side provider unavailability was observed red at rc 0; its registered case required distinct retryable rc 75.
|
||||
- Aggregate `state=success` with zero contexts was observed red: it exited 0 as `terminal-success`; the registered case requires `no-status`/nonzero.
|
||||
- Fork/exact-head controls were observed red: `pr-merge.sh` omitted the fork repository and full SHA, and an ignored-arguments mutant re-resolved through `/branches/` instead of the exact fork commit (two named failures).
|
||||
- GitHub check-run-only success/pending/failure were each misclassified as `no-status`; the RED run had five named failures and proved the Checks API was never queried.
|
||||
- The first merge-pin control was unrunnable because one `local` declaration referenced a variable before assignment under `set -u`; this was disclosed and corrected rather than counted. The runnable RED then showed Gitea payload `{"Do":"squash"}` lacked `head_commit_id`; a separate GitHub run showed `gh pr merge 123 --squash` lacked `--match-head-commit`.
|
||||
- A stale-verdict mutant removed the `--expect-head` comparison and was observed red because a moved head reached the provider merge call.
|
||||
- `bash packages/mosaic/framework/tools/git/test-pr-merge-queue-branch.sh` initially returned rc 1; captured call was `--purpose merge -B main -t 900 -i 15`.
|
||||
|
||||
Logs remain untracked under the worktree as `.mosaic-test-work-red-*.log` and will not be committed.
|
||||
|
||||
## Progress
|
||||
|
||||
- [x] Mission, remediation charter, task evidence, board, issue #1019, and superseded PR #1023 read.
|
||||
- [x] Isolated worktree created and identity configured coherently.
|
||||
- [x] Mutant tests authored and observed red.
|
||||
- [x] Implementation green.
|
||||
- [x] Baseline and focused situational gates green; full package suite has an unrelated framework-shell environment abort recorded below.
|
||||
- [ ] Independent review clean (rev-974 requested changes at `44ffa99a`; bypass remediation committed and awaiting re-review).
|
||||
- [ ] PR CI terminal-green at exact head by full step scan.
|
||||
- [ ] Merge-gate verdict issued against frozen head.
|
||||
|
||||
## Scope disposition
|
||||
|
||||
- The five framework guides are consequential documentation: they define the purpose-aware tri-state contract, including audited push degradation and merge HOLD.
|
||||
- The agent templates are consequential because they ship the same queue-guard instructions into newly seeded agent contracts; leaving them binary/stale would contradict the repaired tool.
|
||||
- `pr-merge.sh` is consequential: it must inspect the PR's exact head branch/repository/SHA and enforce the exact-head merge pin.
|
||||
- `pr-metadata.sh` is consequential only as the normalized source of that head branch/repository/SHA. Its diff is limited to exposing those fields on GitHub and Gitea.
|
||||
- `test-pr-merge-gitea-empty-uid.sh` changes because exact-head Gitea merges now always use the API path (the only path that can send `head_commit_id`), superseding the prior tea-empty-identity fallback behavior.
|
||||
|
||||
## Review remediation
|
||||
|
||||
- rev-974 independently proved that the documented `--skip-queue-guard` merge option bypassed an exit-99 guard stub, reached the provider merge payload, printed success, and exited 0 at head `44ffa99a`.
|
||||
- RED-first reproduction was added to `test-pr-merge-head-pin.sh` before the production fix: `FAIL merge-bypass: --skip-queue-guard reached the provider merge path`, suite rc 1. The test-only commit is `241113e6`.
|
||||
- Production remediation `37aae650` removes the option from parsing, usage, help, and examples. Every merge-capable path now invokes the queue guard; `--dry-run` alone omits it and has a regression proving that it exits before provider dispatch and creates no merge payload.
|
||||
- Existing Gitea merge tests now exercise a successful guard response rather than bypassing the guard.
|
||||
|
||||
## Risks / boundaries
|
||||
|
||||
- The local JSONL audit is durable operational evidence but not tamper-resistant against the same UID. RM-03 does not claim otherwise.
|
||||
- Push-side audited exit 0 is an explicit owner ruling (Option B), accepted to avoid bricking recovery work; merge-side CANNOT_ASSERT remains retryable exit 75/HOLD. The automated security reviewer continues to flag the deliberate push availability tradeoff.
|
||||
- Source/deployed-copy equality is owned by RM-02/D-22; this branch changes repository source and its tests only.
|
||||
|
||||
## Test evidence
|
||||
|
||||
Fresh after rescue checkpoint `b7175012`:
|
||||
|
||||
- Focused situational matrix: tri-state, GitHub checks pagination, branch-absent, merge head branch/repository/SHA, exact-head pin, and Gitea exact-head API regressions all passed.
|
||||
- `bash -n` on the three production shell scripts passed.
|
||||
- `shellcheck -x -P packages/mosaic/framework/tools/git ...` on all changed shell scripts passed.
|
||||
- `pnpm typecheck` passed (45/45 Turbo tasks).
|
||||
- `pnpm lint` passed (25/25 Turbo tasks).
|
||||
- `pnpm format:check` passed.
|
||||
- `pnpm --filter @mosaicstack/mosaic test`: Vitest passed 1508/1508 on the confirmation run; framework-shell then aborted at the pre-existing wake coordinate assertion with exit 97: `BASH_LINENO ... probe reported [3 5], expected [3 4] ... (#973)`. This is outside the RM-03 diff and is disclosed rather than substituted or called green.
|
||||
- The prior package-suite attempt had one transient, out-of-diff `install-ordering-guard.spec.ts` failure (1/1508); its isolated rerun passed 19/19 and the confirmation full Vitest run passed 1508/1508.
|
||||
- After bypass remediation: all six focused RM-03 queue/merge regressions passed, including bypass refusal and dry-run non-dispatch; shell syntax and source-aware ShellCheck passed; `pnpm typecheck`, `pnpm lint`, and `pnpm format:check` passed.
|
||||
- Fresh `test:framework-shell` reached and passed every RM-03 test, then again aborted at the unrelated wake coordinate assertion with exit 97; it remains explicitly non-green rather than substituted.
|
||||
- An ad hoc raw Prettier invocation over `.template` and `.sh` files was unrunnable because no parser is registered for those extensions; it was not used as a substitute for canonical `pnpm format:check`.
|
||||
|
||||
## Final evidence
|
||||
|
||||
Pending.
|
||||
@@ -1,98 +0,0 @@
|
||||
# t_a292e96f — Gitea PR metadata wrapper fix
|
||||
|
||||
## Objective
|
||||
|
||||
Repair Mosaic git wrappers so Gitea PR metadata and merge preflight work for U-Connect PRs on `git.uscllc.com` without selecting the unrelated `git.mosaicstack.dev` tea login.
|
||||
|
||||
## Findings
|
||||
|
||||
- Reproduced the failure from `/src/uconnect-worktrees/t_39ce717c-authentik-smoke-gate` with the current `pr-metadata.sh`:
|
||||
- PR #1905 returned JSON with `number=null`, `baseRefName=""`, `headRefName=""`.
|
||||
- PR #1908 returned JSON with `number=null`, `baseRefName=""`, `headRefName=""`.
|
||||
- Root cause: the wrapper treated HTTP/API error payloads as PR payloads and normalized missing fields to empty strings.
|
||||
- The credential loader can return a non-working `git.uscllc.com` API token in this environment, while host-specific `~/.git-credentials` basic auth succeeds. The wrapper now falls back by host before normalization.
|
||||
- `tea login list` has only `git.mosaicstack.dev` configured here; `pr-merge.sh` previously forced `--login mosaicstack`, which is invalid for `git.uscllc.com` and caused `Login name mosaicstack does not exist`.
|
||||
|
||||
## Changes
|
||||
|
||||
- `packages/mosaic/framework/tools/git/detect-platform.sh`
|
||||
- Added `get_gitea_basic_auth <host>` to retrieve host-specific HTTPS credentials from `~/.git-credentials` without printing secrets.
|
||||
- `packages/mosaic/framework/tools/git/pr-metadata.sh`
|
||||
- Uses strict bash mode.
|
||||
- Checks Gitea HTTP status and fails nonzero on API errors/non-JSON instead of emitting empty branch fields.
|
||||
- Falls back from token auth to host-specific basic auth.
|
||||
- Normalizes standard `head.ref`/`base.ref` and fallback branch fields.
|
||||
- Requires non-empty `headRefName` and `baseRefName`.
|
||||
- Preserves GitHub `gh pr view` behavior.
|
||||
- `packages/mosaic/framework/tools/git/pr-merge.sh`
|
||||
- Reads metadata once for base-branch policy preflight.
|
||||
- Selects a `tea` login only when its configured URL matches the repo host.
|
||||
- Falls back to authenticated Gitea merge API when no matching `tea` login exists, avoiding the wrong `mosaicstack` login for USC repos.
|
||||
- Keeps squash-only and main-only merge policy.
|
||||
- `packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh`
|
||||
- Added fixture-based regression harness for standard Gitea fields, fallback branch fields, `refs/pull/<n>/head` plus `head.label` normalization, and API error payloads.
|
||||
|
||||
## Documentation / changelog note
|
||||
|
||||
This repository currently has no root `CHANGELOG.md`; the scratchpad and `docs/TASKS.md` carry the task-level change record for this wrapper fix.
|
||||
|
||||
## Verification log
|
||||
|
||||
- Red regression check: copied the new `test-pr-metadata-gitea.sh` harness next to `origin/main` wrapper scripts and ran it with `MOSAIC_TEST_WORK_DIR=$PWD/.mosaic-test-work/pr-metadata-gitea-red`; it failed as expected with `headRefName=''` and `baseRefName=''` on the fixture API-error path.
|
||||
- `bash -n packages/mosaic/framework/tools/git/{detect-platform.sh,pr-metadata.sh,pr-merge.sh,test-pr-metadata-gitea.sh}`: passed.
|
||||
- `shellcheck -x -P . -e SC1090 packages/mosaic/framework/tools/git/{detect-platform.sh,pr-metadata.sh,pr-merge.sh,test-pr-metadata-gitea.sh}`: passed.
|
||||
- `MOSAIC_TEST_WORK_DIR=$PWD/.mosaic-test-work/pr-metadata-gitea packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh`: passed; verifies standard Gitea fields, fallback branch fields, `refs/pull/<n>/head` label normalization, and nonzero API-error handling.
|
||||
- Installed wrapper parity: `/home/hermes/.config/mosaic/tools/git/{detect-platform.sh,pr-metadata.sh,pr-merge.sh}` byte-match the PR source copies after validation, so active U-Connect wrapper invocations use the same fix while source PR review runs.
|
||||
- Live sanitized U-Connect metadata from `/src/uconnect` with `MOSAIC_CREDENTIALS_FILE=/src/jarvis-brain/credentials.json`:
|
||||
- PR #1905: `number=1905`, `baseRefName=main`, `headRefName=edith/t_39ce717c-authentik-smoke-gate`, `state=open`, `host=git.uscllc.com`.
|
||||
- PR #1908: `number=1908`, `baseRefName=main`, `headRefName=fix/t_23fa9e1d-portal-health-backend`, `state=closed`, `host=git.uscllc.com`.
|
||||
- Merge preflight dry runs from installed wrappers:
|
||||
- PR #1905: `Dry run: would merge PR #1905 on git.uscllc.com with authenticated Gitea API fallback (base=main, method=squash).`
|
||||
- PR #1908: `Dry run: would merge PR #1908 on git.uscllc.com with authenticated Gitea API fallback (base=main, method=squash).`
|
||||
- PR: `https://git.mosaicstack.dev/mosaicstack/stack/pulls/518`, branch `fix/t-a292e96f-gitea-pr-metadata`.
|
||||
- CI: Recent PR/push pipelines failed before clone/test execution due Woodpecker/Kubernetes PVC API timeout: `dial tcp 10.43.0.1:443: i/o timeout`. No repository test step executed in CI; local targeted verification above remains clean.
|
||||
|
||||
## 2026-06-18 — PR #549 functional blocker remediation
|
||||
|
||||
### Assignment
|
||||
|
||||
Coordinator `mos-claude` assigned remediation for PR #549: fix `packages/mosaic/framework/tools/git/pr-metadata.sh` tmpfile cleanup where an `EXIT` trap references function-local `body_file` after the function returns inside `RAW=$(...)`, producing `body_file: unbound variable` on the authenticated success path and failing to clean up safely on early `set -e` exits.
|
||||
|
||||
### Plan
|
||||
|
||||
1. Add a non-vacuous Gitea test that exercises `curl_gitea_pull` with stubbed `curl` and `GITEA_TOKEN` instead of `MOSAIC_GITEA_PR_METADATA_RAW_FILE`.
|
||||
2. Prove the new test is RED against the current PR head.
|
||||
3. Replace the function-local `EXIT` cleanup with robust function-scoped tmpfile cleanup.
|
||||
4. Re-run targeted tests, `bash -n`, and review gates; commit and push branch only. Do not merge.
|
||||
|
||||
### Constraints / assumptions
|
||||
|
||||
- Do not modify prior injection/JSON fixes in `issue-edit`, `issue-assign`, or `milestone-create`.
|
||||
- Worker role: do not modify `docs/TASKS.md`; orchestrator remains the single writer.
|
||||
- Budget: no explicit token cap provided; keep scope to shell wrapper + targeted regression harness.
|
||||
|
||||
### Remediation results
|
||||
|
||||
- Rebased `fix/tooling-eval-injection-jq-json` onto `origin/main`; branch was already current.
|
||||
- Added a curl-stub regression path that does not use `MOSAIC_GITEA_PR_METADATA_RAW_FILE`, so it exercises `curl_gitea_pull` and its temp body file.
|
||||
- RED evidence: copied the new harness next to the pre-fix `HEAD` version of `pr-metadata.sh`; `MOSAIC_TEST_WORK_DIR=$PWD/.mosaic-test-work/pr-metadata-red-work .../test-pr-metadata-gitea.sh` failed with `body_file: unbound variable` on the curl success path.
|
||||
- Fix: replaced `EXIT` temp-file cleanup with a `RETURN`-scoped cleanup function that removes the body file while the function-local variable is still in scope, preserves the original return status, and clears the `RETURN` trap.
|
||||
- GREEN evidence:
|
||||
- `MOSAIC_TEST_WORK_DIR=$PWD/.mosaic-test-work/pr-metadata-gitea-current packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh` passed.
|
||||
- `bash -n packages/mosaic/framework/tools/git/pr-metadata.sh packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh` passed.
|
||||
- `shellcheck -x -P . -e SC1090 packages/mosaic/framework/tools/git/pr-metadata.sh packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh` passed.
|
||||
|
||||
### Review remediation
|
||||
|
||||
- Codex review returned one should-fix: the early-exit test used `chmod 000`, which is not root-safe in container CI.
|
||||
- Remediation: changed the stubbed 2xx/cat-failure mode to replace the curl output with a broken symlink, which fails deterministically even as root and still validates cleanup via `rm -f -- "$body_file"`.
|
||||
|
||||
### Second review remediation
|
||||
|
||||
- Codex review found the 2xx `cat "$body_file"` read could be masked under command substitution semantics because the branch returned 0 unconditionally.
|
||||
- Remediation: both authenticated 2xx branches now use `cat "$body_file" || return $?` before returning success.
|
||||
- Strengthened the broken-symlink test to require the body-read failure and reject the later `Gitea API returned non-JSON` parse-failure path, so the test verifies the helper-level failure propagation rather than eventual downstream failure.
|
||||
|
||||
### Final review gate
|
||||
|
||||
- Codex review after remediation: approved (`0 blockers, 0 should-fix, 0 suggestions`).
|
||||
@@ -1,31 +0,0 @@
|
||||
# Scratchpad: t_301e4e3b pr-merge.sh Gitea empty-uid fallback
|
||||
|
||||
## Task
|
||||
|
||||
Implement a narrow hardening in `packages/mosaic/framework/tools/git/pr-merge.sh` so Gitea merges recover from the known non-interactive `tea pr merge` identity failure: `user does not exist [uid: 0, name: ]`.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Preserve Mosaic policy gates: squash-only, base branch `main`, queue guard unless explicitly skipped.
|
||||
- Preserve the existing authenticated Gitea API fallback when no tea login exists.
|
||||
- Do not fallback on arbitrary tea failures.
|
||||
- Do not expose tokens or credential-bearing remotes.
|
||||
- Scope is limited to the merge wrapper plus focused test/support/scratchpad files.
|
||||
|
||||
## External issue
|
||||
|
||||
- Gitea issue #520: Harden pr-merge.sh Gitea empty-uid fallback
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add a focused shell regression harness with mocked `tea` and `curl` proving the known empty uid/name failure must fall back to Gitea API.
|
||||
2. Watch the harness fail on current code.
|
||||
3. Implement helper functions in `pr-merge.sh` for redacted command display, known failure classification, and authenticated Gitea API merge fallback.
|
||||
4. Keep unknown `tea` failures blocking by replaying stderr and exiting non-zero.
|
||||
5. Run syntax, shellcheck if available, focused regression, and repo quality gates before push/PR.
|
||||
|
||||
## Session log
|
||||
|
||||
- 2026-05-22: Read Kanban context, Mosaic global/repo instructions, created isolated branch `fix/t_301e4e3b-pr-merge-gitea-empty-uid`, and opened Gitea issue #520 using the Mosaic issue wrapper/API fallback.
|
||||
- 2026-05-22: Added regression harness and watched it fail on current behavior with `user does not exist [uid: 0, name: ]`; implemented narrow fallback and verified known-empty-identity fallback, arbitrary tea failure blocking, and no-tea-login API fallback paths.
|
||||
- 2026-05-22: Validation passed for `bash -n`, `shellcheck -x`, focused shell harness, `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, and `pnpm --filter @mosaicstack/mosaic test`. Full `pnpm test` exposed an out-of-scope gateway DB setup failure (`relation "messages" does not exist`) in `apps/gateway/src/__tests__/cross-user-isolation.test.ts`.
|
||||
@@ -1,48 +0,0 @@
|
||||
# t_5aab9cc8 — pr-merge.sh eval injection remediation
|
||||
|
||||
## Objective
|
||||
|
||||
Remediate PR #521 review blocker: `packages/mosaic/framework/tools/git/pr-merge.sh` must reject non-numeric PR numbers before metadata lookup/merge and must not use `eval` for GitHub merge execution.
|
||||
|
||||
## Scope
|
||||
|
||||
- Shell wrapper only: `packages/mosaic/framework/tools/git/pr-merge.sh`
|
||||
- Focused regression harness: `packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh`
|
||||
- No API/frontend/infra surfaces.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- AC1: `PR_NUMBER` is validated as digits-only immediately after required-argument parsing, before metadata lookup.
|
||||
- AC2: GitHub merge path uses a quoted argv array, not command-string construction plus `eval`.
|
||||
- AC3: Focused tests prove PR-number metacharacters are rejected and cannot execute injected shell commands on GitHub path.
|
||||
- AC4: Focused tests prove PR-number metacharacters are rejected on Gitea path before tea/curl merge calls.
|
||||
- AC5: Existing Gitea empty-uid fallback behavior remains green.
|
||||
- AC6: Syntax, shellcheck where available, focused harness, and relevant repo gates are rerun or absence documented.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add failing regression tests for GitHub eval injection and Gitea invalid PR rejection.
|
||||
2. Implement fail-closed PR number validation before metadata lookup.
|
||||
3. Replace GitHub `eval` command with argv array execution.
|
||||
4. Run required validation and update this scratchpad with evidence.
|
||||
5. Commit, queue-guard, push branch, update PR #521.
|
||||
|
||||
## TDD Log
|
||||
|
||||
- RED: `AGENT_WORK_ROOT="$HERMES_KANBAN_WORKSPACE/work" bash packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh` failed on vulnerable code with `Expected GitHub metacharacter PR number to be rejected` and showed the injected PR number reached the GitHub merge path.
|
||||
- GREEN: Added digits-only validation before metadata lookup and replaced GitHub `eval` with an argv array. The focused harness now passes and verifies invalid PR numbers are rejected before GitHub `gh` calls and before Gitea `tea`/`curl` calls.
|
||||
|
||||
## Validation Evidence
|
||||
|
||||
- PASS: `AGENT_WORK_ROOT="$HERMES_KANBAN_WORKSPACE/work" bash -n packages/mosaic/framework/tools/git/pr-merge.sh packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh`
|
||||
- PASS: `shellcheck -x packages/mosaic/framework/tools/git/pr-merge.sh packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh`
|
||||
- PASS: `AGENT_WORK_ROOT="$HERMES_KANBAN_WORKSPACE/work" bash packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh`
|
||||
- PASS: `pnpm --filter @mosaicstack/mosaic... build`
|
||||
- PASS: `pnpm --filter @mosaicstack/mosaic lint`
|
||||
- PASS: `pnpm --filter @mosaicstack/mosaic typecheck`
|
||||
- PASS: `pnpm --filter @mosaicstack/mosaic test` — 32 files / 291 tests passed.
|
||||
- REVIEW: `/home/hermes/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` could not run due Codex 401 Unauthorized. Independent delegate review completed read-only with PASS / no blockers; non-blocking suggestion to assert GitHub mock log remains empty was applied.
|
||||
|
||||
## Risks / Blockers
|
||||
|
||||
- No active blockers.
|
||||
@@ -1,58 +0,0 @@
|
||||
# Task Ownership Gap Fix Scratchpad
|
||||
|
||||
## Metadata
|
||||
|
||||
- Date: 2026-03-13
|
||||
- Worktree: `/home/jwoltje/src/mosaic-mono-v1-worktrees/fix-task-ownership`
|
||||
- Branch: `fix/task-mission-ownership`
|
||||
- Scope: Fix ownership checks in TasksController/MissionsController and extend gateway ownership tests
|
||||
- Related tracker: worker task only; `docs/TASKS.md` is orchestrator-owned and left unchanged
|
||||
- Budget assumption: no explicit token cap; keep scope limited to requested gateway permission fixes
|
||||
|
||||
## Objective
|
||||
|
||||
Close ownership gaps so task listing/creation and mission creation enforce project/mission ownership and reject cross-user access.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. TasksController `list()` enforces ownership for `projectId` and `missionId`, and does not return cross-user data when neither filter is provided.
|
||||
2. TasksController `create()` rejects unowned `projectId` and `missionId` references.
|
||||
3. MissionsController `create()` rejects unowned `projectId` references.
|
||||
4. Gateway ownership tests cover forbidden task creation and forbidden task listing by unowned project.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Inspect current controller and ownership test patterns.
|
||||
2. Add failing permission tests first.
|
||||
3. Patch controller methods with existing ownership helpers.
|
||||
4. Run targeted gateway tests, then gateway typecheck/lint/full test.
|
||||
5. Perform independent review, record evidence, then complete the requested git/PR workflow.
|
||||
|
||||
## TDD Notes
|
||||
|
||||
- Required: yes. This is auth/permission logic and a bugfix.
|
||||
- Strategy: add failing tests in `resource-ownership.test.ts`, verify red, then implement minimal controller changes.
|
||||
|
||||
## Verification Log
|
||||
|
||||
- `pnpm --filter @mosaicstack/gateway test -- src/__tests__/resource-ownership.test.ts`
|
||||
- Red: failed with 2 expected permission-path failures before controller changes.
|
||||
- Green: passed after wiring ownership checks and adding owned-task filtering coverage.
|
||||
- `pnpm --filter @mosaicstack/gateway typecheck`
|
||||
- Pass on 2026-03-13 after fixing parameter ordering and mission project nullability.
|
||||
- `pnpm --filter @mosaicstack/gateway lint`
|
||||
- Pass on 2026-03-13.
|
||||
- `pnpm --filter @mosaicstack/gateway test`
|
||||
- Pass on 2026-03-13 with 3 test files and 23 tests passing.
|
||||
- `pnpm format:check`
|
||||
- Pass on 2026-03-13.
|
||||
|
||||
## Review Log
|
||||
|
||||
- Manual review: checked for auth regressions, cross-user list leakage, and dashboard behavior impact; kept unfiltered task list functional by filtering to owned projects/missions instead of returning an empty list.
|
||||
- Automated review: `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` running/re-run for independent review evidence.
|
||||
|
||||
## Risks / Blockers
|
||||
|
||||
- Repository-wide Mosaic instructions require merge/issue closure, but the user explicitly instructed PR-only and no merge; follow the user instruction.
|
||||
- `docs/TASKS.md` is orchestrator-owned and will not be edited from this worker task.
|
||||
@@ -1,66 +0,0 @@
|
||||
# Scratchpad — Tess Interaction Agent
|
||||
|
||||
## 2026-07-12 — Mission intake
|
||||
|
||||
**Objective:** Build a Pi-native GPT-5.6 Sol high-reasoning Mosaic interaction agent, named Tess, as Jason's primary Discord/CLI access point for Mosaic fleet and transitional Hermes capabilities. Tess complements Mos and must not become a competing orchestrator.
|
||||
|
||||
**Issue:** #706
|
||||
|
||||
**Budget:** No explicit cap provided. Original working estimate was 290K implementation/review tokens. That estimate is superseded after six security prerequisite tasks were added; revised arithmetic total is pending because the calculation tool was blocked by runtime consent. Run at most two workers; prefer one implementation lane plus one independent review/discovery lane. Re-estimate after planning approval and each milestone.
|
||||
|
||||
**Evidence gathered:**
|
||||
- Mosaic already provides Pi lifecycle hooks, fleet/tmux sessions, Matrix connector/controller pieces, typed chat events, Discord/Telegram channel plugins, and command/plugin registries.
|
||||
- Current `IProviderAdapter` is an LLM model/completion abstraction, not an external agent/session provider.
|
||||
- Required new seam is `AgentRuntimeProvider`: sessions, stream, message, terminate, hierarchy, attach, health, capabilities.
|
||||
- Recurring cross-runtime needs: unified memory/retrieval, Discord routing/approvals, agent state/inbox/compaction recovery, runtime bootstrap, fleet/incident controls, and GitOps workflow.
|
||||
- Project truth must remain in canonical project/Mosaic stores; semantic memory is retrieval/mirror.
|
||||
|
||||
**Decisions:**
|
||||
1. Name: Tess (tessera). Stable machine key `tess`; display name configurable.
|
||||
2. Mos owns orchestration; Tess delegates Mos-owned work through an explicit coordination contract.
|
||||
3. Gateway owns ingress/auth/routing; Discord and CLI remain thin clients.
|
||||
4. tmux/fleet ships first behind an adapter; Matrix/native Mosaic is the forward transport.
|
||||
5. Hermes integration is transitional and capability-negotiated; unsupported operations fail closed.
|
||||
6. No unrestricted Discord shell. Privileged/destructive/customer-visible actions require authorization and approval.
|
||||
|
||||
**Plan:**
|
||||
1. Land requirements/architecture/task graph.
|
||||
2. Deliver runtime contracts and security model.
|
||||
3. Deliver durable Pi service/state.
|
||||
4. Deliver Discord and CLI.
|
||||
5. Deliver fleet/Mos/Hermes/memory/tool plugins.
|
||||
6. Deliver Matrix/native transport, migration matrix, recovery, docs, and qualification.
|
||||
|
||||
**Progress:** Issue #706 created. PRD/manifest/tasks initialized on clean branch `feat/tess-interaction-agent` from `origin/main`.
|
||||
|
||||
**Risks:** 14 GB root filesystem headroom; active fleet lanes; broad migration scope; Discord privilege boundary; possible duplicate orchestration authority.
|
||||
|
||||
## 2026-07-12 — Independent planning and threat review
|
||||
|
||||
**Verdict received:** BLOCK TESS-PLAN-001. Coding remains stopped.
|
||||
|
||||
**Blocking findings:** formal threat model absent; verification matrix absent; migration inventory implied but absent; non-existent task paths; AC-TESS-03 lacked a crisp test. Security review also identified command scope bypass, cross-tenant session attachment, MCP actor impersonation, unsafe Discord service ingress, pre-persistence/egress secret leakage, non-durable replay, and globally scoped GC.
|
||||
|
||||
**Remediation applied:**
|
||||
- Added `docs/tess/ARCHITECTURE.md`.
|
||||
- Added `docs/tess/THREAT-MODEL.md` with TM-01..12.
|
||||
- Added `docs/tess/VERIFICATION-MATRIX.md` mapping AC-TESS-01..11.
|
||||
- Added `docs/tess/MIGRATION-INVENTORY.md`.
|
||||
- Added hard requirements TESS-SEC-002..009.
|
||||
- Added six prerequisite security tasks before provider/ingress implementation.
|
||||
- Corrected task paths to existing package surfaces.
|
||||
- Added explicit GPT-5.6 Sol/high/tool-policy status verification for AC-TESS-03.
|
||||
|
||||
**Re-review 1:** BLOCK only on composite `repo` values that looked like nonexistent paths. Remediated by declaring comma-separated roots and validating every root.
|
||||
|
||||
**Final focused review:** PASS. Deterministic audit validated all task repository roots with zero missing paths; no planning placeholders remained; security prerequisites still gate Tess exposure; observability traceability is explicit.
|
||||
|
||||
**Current gate:** planning PR must merge to `main` with terminal-green CI before any source-code worker starts.
|
||||
|
||||
## 2026-07-13 — M3 cross-surface delivery
|
||||
|
||||
**Branch:** `feat/tess-m3-integration` from `main` at `84d884b9`.
|
||||
|
||||
**Delivered:** Stable Discord `conversationId` enrollment after a visible provider/runtime session is known; idempotent provider-session rebinding that preserves agent/tenant/owner scope; Discord approval/stop target resolution through the durable snapshot; SSE runtime streaming after CLI attach; denial/audit parity including provider authorization denials and HTTP 403 approval-denial mapping.
|
||||
|
||||
**Evidence:** Gateway targeted suite: 37 tests passed; Mosaic CLI interaction test passed; agent durable-session test passed; gateway and CLI typechecks passed; changed-file format and whitespace checks passed. Codex security review found no confident vulnerability. Code review identified a Fastify exception-response mismatch and two UX/acknowledgement issues; all were corrected before the final validation run.
|
||||
@@ -1,38 +0,0 @@
|
||||
# TESS-M1-002 — Provider Registry
|
||||
|
||||
- **Issue:** #707
|
||||
- **Branch:** `feat/tess-provider-registry`
|
||||
- **Objective:** Build the runtime provider registry/service boundary that derives immutable actor/tenant/channel/correlation scope server-side, fail-closes unsupported and destructive runtime operations, binds termination approval to the exact structured action, and emits correlation-safe audit events.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add a provider-agnostic registry in `@mosaicstack/agent` over the merged `AgentRuntimeProvider` contract.
|
||||
2. Write abuse-case tests before implementation for duplicate/unknown providers, immutable server-derived scope, capability denial, approval mismatch/absence, and audit failure.
|
||||
3. Implement the Gateway service that converts only authenticated `ActorTenantScope` plus trusted ingress metadata into a frozen `RuntimeScope`, gates capabilities and terminate approval, and records metadata-only audits.
|
||||
4. Register the service in `AgentModule`, then run focused, baseline, cold-cache, and independent-review gates.
|
||||
|
||||
## Security Invariants
|
||||
|
||||
- Caller-supplied actor/tenant identity never reaches runtime providers.
|
||||
- Provider capability absence and approval/audit failure deny before side effects.
|
||||
- Termination approval is verified against provider, session, actor, tenant, channel, and correlation context.
|
||||
- Audit events retain correlation and authority metadata but never message content or approval material.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-07-12: Created fresh worktree from `origin/main` at `119f64e6`; source and Tess planning/security documentation reviewed.
|
||||
- 2026-07-12: Security TDD added registry and gateway abuse tests before implementation.
|
||||
- 2026-07-12: Implemented `AgentRuntimeProviderRegistry` and gateway `RuntimeProviderService`; registered both in `AgentModule` and documented the internal boundary.
|
||||
- 2026-07-12: Independent review found two audit correctness issues. Remediated completion-audit failure handling and provider execution failures: pre-invocation denials are audited as `denied`; post-invocation errors as `failed`; completion audit failure does not misreport a completed effect as retryable.
|
||||
- 2026-07-12: Final independent security review: no findings. Final code review had one false positive: `@mosaicstack/types` is already declared in `packages/agent/package.json`.
|
||||
|
||||
## Tests
|
||||
|
||||
- TDD red: `pnpm --filter @mosaicstack/gateway test -- runtime-provider-registry.service.test.ts` failed before both audit remediations, as expected.
|
||||
- Focused: package registry 2 tests and gateway security boundary 7 tests pass.
|
||||
- Cold-cache: removed this worktree's `node_modules`, then `pnpm install --offline --frozen-lockfile --store-dir /home/jarvis/.local/share/pnpm/store` passed.
|
||||
- Cold-cache baseline: `TURBO_FORCE=true pnpm typecheck` — 42/42 tasks passed; `TURBO_FORCE=true pnpm lint` — 23/23 tasks passed; `TURBO_FORCE=true pnpm format:check` passed; `TURBO_FORCE=true pnpm test` — 42/42 tasks passed (gateway 548 tests passed, 11 intentionally skipped).
|
||||
|
||||
## Risks / Blockers
|
||||
|
||||
- The canonical durable approval implementation is currently command-specific. This card introduces a fail-closed runtime approval verifier boundary so a runtime provider cannot terminate until its exact-action verifier is wired; later provider implementations cannot bypass it.
|
||||
@@ -1,75 +0,0 @@
|
||||
# TESS-M1-003 — Fleet/tmux Runtime Provider
|
||||
|
||||
- **Task:** `TESS-M1-003`
|
||||
- **Issue:** `#707`
|
||||
- **Branch:** `feat/tess-fleet-provider`
|
||||
- **PR target:** `main`
|
||||
- **Budget:** 30K estimate from `docs/tess/TASKS.md`; work remains scoped to `packages/mosaic`, `packages/agent`, and Tess architecture/scratchpad documentation.
|
||||
|
||||
## Objective
|
||||
|
||||
Implement `TESS-FLT-001` as a tmux/fleet `AgentRuntimeProvider` on the M1 registry contract. Operations must use roster-bound, exact tmux targets; fail closed on missing or mismatched peer identity; allow read-only attach only; use exact-target message delivery and termination; and expose no arbitrary shell, socket, or fuzzy session targeting.
|
||||
|
||||
## Requirements and Security Invariants
|
||||
|
||||
- `TESS-FLT-001`: fleet roster/status/heartbeat inspection, message delivery, session hierarchy, safe attach, controlled termination/recovery.
|
||||
- `TESS-ARP-001` / `TESS-TRN-001`: conform to the runtime provider contract and advertise only implemented capabilities.
|
||||
- TM-10: exact target/socket binding and peer identity verification; wrong socket, target, or identity must refuse delivery/attach.
|
||||
- Gateway supplies immutable actor/tenant/channel/correlation scope and consumes durable termination approvals before provider invocation.
|
||||
- `control` attach is denied. A provider attach is a scoped read-only logical handle; it never opens a server-side interactive terminal or exposes a raw tmux target.
|
||||
- M2 will make durable attachment/session state available. This M1 provider does not claim durable attachment handles or durable message idempotency.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add security TDD cases first for fuzzy/unrostered targets, incorrect socket/identity, control attach, attachment scope replay, and termination exact targeting.
|
||||
2. Add Mosaic fleet primitives for exact target validation and identity probing from the roster/socket.
|
||||
3. Implement and export the fleet/tmux provider in `@mosaicstack/agent`, using only those primitives and a command-runner seam.
|
||||
4. Update Tess architecture docs and this evidence log.
|
||||
5. Run focused tests, independent code/security reviews, cold-cache forced gates, then create a PR with `Refs #707`.
|
||||
|
||||
## Branch/Base Note
|
||||
|
||||
The orchestrator corrected the initial brief: `feat/tess-interaction-agent` is a stale planning branch. This branch was correctly created from `origin/main` at `e92186d7` (including M1-002) and will open a clean PR to `main` with `Refs #707`.
|
||||
|
||||
## Progress
|
||||
|
||||
- [x] Read PRD, Tess architecture, threat model, runtime contract, registry, fleet command primitives, task record, and issue #707.
|
||||
- [x] Created clean worktree from `origin/main` at `e92186d7`.
|
||||
- [x] Security TDD tests written before implementation; initially failed because the transport/provider modules did not exist.
|
||||
- [x] Fleet transport and capability-limited provider implemented; read/list/attach and direct Tess write/control default to deny pending scope-aware authority adapters.
|
||||
- [x] Focused typecheck, lint, formatting, and abuse tests passed (transport: 7; provider: 14).
|
||||
- [x] Cold-cache forced workspace gates passed after reinstall; final workspace gates also passed.
|
||||
- [x] Independent Codex code and security reviews passed with no findings.
|
||||
|
||||
## Verification Evidence
|
||||
|
||||
- `pnpm --filter @mosaicstack/mosaic typecheck` — pass.
|
||||
- `pnpm --filter @mosaicstack/agent typecheck` — pass.
|
||||
- `pnpm --filter @mosaicstack/mosaic lint` — pass.
|
||||
- `pnpm --filter @mosaicstack/agent lint` — pass.
|
||||
- `pnpm --filter @mosaicstack/mosaic test -- src/fleet/tmux-runtime-transport.test.ts` — 7 passed.
|
||||
- `pnpm --filter @mosaicstack/agent test -- src/tmux-fleet-runtime-provider.test.ts` — 14 passed.
|
||||
- The worktree dependency install must use `--store-dir /home/jarvis/.local/share/pnpm/store` because machine pnpm config points to an unreadable root-owned store. This is a local tool configuration issue, not an application workaround.
|
||||
|
||||
## Documentation Checklist
|
||||
|
||||
- [x] Canonical PRD and Tess architecture are current for this internal provider; no HTTP/API endpoint changed.
|
||||
- [x] `docs/tess/ARCHITECTURE.md` documents the internal fleet target/identity, read-only attach, and Mos authority boundary.
|
||||
- [x] No user/admin/API sitemap updates are applicable because no user-facing or HTTP API surface was introduced.
|
||||
|
||||
## Acceptance Criteria to Evidence
|
||||
|
||||
| Acceptance criterion | Evidence target |
|
||||
| --- | --- |
|
||||
| Only roster-bound exact targets are operated | Provider abuse tests prove unknown/prefix targets yield typed denial and runner is untouched. |
|
||||
| Socket and peer runtime identity are exact | Provider abuse tests prove wrong socket/no pane/runtime drift deny before send/attach/terminate. |
|
||||
| Message sends are capability-safe and exact | Tests assert the maintained sender receives only the configured socket and exact roster session. |
|
||||
| Fleet reads cannot cross an authority boundary | Tests prove list and read attach default-deny without a scope-aware read authority; per-target authority filtering is enforced. |
|
||||
| Attach cannot grant control or replay across scope | Tests deny `control`; attachment handles are random, scoped, short-lived, single-use for detach, and pruned after expiry. |
|
||||
| Termination is exact and caller cannot select arbitrary target | Tests assert roster/identity validation precedes exact `tmux kill-session -t =<agent>`. Gateway tests from M1-002 cover approval consumption. |
|
||||
| Documentation describes the boundary | `docs/tess/ARCHITECTURE.md` documents fleet capability, scope, and non-goals. |
|
||||
|
||||
## Risks / Decisions
|
||||
|
||||
- Runtime process identity can only be verified from the declared fleet roster and exact tmux pane command in M1. The tmux server itself is a trusted local transport boundary; stronger authenticated peer attestations are deferred to the Matrix/native provider.
|
||||
- The current roster schema does not encode per-agent tenant/owner. Scope-aware read/write authority adapters remain the integration point for gateway/Mos ownership policy; provider scope is bound to logical attachment handles to prevent replay.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user