chore: consolidate new foundation and archive v1 (#1495)
This commit is contained in:
@@ -0,0 +1,76 @@
|
||||
---
|
||||
kind: record
|
||||
status: active
|
||||
---
|
||||
|
||||
# #1019 — Zero-timeout queue-guard harness race
|
||||
|
||||
- **Issue:** #1019 (parent status remains `believed-fixed, pending jarvis validation`; do not close)
|
||||
- **Branch:** `fix/1019-ci-queue-timeout-harness`
|
||||
- **Owner:** `be-coder-08`
|
||||
- **Base:** `origin/main` at `5916aeefd6ed12bcac086c6834c7f6c4ae38e1bc`
|
||||
- **Charter:** `/home/hermes/agent-work/tl-mosaic/CHARTER-1019-HARNESS-FIX.md`
|
||||
|
||||
## Objective
|
||||
|
||||
Make `test-ci-queue-wait-tristate.sh` deterministic without changing any asserted outcome. Remove the indiscriminate zero-timeout race, require every status-classification case to prove the provider was observed, and prove the harness-controlled virtual clock is active.
|
||||
|
||||
## Scope
|
||||
|
||||
- In scope: `packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh` only, plus this evidence scratchpad.
|
||||
- Out of scope: guard parsers, D2/D3 behavior, installer/reseed staleness, PR #1060, and issue closure.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
1. RED deterministically reproduces deadline pre-emption before the provider call.
|
||||
2. Every case that intends status classification positively proves provider observation.
|
||||
3. Pending observes `pending` before deterministic virtual-time expiration.
|
||||
4. The virtual clock has a positive interception control; a broken-clock mutant makes the suite red.
|
||||
5. The exact CI-base image passes the final harness repeatedly with zero failures.
|
||||
6. Baseline gates, independent code/security review, exact-head CI, and coordinator-authorized squash merge pass.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add deterministic RED instrumentation for the known merge/provider-unreachable pre-emption.
|
||||
2. Replace global `-t 0` with a nonzero timeout interpreted under an event-driven virtual clock; stub sleep without wall waiting.
|
||||
3. Add provider-observation and virtual-clock positive controls without changing outcome assertions.
|
||||
4. Run focused shell checks, repeat in exact CI-base image, baseline gates, and independent reviews.
|
||||
5. Commit with both identity layers, queue-guard plus direct Woodpecker terminal-state verification, push, self-post PR, verify poster/head/CI, obtain coordinator merge authorization, then squash merge without closing #1019.
|
||||
|
||||
## Budget
|
||||
|
||||
- No explicit token cap supplied. Keep scope to one harness file and one scratchpad; stop/report at the charter's 60% context gate.
|
||||
|
||||
## Evidence
|
||||
|
||||
- RED, deterministic pre-provider expiry: `evidence/1019-harness-fix/red-pre-provider-expiry.log` — rc 1; merge/provider-unreachable got rc 124 instead of 75, omitted CANNOT_ASSERT, did not observe the status provider, and wrote no additional audit record (four named failures).
|
||||
- GREEN host focused harness: `evidence/1019-harness-fix/green-host.log` — rc 0, all outcome classes passed.
|
||||
- Load-bearing clock negative control: a temporary same-directory mutant replaced the virtual `date` body with `/bin/date`; `evidence/1019-harness-fix/red-clock-not-intercepted.log` — rc 1 with named `virtual clock interception did not run` failures. The mutant file was removed after the run.
|
||||
- Exact CI-base repeat: `git.mosaicstack.dev/mosaicstack/stack/ci-base:latest`, repository mounted read-only, harness work under container `/tmp`; `evidence/1019-harness-fix/ci-image-repeat/summary.log` — **100 pass / 0 fail / 100 total**.
|
||||
- Synchronization design: provider-status observation creates the event marker; virtual time is 1000 before the event and 1002 afterward. Pending alone reaches the stubbed no-op sleep and a post-observation deadline check. `-t 1` is uniquely load-bearing because removing it restores the 900-second default deadline at virtual time 1900, which 1002 does not cross. The numeric timeout is subject semantics under virtual time, not a wall-clock synchronization duration.
|
||||
|
||||
## Review remediation — semantic timeout vs. liveness bound
|
||||
|
||||
Security review found that virtual time remained at 1000 forever before provider observation and stubbed sleep never waited. A regression looping before the status endpoint—or blocking in the first provider call—therefore could prevent `run_guard` from returning, so the post-return provider assertion could never fire.
|
||||
|
||||
**General rule:** A timeout usually serves two purposes: semantics and liveness. Removing wall time from semantic synchronization can silently remove the only independent hang bound. Preserve deterministic virtual time for subject semantics, but provide a separately implemented real-clock liveness watchdog and prove that watchdog fires.
|
||||
|
||||
Remediation:
|
||||
|
||||
- Every guard subject invocation is launched by absolute `/usr/bin/python3` in a new session. Python's internal monotonic `wait(timeout=...)` provides real-clock liveness independently of PATH; expiry kills the entire isolated process group, so neither PATH-front shims nor a blocked provider descendant can retain the capture pipe.
|
||||
- Watchdog expiry returns distinct harness rc 90 plus `FAIL HANG watchdog`, separate from subject timeout rc 124.
|
||||
- A first attempt using absolute `/usr/bin/timeout -s KILL` passed on GNU coreutils but failed in the exact Alpine CI-base image: BusyBox killed the immediate wrapper while the guard/provider descendants survived and retained the command-substitution pipe. The process-group kill is therefore required behavior, not portability polish.
|
||||
- A committed positive control hangs the branch-provider stub before the status endpoint. It must terminate through the watchdog, emit the hang-specific diagnostic, return rc 90, and prove the status provider was never reached.
|
||||
- RED before remediation: a temporary ordinary-success mutant hung before provider observation; only an external control could kill the suite (rc 137), and there was no internal hang-specific diagnostic (`red-watchdog-absent.log`).
|
||||
- The watchdog mutant/control is load-bearing: removing the internal watchdog leaves the control unable to produce its required rc 90 and diagnostic.
|
||||
|
||||
Post-review evidence:
|
||||
|
||||
- Host focused harness with process-group watchdog: rc 0 (`green-watchdog-process-group-host.log`).
|
||||
- Exact Alpine CI-base focused harness with process-group watchdog: rc 0 (`green-watchdog-ci-image.log`).
|
||||
- Hanging ordinary-success mutant: suite rc 1; success returned rc 90, emitted `FAIL HANG watchdog`, and loudly reported that provider/clock observation did not occur (`red-watchdog-fires.log`).
|
||||
- Removed-`-t 1` mutant: suite rc 1; pending was terminated by the watchdog instead of producing `ASSERTED_NOT_READY`, proving the explicit timeout is load-bearing (`red-timeout-argument-removed.log`).
|
||||
|
||||
## 60% context hold
|
||||
|
||||
Stopped before baseline/review/commit as required by the charter. Remaining: inspect final diff, shell/static/baseline gates, independent code/security review, remediation if any, identity-bound commit/trailer verification, mandatory queue guard plus direct terminal Woodpecker `mosaic` enumeration, push, self-posted PR/provider poster read-back, exact-head terminal-green CI, coordinator merge authorization, squash merge, main CI verification, and leave #1019 unclosed as `believed-fixed, pending jarvis validation`.
|
||||
@@ -0,0 +1,234 @@
|
||||
---
|
||||
kind: record
|
||||
status: active
|
||||
---
|
||||
|
||||
# #1043 — Fleet pane git-identity propagation
|
||||
|
||||
## Objective
|
||||
|
||||
Ensure a fleet seat's launched runtime process receives its roster-derived `MOSAIC_GIT_IDENTITY`, and lock the complete generated-environment propagation boundary with an enumerated set comparison.
|
||||
|
||||
## Tracking
|
||||
|
||||
- External issue: `mosaicstack/stack#1043`
|
||||
- Branch: `fix/1043-pane-git-identity`
|
||||
- Coordinator: `tl-mosaic`
|
||||
- `docs/TASKS.md`: read-only by project worker contract; not modified.
|
||||
|
||||
## Constraints
|
||||
|
||||
- RED-first bug reproducer is mandatory.
|
||||
- R7 delete-the-subject mutation must turn the behavioral test red.
|
||||
- Assert launched-process environment, not source text.
|
||||
- One push only; do not poll CI after push.
|
||||
- Run the CI queue guard immediately before push and report its `state=` line as state, not evidence.
|
||||
- Do not modify a live host launcher or obtain/copy another credential.
|
||||
- Self-post the PR, verify provider attribution, then stop.
|
||||
- Final status wording: `believed-fixed, pending jarvis validation`.
|
||||
|
||||
## Scope inventory
|
||||
|
||||
Re-derived against `origin/main` at `85d2108e`:
|
||||
|
||||
- Launch consumer: `packages/mosaic/framework/tools/fleet/start-agent-session.sh`
|
||||
- Behavioral launch test: `packages/mosaic/framework/tools/fleet/test-start-agent-session.sh`
|
||||
- Generated-environment contract/parser: `packages/mosaic/src/fleet/generated-env-boundary.ts`
|
||||
- Roster projection producers:
|
||||
- `packages/mosaic/src/commands/fleet.ts`
|
||||
- `packages/mosaic/src/fleet/fleet-reconciler.ts`
|
||||
- `packages/mosaic/src/fleet/fleet-agent-crud.ts`
|
||||
- `packages/mosaic/src/fleet/v1-v2-migration.ts`
|
||||
- Contract and producer tests discovered by repository search.
|
||||
- Generated-environment operator/developer docs and their executable documentation contract test.
|
||||
|
||||
Discrepancy sent to `tl-mosaic`: current main no longer contains the charter's `PANE_SHELL_SNIPPET`; #772 replaced it with an `/usr/bin/env -i` argv launch boundary, and current generated projections do not declare git identity. Code-read inventory is **NOT MEASURED** behavior.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add the process-environment set-comparison regression first and record RED.
|
||||
2. Add roster-derived `MOSAIC_GIT_IDENTITY=<agent name>` to the complete generated projection contract.
|
||||
3. Validate identity syntax and equality with `MOSAIC_AGENT_NAME`; pass it through the clean pane environment.
|
||||
4. Update affected projection tests and generated-environment docs.
|
||||
5. Run focused and baseline gates.
|
||||
6. Perform R7 by deleting the pane propagation entry, prove RED, restore, and prove GREEN.
|
||||
7. Run independent review, remediate, commit, queue guard, one push, self-post PR, verify provider attribution, and stop without CI polling.
|
||||
|
||||
## Budget
|
||||
|
||||
No explicit token cap was provided. Working cap: one narrow logical unit, no dependency installation unless existing tooling requires it, no unrelated refactor.
|
||||
|
||||
## Evidence log
|
||||
|
||||
### TDD and mutation evidence
|
||||
|
||||
- RED-first, repository launcher: `bash packages/mosaic/framework/tools/fleet/test-start-agent-session.sh` exited 64 on pre-fix source with `code=unknown-key key=MOSAIC_GIT_IDENTITY`. The generated seat could not launch with the required declared identity.
|
||||
- GREEN: the same repository launcher test emitted `ok - start-agent-session generated environment boundary`.
|
||||
- R7 delete-the-subject: removed only `"MOSAIC_GIT_IDENTITY=$MOSAIC_GIT_IDENTITY"` from the repository launch array; the same test exited 1 with `FAIL: runtime pane omitted or changed generated environment keys: MOSAIC_GIT_IDENTITY`.
|
||||
- R7 restoration: restored that launch entry; the same test returned green.
|
||||
- Launcher under test is explicitly `packages/mosaic/framework/tools/fleet/start-agent-session.sh` through the test's `$START`, **not** the stale installed host copy.
|
||||
|
||||
### Situational and focused tests
|
||||
|
||||
- Repository launcher boundary: green, including set comparison of all nine generated projection entries and fail-before-tmux cases for missing, unsafe, mismatched, and local-shadow Git identity.
|
||||
- Fleet systemd launcher integration: `bash packages/mosaic/framework/systemd/user/test-fleet-units.sh` — green.
|
||||
- Focused Mosaic Vitest set: 6 files, 311 tests — green.
|
||||
- `bash -n` on changed shell files — green.
|
||||
- `git diff --check` — green.
|
||||
|
||||
### Baseline gates
|
||||
|
||||
- `pnpm typecheck` — 45/45 tasks green.
|
||||
- `pnpm lint` — 25/25 tasks green.
|
||||
- `pnpm format:check` — green.
|
||||
- `pnpm test:checkout` — green.
|
||||
- Repository-wide Vitest under a hermetic current-version npm prefix: Mosaic 81/81 files and 1510/1510 tests green; other workspace test tasks shown green before the framework-shell phase.
|
||||
- Canonical `pnpm test` is not fully green on this host for unrelated environment-sensitive gates:
|
||||
1. the first two runs exposed the globally installed Mosaic 0.0.48 update banner in three CLI smoke tests expecting empty stderr;
|
||||
2. after isolating that global-version input, the framework wake assertion aborted at the known `#973` Bash `BASH_LINENO` convention check (exit 97; observed `[3 5]`, expected `[3 4]`).
|
||||
No tests were weakened or bypassed; focused changed-surface tests are green. CI remains the canonical clean-environment result and is intentionally not polled after push per charter.
|
||||
|
||||
### Independent review
|
||||
|
||||
- Codex code review first pass: request changes for missing shell rejection-path coverage.
|
||||
- Remediation: added table-driven missing/unsafe/mismatch/local-shadow launcher cases, each asserting no tmux call.
|
||||
- Codex code re-review: **approve**, no findings, confidence 0.88.
|
||||
- Codex security review: risk `none`, no findings, confidence 0.97.
|
||||
|
||||
### Acceptance criteria mapping
|
||||
|
||||
| Acceptance criterion | Evidence |
|
||||
| --- | --- |
|
||||
| AC-FGI-01: launched process receives every generated key/value | Repository launcher process-environment `comm -23` set comparison; GREEN and R7 RED evidence above |
|
||||
| AC-FGI-02: missing, unsafe, or split identity fails before tmux | Table-driven shell cases plus TypeScript generated-boundary tests |
|
||||
| AC-FGI-03: focused/baseline/review evidence recorded | Commands and review outcomes above; host-sensitive full-suite limitations stated explicitly |
|
||||
|
||||
### Documentation checklist
|
||||
|
||||
- PRD updated with #1043 requirements and acceptance criteria.
|
||||
- Fleet launch runbook, generated-env concept, and generated-env reference updated.
|
||||
- No API/OpenAPI, sitemap, user publishing target, deployment, or external docs publication change applies.
|
||||
- `docs/TASKS.md` remains unmodified per its single-writer project contract.
|
||||
|
||||
## Round 2 — PR #1073 review 97 remediation
|
||||
|
||||
### Review blocker
|
||||
|
||||
The launched-process suite was signed-excluded from CI enumeration. Manual GREEN/R7 evidence therefore did not prove a PR workflow could detect regression.
|
||||
|
||||
### RED-first and canonical wiring
|
||||
|
||||
1. Removed the suite's signed exclusion before adding a CI execution path.
|
||||
2. `check-test-enumeration.sh` went RED with exact `UNENUMERATED` output for `test-start-agent-session.sh`: population 49, enumerated 30, excluded 18.
|
||||
3. Added both `framework/tools/fleet/test-start-agent-session.sh` and `framework/systemd/user/test-fleet-units.sh` to `@mosaicstack/mosaic`'s canonical `test:framework-shell` chain.
|
||||
4. The guard returned GREEN: population 49, enumerated 32, excluded 18, surfaces 45. The systemd suite is outside the guard's tools-only population but now has the same explicit canonical execution disposition.
|
||||
|
||||
### Workflow-level R7
|
||||
|
||||
- Deleted only the pane launch entry `"MOSAIC_GIT_IDENTITY=$MOSAIC_GIT_IDENTITY"`.
|
||||
- Ran the exact `.woodpecker/ci.yml` test-step command, `pnpm test`, with only a temporary PATH-scoped npm shim reporting the checkout's current 0.0.49 version so the unrelated global 0.0.48 banner could not preempt the shell chain.
|
||||
- Result: exit 1 at `@mosaicstack/mosaic#test`, with the enumeration guard GREEN followed by `FAIL: runtime pane omitted or changed generated environment keys: MOSAIC_GIT_IDENTITY`.
|
||||
- Restored the launch entry. The canonical `test:framework-shell` chain then reached both newly wired suites and printed both GREEN markers before the known unrelated #973 host-only `BASH_LINENO` abort.
|
||||
- An actual provider PR workflow on the intentionally broken mutant is **NOT MEASURED**: the one-push constraint forbids pushing a red mutant and then a repaired head. Local execution proves the exact PR workflow command and dependency chain go RED on the subject deletion; CI on the repaired pushed head remains canonical.
|
||||
|
||||
### Workflow population
|
||||
|
||||
- **DEFINED:** 3 workflows (`ci.yml`, `ci-image.yml`, `publish.yml`).
|
||||
- **ELIGIBLE for `pull_request`:** 1/3 (`ci.yml`), based on top-level `when:` clauses.
|
||||
- **REPORTED:** Round-1 exact-head provider read reported 1/1 eligible context (`ci/woodpecker/pr/ci`). Post-remediation-head reported count is **NOT MEASURED** by this seat because CI polling is prohibited; workflow definitions and eligibility did not change.
|
||||
|
||||
### Independent remediation review
|
||||
|
||||
- First Round-2 review identified a CI-image blocker: the newly wired launcher suite used Perl, which the Alpine CI base does not install.
|
||||
- Replaced the suite's three Perl-only fixture mutations with POSIX/BusyBox-compatible `sed -i` substitutions; production behavior and assertions are unchanged.
|
||||
- Codex re-review: **APPROVE**, confidence 0.93, no findings.
|
||||
|
||||
### Vitest denominator reconciliation
|
||||
|
||||
The PR's `311/311` is correct for its explicitly named six-file command at both the original and remediation worktrees:
|
||||
|
||||
- generated environment boundary: 24
|
||||
- fleet documentation: 23
|
||||
- Tess service profile: 6
|
||||
- fleet regen command: 27
|
||||
- fleet agent CRUD command: 22
|
||||
- fleet command: 209
|
||||
- total: **311**
|
||||
|
||||
Review 97 reported 312/312 without naming its six files. That is a different or miscounted population and cannot replace the command-scoped 311 denominator; the PR follow-up will name the exact files and arithmetic.
|
||||
|
||||
## Round 3 — Alpine stale-marker portability
|
||||
|
||||
### Objective and plan
|
||||
|
||||
- Replace the GNU-only relative-date fixture with a deterministic POSIX/BusyBox timestamp while preserving the required stale-marker assertion.
|
||||
- Re-run the launcher suite in the canonical `ci-base:latest` Alpine image, then run applicable repository gates and independent review.
|
||||
- Update the PR body to name the repeated GNU-host/Alpine-CI portability pattern, run the mandatory queue guard, push once, verify provider attribution, and stop without CI polling.
|
||||
- Working budget: 8K tokens; scope is one fixture line plus delivery evidence. No production behavior changes.
|
||||
|
||||
### RED-first evidence
|
||||
|
||||
Before the fix, the canonical CI image command
|
||||
`docker run --rm -v "$PWD:/work" -w /work git.mosaicstack.dev/mosaicstack/stack/ci-base:latest bash packages/mosaic/framework/tools/fleet/test-start-agent-session.sh`
|
||||
exited 1 at the stale-marker setup with exact BusyBox output
|
||||
`touch: invalid date '10 seconds ago'`. The prior fresh-marker assertions had already executed, matching pipeline 2233's failure location.
|
||||
|
||||
### Root cause and fix
|
||||
|
||||
The test used GNU `touch -d` relative-date parsing although the PR workflow runs on Alpine/BusyBox. The fixture now uses POSIX `touch -t 200001010000.00`, a fixed timestamp that is unconditionally stale; the stale assertion remains mandatory and was not made tolerant of missing timestamp metadata.
|
||||
|
||||
### Structural pattern
|
||||
|
||||
This is the third GNU-host/Alpine-CI portability defect in the lane: GNU `grep` multi-match counting, Perl-only fixture mutation, and GNU `touch -d` date parsing. The repeated cause is shell suites authored on a GNU host but executed in an Alpine CI image; durable prevention belongs in CI-image execution or portability lint, not assertion weakening.
|
||||
|
||||
### GREEN and quality evidence
|
||||
|
||||
- Focused launcher suite in `ci-base:latest`: exit 0, `ok - start-agent-session generated environment boundary`.
|
||||
- Canonical test step in `ci-base:latest` with the pipeline's `pgvector/pgvector:pg17` service, readiness check, migration, and `pnpm test`: exit 0; 46/46 Turbo tasks; Mosaic 81/81 files and 1510/1510 tests; Gateway 57 passed/5 skipped files and 629 passed/11 skipped tests; enumeration 49 population / 32 enumerated / 18 signed exclusions / 45 named surfaces.
|
||||
- The first image-only `pnpm test` attempt lacked the pipeline PostgreSQL service and failed only on connection refusal after the launcher suite was GREEN. The rerun supplied the canonical service precondition and passed.
|
||||
- Canonical-image baseline: typecheck 45/45 tasks, lint 25/25 tasks, format check GREEN; `git diff --check` GREEN.
|
||||
- Independent Codex code review: APPROVE, confidence 0.96, 2/2 Round-3 files, no findings.
|
||||
- Independent Codex security review: risk none, confidence 0.99, 2/2 Round-3 files, no findings.
|
||||
|
||||
### Re-derived inventory and denominators
|
||||
|
||||
- Round-3 git delta: **2/2 files** — launcher suite and task scratchpad; 25 insertions / 1 deletion before evidence finalization.
|
||||
- Full PR path inventory against `origin/main` at `85d2108e`: **19/19 changed paths**; Round 3 adds no new PR path.
|
||||
- Workflow definition population: **1/3 pull-request-eligible** (`ci.yml` of `ci.yml`, `ci-image.yml`, `publish.yml`).
|
||||
- Do not re-litigate the settled 311/312 populations; both are valid for their separately named Tess6 and CRUD-core7 sets.
|
||||
|
||||
## Round 4 — bound stale-marker observation
|
||||
|
||||
### Objective and plan
|
||||
|
||||
- Make the heartbeat assertion discriminate an initially stale native marker from a fresh marker without changing the production staleness threshold or shortening the polling window.
|
||||
- Freeze only the sidecar's numeric observation clock during the stale-fixture arm so elapsed assertion time cannot turn a fresh mutant stale.
|
||||
- Prove two independent mutants RED: disable production stale-marker detection while retaining the stale fixture; replace the stale fixture with a fresh marker. Restore the tree and prove GREEN in the canonical Alpine image.
|
||||
- Re-derive the changed-path inventory, run applicable quality and independent review gates, commit with environment-only author/committer identity, queue-guard, push once, verify provider attribution using curl stdin config, and stop without CI polling.
|
||||
- Working budget: 8K tokens. Scope is the launcher test and its scratchpad evidence; production launcher behavior remains unchanged.
|
||||
|
||||
### Root cause and bounded observation
|
||||
|
||||
The 30 × 0.1-second assertion window overlaps the production `now - marker > interval * 2 + 1` threshold at interval 1. Depending on second boundaries and load, a fresh marker can age past the threshold before the assertion ends. A focused pre-fix fresh-mutant attempt returned RED while Review 101's full-suite run returned GREEN; the differing result is itself timing dependence, not a discriminating assertion.
|
||||
|
||||
The test now supplies a fixed numeric epoch only to the stale-fixture sidecar. Its real marker mtime is still read from the filesystem, but assertion runtime cannot advance `now`. Date formatting still delegates to the image's real `/bin/date`. Neither the production threshold nor the 30 × 0.1-second polling window changed.
|
||||
|
||||
### Two-mutant RED / restored GREEN
|
||||
|
||||
All three runs used `git.mosaicstack.dev/mosaicstack/stack/ci-base:latest`:
|
||||
|
||||
1. **Stale-detection mutant RED:** replaced only the production stale-age predicate with `false` while retaining the fixed stale marker; suite exit 1 with `FAIL: heartbeat sidecar did not resume after native marker became stale or absent`.
|
||||
2. **Fresh-marker mutant RED:** replaced only `touch -t 200001010000.00` with fresh `touch`; suite exit 1 with the same failed stale-resumption assertion. The fixed observation epoch kept the mutant fresh throughout all 30 polls.
|
||||
3. **Restored tree GREEN:** suite exit 0 with `ok - start-agent-session generated environment boundary`.
|
||||
|
||||
### Re-derived inventory
|
||||
|
||||
- Round-4 delta: **2/2 files** — launcher test plus task scratchpad; production launcher delta is empty.
|
||||
- Full PR inventory against `origin/main`: **19/19 paths**; Round 4 adds no path.
|
||||
- Production stale threshold remains `now - marker > iv * 2 + 1`; assertion polling remains 30 × 0.1 seconds.
|
||||
- Review 101's confirmed enumeration/workflow/CI and attribution evidence is accepted without re-polling or re-derivation.
|
||||
|
||||
## Residual risk
|
||||
|
||||
- Landing on `main` does not update the currently installed host launcher. Host framework installation/reseed and Jarvis live-seat validation are separate downstream events.
|
||||
- Canonical CI result is pending and will not be polled by this seat.
|
||||
@@ -0,0 +1,102 @@
|
||||
---
|
||||
kind: record
|
||||
status: active
|
||||
---
|
||||
|
||||
# #1098 — Framework shell portability / red main
|
||||
|
||||
## Objective
|
||||
|
||||
Restore terminal-green `main` by making the `test-start-agent-session.sh` clean-environment assertion semantic and portable without removing either newly enumerated framework-shell suite.
|
||||
|
||||
## Scope
|
||||
|
||||
- Tracking issue: `mosaicstack/stack#1098`
|
||||
- Branch: `fix/framework-shell-portability`
|
||||
- Base: `origin/main` at `4fa2768962702d53e16e8b67ee6ad52ebcb0910e`
|
||||
- Primary file: `packages/mosaic/framework/tools/fleet/test-start-agent-session.sh`
|
||||
- Requirements source: `docs/PRD.md` § Framework shell assertion portability (#1098)
|
||||
- Out of scope: deployed files under `~/.config/mosaic`, pnpm-store cleanup, checkout deletion, and changes to the launcher’s `/usr/bin/env -i` behavior.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
1. The test inspects the captured NUL-delimited tmux argv semantically and accepts an adjacent `/usr/bin/env`, `-i` pair regardless of trailing payload size or pipe scheduling.
|
||||
2. Missing `/usr/bin/env`, missing `-i`, and non-adjacent `-i` remain failures.
|
||||
3. Failure output includes the observed argv records with stable indexes and shell escaping; it exposes no credentials because this fixture supplies only generated non-secret launch data.
|
||||
4. The focused suite passes on the dev host and in the repository CI image; the blocking PR/main pipeline returns terminal green.
|
||||
5. Independent review passes; PR is squash-merged and #1098 is closed only after merged-main CI is terminal green.
|
||||
|
||||
## Budget
|
||||
|
||||
- ASSUMPTION: 30K-token working budget; rationale: one shell-test defect plus full PR/CI lifecycle.
|
||||
- Auto-reduction: focused shell and package gates first; rely on canonical Woodpecker for the full monorepo suite rather than duplicating a dependency install under constrained `/home`.
|
||||
- Disk baseline before clone/build: `/home` 7.1G free (99% used), `/tmp` 2.4G free (92% used).
|
||||
|
||||
## Investigation
|
||||
|
||||
### First-hand CI evidence
|
||||
|
||||
- Public log: `GET https://ci.mosaicstack.dev/api/repos/47/logs/2269/53041`
|
||||
- Decoded 1,436 entries (11 null `data` entries treated as empty log rows), 190,756 bytes.
|
||||
- Failure: `FAIL: pane command did not clear its environment` immediately after the expected pane-PID warning.
|
||||
- BusyBox primitives, complete assertion pipeline, real CI image, stale/current image digests, Turbo cache masking, gateway failure, and heartbeat-sidecar concurrent writing were independently excluded.
|
||||
|
||||
### Root cause
|
||||
|
||||
The assertion ends in:
|
||||
|
||||
```bash
|
||||
printf '%s\n' "$pane_args" | tail -n +"$after_pane_env" | grep -qxF -- '-i'
|
||||
```
|
||||
|
||||
The script has `set -o pipefail`. `grep -q` exits as soon as it finds the valid `-i` record. Upstream `tail`/`printf` can then receive SIGPIPE, making the aggregate pipeline nonzero even though grep returned 0 and the semantic property is true. This depends on payload size, pipe capacity, and scheduling, explaining a local/image pass with a CI failure.
|
||||
|
||||
Discriminating stress control with `/usr/bin/env` followed immediately by `-i`:
|
||||
|
||||
- 8,192-byte trailing payload: `printf=0 tail=0 grep=0`, aggregate 0.
|
||||
- 16,384-byte trailing payload: `printf=0 tail=141 grep=0`, aggregate 141.
|
||||
- 32,768+ bytes: `printf=141 tail=141 grep=0`, aggregate 141.
|
||||
- A full-reading `grep -xF` control remained 0 for every payload.
|
||||
|
||||
This is a third branch omitted by the earlier present-vs-corrupted split: the pair can be present and intact while `pipefail` reports an upstream SIGPIPE.
|
||||
|
||||
## TDD plan
|
||||
|
||||
1. RED: preserve the one-off stress reproducer above and add an automated large-argv semantic regression that fails under the current pipeline implementation.
|
||||
2. GREEN: parse the authoritative NUL-delimited capture into a Bash array and search for an adjacent `/usr/bin/env`, `-i` pair without a short-circuit pipeline.
|
||||
3. Add negative controls for missing, detached, and reversed tokens.
|
||||
4. On failure, print indexed `%q` argv records before returning nonzero.
|
||||
5. Run focused suite, mutation controls, shell syntax/format checks, then repository baseline gates feasible without dependency installation.
|
||||
6. Independent review, queue guard, push, PR, CI, coordinator merge authorization, squash merge, merged-main CI, issue close.
|
||||
|
||||
## Progress
|
||||
|
||||
- [x] Checkout created and based on `origin/main` `4fa27689`.
|
||||
- [x] CI log decoded directly.
|
||||
- [x] Root-cause stress control reproduced semantic match + aggregate pipeline failure.
|
||||
- [x] RED evidence: intact `/usr/bin/env`, `-i` fixture produced component statuses `0/141/0` and aggregate 141 under the former `grep -q` pipeline; full-reading semantic control stayed 0.
|
||||
- [x] GREEN implementation: direct NUL-argv adjacency parser, indexed diagnostics, and full-reading scalar predicates replace all load-bearing early-exit pipelines in this test.
|
||||
- [x] Baseline/situational tests:
|
||||
- focused launcher suite: PASS on GNU host and cached Alpine CI image;
|
||||
- paired `test-fleet-units.sh`: PASS;
|
||||
- enumeration guard: PASS (`population=53`, `enumerated=36`, `excluded=18`), 14/14 mutation needles;
|
||||
- `bash -n`, ShellCheck, `git diff --check`: PASS;
|
||||
- static denominator after change: zero load-bearing `grep -q`/`head`/`-m1` pipeline candidates in `test-start-agent-session.sh`;
|
||||
- delete-the-subject mutation removing production `-i`: RED with 78 indexed argv records, byte count, and explicit boundary failure.
|
||||
- [x] Independent review:
|
||||
- first Codex review: request changes — negative fixtures did not each assert diagnostics;
|
||||
- remediation: centralized predicate + diagnostic wrapper and exercised all four negative fixtures;
|
||||
- second Codex review: APPROVE, 0 blockers/should-fix/suggestions;
|
||||
- Codex security review: risk none, 0 findings.
|
||||
- [ ] PR CI, formal fleet review, merge, merged-main CI, issue closure.
|
||||
|
||||
## Documentation disposition
|
||||
|
||||
- Updated canonical `docs/PRD.md` with FSP requirements and acceptance criteria.
|
||||
- This is an internal test/reliability change with no API, user workflow, deployment, navigation, or publishing-surface change; no user/admin/API/sitemap update is required.
|
||||
- `docs/TASKS.md` remains unchanged because the project contract makes it orchestrator-only.
|
||||
|
||||
## Risks
|
||||
|
||||
- The CI failure did not print its captured argv, so the exact CI payload is unavailable. The stress control proves the assertion is non-portable and can emit the exact false verdict; branch CI is the canonical confirmation that replacing it resolves pipeline 2269’s failure class.
|
||||
- Printing fixture argv is safe only while this test’s projection remains non-secret. The diagnostic must stay scoped to the test capture and shell-escaped.
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
kind: record
|
||||
status: active
|
||||
---
|
||||
|
||||
# #1099 — pipefail + early-exit sweep
|
||||
|
||||
## Scope and decisions
|
||||
|
||||
- Baseline `df4c591ab42aa1ae62c12935fdc0e772684864a0`, after #1100 removed its 35 sites.
|
||||
- Split into review-sized non-closing tranches: runtime/general; tmux/git/quality tests; wake validation/tests.
|
||||
- Do not equate class membership with demonstrated risk. Do not use payload size or pipeline stage count as a safety proxy.
|
||||
- Preserve the issue's withdrawn findings for `qa-hook-stdin.sh` and the two fresh-directory `pnpm pack` lookups. Fix `install.sh:312` because malformed multi-root input must reach its named handler.
|
||||
|
||||
## Tranche 1 TDD
|
||||
|
||||
RED-first control: `node --test scripts/pipefail-early-exit.test.mjs` reported exactly 26 non-accepted runtime/general sites, including `install.sh:312`, and exited 1. A checked-in fixture generated from immutable baseline `df4c591a` records all 26 normalized sites; the control passes every fixture entry through the same scanner, asserts exact identity/count/uniqueness, and separately requires zero findings in the current tree. It also inventories accepted sites rather than silently excluding whole files.
|
||||
|
||||
Construction choices:
|
||||
|
||||
- here-string/file redirection for scalar grep assertions;
|
||||
- full capture then parameter expansion for first-line selection;
|
||||
- arrays/`mapfile` for complete populations;
|
||||
- direct jq/awk/grep selection where one tool can express the property;
|
||||
- no `|| true` added to a load-bearing assertion.
|
||||
|
||||
Site-by-site verdicts: `docs/reports/quality/1099-pipefail-sweep.md`.
|
||||
|
||||
## Tranche 2 TDD
|
||||
|
||||
Expanded the unconditional scanner over 11 non-wake test harnesses. RED named exactly 22 source lines; a second immutable-baseline fixture now asserts those 22 entries through the same scanner. Rewrites preserve command status by capturing producers before redirected assertions, use parameter expansion for line selection, and use complete `mapfile` populations where ordering matters. Current-tree finding count is zero for tranches 1 and 2.
|
||||
|
||||
## Tranche 3 TDD
|
||||
|
||||
Expanded the shared scanner over four wake validation harnesses. RED named 26 occurrences. The wake fixture asserts 26 occurrences / 25 normalized identities through the same scanner; all scalar assertions now use redirection, direct jq selection, complete capture, or consuming diagnostic ranges. Current-tree finding count is zero across the full scoped population.
|
||||
|
||||
## Verification so far
|
||||
|
||||
- `bash -n` on every changed shell script: pass.
|
||||
- structural Node control: pass.
|
||||
- `test-mutate-push-guard.sh`: 8/8 pass.
|
||||
- `test-send-message-verdict.sh`: 3/3 pass.
|
||||
- `test-send-message-socket.sh`: pass.
|
||||
- Independent review 143 found two semantic regressions: a help-probe `|| true` changed the failure truth table, and an unguarded Git capture changed non-Git data-dir behavior from rc 0 + JSON to silent rc 128. Both received RED-first regressions before correction; help status is now separate and required, and Git status remains condition-guarded.
|
||||
- Wake static inventory remains aligned at 261/261 after line-neutral rewrites; no static-set mismatch. Wake detector/reconcile/digest/preimage suites terminate at their existing fail-closed #973 `BASH_LINENO` environment probe (exit 97, observed `[3 5]`, expected `[3 4]`) before subject tests. No bypass or skip was used; canonical CI remains required.
|
||||
- ShellCheck reports only pre-existing source-following, unused-variable, and untouched `ls | head` findings; no new diagnostic was introduced.
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
kind: record
|
||||
status: active
|
||||
---
|
||||
|
||||
# #1146 — CI Queue Guard Purpose Semantics
|
||||
|
||||
## Objective
|
||||
|
||||
Make the pre-push queue guard wait for queued/running CI without requiring the previous remote head to have successful CI. Preserve fail-closed merge readiness.
|
||||
|
||||
## Scope
|
||||
|
||||
- `packages/mosaic/framework/tools/git/ci-queue-wait.sh`
|
||||
- focused queue-guard regression tests
|
||||
- design and scratchpad documentation
|
||||
- local framework activation required before the fixed guard can authorize this branch's push
|
||||
|
||||
## Plan
|
||||
|
||||
1. Freeze purpose-specific behavior in failing process-level tests.
|
||||
2. Implement the smallest state-dispatch change.
|
||||
3. Run focused shell tests and repository quality gates.
|
||||
4. Obtain independent review and remediate findings.
|
||||
5. Install the reviewed framework source locally, run the mandatory pre-push queue guard, and push.
|
||||
6. Open a PR against `next`, verify terminal-green CI, and close #1146 after merge.
|
||||
|
||||
## Budget
|
||||
|
||||
- ASSUMPTION: no explicit token cap was provided.
|
||||
- Working estimate: 12K tokens.
|
||||
- Scope reduction: change only final-state dispatch and focused tests; do not redesign provider adapters.
|
||||
|
||||
## Progress
|
||||
|
||||
- Confirmed source and installed guards are byte-identical.
|
||||
- Reproduced `terminal-failure` blocking `--purpose push`.
|
||||
- Root cause: final-state dispatch requires terminal success for both push and merge.
|
||||
- Design approved: push is queue-clear on valid non-pending states; merge remains fail-closed.
|
||||
|
||||
## Tests
|
||||
|
||||
- RED confirmed before implementation: the focused tri-state harness reported push `terminal-failure` and `no-status` as `ASSERTED_NOT_READY`.
|
||||
- GREEN: `bash packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh` — all outcome classes passed.
|
||||
- GREEN: `bash packages/mosaic/framework/tools/git/test-ci-queue-wait-github-checks.sh` — 6/6 purpose-aware cases passed.
|
||||
- GREEN: `bash -n` passed for the changed guard and both focused harnesses.
|
||||
- GREEN: `pnpm preflight`, `pnpm typecheck`, and `pnpm lint` passed.
|
||||
- `pnpm test` ran 45/46 workspace test tasks successfully, but the pre-existing Gateway `cross-user-isolation.test.ts` failed during cleanup with PostgreSQL error `28P01` (local `mosaic` password authentication failure). The changed Mosaic framework test task passed within that run.
|
||||
- GREEN: focused queue and merge shell regressions passed after the wrapper change.
|
||||
- GREEN: isolated Mosaic Vitest run passed (81 files, 1,514 tests).
|
||||
- The normal parallel Mosaic Vitest run has an environment-sensitive pre-existing failure in `install-ordering-guard.spec.ts`: the real activation probe changes between two calls while other suites run concurrently. Running the same spec alone and the complete Vitest suite with one fork passes.
|
||||
- The framework shell suite's pre-existing `version_coupling_unittest.py` also fails locally because the newly installed `mosaic` is now on PATH despite the test injecting a nonexistent PATH; CI's clean image does not have this global CLI. All changed queue/merge harnesses pass.
|
||||
- GREEN: `pnpm format:check` passed.
|
||||
- Note: an additional ad hoc Prettier command was not applicable to shell files because Prettier has no shell parser; the repository-wide format check passed using its configured file globs.
|
||||
|
||||
## Review
|
||||
|
||||
- Independent Codex review of the six-file diff: approved, confidence 0.84, zero blockers/should-fix/suggestions.
|
||||
- Review confirmed push queue-clear behavior, merge fail-closed behavior, and `--require-status` coverage.
|
||||
|
||||
## Risks and Blockers
|
||||
|
||||
- Canonical framework activation completed with `MOSAIC_SYNC_ONLY=1 MOSAIC_INSTALL_MODE=keep MOSAIC_SKIP_SKILLS_SYNC=1 bash packages/mosaic/framework/install.sh`.
|
||||
- Source and installed queue guards are byte-identical (`cmp` and SHA-256 parity passed).
|
||||
- The installed pre-push guard now passes for the not-yet-remote feature branch with `queue clear`.
|
||||
- The required merge wrapper then exposed a second bootstrap defect: `pr-merge.sh` hardcoded `main`, contradicting the documented PR-based `next` integration lane. Tracked as #1149 and fixed in the same delivery branch with a regression fixture targeting `next`.
|
||||
- Activation emitted the existing manifest-safety warning that six `fleet/run/*.hb*` operator files were touched then restored; no data loss was observed, but this remains a pre-existing framework-manifest defect to report separately.
|
||||
- The first activation attempt timed out after 600 seconds while copying the 113K-file operator snapshot; the bounded 1,800-second retry completed successfully. It left a partial durable snapshot from the interrupted attempt in the normal backup directory; the completed snapshot is the newer `pre-update-20260810T195317Z` entry.
|
||||
- Full baseline test completion is blocked by the unrelated local PostgreSQL authentication/cleanup failure described above; CI has its own disposable PostgreSQL service.
|
||||
- Existing `.mosaic/orchestrator/*` working-tree changes are unrelated and must remain unstaged.
|
||||
@@ -0,0 +1,161 @@
|
||||
---
|
||||
kind: record
|
||||
status: active
|
||||
---
|
||||
|
||||
# #1150 — Pi persistent goal extension
|
||||
|
||||
- **Task ID:** ISSUE-1150 (no `docs/TASKS.md` row; that file is orchestrator-only)
|
||||
- **Issue:** #1150 — `pi: add persistent /goal controller extension to Mosaic framework`
|
||||
- **Branch:** `feat/1150-pi-goal-extension`
|
||||
- **Mode:** Delivery
|
||||
- **Status:** in progress
|
||||
|
||||
## Objective
|
||||
|
||||
Build and locally validate a Mosaic-owned Pi `/goal` extension. Source must ship from
|
||||
`packages/mosaic/framework/runtime/pi/`, framework sync must deploy it under
|
||||
`~/.config/mosaic/runtime/pi/`, and no extension/configuration asset may be written into `~/.pi`.
|
||||
Pi's native session manager remains the owner of session entries.
|
||||
|
||||
## Scope and acceptance source
|
||||
|
||||
- Canonical requirements: `docs/PRD.md`, section **Pi Persistent Goal Loop (#1150)**.
|
||||
- User intent: continuous goal orientation and status checking after each Pi turn and compaction,
|
||||
tested locally before framework delivery.
|
||||
- Documentation target: canonical in-repo user/developer/runtime docs; no external publication.
|
||||
|
||||
## Assumptions
|
||||
|
||||
- `ASSUMPTION:` Initial semantic verification uses two consecutive structured, evidence-bearing
|
||||
reports from the working agent rather than a second model request after every turn. This keeps the
|
||||
loop testable and avoids doubling model cost while making the limitation explicit.
|
||||
- `ASSUMPTION:` Default autonomous bounds are 40 turns and 6 repeated no-progress reports, with only
|
||||
bounded numeric environment overrides.
|
||||
- `ASSUMPTION:` A local smoke copy to `~/.config/mosaic/runtime/pi/goal-extension.ts` is authorized by
|
||||
the user's explicit request. Full framework reseed into the live home is not required for the smoke
|
||||
test and would touch unrelated framework-owned files.
|
||||
|
||||
## Budget
|
||||
|
||||
- Working estimate: 30K implementation/review tokens.
|
||||
- Hard user cap: none stated.
|
||||
- Cost control: deterministic fake-Pi tests; no nested evaluator calls; only bounded arithmetic/load
|
||||
smoke workflows against the installed runtime.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Update PRD and create tracking/scratchpad artifacts.
|
||||
2. Read launcher, installer ownership, Pi extension, and documentation surfaces.
|
||||
3. TDD: add fake-Pi behavior tests for commands, state restoration, turn checks, compaction, limits,
|
||||
verification, and continuation deduplication.
|
||||
4. Implement `runtime/pi/goal-extension.ts` and deterministic launcher discovery.
|
||||
5. Add framework-sync/deployment acceptance coverage.
|
||||
6. Update user, developer, runtime, framework README, and sitemap documentation.
|
||||
7. Run focused tests, local Mosaic-path smoke test, then baseline repository gates.
|
||||
8. Run independent review, remediate, commit, push/PR/CI/merge/issue closure per delivery gates.
|
||||
|
||||
## TDD decision
|
||||
|
||||
Applied. The continuation state machine and lifecycle scheduling are control-path logic where a race
|
||||
or false terminal state can cause unbounded work or premature completion.
|
||||
|
||||
## Progress checkpoints
|
||||
|
||||
- [x] Issue #1150 created through Mosaic wrapper.
|
||||
- [x] Isolated worktree created from `origin/main`.
|
||||
- [x] PRD requirements and acceptance criteria added.
|
||||
- [x] Task scratchpad created.
|
||||
- [x] RED controller and security-regression tests written and observed failing before implementation.
|
||||
- [x] Goal controller, launcher discovery, framework deployment coverage, and bounded state machine
|
||||
implemented.
|
||||
- [x] User, admin, developer, runtime, adapter, README, and sitemap documentation updated.
|
||||
- [x] Final source copied additively to `~/.config/mosaic/runtime/pi/goal-extension.ts`; source and
|
||||
deployed SHA-256 are identical.
|
||||
- [x] Live Pi RPC smoke from the exact Mosaic path reached `achieved` with two verification passes and
|
||||
no extension errors.
|
||||
- [x] Baseline and situational checks completed, except the explicitly documented unavailable
|
||||
PostgreSQL-only root integration case.
|
||||
- [x] Independent code and OWASP/security reviews completed; all findings remediated and re-reviewed.
|
||||
- [ ] Commit, push, PR, terminal-green CI, squash merge, and issue closure complete.
|
||||
|
||||
## Tests and evidence
|
||||
|
||||
### Situational
|
||||
|
||||
- `pnpm --filter @mosaicstack/mosaic exec vitest run src/runtime/pi-goal-extension.spec.ts`
|
||||
- final: 25 passed.
|
||||
- Covers commands, per-turn checks, context injection, two-pass verification, mixed-report
|
||||
rejection, bounded limits, compaction, branch restore, stale timers, credential redaction,
|
||||
typed-field false-positive protection, and append-only legacy-state fail-closed behavior.
|
||||
- Final focused launcher/controller/file-adapter run: 3 files / 67 tests passed.
|
||||
- Final V8 coverage for `framework/runtime/pi/goal-extension.ts`:
|
||||
- 99.17% statements/lines, 93.78% branches, 100% functions.
|
||||
- Installer migration fixture: 24 passed and byte-compared the deployed framework asset.
|
||||
- Standalone extension TypeScript check against installed Pi 0.84.1 types passed:
|
||||
`pnpm --filter @mosaicstack/mosaic exec tsc --noEmit --pretty false --module NodeNext
|
||||
--moduleResolution NodeNext --target ES2022 --skipLibCheck framework/runtime/pi/goal-extension.ts`.
|
||||
- Live deployment/load evidence:
|
||||
- source/deployed SHA-256:
|
||||
`1f0a3806e0948ad5f49684273a7e535e9880c148f7fd16d13ee487fcd601f637`.
|
||||
- `get_commands` identified `/goal` as an extension command sourced from
|
||||
`~/.config/mosaic/runtime/pi/goal-extension.ts`; `/goal help` succeeded; zero extension errors.
|
||||
- live arithmetic goal ended `achieved`, verification `2/2`, with 3 goal reports / 3 agent starts
|
||||
and zero extension errors.
|
||||
- no goal extension exists under `~/.pi` extension paths.
|
||||
|
||||
### Baseline
|
||||
|
||||
- `pnpm build`: passed before the final framework-only redaction remediation; the extension is not a
|
||||
package build input and its final source passed the standalone Pi type check.
|
||||
- `pnpm typecheck`: 45/45 tasks passed.
|
||||
- `pnpm lint`: 25/25 tasks passed.
|
||||
- `pnpm format:check`: passed.
|
||||
- Final Mosaic package components:
|
||||
- Vitest: 82 files / 1,539 tests passed.
|
||||
- full `test:framework-shell` harness passed.
|
||||
- the discovered pre-existing tmux loader-marker race was reproduced with constructor PID
|
||||
evidence, fixed with a pane readiness/FIFO barrier, passed 3 consecutive focused runs, and passed
|
||||
in the full shell harness.
|
||||
- one combined rerun encountered the separate existing real-lease probe TOCTOU in
|
||||
`install-ordering-guard.spec.ts`; an earlier final Vitest run was fully green and the changed
|
||||
focused suites remained green.
|
||||
- Gateway safe baseline excluding the prohibited PostgreSQL-only fixture: 55 files / 600 tests passed
|
||||
(6 files / 12 tests skipped by their existing environment gates).
|
||||
- Root `pnpm test` reached 43 successful workspace tasks and all changed-package Vitest tests, but
|
||||
the unchanged `apps/gateway/src/__tests__/cross-user-isolation.test.ts` afterAll hook retried a
|
||||
PostgreSQL connection and failed authentication (`28P01`). This checkout explicitly forbids local
|
||||
PostgreSQL startup/access; the failure is unrelated to #1150 and cannot be remediated by starting
|
||||
the database. The gateway suite excluding that PostgreSQL-only file and required CI are used as
|
||||
the safe verification paths.
|
||||
|
||||
### Independent review
|
||||
|
||||
- Codex code review: approved, 0 findings across 15 files.
|
||||
- Initial Codex security review: one medium CWE-532/A09 finding for raw report persistence.
|
||||
- Remediation added central credential-pattern redaction, prompt/docs guidance, canary tests, typed
|
||||
field false-positive guards, and sticky fail-closed restore for credential-bearing append-only
|
||||
history.
|
||||
- Codex security re-review: risk `none`, 0 findings, confidence 0.87.
|
||||
- Focused remediation review findings were fixed; final focused re-review verdict: `APPROVE`.
|
||||
- Focused independent review of the tmux readiness barrier: `APPROVE`, no actionable findings.
|
||||
|
||||
## Risks and blockers
|
||||
|
||||
- Live `~/.config/mosaic` is shared by active Pi/fleet processes. Local deployment remained a single
|
||||
additive framework file and did not reload or restart unrelated sessions.
|
||||
- Completion verification is semantic, not mathematical: the active agent supplies structured
|
||||
evidence twice. Operators must still inspect consequential outcomes.
|
||||
- Credential redaction is pattern-based defense-in-depth, not a secret store. It covers
|
||||
controller-owned state/status/tool details, not Pi's separate model-message/tool-call history.
|
||||
Goals and reports must never contain real secrets or raw sensitive output. Because Pi session
|
||||
entries are append-only, a detected credential-bearing legacy branch fails closed and the affected
|
||||
session must be removed.
|
||||
- Current installed Pi is newer than the repository's historical gateway Pi dependency. The
|
||||
extension was checked and smoke-tested against installed Pi 0.84.1 using stable documented APIs.
|
||||
- Local root testing cannot safely execute the unchanged PostgreSQL-only integration fixture under
|
||||
the checkout's explicit database safety constraints. Terminal-green PR CI remains mandatory before
|
||||
merge.
|
||||
- The unchanged real-lease default-probe test can observe different broker availability across its two
|
||||
sequential probes; one combined package rerun hit that existing TOCTOU. The same final Vitest suite
|
||||
passed in a separate run, and CI remains the merge authority.
|
||||
@@ -0,0 +1,94 @@
|
||||
---
|
||||
kind: record
|
||||
status: active
|
||||
---
|
||||
|
||||
# #1174 — Wrapper guard rounds 10–11
|
||||
|
||||
## Objective
|
||||
|
||||
Make checkout enforcement judge Git placement operands rather than every HOME-shaped word in the command, without reopening `--separate-git-dir` placement under HOME.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Reproduce the four over-blocks and the placement-option control at head `20d86e39`.
|
||||
2. Add RED fixtures before production changes.
|
||||
3. Extract clone/worktree placement operands from the existing shell-aware normalized stream.
|
||||
4. Run the full guard corpus, historical-head discrimination, syntax/static checks, probes, review, and CI.
|
||||
|
||||
## Progress and evidence
|
||||
|
||||
- Reproduced: `NOTE=$HOME`, `--reference=$HOME`, `GIT_DIR=$HOME/x`, and `--template=$HOME/t` all blocked despite explicit `/src/wt` destinations.
|
||||
- RED at `20d86e39`: expanded suite had 8 failures, all HOME-valued non-placement cases.
|
||||
- GREEN: expanded suite passes 242/242.
|
||||
- Round-10 probes: 7/7 placement expectations and 4/4 placement-option controls pass.
|
||||
- Earlier path probes remain green: 60/60, 24/24, and 17/17.
|
||||
- Historical discrimination with the 242-fixture suite:
|
||||
- `3d0a882a`: 216 pass / 26 fail.
|
||||
- `4b8eba95`: 222 pass / 20 fail.
|
||||
- `20d86e39`: 234 pass / 8 fail.
|
||||
- `bash -n`, ShellCheck warning-or-higher, and `git diff --check`: pass.
|
||||
|
||||
## Residual / risk
|
||||
|
||||
- Relative destinations whose effective path depends on cwd are tracked separately by #1197 and remain out of scope.
|
||||
- Unknown future Git options with a separate following value fail closed when that value is HOME-shaped. This may require classification when Git adds an unrelated path-taking option, but prevents a new placement option from silently bypassing the guard.
|
||||
|
||||
## Round 11 objective and intake
|
||||
|
||||
- **Issue / PR:** #1174.
|
||||
- **Objective:** Remove the finite boolean-flag allowlists that turn accepted clone/worktree flags into fake placement operands, while preserving all real HOME placement blocks.
|
||||
- **Scope:** `wrapper-guard.sh`, its hermetic fixtures, and task documentation. Relative cwd-dependent destinations remain in #1197.
|
||||
- **Surfaces:** security-sensitive Bash hook behavior and shell/Git option grammar; no API, DB, UI, auth, deploy, or dependency changes.
|
||||
- **Budget assumption:** 25K working tokens; reduce exploratory matrices before reducing acceptance coverage.
|
||||
|
||||
### Round 11 plan
|
||||
|
||||
1. Use Git itself to classify accepted/rejected clone and worktree options, and Bash itself to resolve path-word expectations.
|
||||
2. Add RED fixtures for all six reported clone flags, generated negations, and equivalent worktree grammar.
|
||||
3. Replace the open-ended unknown-option fail-closed fallback with a parser based on the closed value-taking option surface; keep explicit placement options special.
|
||||
4. Run the full corpus, historical discrimination, shell/static checks, targeted probes, independent code/security review, one push, and exact-head CI.
|
||||
|
||||
### Root-cause evidence
|
||||
|
||||
- Git 2.39.5 accepts all six reported clone flags and the broader generated family measured in the brief: `--bare`, `--mirror`, `--ipv4`, `--ipv6`, `-4`, `-6`, `--no-local`, `--no-reject-shallow`, `--no-bare`, `--no-sparse`, `--no-dissociate`, `--no-shallow-submodules`, `--no-quiet`, `--no-progress`, and `--no-recurse-submodules`; it rejects `--relative-paths` as unknown.
|
||||
- Git 2.39.5 accepts worktree negations including `--no-force`, `--no-detach`, `--no-lock`, `--no-guess-remote`, and `--no-track`; the current finite worktree flag list does not describe that generated family.
|
||||
- `bash -c "printf '%s' <word>"` resolves `$HOME/source`, `${HOME}/source`, and `"$HOME"/source` under HOME while `/src/wt` remains outside it.
|
||||
- **Hypothesis:** only separate-value options need positive classification. Treat every other option token as a no-value flag unless it is the explicit placement option; this matches Git's non-enumerable boolean family and confines the residual to genuinely new future value-taking options.
|
||||
|
||||
### TDD and verification checkpoints
|
||||
|
||||
- RED against the unmodified `91cc37bc` guard: 253 pass / 22 fail in the initial expanded 275-fixture suite. Failures include all 15 accepted clone flags, accepted long abbreviations, short value-taking bundles, abbreviated placement, worktree metadata abbreviation, and both directions of bundled worktree branch parsing.
|
||||
- An exploratory fail-closed residual test drove emission of every worktree positional. Re-review correctly showed that this over-blocked HOME-shaped commit-ish metadata; a new commit-ish fixture failed RED against that intermediate implementation (278 pass / 2 fail, including one transient message assertion) and the parser was restored to emit only the actual path.
|
||||
- GREEN after remediation: 280/280.
|
||||
- Ultron's 13-shape option probe: 13/13 correct, including the six reported over-blocks, HOME destinations, end-of-options, worktree controls, and a later-command placement.
|
||||
- Round-10 probes remain green: 7/7 subject-placement expectations and 4/4 `--separate-git-dir` controls.
|
||||
- Earlier shell/path probes remain green: 60/60, 24/24, and 17/17.
|
||||
- `bash -n`, ShellCheck warning-or-higher, and `git diff --check`: pass.
|
||||
|
||||
### Deliberate residual
|
||||
|
||||
A future Git release could add a new separate-value option absent from the closed value grammar. It defaults to no-value flag parsing, which leaves the following word positional. For clone, this can fail open if that future option itself creates repository state at its value. For worktree, it can shift which word is read as the path. This hypothetical future ambiguity is accepted deliberately because failing closed on every unclassified option is proven to over-block Git's open-ended present-day boolean/`--no-*` family. Every value-taking and placement option Git currently supports is classified, including accepted abbreviations of `--separate-git-dir`. Relative cwd-dependent targets remain in #1197.
|
||||
|
||||
### Independent review checkpoint
|
||||
|
||||
- Initial Codex code/security review raised `--orphan` as value-taking. Upstream Git `master` contradicts that premise: the synopsis is `[--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>]`, and the prose derives the branch from the path when `-b`/`-B` is absent. `--orphan` is therefore correctly handled as a boolean flag.
|
||||
- The security review separately identified the generic future worktree shift residual. An attempted fail-closed remediation emitted every positional, but code re-review correctly rejected it because valid grammar has only one placement positional and an optional commit-ish. Final behavior checks only the path and documents the hypothetical future option shift deliberately; paired actual-grammar `--orphan` fixtures cover safe/HOME paths and `-b` metadata.
|
||||
- Security re-review initially had no findings. Code re-review's commit-ish blocker was remediated with a RED fixture and path-only restoration; final code re-review approved with no findings.
|
||||
- Final security review then found non-canonical absolute and symlink aliases. Eight lexical fixtures failed RED against the prior implementation, followed by three symlink fixtures failing RED. Remediation expands only shell-visible HOME tokens, resolves the longest existing directory prefix physically, and lexically normalizes the nonexistent suffix. The suite is now 292/292.
|
||||
- Inherent residual: a symlink can be replaced between pre-tool inspection and Git execution. Existing aliases are resolved; eliminating the race requires enforcement inside the filesystem mutation path rather than a text pre-hook. Security review classified this medium, and architectural closure is tracked in #1199.
|
||||
- Final independent code review: APPROVE, 0 findings. Final security review: no critical/high findings; the single medium TOCTOU residual is explicitly tracked in #1199.
|
||||
|
||||
### Final local evidence
|
||||
|
||||
- Final hermetic suite: 292/292; the same suite against `91cc37bc` discriminates at 256 pass / 36 fail.
|
||||
- Ultron option probe: 13/13; round-10 probes: 7/7 plus 4/4 controls; earlier shell/path probes: 60/60, 24/24, and 17/17.
|
||||
- `bash -n`, ShellCheck warning-or-higher, `git diff --check`, sanitization gate, and test-enumeration gate (population 55; 38 enumerated; 18 signed exclusions): pass.
|
||||
- Independent code review: APPROVE, 0 findings. Security review's remaining medium TOCTOU architecture residual is tracked in #1199; no critical/high findings remain.
|
||||
- Repository-wide TypeScript gates require dependencies absent from this worktree; the canonical Woodpecker pipeline will run them against the pushed exact head.
|
||||
|
||||
### Documentation checklist
|
||||
|
||||
- `docs/PRD.md` updated with WPG requirements, acceptance, canonicalization, and residual risk.
|
||||
- Task scratchpad updated in the same logical change set; `docs/TASKS.md` remains orchestrator-only.
|
||||
- No API, auth, UI, navigation, deployment, user-guide, or admin-guide surface changed; OpenAPI, endpoint index, sitemap, and publishing are not applicable.
|
||||
@@ -0,0 +1,82 @@
|
||||
---
|
||||
kind: record
|
||||
status: active
|
||||
---
|
||||
|
||||
# #1179 — Required security DI wiring
|
||||
|
||||
## Objective
|
||||
|
||||
Eliminate the shared fail-open defect class **absence read as permission**:
|
||||
|
||||
- FL-01: missing `CommandAuthorizationService` must refuse Nest startup and must not permit command effects.
|
||||
- FL-11: missing `SystemOverrideService` must refuse Nest startup and must not omit stored instruction authority while allowing provider/session effects.
|
||||
|
||||
## Tracking
|
||||
|
||||
- Issue: #1179, child of #1156
|
||||
- Branch: `fix/1179-required-security-di`
|
||||
- Base: `origin/next` at `216cd72226cd9ee17eea461cfe7cd0e010a22f02`
|
||||
|
||||
## Plan
|
||||
|
||||
1. RED: compile the real `AppModule` graph with each required provider independently removed, with a positive control for each intact binding.
|
||||
2. RED: directly exercise each malformed absence path and assert zero command/provider/session effects.
|
||||
3. Stop and report RED to the coordinator before production implementation.
|
||||
4. After authorization, make both constructor injections required, remove absence-as-permission branches, and update explicit legitimate optional test seams.
|
||||
5. Run focused Gateway tests, typecheck, lint, format, build, independent exact-head verification, and focused security review.
|
||||
|
||||
## Immutable path fence
|
||||
|
||||
Production changes are confined to:
|
||||
|
||||
- `apps/gateway/src/commands/command-executor.service.ts`
|
||||
- `apps/gateway/src/agent/agent.service.ts`
|
||||
|
||||
Tests and task evidence are confined to:
|
||||
|
||||
- `apps/gateway/src/__tests__/required-security-wiring.test.ts`
|
||||
- existing direct-constructor specs that require explicit required arguments
|
||||
- `docs/scratchpads/1179-required-security-di.md`
|
||||
|
||||
No files in #1178, #1072, #1080, or #1054 lanes are in scope. `docs/TASKS.md` is orchestrator-owned and will not be modified.
|
||||
|
||||
## Budget
|
||||
|
||||
No explicit token ceiling was provided. Working assumption: one narrow Gateway security packet; split and stop if either arm requires unrelated module rewiring.
|
||||
|
||||
## Progress
|
||||
|
||||
- Intake read from #1179 and parent #1156.
|
||||
- Base independently resolved from the issue's pre-native-stage ordering and repository `origin/next` ref; branch HEAD verified byte-for-byte against the remote ref.
|
||||
- Real consumers and direct constructors inventoried.
|
||||
|
||||
## Tests
|
||||
|
||||
### RED
|
||||
|
||||
- `required-security-wiring.test.ts`: 4 failed, 2 passed before implementation.
|
||||
- Both real-graph negative controls showed module compilation accepted the missing target binding.
|
||||
- Direct FL-01 showed one unauthorized command effect; direct FL-11 showed one provider prompt and one session counter mutation.
|
||||
|
||||
### GREEN
|
||||
|
||||
- `required-security-wiring.test.ts`: 6/6 passed.
|
||||
- FL-01-only production revert: exactly the two FL-01 test cases failed; all four other cases, including FL-11, passed.
|
||||
- FL-11-only production revert: exactly the two FL-11 test cases failed; all four other cases, including FL-01, passed.
|
||||
- Full Gateway suite: 74 files passed, 7 skipped; 831 tests passed, 17 skipped.
|
||||
- Gateway typecheck: passed.
|
||||
- Gateway lint: passed.
|
||||
- Gateway build: passed.
|
||||
- Changed-file Prettier check: passed.
|
||||
|
||||
### Review
|
||||
|
||||
- Codex code review: APPROVE, 0 findings.
|
||||
- Codex focused security review: risk `none`, 0 findings.
|
||||
- Independent exact-head review remains assigned to Scrappy through the coordinator.
|
||||
|
||||
## Risks / blockers
|
||||
|
||||
- `AgentModule` / `CommandsModule` / `ChatModule` contain a production cycle; the module test therefore uses the real top-level `AppModule` and replaces only storage/network leaves, preserving the target service in each arm while isolating the separate required consumer that would otherwise mask that arm's defect.
|
||||
- No broad module rewrite was required.
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
kind: record
|
||||
status: active
|
||||
---
|
||||
|
||||
# #1194 — Installed framework-tool drift detection and refresh analysis
|
||||
|
||||
## Decision
|
||||
|
||||
The reported queue-guard source defect was already fixed on `main` by `58b971ab`; the live failure came from a stale `~/.config/mosaic/tools/git/ci-queue-wait.sh`. The durable fix is therefore a detector, not a duplicate queue-guard patch.
|
||||
|
||||
`mosaic doctor` now compares the framework tools bundled with the executing Mosaic package against the deployed tools tree. Doctor is the selected visibility boundary because it is observational and operator-invoked: unlike session start, it does not add a repository/network scan to every seat launch, and it cannot silently replace identity or messaging tools while seats are active. It reports drift without changing files. `--fail-on-warn` converts detected drift into a non-zero doctor result.
|
||||
|
||||
## Classification
|
||||
|
||||
The existing `framework-manifest.txt` is authoritative. The detector invokes the canonical shared `tools/_lib/manifest.sh classify` implementation over the complete source census and refuses missing, unreadable, malformed, incomplete, or zero-framework ownership output. Policy is therefore read rather than duplicated:
|
||||
|
||||
- Current policy classifies source files under `tools/**` as framework-owned and required in the deployed tools tree.
|
||||
- Current policy explicitly classifies `tools/_lib/credentials.json` operator-owned and excludes it from byte comparison; future policy changes take effect without a detector edit.
|
||||
- A file present only in the deployed tools tree is operator-owned/unknown by the manifest's fail-safe default. The detector reports it as `INSTALLED_ONLY operator-or-unknown` under `--verbose` but does not fail or delete it.
|
||||
- Empty/partial source traversal, unreadable directories/files, symlinked census entries, root aliases, and descendant source aliases all return `CANNOT_ASSERT` rather than manufacturing agreement.
|
||||
|
||||
This means `NOT_INSTALLED` is not suppressed by filename guesses such as “test” or “README”: if it ships below source `tools/**`, the installer contract says it should be installed. Source-only implementation files outside `tools/**` are outside this detector population by construction.
|
||||
|
||||
## Current host analysis (observation only; no refresh performed)
|
||||
|
||||
A direct source-vs-installed census showed broad drift, including identity and messaging behavior:
|
||||
|
||||
- Identity/provider operations: stale `git/detect-platform.sh`, `issue-comment.sh`, `issue-create.sh`, `issue-close.sh`, `issue-view.sh`, `pr-create.sh`, `pr-merge.sh`, `pr-review.sh`, `pr-metadata.sh`; missing `pr-edit.sh` and several identity/read-back regression tools.
|
||||
- Messaging/session: stale `tmux/agent-send.sh`, `tmux/send-message.sh`, their regressions, and `fleet/start-agent-session.sh`.
|
||||
- Gate enforcement: stale `git/ci-queue-wait.sh`; missing the queue tri-state/process-level suites and terminal-green verifier.
|
||||
- Lease/QA behavior: stale lease-broker launch/mutation/receipt tools and QA hooks.
|
||||
|
||||
Counts vary with source head and installed local/operator files; the detector prints measured counts every run rather than baking this snapshot into policy.
|
||||
|
||||
## Reviewed refresh command — analyse only, do not run during active seats
|
||||
|
||||
Use the package/release updater's manifest-driven keep-mode sync during a quiet maintenance window:
|
||||
|
||||
```bash
|
||||
MOSAIC_SYNC_ONLY=1 \
|
||||
MOSAIC_INSTALL_MODE=keep \
|
||||
MOSAIC_HOME="$HOME/.config/mosaic" \
|
||||
bash /path/to/reviewed/@mosaicstack/mosaic/framework/install.sh
|
||||
```
|
||||
|
||||
For the globally installed package, resolve the reviewed installer rather than guessing its path:
|
||||
|
||||
```bash
|
||||
PACKAGE_ROOT="$(dirname "$(node -p "require.resolve('@mosaicstack/mosaic/package.json')")")"
|
||||
MOSAIC_SYNC_ONLY=1 MOSAIC_INSTALL_MODE=keep MOSAIC_HOME="$HOME/.config/mosaic" \
|
||||
bash "$PACKAGE_ROOT/framework/install.sh"
|
||||
```
|
||||
|
||||
Do not run this while agent seats are active: the stale set includes identity selection, provider mutation, messaging, queue/merge guards, lease enforcement, and session launch. Syncing those files in place can change behavior between a seat's preflight and mutation.
|
||||
|
||||
## Post-refresh verification
|
||||
|
||||
1. Run `mosaic doctor --fail-on-warn`; require `stale=0 not-installed=0` from the framework drift summary (other unrelated doctor warnings must also be adjudicated).
|
||||
2. Re-run the constructed process-level queue probes against the **installed path**, not the source checkout. Use the source suite while overriding its subject path in a reviewed scratch copy, or reproduce these exact observations:
|
||||
- pending provider payload: guard must print `state=pending`, print the pending context, wait, and exit non-zero/timeout — never return immediately with rc 0;
|
||||
- malformed payload: guard must print `state=malformed` and exit non-zero;
|
||||
- unsupported but valid status vocabulary: guard must print `state=unknown` and exit non-zero.
|
||||
3. Run provider author read-back for one deliberately low-risk wrapper operation before resuming fleet mutation work; wrapper self-report is not identity evidence.
|
||||
4. Relaunch seats only after the quiet-window verification, because existing processes retain loaded environment/context.
|
||||
|
||||
## Probe evidence
|
||||
|
||||
The detector regression constructs a stale installed tool plus a missing shipped tool and observes rc 1 with distinct `STALE` and `NOT_INSTALLED` lines. That case would pass or be invisible before this change because no installed-vs-shipped comparison existed. Additional review-red controls prove:
|
||||
|
||||
- empty and unreadable source censuses return `CANNOT_ASSERT` (they returned clean rc 0 at the first PR head);
|
||||
- deleting the manifest returns `CANNOT_ASSERT`, while changing manifest ownership changes the verdict through the canonical resolver (the first head never opened the manifest);
|
||||
- root and descendant symlink/source aliases cannot return clean (the first head returned clean for a source-backed installed subtree);
|
||||
- a checker hung during doctor is terminated by a bounded watchdog, emits `CANNOT_ASSERT`, and doctor reaches its final warnings line (the first head hung and suppressed the remaining audit).
|
||||
|
||||
Controls retain byte-identical success, exact credential carve-out behavior, and installed-only preservation.
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
kind: record
|
||||
status: active
|
||||
---
|
||||
|
||||
# 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,202 @@
|
||||
---
|
||||
kind: record
|
||||
status: active
|
||||
---
|
||||
|
||||
# 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 |
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
kind: guide
|
||||
status: active
|
||||
---
|
||||
|
||||
# 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]]
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
kind: record
|
||||
status: active
|
||||
---
|
||||
|
||||
# W-B — Measure Pi's real tool registry
|
||||
|
||||
- **Task / internal ref:** W-B from the lease-remediation orchestrator brief (no matching `docs/TASKS.md` row; workers do not modify that file)
|
||||
- **Objective:** identify the exact tool names emitted as `event.toolName` by the installed Pi runtime and compare them with the broker's Pi read-only carve-out.
|
||||
- **Scope:** measurement and report only; no broker or runtime source changes. W-C is out of scope.
|
||||
- **Budget:** no explicit token cap; constrained to this scratchpad and one local commit.
|
||||
- **Installed runtime:** `@earendil-works/pi-coding-agent` / `pi` `0.84.1`.
|
||||
|
||||
## Method
|
||||
|
||||
I created a throwaway extension at `/tmp/measure-pi-tool-registry.ts` (not in the worktree). On `session_start` it recorded `pi.getAllTools()` and `pi.getActiveTools()`; on every `tool_call` it appended the exact `event.toolName`. I then launched an isolated, ephemeral Pi session with all built-ins explicitly selected:
|
||||
|
||||
```text
|
||||
PI_OFFLINE=1 pi --mode print --no-session --no-approve \
|
||||
--no-context-files --no-skills --no-prompt-templates --no-extensions \
|
||||
-e /tmp/measure-pi-tool-registry.ts \
|
||||
--tools read,bash,edit,write,grep,find,ls <deterministic probe prompt>
|
||||
```
|
||||
|
||||
The prompt exercised file read, content search, file search, directory listing, shell execution, file write, and file edit. Pi exited `0`; every selected tool produced one `tool_call`. The write/edit control artifact ended with exact content `after`, proving the mutating calls executed in order.
|
||||
|
||||
This runtime observation was cross-checked against the installed distribution's canonical registry at `dist/core/tools/index.js:17`, which declares the same seven names. The gate consumes the measured field directly at `packages/mosaic/framework/runtime/pi/mosaic-extension.ts:368`.
|
||||
|
||||
## Exact distinct built-in set
|
||||
|
||||
The installed Pi built-in registry is exactly:
|
||||
|
||||
```text
|
||||
{bash, edit, find, grep, ls, read, write}
|
||||
```
|
||||
|
||||
| Tool | Runtime registry observation | `tool_call` observation | Installed definition |
|
||||
| --- | --- | --- | --- |
|
||||
| `read` | `<builtin:read>` | observed once | `dist/core/tools/read.js:138` |
|
||||
| `bash` | `<builtin:bash>` | observed once | `dist/core/tools/bash.js:231` |
|
||||
| `edit` | `<builtin:edit>` | observed once | `dist/core/tools/edit.js:170` |
|
||||
| `write` | `<builtin:write>` | observed once | `dist/core/tools/write.js:138` |
|
||||
| `grep` | `<builtin:grep>` | observed once | `dist/core/tools/grep.js:79` |
|
||||
| `find` | `<builtin:find>` | observed once | `dist/core/tools/find.js:79` |
|
||||
| `ls` | `<builtin:ls>` | observed once | `dist/core/tools/ls.js:61` |
|
||||
|
||||
The raw distinct `event.toolName` result was:
|
||||
|
||||
```json
|
||||
["bash", "edit", "find", "grep", "ls", "read", "write"]
|
||||
```
|
||||
|
||||
Pi registers all seven, but its default active set is only `read`, `bash`, `edit`, and `write` (`dist/core/sdk.js:132`). The probe explicitly activated all seven so the three search/list tools could be observed at the hook.
|
||||
|
||||
## Positive control
|
||||
|
||||
The known `read` tool was the control. The method surfaced it twice:
|
||||
|
||||
1. `pi.getAllTools()` returned `read` with source path `<builtin:read>`.
|
||||
2. Reading `/tmp/pi-registry-probe/seed.txt`, which contained `CONTROL_TOKEN`, produced one hook record with `event.toolName === "read"`.
|
||||
|
||||
The control was therefore positive; the seven-name result is measured, not an empty-probe inference.
|
||||
|
||||
## Carve-out comparison and collision result
|
||||
|
||||
The broker currently declares `{"read", "grep", "find", "ls"}` at `packages/mosaic/framework/tools/lease-broker/daemon.py:54`.
|
||||
|
||||
- `read`: real built-in.
|
||||
- `grep`: real built-in.
|
||||
- `find`: real built-in.
|
||||
- `ls`: real built-in.
|
||||
|
||||
All four carve-out names are exact, case-sensitive Pi tool names.
|
||||
|
||||
The general execution/writing tool names are `bash`, `edit`, and `write`. Their intersection with the carve-out is empty:
|
||||
|
||||
```text
|
||||
{bash, edit, write} ∩ {read, grep, find, ls} = ∅
|
||||
```
|
||||
|
||||
Therefore no general shell-exec or file-mutating Pi tool shares a name with a carve-out entry. `grep` and `find` may invoke constrained search helpers internally, but neither exposes an arbitrary command interface; the arbitrary command tool is distinctly named `bash`.
|
||||
|
||||
The Mosaic extension separately registers the non-built-in custom tool `mosaic_context_recover` at `packages/mosaic/framework/runtime/pi/mosaic-extension.ts:379`; the broker handles that identity through its dedicated recovery exemption rather than the read-only set (`daemon.py:722`). Unknown or third-party custom tools are not part of Pi's built-in seven-name registry and remain outside the carve-out.
|
||||
|
||||
## Verification evidence
|
||||
|
||||
- `pi --version` → `0.84.1`.
|
||||
- Isolated probe exit → `0`.
|
||||
- Runtime `getAllTools()` count → `7`, all with `sourceInfo.source === "builtin"`.
|
||||
- Distinct hook names → `bash`, `edit`, `find`, `grep`, `ls`, `read`, `write`.
|
||||
- Hook counts → exactly one call for each of the seven names.
|
||||
- Mutation artifact after `write` then `edit` → exact content `after`.
|
||||
- Installed registry source → `allToolNames = new Set(["read", "bash", "edit", "write", "grep", "find", "ls"])`.
|
||||
|
||||
## Risks / limitations
|
||||
|
||||
- The probe deliberately disabled all other extensions, so extension-defined third-party tools were excluded from the built-in registry measurement. The production gate still receives those names and treats names outside the broker carve-out as mutating/fail-closed.
|
||||
- Explicit `--tools` activation was required to exercise `grep`, `find`, and `ls`; this does not imply they are active in Pi's default four-tool configuration.
|
||||
@@ -0,0 +1,660 @@
|
||||
---
|
||||
kind: record
|
||||
status: active
|
||||
---
|
||||
|
||||
# Mission Scratchpad — MVP
|
||||
|
||||
> Append-only log. NEVER delete entries. NEVER overwrite sections.
|
||||
> This is the orchestrator's working memory across sessions.
|
||||
|
||||
## Original Mission Prompt
|
||||
|
||||
```
|
||||
Active mission detected: MVP. Read the mission state files and report status.
|
||||
User confirmed: start the planning gate.
|
||||
```
|
||||
|
||||
## Planning Decisions
|
||||
|
||||
### 2026-03-13 — Milestone and task breakdown
|
||||
|
||||
- PRD defines 8 phases (Phase 0–7), mapped 1:1 to Gitea milestones
|
||||
- 59 issues created on git.mosaicstack.dev/mosaic/mosaic-stack (#1–#59)
|
||||
- Each phase has a verification task as the final issue
|
||||
- Task IDs use P{phase}-{seq} format (P0-001 through P7-008)
|
||||
- Repo created as `mosaic/mosaic-stack` (private) on Gitea
|
||||
- Milestones: ms-157 (Phase 0) through ms-164 (Phase 7)
|
||||
- Total: 59 tasks across 8 milestones
|
||||
|
||||
### Phase structure
|
||||
|
||||
| Phase | Version | Tasks | Focus |
|
||||
| ----- | ------- | ----- | ---------------------------------------------------------- |
|
||||
| 0 | v0.0.1 | 9 | Foundation — monorepo, types, db, auth, OTEL, Docker, CI |
|
||||
| 1 | v0.0.2 | 9 | Core API — gateway, brain, queue, routes, WebSocket |
|
||||
| 2 | v0.0.3 | 7 | Agent Layer — Pi SDK, multi-provider, routing, coord |
|
||||
| 3 | v0.0.4 | 8 | Web Dashboard — Next.js, chat, tasks, projects, admin |
|
||||
| 4 | v0.0.5 | 7 | Memory & Intelligence — memory, log, summarization, skills |
|
||||
| 5 | v0.0.6 | 5 | Remote Control — Discord, Telegram, SSO |
|
||||
| 6 | v0.0.7 | 6 | CLI & Tools — CLI, prdy, quality-rails, installer, TUI |
|
||||
| 7 | v0.1.0 | 8 | Polish & Beta — MCP, providers, E2E, docs, release |
|
||||
|
||||
## Session Log
|
||||
|
||||
| Session | Date | Milestone | Tasks Done | Outcome |
|
||||
| ------- | ---------- | -------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| 1 | 2026-03-13 | Planning | Planning gate | Milestones created, 59 issues created, TASKS.md populated, manifest updated |
|
||||
| 2 | 2026-03-13 | Vertical slice | P1-001, P1-007, P1-008, P2-001, P5-002, P6-005 | Communication spine built and merged (PR #61). Gateway + TUI + Discord. 3-agent gatekeeper review, 10/16 issues remediated, 4 deferred. |
|
||||
| 3 | 2026-03-13 | Foundation | P0-002, P0-005, P0-006 | Foundation layer merged (PR #65). Docker Compose (PG+pgvector, Valkey, OTEL Collector, Jaeger), OTEL auto-instrumentation in gateway, @mosaicstack/types with DTOs + Socket.IO typed event maps. |
|
||||
|
||||
### Session 4 — Docker Compose fix
|
||||
|
||||
| Session | Date | Milestone | Tasks Done | Outcome |
|
||||
| ------- | ---------- | ---------- | ---------- | ---------------------------------------------------------------------------------------------------------------- |
|
||||
| 4 | 2026-03-12 | Foundation | (fix) | Fixed Jaeger tag (2→2.6.0), remapped PG/Valkey ports (5433/6380) to avoid host conflicts. PR #66 merged to main. |
|
||||
|
||||
**Verification evidence:**
|
||||
|
||||
- All 4 containers healthy (PG, Valkey, OTEL Collector, Jaeger)
|
||||
- OTEL pipeline proven: `mosaic-gateway` service visible in Jaeger UI
|
||||
- Gateway traces flow through Collector → Jaeger
|
||||
|
||||
### Session 5 — Phase 0-1 completion
|
||||
|
||||
| Session | Date | Milestone | Tasks Done | Outcome |
|
||||
| ------- | ---------- | ---------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
|
||||
| 5 | 2026-03-12 | Phase 0, Phase 1 | P0-003, P0-004, P0-007, P0-008, P0-009, P1-002–P1-006, P1-009 | Foundation + Core API complete. DB, auth, CI, brain, queue, CRUD routes all merged and green. |
|
||||
|
||||
### Session 6 — Phase 2 agent layer
|
||||
|
||||
| Session | Date | Milestone | Tasks Done | Outcome |
|
||||
| ------- | ---------- | --------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
||||
| 6 | 2026-03-12 | Phase 2 | P2-002, P2-003, P2-004, P2-005, P2-006, FIX-01 | Multi-provider routing, tool registration, coord migration, session management, dispose() fix. PRs #74–#78. |
|
||||
|
||||
### Session 7-8 — Phase 2 verification + completion
|
||||
|
||||
| Session | Date | Milestone | Tasks Done | Outcome |
|
||||
| ------- | ---------- | --------- | ---------- | ----------------------------------------------------------------------------------- |
|
||||
| 7-8 | 2026-03-12 | Phase 2 | P2-007 | 19 unit tests (routing + coord). PR #79 merged, issue #25 closed. Phase 2 complete. |
|
||||
|
||||
### Session 11 — Phase 5 completion
|
||||
|
||||
| Session | Date | Milestone | Tasks Done | Outcome |
|
||||
| ------- | ---------- | --------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 11 | 2026-03-14 | Phase 5 | P5-005 | Wired Telegram plugin into gateway (was stubbed). Updated .env.example with all P5 env vars. PR #99 merged, issue #45 closed. Phase 5 complete. |
|
||||
|
||||
**Findings during verification:**
|
||||
|
||||
- Telegram plugin was built but not wired into gateway (stub warning in plugin.module.ts)
|
||||
- Discord plugin was fully wired
|
||||
- SSO/Authentik OIDC adapter was fully wired
|
||||
- All three quality gates passing
|
||||
|
||||
### Session 11 (continued) — Phase 6 completion
|
||||
|
||||
| Session | Date | Milestone | Tasks Done | Outcome |
|
||||
| ------- | ---------- | --------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
||||
| 11 | 2026-03-14 | Phase 6 | P6-002, P6-003, P6-004, P6-001, P6-006 | Full CLI & Tools migration. PRs #100-#104 merged. Also fixed 2 gateway startup bugs (PR #102). Phase 6 complete. |
|
||||
|
||||
**Phase 6 details:**
|
||||
|
||||
- P6-002: @mosaicstack/prdy migrated from v0 (~400 LOC). PR #101.
|
||||
- P6-003: @mosaicstack/quality-rails migrated from v0 (~500 LOC). PR #100.
|
||||
- P6-004: @mosaicstack/mosaic wizard migrated from v0 (2272 LOC, 28 files). PR #103.
|
||||
- P6-001: CLI subcommands wired — tui, prdy, quality-rails, wizard all working. PR #104.
|
||||
- BUG-1: PLUGIN_REGISTRY circular import fixed via plugin.tokens.ts. PR #102.
|
||||
- BUG-2: AuthStorage.create() → .inMemory() to prevent silent exit. PR #102.
|
||||
|
||||
### Session 11 (continued) — E2E testing + bug fixes + Phase 7 rescope
|
||||
|
||||
**Bug fixes merged during E2E testing (PRs #107-#117):**
|
||||
|
||||
- CI: from_secret syntax for Woodpecker v2 (#107)
|
||||
- Gateway: dotenv loading from monorepo root (#108)
|
||||
- Gateway: missing @Inject() decorators causing silent hang (#109)
|
||||
- Gateway: CORS + memory userId + pgvector auto-init (#110)
|
||||
- Auth: BetterAuth trustedOrigins for web dashboard (#111)
|
||||
- Auth: CORS headers on raw BetterAuth HTTP handler (#112)
|
||||
- Husky: removed deprecated v9 shim lines (#113)
|
||||
- CLI: login command + authenticated TUI sessions (#114)
|
||||
- CLI: Origin header on auth requests (#115)
|
||||
- Agent: Ollama provider registration with openai-completions API (#116, #117)
|
||||
|
||||
**E2E testing results:**
|
||||
|
||||
- Web UI: login works, projects list, chats list (but chat doesn't function)
|
||||
- TUI: authenticated connection works, agent responds via Ollama llama3.2
|
||||
- Agent tools: brain, coord, memory tools confirmed working
|
||||
- Gateway: all routes mapped, providers register correctly
|
||||
|
||||
**Phase 7 rescoped (Jason directed):**
|
||||
|
||||
- Phase 7 renamed from "Polish & Beta" to "Feature Completion (v0.0.8)"
|
||||
- Added 13 new tasks (P7-009 through P7-021): web UI, agent tools, CLI, coord architecture
|
||||
- P7-002 (extra SSO), P7-003 (extra LLM), P7-005 (perf), P7-008 (v0.1.0 tag) moved to Phase 8
|
||||
- Phase 8 added as "Polish & Beta (v0.1.0)"
|
||||
- Reason: platform isn't feature-complete enough for beta — web UI is scaffolded but non-functional for real use, agent tooling is minimal, CLI needs model switching
|
||||
|
||||
## Open Questions
|
||||
|
||||
(none at this time)
|
||||
|
||||
## Corrections
|
||||
|
||||
### 2026-03-13 — Vertical slice reorder (Jason directed)
|
||||
|
||||
**Original plan:** Linear Phase 0 → 1 → 2 → ... execution.
|
||||
|
||||
**Correction:** Vertical slice first. Scaffold monorepo, then build the Pi TUI → Gateway → Discord communication spine end-to-end before backfilling auth, brain, memory, CRUD, etc.
|
||||
|
||||
**Why:** Validate the architecture's core message flow before investing in horizontal layers. If the communication channels don't work, nothing else matters.
|
||||
|
||||
**Revised execution sequence:**
|
||||
|
||||
| Step | Tasks (cross-phase) | What it proves |
|
||||
| ---- | -------------------------------------------------------------------- | ------------------------ |
|
||||
| 1 | P0-001: Scaffold monorepo | Build system works |
|
||||
| 2 | P0-005: Docker Compose (PG + Valkey) | Infrastructure runs |
|
||||
| 3 | P0-002: @mosaicstack/types (minimal — gateway, agent, chat types) | Shared contracts |
|
||||
| 4 | P1-001: Gateway scaffold (minimal NestJS + Fastify) | API surface boots |
|
||||
| 5 | P1-007: WebSocket server (chat streaming) | Real-time channel works |
|
||||
| 6 | P1-008: Basic agent dispatch (single provider) | LLM responds |
|
||||
| 7 | P2-001: @mosaicstack/agent — Pi SDK integration (minimal) | Pi sessions work |
|
||||
| 8 | P6-005: Pi TUI integration (mosaic tui → gateway) | TUI ↔ Gateway proven |
|
||||
| 9 | P5-001: Plugin host (channel plugin interface) | Plugin arch works |
|
||||
| 10 | P5-002: Discord plugin (bot + channel) | Discord ↔ Gateway proven |
|
||||
| — | Then backfill: auth, brain, db, queue, OTEL, CI, web dashboard, etc. |
|
||||
|
||||
### Session 9 — Phase 3 Web Dashboard (P3-001 through P3-007)
|
||||
|
||||
| Session | Date | Milestone | Tasks Done | Outcome |
|
||||
| ------- | ---------- | --------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 9 | 2026-03-12 | Phase 3 | P3-001 through P3-007 | Full web dashboard: Next.js 16 scaffold, auth pages, chat UI, tasks (list+kanban), projects, settings, admin. PRs #82-#89 merged. |
|
||||
|
||||
### Session 10 — Phase 3 verification (P3-008)
|
||||
|
||||
| Session | Date | Milestone | Tasks Done | Outcome |
|
||||
| ------- | ---------- | --------- | ---------- | -------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 10 | 2026-03-13 | Phase 3 | P3-008 | Phase 3 verification: typecheck 18/18, lint 18/18, format clean, build green (10 routes), 10 tests pass. Phase 3 complete. |
|
||||
|
||||
### Session 10 (continued) — Phase 4 Memory & Intelligence
|
||||
|
||||
| Session | Date | Milestone | Tasks Done | Outcome |
|
||||
| ------- | ---------- | --------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 10 | 2026-03-13 | Phase 4 | P4-001 through P4-007 | Full memory + log system: DB schema (preferences, insights w/ pgvector, agent_logs, skills, summarization_jobs), @mosaicstack/memory + @mosaicstack/log packages, embedding service, summarization pipeline w/ cron, memory tools in agent sessions, skill management CRUD. All gates green. |
|
||||
|
||||
### Session 12 — Phase 7 planning + execution start
|
||||
|
||||
| Session | Date | Milestone | Tasks Done | Outcome |
|
||||
| ------- | ---------- | --------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 12 | 2026-03-15 | Phase 7 | Planning | Merged rescope PR #119. Created 15 Gitea issues (#120-#134) for P7-009 through P7-021 + FIX-02/FIX-03. Planned 10-wave execution order with 2-worker parallelism. |
|
||||
|
||||
**Phase 7 execution plan (10 waves, max 2 parallel workers):**
|
||||
|
||||
| Wave | Task A | Task B |
|
||||
| ---- | ------------------------------- | -------------------------------------------- |
|
||||
| 1 | P7-009 Web chat WS (#120) | P7-001 MCP hardening (#52) |
|
||||
| 2 | P7-010 Conversation mgmt (#121) | P7-015 Agent tools (#126) |
|
||||
| 3 | P7-011 Project views (#122) | P7-016 MCP client (#127) |
|
||||
| 4 | P7-012 Provider UI (#123) | P7-017 Skill invocation (#128) |
|
||||
| 5 | P7-013 Settings persist (#124) | P7-018 CLI model switch (#129) |
|
||||
| 6 | P7-014 Admin panel (#125) | P7-019 CLI sessions (#130) |
|
||||
| 7 | P7-020 Coord DB (#131) | — |
|
||||
| 8 | FIX-02 TUI state (#133) | FIX-03 Agent sandbox (#134) |
|
||||
| 9 | P7-004 E2E Playwright (#55) | P7-006 Docs (#57) + P7-007 Deploy docs (#58) |
|
||||
| 10 | P7-021 Verify Phase 7 (#132) | — |
|
||||
|
||||
### Session 12 — Phase 7 completion summary
|
||||
|
||||
**All 17 Phase 7 tasks + 2 backlog fixes completed in a single session.**
|
||||
|
||||
PRs merged: #136, #137, #138, #139, #140, #141, #142, #143, #144, #145, #146, #147, #148, #149, #150, #151, #152, #153
|
||||
Issues closed: #52, #55, #57, #58, #120-#134
|
||||
|
||||
**Verification evidence:**
|
||||
|
||||
- Typecheck: 32/32 tasks green
|
||||
- Lint: 18/18 packages green
|
||||
- Format: All files clean
|
||||
- 19 PRs squash-merged to main, all quality gates passed
|
||||
|
||||
**Phase 7 delivered:**
|
||||
|
||||
- Web: functional chat (WS streaming), conversation management, project detail views, provider UI, settings persistence, admin panel
|
||||
- Agent: 7 new tools (file/git/shell/web), MCP server (14 tools), MCP client (external server bridge), skill invocation
|
||||
- CLI: model/provider switching, session management
|
||||
- Infrastructure: coord DB migration, agent sandbox hardening
|
||||
- Quality: E2E Playwright suite (~35 tests), comprehensive docs (user/admin/dev/deployment)
|
||||
- Fixes: TUI state updater, agent session sandboxing
|
||||
|
||||
### Session 13 — CLI Command Architecture (P8-005, P8-006)
|
||||
|
||||
| Session | Date | Milestone | Tasks Done | Outcome |
|
||||
| ------- | ---------- | --------- | -------------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| 13 | 2026-03-15 | Phase 8 | P8-005, P8-006 | CLI command architecture implemented. DB schema, brain repo, gateway endpoints, CLI commands. PR #158 merged. |
|
||||
|
||||
**Changes delivered:**
|
||||
|
||||
- DB: Extended agents table (projectId, ownerId, systemPrompt, allowedTools, skills, isSystem). Added agentId to conversations.
|
||||
- Brain: New agents repository with findAccessible (owner's + system agents).
|
||||
- Gateway: /api/agents CRUD, consolidated /api/missions with user-scoped CRUD + /tasks sub-routes, coord slimmed to file-based only, agentConfigId wired into session creation.
|
||||
- CLI: `mosaic agent` (--list, --new, --show, --update, --delete), `mosaic mission` (--list, --init, --plan, --update, task subcommand), `mosaic prdy` (gateway-aware), shared with-auth + select-dialog utilities.
|
||||
- TUI: --agent and --project flags, agent name display in top bar, agentId in socket payload.
|
||||
- Types: agentId added to ChatMessagePayload.
|
||||
- Tests: 23/23 gateway tests pass (updated ownership test for user-scoped missions).
|
||||
|
||||
### Session 14 — Platform Architecture Plan Augmentation + Task Breakdown
|
||||
|
||||
| Session | Date | Milestone | Tasks Done | Outcome |
|
||||
| ------- | ---------- | --------- | ---------- | ------------------------------------------------------------- |
|
||||
| 14 | 2026-03-15 | Phase 8 | P8-018 | Augmented plan, created 13 issues, created Phase 8 milestone. |
|
||||
|
||||
**Decisions made:**
|
||||
|
||||
- This plan is Phase 7 feature extension work, not Phase 8 beta scope. P8-001–P8-004 (SSO, LLM, perf, release gate) are deferred to far future.
|
||||
- `/provider` OAuth in TUI: URL-to-clipboard + Valkey poll token pattern (same as Pi agent)
|
||||
- Add `mutable` column to preferences now (P8-007 DB migration)
|
||||
- Teams architecture: `teams` + `team_members` tables, `teamId`/`ownerType` on projects. Workspace path branches on owner type: `users/<uid>/` vs `teams/<tid>/`.
|
||||
- Phase dependency chain decided: Wave 1 (DB+Types) → Wave 2 (TUI+toolhardening) → Wave 3 (gateway registry, gating) → Wave 4 (prefs+commands) → Wave 5 (reload+GC) → Wave 6 (workspaces) → Wave 7 (autocomplete) → Wave 8 (verify).
|
||||
|
||||
**Plan augmentations added:**
|
||||
|
||||
- Teams Architecture section (DB schema, workspace paths, RBAC)
|
||||
- REST Route Specifications table
|
||||
- `/provider` OAuth flow (URL+clipboard+polling)
|
||||
- Preferences `mutable` migration spec
|
||||
- Test Strategy (per-task test files + key test cases)
|
||||
- Phase Execution Order (dependency graph + wave plan)
|
||||
|
||||
**Issues created:** #160–#172 (Gitea milestone ms-165)
|
||||
**P8-018 closed:** Spin-off stubs created (gatekeeper-service.md, task-queue-unification.md, chroot-sandboxing.md)
|
||||
|
||||
**Next:** Begin execution at Wave 1 — P8-007 (DB migrations) + P8-008 (Types) in parallel.
|
||||
|
||||
---
|
||||
|
||||
### Session 15 — 2026-04-19 — MVP Rollup Manifest Authored
|
||||
|
||||
| Session | Date | Milestone | Tasks Done | Outcome |
|
||||
| ------- | ---------- | -------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 15 | 2026-04-19 | (rollup-level) | MVP-T01 (manifest), MVP-T02 (archive iuv-v2), MVP-T03 (land FED planning) | Authored MVP rollup manifest at `docs/MISSION-MANIFEST.md`. Federation v1 planning merged to `main` (PR #468 / commit `66512550`). Install-ux-v2 archived as complete. |
|
||||
|
||||
**Gap context:** The MVP scratchpad was last updated at Session 14 (2026-03-15). In the intervening month, two sub-missions ran outside the MVP framework: `install-ux-hardening` (complete, `mosaic-v0.0.25`) and `install-ux-v2` (complete on 2026-04-19, `0.0.27` → `0.0.29`). Both archived under `docs/archive/missions/`. The phase-based execution from Sessions 1–14 (Phases 0–8, issues #1–#172) substantially shipped during this window via those sub-missions and standalone PRs — the MVP mission was nominally active but had no rollup manifest tracking it.
|
||||
|
||||
**User reframe (this session):**
|
||||
|
||||
> There will be more in the MVP. This will inevitably become scope creep. I need a solution that works via webUI, TUI, CLI, and just works for MVP. Federation is required because I need it to work NOW, so my disparate jarvis-brain usage can be consolidated properly.
|
||||
|
||||
**Decisions:**
|
||||
|
||||
1. **MVP is the rollup mission**, not a single-purpose mission. Federation v1 is one workstream of MVP, not MVP itself. Phase 0–8 work is preserved as historical context but is no longer the primary control plane.
|
||||
2. **Three-surface parity (webUI / TUI / CLI) is a cross-cutting MVP requirement** (MVP-X1), not a workstream. Encoded explicitly so it can't be silently dropped.
|
||||
3. **Scope creep is named and accommodated.** Manifest has explicit "Likely Additional Workstreams" section listing PRD-derived candidates without committing execution capacity to them.
|
||||
4. **Workstream isolation** — each workstream gets its own manifest under `docs/{workstream}/MISSION-MANIFEST.md`. MVP manifest is rollup only.
|
||||
5. **Archive-don't-delete** — install-ux-v2 manifest moved to `docs/archive/missions/install-ux-v2-20260405/` with status corrected to `complete` (IUV-M03 closeout note added pointing at PR #446 + releases 0.0.27 → 0.0.29).
|
||||
6. **Federation planning landed first** — PR #468 merged before MVP manifest authored, so the manifest references real on-`main` artifacts.
|
||||
|
||||
**Open items:**
|
||||
|
||||
- `.mosaic/orchestrator/mission.json` MVP slot remains empty (zero milestones). Tracked as MVP-T04. Defer until next session — does not block W1 kickoff. Open question: hand-edit vs. `mosaic coord init` reinit.
|
||||
- Additional workstreams (web dashboard parity, TUI/CLI completion, remote control, multi-user/SSO, LLM provider expansion, MCP, brain) anticipated per PRD but not declared. Pre-staged in manifest's "Likely Additional Workstreams" list.
|
||||
|
||||
**Artifacts this session:**
|
||||
|
||||
| Artifact | Status |
|
||||
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| PR #468 (`docs(federation): PRD, milestones, mission manifest, and M1 task breakdown`) | merged 2026-04-19 → `main` (commit `66512550`) |
|
||||
| `docs/MISSION-MANIFEST.md` (MVP rollup, replaces install-ux-v2 manifest) | authored on `docs/mvp-mission-manifest` branch |
|
||||
| `docs/TASKS.md` (MVP rollup, points at workstream task files) | authored |
|
||||
| Install-ux-v2 manifest + tasks + scratchpad + iuv-m03-design | moved to `docs/archive/missions/install-ux-v2-20260405/` with status corrected to complete |
|
||||
|
||||
**Next:** PR `docs/mvp-mission-manifest` → merge to `main` → next session begins W1 / FED-M1 from clean state.
|
||||
|
||||
---
|
||||
|
||||
## Session 16 — 2026-04-19 — claude
|
||||
|
||||
**Mode:** Delivery (W1 / FED-M1 execution)
|
||||
**Branch:** `feat/federation-m1-tier-config`
|
||||
**Context budget:** 200K, currently ~45% used (compaction-aware)
|
||||
|
||||
**Goal:** FED-M1-01 — extend `mosaic.config.json` schema: add `"federated"` to tier enum.
|
||||
|
||||
**Critical reconciliation surfaced during pre-flight:**
|
||||
|
||||
The federation PRD (`docs/federation/PRD.md` line 247) defines three tiers: `local | standalone | federated`.
|
||||
The existing code (`packages/config/src/mosaic-config.ts`, `packages/mosaic/src/types.ts`, `packages/mosaic/src/stages/gateway-config.ts`) uses `local | team`.
|
||||
|
||||
`team` is the same conceptual tier as PRD `standalone` (Postgres + Valkey, no pgvector). Rather than carrying a confusing alias forever, FED-M1-01 will rename `team` → `standalone` and add `federated` as a third value, so all downstream federation work has a coherent vocabulary.
|
||||
|
||||
Affected files (storage-tier semantics only — Team/workspace usages unaffected):
|
||||
|
||||
- `packages/config/src/mosaic-config.ts` (StorageTier type, validator enum, defaults)
|
||||
- `packages/mosaic/src/types.ts` (GatewayStorageTier)
|
||||
- `packages/mosaic/src/stages/gateway-config.ts` (~10 references)
|
||||
- `packages/mosaic/src/stages/gateway-config.spec.ts` (test references)
|
||||
- Possibly `tools/e2e-install-test.sh` (referenced grep) and headless env hint string
|
||||
|
||||
**Worker plan:**
|
||||
|
||||
1. Spawn sonnet subagent with explicit task spec + the reconciliation context above.
|
||||
2. Worker delivers diff; orchestrator runs `pnpm typecheck && pnpm lint && pnpm format:check`.
|
||||
3. Independent `feature-dev:code-reviewer` subagent reviews diff.
|
||||
4. Second independent verification subagent (general-purpose, sonnet) verifies reviewer's claims and confirms all `'team'` storage-tier references migrated, no `Team`/workspace bleed.
|
||||
5. Open PR via tea CLI; wait for CI; queue-guard; squash merge; record actuals.
|
||||
|
||||
**Open items:**
|
||||
|
||||
- `MVP-T04` (sync `.mosaic/orchestrator/mission.json`) still deferred.
|
||||
- `team` tier rename touches install wizard headless env vars (`MOSAIC_STORAGE_TIER=team`); will need 0.0.x deprecation note in scratchpad if release notes are written this milestone.
|
||||
|
||||
---
|
||||
|
||||
## Session 17 — 2026-04-19 — claude
|
||||
|
||||
**Mode:** Delivery (W1 / FED-M1 execution; resumed after compaction)
|
||||
**Branches landed this run:** `feat/federation-m1-tier-config` (PR #470), `feat/federation-m1-compose` (PR #471), `feat/federation-m1-pgvector` (PR #472)
|
||||
**Branch active at end:** `feat/federation-m1-detector` (FED-M1-04, ready to push)
|
||||
|
||||
**Tasks closed:** FED-M1-01, FED-M1-02, FED-M1-03 (all merged to `main` via squash, CI green, issue #460 still open as milestone).
|
||||
|
||||
**FED-M1-04 — tier-detector:** Worker delivered `apps/gateway/src/bootstrap/tier-detector.ts` (~210 lines) + `tier-detector.spec.ts` (12 tests). Independent code review (sonnet) returned `changes-required` with 3 issues:
|
||||
|
||||
1. CRITICAL: `probeValkey` missing `connectTimeout: 5000` on the ioredis Redis client (defaulted to 10s, violated fail-fast spec).
|
||||
2. IMPORTANT: `probePgvector` catch block did not discriminate "library not installed" (use `pgvector/pgvector:pg17`) from permission errors.
|
||||
3. IMPORTANT: Federated tier silently skipped Valkey probe when `queue.type !== 'bullmq'` (computed Valkey URL conditionally).
|
||||
|
||||
Worker fix-up round addressed all three:
|
||||
|
||||
- L147: `connectTimeout: 5000` added to Redis options
|
||||
- L113-117: catch block branches on `extension "vector" is not available` substring → distinct remediation per failure mode
|
||||
- L206-215: federated branch fails fast with `service: 'config'` if `queue.type !== 'bullmq'`, then probes Valkey unconditionally
|
||||
- 4 new tests (8 → 12 total) cover each fix specifically
|
||||
|
||||
Independent verifier (haiku) confirmed all 6 verification claims (line numbers, test presence, suite green: 12/12 PASS).
|
||||
|
||||
**Process note — review pipeline working as designed:**
|
||||
|
||||
Initial verifier (haiku) on the first delivery returned "OK to ship" but missed the 3 deeper issues that the sonnet code-reviewer caught. This validates the user's "always verify subagent claims independently with another subagent" rule — but specifically with the **right tier** for the task: code review needs sonnet-level reasoning, while haiku is fine for verifying surface claims (line counts, file existence) once review issues are known. Going forward: code review uses sonnet (`feature-dev:code-reviewer`), claim verification uses haiku.
|
||||
|
||||
**Followup tasks tracked but deferred:**
|
||||
|
||||
- #7: `tier=local` hardcoded in gateway-config resume branches (~262, ~317) — pre-existing bug, fix during M1-06 (doctor) or M1-09 (regression).
|
||||
- #8: confirm `packages/config/dist` not git-tracked.
|
||||
|
||||
**Next:** PR for FED-M1-04 → CI wait → merge. Then FED-M1-05 (migration script, codex/sonnet, 10K).
|
||||
|
||||
---
|
||||
|
||||
## Session 18 — 2026-04-19 — FED-M1-07 + FED-M1-08
|
||||
|
||||
**Branches landed this run:** `feat/federation-m1-integration` (PR #476, FED-M1-07), `feat/federation-m1-migrate-test` (PR #477, FED-M1-08)
|
||||
**Branch active at end:** none — both PRs merged to main, branches deleted
|
||||
|
||||
**M1 progress:** 8 of 12 tasks done. Remaining: M1-09 (regression e2e, haiku), M1-10 (security review, sonnet), M1-11 (docs, haiku), M1-12 (close + release, orchestrator).
|
||||
|
||||
### FED-M1-07 — Integration tests for federated tier gateway boot
|
||||
|
||||
Three test files under `apps/gateway/src/__tests__/integration/` gated by `FEDERATED_INTEGRATION=1`:
|
||||
|
||||
- `federated-boot.success.integration.test.ts` — `detectAndAssertTier` resolves; `pg_extension` row for `vector` exists
|
||||
- `federated-boot.pg-unreachable.integration.test.ts` — throws `TierDetectionError` with `service: 'postgres'` when PG port is closed
|
||||
- `federated-pgvector.integration.test.ts` — TEMP table with `vector(3)` column round-trips data
|
||||
|
||||
Independent code review (sonnet) returned VERDICT: B with two IMPORTANT items, both fixed in the same PR:
|
||||
|
||||
- Port 5499 collision risk → replaced with `net.createServer().listen(0)` reserved-port helper
|
||||
- `afterAll` and `sql` scoped outside `describe` → moved both inside `describe.skipIf` block
|
||||
|
||||
Independent surface verifier (haiku) confirmed all claims. 4/4 tests pass live; 4/4 skip cleanly without env var.
|
||||
|
||||
### FED-M1-08 — Migration integration test (caught real P0 bug)
|
||||
|
||||
`packages/storage/src/migrate-tier.integration.test.ts` seeds temp PGlite with cross-table data (users, teams, team_members, conversations, messages), runs `runMigrateTier`, asserts row counts + spot-checks. Gated by `FEDERATED_INTEGRATION=1`.
|
||||
|
||||
**P0 bug surfaced and fixed in same PR:** `DrizzleMigrationSource.readTable()` returns Drizzle's camelCase keys (`emailVerified`, `userId`); `PostgresMigrationTarget.upsertBatch()` was using them verbatim as SQL identifiers, producing `column "emailVerified" does not exist` against real federated PG. The 32 unit tests in M1-05 missed this because both source and target were mocked. Fix: `normaliseSourceRow` now applies `toSnakeCase` (`/[A-Z]/g` → `_<lowercase>`), idempotent on already-snake_case keys.
|
||||
|
||||
Code review (sonnet) returned VERDICT: B with one IMPORTANT and one MINOR, both fixed:
|
||||
|
||||
- `createPgliteDbWithVector` and `runPgliteMigrations` were initially added to `@mosaicstack/db` public exports → moved to `packages/storage/src/test-utils/pglite-with-vector.ts` (avoids polluting prod consumers with WASM bundle)
|
||||
- `afterAll` did not call `cleanTarget` → added before connection close, ensuring orphan rows cleaned even on test panic
|
||||
|
||||
Side change: `packages/storage/package.json` gained `"type": "module"` (codebase convention; required for `import.meta.url` in test-utils). All other workspace packages already declared this.
|
||||
|
||||
### Process notes for this session
|
||||
|
||||
- Review-then-verify pipeline now battle-tested: M1-08 reviewer caught the P0 bug + the public-API leak that the worker would have shipped. Without review, both would have gone to main.
|
||||
- Integration tests are paying for themselves immediately: M1-08 caught a real P0 in M1-05 that 32 mocked unit tests missed. Going forward, **at least one real-services integration test per code-mutating PR** should become a soft norm where feasible.
|
||||
- TASKS.md status updates continue to ride on the matching feature branch (avoids direct-to-main commits).
|
||||
|
||||
**Followup tasks tracked but still deferred (no change):**
|
||||
|
||||
- #7: `tier=local` hardcoded in gateway-config resume branches (~262, ~317)
|
||||
- #8: confirm `packages/config/dist` not git-tracked
|
||||
|
||||
**Next:** FED-M1-09 — standalone regression e2e (haiku canary, ~4K). Verifies that the existing `standalone` tier behavior still works end-to-end on the federation-touched build, since M1 changes touched shared paths (storage, config, gateway boot).
|
||||
|
||||
---
|
||||
|
||||
## Session 19 — 2026-04-19 — FED-M1-09 → FED-M1-12 (M1 close)
|
||||
|
||||
**Branches landed this run:** `feat/federation-m1-regression` (PR #478, M1-09), `feat/federation-m1-security-review` (PR #479, M1-10), `feat/federation-m1-docs` (PR #480, M1-11), `feat/federation-m1-close` (PR #481, M1-12)
|
||||
**Branch active at end:** none — M1 closed, all branches deleted, issue #460 closed, release tag `fed-v0.1.0-m1` published
|
||||
|
||||
**M1 progress:** 12 of 12 tasks done. **Milestone complete.**
|
||||
|
||||
### FED-M1-09 — Standalone regression canary
|
||||
|
||||
Verification-only milestone. Re-ran the existing standalone/local test suites against current `main` (with M1-01 → M1-08 merged):
|
||||
|
||||
- 4 target gateway test files: 148/148 pass (conversation-persistence, cross-user-isolation, resource-ownership, session-hardening)
|
||||
- Full gateway suite: 351 pass, 4 skipped (FEDERATED_INTEGRATION-gated only)
|
||||
- Storage unit tests: 85 pass, 1 skipped (integration-gated)
|
||||
- Top-level `pnpm test`: all green; only env-gated skips
|
||||
|
||||
No regression in standalone or local tier. Federation M1 changes are non-disruptive.
|
||||
|
||||
### FED-M1-10 — Security review (two rounds, 7 findings)
|
||||
|
||||
Independent security review surfaced three high-impact and four medium findings; all fixed in same PR.
|
||||
|
||||
**Round 1 (4 findings):**
|
||||
|
||||
- MEDIUM: Credential leak via `postgres`/`ioredis` driver error messages (DSN strings) re-thrown by `migrate-tier.ts` → caller; `cli.ts:402` outer catch
|
||||
- MEDIUM: Same leak in `tier-detection.ts` `probePostgresMeasured` / `probePgvectorMeasured` → emitted as JSON by `mosaic gateway doctor --json`
|
||||
- LOW-MEDIUM: No advisory lock on `migrate-tier`; two concurrent invocations could both pass `checkTargetPreconditions` (non-atomic) and race
|
||||
- ADVISORY: `SKIP_TABLES` lacked rationale comment
|
||||
|
||||
**Fixes:**
|
||||
|
||||
- New internal helper `packages/storage/src/redact-error.ts` — regex `(postgres(?:ql)?|rediss?):\/\/[^@\s]*@` → `<scheme>://***@`. NOT exported from package public surface. 10 unit tests covering all schemes, multi-URL, no-creds, case-insensitive.
|
||||
- `redactErrMsg` applied at all 5 leak sites
|
||||
- `PostgresMigrationTarget.tryAcquireAdvisoryLock()` / `releaseAdvisoryLock()` using session-scoped `pg_try_advisory_lock(hashtext('mosaic-migrate-tier'))`. Acquired before preflight, released in `finally`. Dry-run skips. Non-blocking.
|
||||
- `SKIP_TABLES` comment expanded with rationale for skipped tables (TTL'd / one-time / env-bound) AND why `accounts` (OAuth) and `provider_credentials` (AI keys) are intentionally migrated (durable user-bound, not deployment-bound).
|
||||
|
||||
**Round 2 (3 findings missed by first round):**
|
||||
|
||||
- HIGH: Round 1 regex only covered `postgres` scheme, not `redis`/`rediss` — extended to `(postgres(?:ql)?|rediss?)`
|
||||
- HIGH: `probeValkeyMeasured` was missed in Round 1 → applied `redactErrMsg`
|
||||
- MEDIUM: `cli.ts:402` migrate-tier outer catch was missed in Round 1 → applied `redactErrMsg`
|
||||
|
||||
**Process validation:** the two-round review pattern proved load-bearing for security work. A single review-then-fix cycle would have shipped the Valkey credential leak.
|
||||
|
||||
### FED-M1-11 — Docs (haiku)
|
||||
|
||||
- `docs/federation/SETUP.md` (119 lines): federated tier setup — what it is, prerequisites, docker compose start, mosaic.config.json snippet, doctor health check, troubleshooting
|
||||
- `docs/guides/migrate-tier.md` (147 lines): when to migrate, dry-run first, what migrates/skips with rationale, idempotency + advisory-lock semantics, no in-place rollback
|
||||
- `README.md` Configuration blurb linking to both
|
||||
- Runbook deferred to FED-M7 per TASKS.md scope rule
|
||||
|
||||
### FED-M1-12 — Aggregate close (this PR)
|
||||
|
||||
- Marked M1-12 done in TASKS.md
|
||||
- MISSION-MANIFEST.md: phase → "M1 complete", progress 1/7, M1 row done with PR range #470-#481, session log appended
|
||||
- This Session 19 entry added
|
||||
- Issue #460 closed via `~/.config/mosaic/tools/git/issue-close.sh -i 460`
|
||||
- Release tag `fed-v0.1.0-m1` created and pushed to gitea
|
||||
|
||||
### M1 PR ledger
|
||||
|
||||
| PR | Task | Branch |
|
||||
| ---- | ----------------------------------------- | ---------------------------------- |
|
||||
| #470 | M1-01 (tier config schema) | feat/federation-m1-tier-config |
|
||||
| #471 | M1-02 (compose overlay) | feat/federation-m1-compose |
|
||||
| #472 | M1-03 (pgvector adapter) | feat/federation-m1-pgvector |
|
||||
| #473 | M1-04 (tier-detector) | feat/federation-m1-detector |
|
||||
| #474 | M1-05 (migrate-tier script) | feat/federation-m1-migrate |
|
||||
| #475 | M1-06 (gateway doctor) | feat/federation-m1-doctor |
|
||||
| #476 | M1-07 (boot integration tests) | feat/federation-m1-integration |
|
||||
| #477 | M1-08 (migrate integration test + P0 fix) | feat/federation-m1-migrate-test |
|
||||
| #478 | M1-09 (standalone regression) | feat/federation-m1-regression |
|
||||
| #479 | M1-10 (security review fixes) | feat/federation-m1-security-review |
|
||||
| #480 | M1-11 (docs) | feat/federation-m1-docs |
|
||||
| #481 | M1-12 (aggregate close) | feat/federation-m1-close |
|
||||
|
||||
### Process learnings (M1 retrospective)
|
||||
|
||||
1. **Two-round security review is non-negotiable for security work.** First round caught postgres credential leaks; second round caught equivalent valkey leaks the worker missed when extending the regex. Single-round would have shipped HIGH severity issues.
|
||||
2. **Real-services integration tests catch what mocked unit tests cannot.** M1-08 caught a P0 in M1-05 (camelCase column names) that 32 mocked unit tests missed because both source and target were mocked. Going forward: at least one real-services test per code-mutating PR where feasible.
|
||||
3. **Test-utils for live services co-locate with consumer, not in shared library.** M1-08 reviewer caught `createPgliteDbWithVector` initially being added to `@mosaicstack/db` public exports — would have polluted prod consumers with WASM bundle. Moved to `packages/storage/src/test-utils/`.
|
||||
4. **Per-task budgets including tests/review/docs more accurate than PRD's implementation-only estimates.** M1 PRD estimated 20K; actual ~74K. Future milestones should budget the full delivery cycle.
|
||||
5. **TASKS.md status updates ride feature branches, never direct-to-main.** Caught one violation early in M1; pattern held for all 12 tasks.
|
||||
6. **Subagent tier matters.** Code review needs sonnet-level reasoning (haiku missed deep issues in M1-04); claim verification (line counts, file existence) is fine on haiku.
|
||||
|
||||
**Followup tasks still deferred (carry forward to M2):**
|
||||
|
||||
- #7: `tier=local` hardcoded in gateway-config resume branches (~262, ~317)
|
||||
- #8: confirm `packages/config/dist` not git-tracked
|
||||
|
||||
**Next mission step:** FED-M2 (Step-CA + grant schema + admin CLI). Per TASKS.md scope rule, M2 will be decomposed when it enters active planning. Issue #461 tracks scope.
|
||||
|
||||
## Session 20 — 2026-04-21 — FED-M2 kickoff
|
||||
|
||||
### Decisions
|
||||
|
||||
- **Workstream split**: parallel CODE (M2-01..M2-13, ~72K) + DEPLOY (DEPLOY-01..DEPLOY-05, ~16K) tracks; re-converge at M2-10 E2E.
|
||||
- **Test hosts**: `mos-test-1.woltje.com` (querying side / Server A), `mos-test-2.woltje.com` (serving side / Server B). Wildcard `*.woltje.com` A→174.137.97.162 already exists; Traefik wildcard cert covers both subdomains. No DNS or cert work needed pre-deploy.
|
||||
- **Portainer access**: requires `PORTAINER_INSECURE=1` flag added to mosaic wrappers (self-signed cert at `https://10.1.1.43:9443`). PR pending on `feat/mosaic-portainer-tls-flag`.
|
||||
- **Image policy**: deploy by digest (immutable) per Mosaic policy. `gateway:fed-v0.1.0-m1` digest = `sha256:9b72e202a9eecc27d31920b87b475b9e96e483c0323acc57856be4b1355db1ec`.
|
||||
|
||||
### DEPLOY-01 — image manifest verified
|
||||
|
||||
- Tag `fed-v0.1.0-m1` exists at `git.mosaicstack.dev/mosaicstack/stack/gateway`
|
||||
- Digest: `sha256:9b72e202a9eecc27d31920b87b475b9e96e483c0323acc57856be4b1355db1ec`
|
||||
- 9 layers, ~530MB total
|
||||
- Use this digest in DEPLOY-02 stack template (do NOT reference `:fed-v0.1.0-m1` tag in stack — pin to digest)
|
||||
|
||||
### Registry auth note
|
||||
|
||||
- Gitea container registry uses Bearer token flow (`/v2/token?service=container_registry&scope=repository:<repo>:pull`)
|
||||
- Username: `jarvis` (NOT `mosaicstack`); password: `gitea.mosaicstack.token` from credentials.json
|
||||
- Direct `Authorization: Bearer <pat>` does NOT work — must exchange PAT for registry token first
|
||||
|
||||
### Active PRs
|
||||
|
||||
- #483 — docs: M2 mission planning (TASKS decomposition + manifest update) — CI running
|
||||
- (pending) `feat/mosaic-portainer-tls-flag` — wrapper PORTAINER_INSECURE flag (sonnet subagent in progress)
|
||||
- (pending) `feat/federation-m2-schema` — FED-M2-01 DB schema migration (sonnet subagent in progress)
|
||||
|
||||
### MISSION-MANIFEST layout fix
|
||||
|
||||
- Initial M2 commit had Test Infrastructure block inserted by lint-staged prettier between "Last Updated" and "Parent Mission" — split mission frontmatter
|
||||
- Fixed in 3d001fdb: moved Parent Mission back to frontmatter, kept Test Infrastructure as standalone H2 between Mission and Context
|
||||
|
||||
## Session 21 — 2026-04-21/22 — DEPLOY-02 merged, gateway image bug discovered, M2-01 in remediation
|
||||
|
||||
### PRs merged
|
||||
|
||||
- **#483** — docs(federation): M2 mission planning (TASKS decomposition + manifest update)
|
||||
- **#484** — feat(mosaic-portainer): PORTAINER_INSECURE flag for self-signed TLS (wrapper sync to `~/.config/mosaic/tools/portainer/` done manually due to broken `mosaic upgrade` `set -o pipefail` on dash)
|
||||
- **#485** — feat(deploy): portainer stack template `deploy/portainer/federated-test.stack.yml` for federation test instances [DEPLOY-02]
|
||||
|
||||
### Stack deployed (mos-test-1, mos-test-2)
|
||||
|
||||
- Both stacks created on Portainer endpoint 3 (`local` Swarm @ 10.1.1.43, the only endpoint with traefik-public + woltje.com wildcard cert)
|
||||
- Swarm ID `l7z67tfpd4bvj4979ufpkyi50`
|
||||
- Image pinned to digest `sha256:9b72e202a9eecc27d31920b87b475b9e96e483c0323acc57856be4b1355db1ec`
|
||||
- Traefik labels target `${HOST_FQDN}` per env
|
||||
|
||||
### CRITICAL FINDING — gateway image runtime-broken
|
||||
|
||||
- `docker run` against `gateway:fed-v0.1.0-m1` fails immediately:
|
||||
`Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dotenv' imported from /app/dist/main.js`
|
||||
- Root cause: `docker/gateway.Dockerfile` copies `/app/node_modules` from builder — but pnpm puts deps in the content-addressed `.pnpm/` store with symlinks at `apps/gateway/node_modules/*`. The runner stage misses the symlinks → Node can't resolve workspace deps.
|
||||
- M1 release was never runtime-tested as a stripped container; CI passed because tests run in dev tree where pnpm symlinks are intact.
|
||||
- **Fix in flight** (subagent `a78a9ab0ddae91fbc`): switch builder to `pnpm --filter @mosaic/gateway --prod deploy /deploy`, then runner copies `/deploy/node_modules` + `/deploy/dist` + `/deploy/package.json`.
|
||||
|
||||
### M2-01 schema review verdict — NEEDS CHANGES
|
||||
|
||||
- PR #486 (`feat/federation-m2-schema`) — independent reviewer (sonnet) found 2 real issues:
|
||||
1. `federation_audit_log` time-range indexes missing `.desc()` on `created_at` (3 places)
|
||||
2. Reserved columns missing per TASKS.md M2-01 spec: `query_hash`, `outcome`, `bytes_out` (M4 will write; spec said reserve now)
|
||||
- Also notes (advisory): subject_user_id correctly `text` (matches BetterAuth users.id; spec defect, not code defect); peer→grant cascade test not present (would be trivial to add)
|
||||
- **Remediation in flight** (subagent `a673dd9355dc26f82` in worktree `agent-a4404ac1`): apply DESC + reserved cols, regenerate migration in place (preferred) or stack 0009 (fallback), force-push, post PR comment.
|
||||
|
||||
### Process notes
|
||||
|
||||
- Branch race incident: schema subagent + wrapper subagent both ran in main checkout → schema files appeared on wrapper branch. Recovered by TaskStop, `git checkout --` to clean, respawned schema subagent with `isolation: "worktree"`. **Rule going forward:** any subagent doing code edits gets `isolation: "worktree"` unless work is single-file and the orchestrator confirms no other branch will touch overlapping files.
|
||||
- `pr-create.sh` shell-quotes backticks badly → use `tea pr create --repo mosaicstack/stack` directly (matches CLI-skill behavior). Will leave a followup to harden pr-create.sh.
|
||||
- Gitea registry auth: bearer-token exchange flow (`/v2/token?service=container_registry&scope=repository:<repo>:pull`) — direct `Authorization: Bearer <pat>` returns 401.
|
||||
- Portainer Swarm stack create endpoint: `POST /api/stacks/create/swarm/string?endpointId=<id>` (NOT `/api/stacks?type=1` — deprecated and rejected with 400).
|
||||
|
||||
### In-flight at compaction boundary
|
||||
|
||||
- Subagent `a78a9ab0ddae91fbc` — Dockerfile pnpm-deploy fix → PR (not yet opened at handoff)
|
||||
- Subagent `a673dd9355dc26f82` — M2-01 schema remediation (DESC + reserved cols) → force-push to PR #486
|
||||
- Both will trigger CI; orchestrator must independently re-review fixes (especially the security-adjacent schema work) per "always verify subagent claims" rule.
|
||||
|
||||
### Next after subagents return
|
||||
|
||||
1. Independent re-review of schema remediation (different subagent, fresh context)
|
||||
2. Merge #486 if green
|
||||
3. Merge Dockerfile fix PR if green → triggers Kaniko CI rebuild → capture new digest
|
||||
4. Update `deploy/portainer/federated-test.stack.yml` to new digest in a small PR
|
||||
5. Redeploy mos-test-1 + mos-test-2 (Portainer stack update via API)
|
||||
6. Verify HTTPS reachability + `/health` endpoint at both hosts
|
||||
7. DEPLOY-03/04 acceptance probes (`mosaic gateway doctor --json`, pgvector `vector(3)` round-trip)
|
||||
8. DEPLOY-05: author `docs/federation/TEST-INFRA.md`
|
||||
9. M2-02 (Step-CA sidecar) kicks off after image health is green
|
||||
|
||||
### Session 23 — 2026-04-21 — M2 close + M3 decomposition
|
||||
|
||||
**Closed at compaction boundary:** all 13 M2 tasks done, PRs #494–#503 merged to `main`, tag `fed-v0.2.0-m2` published, Gitea release notes posted, issue #461 closed. Main at `4ece6dc6`.
|
||||
|
||||
**M2 hardening landed in PR #501** (security review remediation):
|
||||
|
||||
- CRIT-1: post-issuance OID verification in `ca.service.ts` (rejects cert if `mosaic_grant_id` / `mosaic_subject_user_id` extensions missing or mismatched)
|
||||
- CRIT-2: atomic activation guard `WHERE status='pending'` on grant + `WHERE state='pending'` on peer; throws `ConflictException` if lost race
|
||||
- HIGH-2: removed try/catch fallback in `extractCertNotAfter` — parse failures propagate as 500 (no silent 90-day default)
|
||||
- HIGH-4: token slice for logging (`${token.slice(0, 8)}...`) — no full token in stdout
|
||||
- HIGH-5: `redeem()` wrapped in try/catch with best-effort failure audit; uses `null` (not `'unknown'`) for nullable UUID FK fallback
|
||||
- MED-3: `createToken` validates `grant.peerId === dto.peerId`; `BadRequestException` on mismatch
|
||||
|
||||
**Remaining M2 security findings deferred to M3+:**
|
||||
|
||||
- HIGH-1: peerId/subjectUserId tenancy validation on `createGrant` (M3 ScopeService work surfaces this)
|
||||
- HIGH-3: Step-CA cert SHA-256 fingerprint pinning (M5 cert handling)
|
||||
- MED-1: token entropy already 32 bytes — wontfix
|
||||
- MED-2: per-route rate limit on enrollment endpoint (M4 rate limit work)
|
||||
- MED-4: CSR CN binding to peer's commonName (M3 AuthGuard work)
|
||||
|
||||
**M3 decomposition landed in this session:**
|
||||
|
||||
- 14 tasks (M3-01..M3-14), ~100K estimate
|
||||
- Structure mirrors M1/M2 pattern: foundation → server stream + client stream + harness in parallel → integration → E2E → security review → docs → close
|
||||
- M3-02 ships local two-gateway docker-compose (`tools/federation-harness/`) so M3-11 E2E is not blocked on the Portainer test bed (which is still blocked on `FED-M2-DEPLOY-IMG-FIX`)
|
||||
|
||||
**Subagent doctrine retained from M2:**
|
||||
|
||||
- All worker subagents use `isolation: "worktree"` to prevent branch-race incidents
|
||||
- Code review is independent (different subagent, no overlap with author of work)
|
||||
- `tea pr create --repo mosaicstack/stack --login mosaicstack` is the working PR-create path; `pr-create.sh` has shell-quoting bugs (followup #45 if not already filed)
|
||||
- Cost tier: foundational implementation = sonnet, docs = haiku, complex multi-file architecture (security review, scope service) = sonnet with two review rounds
|
||||
|
||||
**Next concrete step:**
|
||||
|
||||
1. PR for the M3 planning artifact (this commit) — branch `docs/federation-m3-planning`
|
||||
2. After merge, kickoff M3-01 (DTOs) on `feat/federation-m3-types` with sonnet subagent in worktree
|
||||
3. Once M3-01 lands, fan out: M3-02 (harness) || M3-03 (AuthGuard) → M3-04 (ScopeService) || M3-08 (FederationClient)
|
||||
4. Re-converge at M3-10 (Integration) → M3-11 (E2E)
|
||||
@@ -0,0 +1,104 @@
|
||||
---
|
||||
kind: record
|
||||
status: active
|
||||
---
|
||||
|
||||
# PR merge squash message field
|
||||
|
||||
- **Charter:** `/home/hermes/agent-work/CHARTER-PRMERGE-MESSAGE-FIELD.md`
|
||||
- **Owner:** `be-coder-08`
|
||||
- **Branch:** `fix/pr-merge-message-field`
|
||||
- **Base:** remote `main` / local `origin/main` at `85d2108e4ed15c744ad3b87a5b629e7b2d39405a`
|
||||
- **Estate:** HOMELAB tooling shared by HOMELAB and USC
|
||||
|
||||
## Objective
|
||||
|
||||
Add an optional, identity-checked Gitea squash message to `pr-merge.sh` so genuine multi-author PRs retain non-poster branch authors without weakening hardcoded squash behavior.
|
||||
|
||||
## Binding requirements
|
||||
|
||||
1. `Do` remains hardcoded to `squash`; no provider/repository default may select merge style.
|
||||
2. A verified trailer uses a PR commit's linked `author.login` and that same commit's author email. No `/users/{login}` primary-email lookup occurs. Recorded rationale: this asks only what the provider can answer.
|
||||
3. A commit with `author.login` null blocks before merge, prints both the null provider fact and commit email fact, and names the escalation principal.
|
||||
4. The BLOCK arm must be observed firing; a normal canonical single-author API payload remains explicit squash plus its reviewed `head_commit_id`.
|
||||
5. Every provider mutation is read back from the provider; no real PR is merged during tests.
|
||||
|
||||
## Derived interface decisions
|
||||
|
||||
- Add `--co-author-trailers` rather than accepting arbitrary message text. The wrapper enumerates PR commits and constructs trailers, making an unchecked `Co-authored-by` line unexpressible.
|
||||
- Require `--escalate-to PRINCIPAL` with `--co-author-trailers`, so the BLOCK diagnostic always names a principal rather than a generic role.
|
||||
- Do not expose `MergeTitleField` separately. When trailers exist, set it from the provider PR title and set `MergeMessageField` only to construction-generated trailers. This preserves one provider source for the title and avoids an unrelated caller-controlled degree of freedom.
|
||||
- Preserve first-commit order and emit one trailer per distinct non-poster `author.login`, using that first linked commit's own email.
|
||||
|
||||
## Canonical delivery plan
|
||||
|
||||
1. Port the capability into the installed source of truth, `packages/mosaic/framework/tools/git/pr-merge.sh`; do not retain `infra/fleet/tools/git` as a second copy.
|
||||
2. Preserve canonical `--expect-head`, exact head branch/repository/SHA queue inspection, Gitea atomic head pinning, GitHub `--match-head-commit`, and delete-after-merge semantics.
|
||||
3. Do not port the deployed-only `--skip-queue-guard` bypass. Add the focused harness to the canonical framework-shell suite and re-establish RED/GREEN on the packaged baseline.
|
||||
4. Deliver through a reviewed package release followed by `mosaic update` with its default framework reseed. The installer snapshots, manifest-syncs framework-owned `tools/**`, and rolls back on failure.
|
||||
5. Before either estate relies on the change, require installed/package hash equality, `MergeMessageField` presence, and a green focused harness. Release/reseed ownership is currently unassigned and blocks activation after source merge.
|
||||
|
||||
## Evidence
|
||||
|
||||
- RED against the byte-identical deployed baseline (`sha256 08a65e8584c5…`): rc 1 with eight named failures. The wrapper rejected `--co-author-trailers`; the null-login path emitted none of the required BLOCK facts/principal; and both verified/ordinary API paths failed the stdin-config credential assertion (ordinary path exposed the fixture token through curl argv). Log: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-message-field-red.log`.
|
||||
- GREEN on the deployed-baseline candidate: verified linked multi-author payload, null-login BLOCK, required named principal, explicit squash, stdin-config token transport, and absence of `/users` lookup all passed. Log: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-message-field-green.log`.
|
||||
- RED against canonical packaged baseline `c581ef48…`: rc 1 with 32 assertions. It rejects the new option, and the first harness version did not satisfy canonical head branch/repository/SHA metadata. Log: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-packaged-baseline-red.log`. The port adapts the fixture rather than weakening canonical head controls.
|
||||
- Provider capability probe against `git.mosaicstack.dev`: authenticated `be-coder-08` POST to deliberately nonexistent PR `2147483647` with both message fields returned JSON HTTP 404; the unauthenticated same request returned JSON HTTP 401 (not the charter's predicted 403). The authenticated-vs-unauthenticated differential proves write authorization resolved while no mergeable subject existed. `tl-mosaic` ruled the literal non-load-bearing: preserve the observed 404/401 pair and do not manufacture a 403 case. No cause was inferred and no real PR was targeted.
|
||||
- Provider-generated trailer behavior is not treated as exclusive or absent. The wrapper's VERIFIED/BLOCK decision binds each requested non-poster trailer to commit `author.login` plus that commit's email; it does not assume `MergeMessageField` is the squash's only trailer source. The poster is omitted from the constructed list because the resulting squash author already records the poster; any additional provider-generated trailer is outside this change's unmeasured mechanism.
|
||||
- An early candidate SHA-256 `5de32876990e4f26920448cb3220cc7f1146d558b4dd2bc1ee1a2abee2f2cbe6` passed the initial harness, then author-side review found credential-fallback and argv-exposure defects. The live deployed wrapper was atomically restored to baseline SHA-256 `08a65e8584c52c6d41ea1c686f8b95585c21e4b37320a2447eba09359a0e02c1`; the remediated candidate remains only in the worktree.
|
||||
|
||||
## Remediation and current review state
|
||||
|
||||
1. Token and Basic Auth now use stdin curl configuration, not argv. PR title, contributor email, and the JSON payload also remain out of child argv.
|
||||
2. Each credential attempt binds commit inspection and merge. A token failure during either inspection or mutation causes Basic fallback to repeat inspection before mutation; the payload pins the inspected `head_commit_id`.
|
||||
3. Focused tests cover token-resolution fail-closed behavior, both HTTP-401 fallback seams, metadata/credential argv absence, null-login BLOCK, explicit squash, canonical reviewed-head binding, unchanged ordinary payload, and retained log-safe provider diagnostics. Token-resolution RED: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-token-resolution-red.log`.
|
||||
4. Codex review rounds 3–5 requested retained provider error text, log-safe provider diagnostics, fail-closed credential fallback, stable value-option parsing, and PR-title trailer-injection prevention. These are remediated with regression assertions. A post-remediation independent review is still required.
|
||||
5. **Accepted linkage limitation:** `author.login` resolution proves that the commit address maps to a registered provider account. It does not prove that the named principal authored the commit because Git author metadata is self-asserted. This gate checks attribution linkage, not authorship; commit signing is out of scope and currently unadopted. Coordinators explicitly ruled that this does not add a third state.
|
||||
6. Codex's sandbox could not execute the harness because its checkout was read-only; that environmental limitation is recorded separately from host-side test results.
|
||||
|
||||
## Disposable provider fixture acceptance
|
||||
|
||||
- Use a retained scratch repository only, with two branch authors and `author != committer` on at least one commit.
|
||||
- Arm A supplies a message-field trailer for one non-poster; record whether that value lands without forcing the partial-pair result into under-specified `APPENDS`/`REPLACES` labels. Demonstrate an absence control.
|
||||
- Arm B includes a registered trailer for a different non-poster on a branch commit; record whether it survives or drops. Verify identity through an existing commit whose `author.login` resolves and demonstrate an absence control.
|
||||
- Parse landed trailers key-agnostically with `^[A-Za-z-]+-[Bb]y:` and record generated poster pair presence/absence plus resulting poster attribution.
|
||||
- Record `/users/<login>` status and raw email only as non-gating estate telemetry. Never read `active`, `visibility`, or any profile field as an identity gate.
|
||||
- Use distinct principals: poster `be-coder-08`, merger `Mos`, Arm A `be-coder-07`, and Arm B `be-coder-06`. Capture every trailer-shaped line verbatim and in order. Zero trailer lines means the generator did not fire and the run is `VOID`, not evidence that either arm dropped.
|
||||
- Report the same read-back evidence to `mos-claude` on socket `default` and `tl-mosaic` on socket `mosaic-fleet`. Report values rather than mechanism inferences and stop on any poster-attribution regression.
|
||||
|
||||
## Fixture preflight
|
||||
|
||||
- Retained public repository: `mosaicstack/prmerge-trailer-fixture`; PR `#1`, posted by `be-coder-08` and reserved for merge by `Mos`.
|
||||
- Existing `mosaicstack/stack` commits resolve `be-coder-07` and `be-coder-06` through `author.login`; exact addresses are `[email protected]` and `[email protected]`.
|
||||
- Non-gating HOMELAB telemetry for authenticated reader `be-coder-08`: `/api/v1/users/be-coder-06` returned HTTP 200 with raw `email` value `[email protected]`.
|
||||
- Provider preflight showed PR commit enumeration is newest-first. A new RED test proved that deriving `head_commit_id` from the final array element selected the wrong commit. The candidate now reads `.head.sha` from the authenticated PR endpoint before enumeration, verifies it appears in the commit set, and atomically pins that SHA in the explicit squash payload. RED: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-head-order-red.log`.
|
||||
- Fixture PR head `f6ba6e5105031fa21f5ff7bd8e4379d99c16e1de` has `author.login=be-coder-07`, `committer.login=be-coder-08`, and branch-message trailer `Co-authored-by: be-coder-06 <[email protected]>`.
|
||||
|
||||
## Fixture result
|
||||
|
||||
- `Mos` merged retained fixture PR `#1` through staged candidate SHA-256 `60e779a85fd13b729d859ea7c986d1e9b1641b97991611329226c1b3113ffb6e`; resulting squash commit: `3f550715d9bc716426fd355a65fe997b3a90fa7d` with one parent.
|
||||
- Provider read-back: poster/commit author `be-coder-08`, committer/merger `Mos`. The run is non-void.
|
||||
- Trailer-shaped lines, verbatim and in order:
|
||||
1. `Co-authored-by: be-coder-07 <[email protected]>`
|
||||
2. `Co-authored-by: be-coder-08 <[email protected]>`
|
||||
- Arm A supplied field value (`be-coder-07`) landed. Arm B branch trailer (`be-coder-06`) dropped. Both fabricated absence controls remained absent. No `Co-committed-by:` line landed.
|
||||
- The candidate payload construction explicitly excludes the poster and supplied only the Arm A `be-coder-07` line. Therefore the landed poster line was provider-generated, not candidate-composed. The raw result supports `FIELD LANDS`, `BRANCH DROPS`, and `POSTER GENERATED`; it does not support a claim that candidate code supplied the poster. Evidence: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-fixture-readback.log` and the retained provider object.
|
||||
- Retained fixture PR `#2` measured the N=2 shape needed by `#1030`: supplied `be-coder-07` then `be-coder-06`; both landed in that order, followed by the provider-generated poster line. No truncation or dedup occurred at N=2. Resulting squash: `39db9d13aed0…`.
|
||||
|
||||
## Current hold point
|
||||
|
||||
PR `mosaicstack/stack#1066` is open. Its first frozen head `f4b162fa…` was terminal-green in Woodpecker `mosaic` pipeline `#2225`, but that evidence becomes stale when the canonical port moves the head. The deployed wrapper remains baseline `08a65e85…`; no manual copy will occur. Canonical port tests, commit amendment, rebase, one guarded force-with-lease, exact-head CI, and new independent review remain. Even after source merge, activation remains blocked on an assigned package-release/reseed owner and installed-byte read-back.
|
||||
|
||||
## Security review 96 remediation
|
||||
|
||||
Exact reviewed predecessor head: `1ceb11058f64dd7f4a817ceb2124f980a1c4dd23`.
|
||||
|
||||
RED-first focused harness produced 10 named failures: all curl calls lacked size/time/connect bounds; raw ESC email reached mutation; oversized and stalled curl failures were discarded and reached mutation; nonempty Basic output with resolver rc 91 authorized mutation.
|
||||
|
||||
Security remediation:
|
||||
|
||||
- Removed the cross-principal HTTP-401 Basic fallback. Both inspection-401 and merge-401 paths now refuse without Basic resolution or mutation; `get_gitea_basic_auth` references in the merge subject are 0.
|
||||
- Applied `--max-filesize`, `--max-time`, and `--connect-timeout` to all 3/3 provider curl sites and fail closed on curl transport rc at all 3/3 sites.
|
||||
- Required linked email bytes to be ASCII and printable before constructing `MergeMessageField`; guarded construction sites 1/1.
|
||||
|
||||
GREEN: message-field, exact-head, empty-UID/API, queue branch/repository/SHA, bash syntax, ShellCheck, and diff check pass. R7 total-removal mutants went RED: email guard 3 rows; bound switches 1 row; transport-rc guards 4 rows; HTTP-401 refusal 3 rows. R7 bound: mutants prove total removal only; explicit denominators above prove site coverage.
|
||||
@@ -0,0 +1,247 @@
|
||||
---
|
||||
kind: record
|
||||
status: active
|
||||
---
|
||||
|
||||
# Scratchpad — RI-050 orchestrator (jarvis, dragon-lin)
|
||||
|
||||
Mission: alpha 0.0.50 release-integrity floor. Issue #1275. Base `next` @ 476db12b.
|
||||
Design SSOT: jarvis-brain `docs/plans/2026-08-16_mosaic-stack-sdlc-protocol.md` (SDLC-D-033..038).
|
||||
|
||||
## Mode (Jason's directives)
|
||||
|
||||
- Orchestrator: jarvis (this session, dragon-lin). NOT mos-claude; work stays on this host.
|
||||
- Workers: local pi headless — `pi --model zai/glm-5.3:high -p` in the card's worktree, tools read,bash,edit,write.
|
||||
- Delegation override of stack AGENTS.md `agent` column: rows carry `pi-glm-5.3` (outside cron table so no auto-claim).
|
||||
- Target branch: `next`. Cards branch from `origin/next`, squash-merge via PR.
|
||||
|
||||
## Operational constraints (measured this session)
|
||||
|
||||
- Main checkout at `/home/jwoltje/src/mosaic-stack` is a dirty diverged `main` (ahead 1139/behind 711) — NEVER touched. All work in `/home/jwoltje/src/mosaic-stack-worktrees/<branch>`.
|
||||
- Disk: /home 187G free. /tmp only 8.7G — keep pnpm stores/node_modules under /home.
|
||||
- `main` and `next` have DIVERGED; PRs target `next`.
|
||||
- Identity: pin `GITEA_LOGIN=mosaicstack-jarvis` for all wrapper ops. Issue #1275 verified authored by @jarvis.
|
||||
- `ci-queue-wait.sh` on this host is fail-open (board: fix #1032 not installed) — substitute SHA-status checks via `/commits/{sha}/status` and diff failing step names.
|
||||
- CI on PRs runs `pull_request` pipelines (any branch) incl. ci-postgres service. Push CI runs on main only; publish runs on push/tag to next + manual.
|
||||
- Wrapper gaps on this host per board (7 gaps; e.g. no pr-review-list, issue-assign broken, pr-merge makes no trailers): verify outcomes by reading back provider state, never trust rc alone.
|
||||
- Publish pipeline currently: install → build → publish-npm/publish-next-npm (+image). No verify. CI steps: install, sanitization, upgrade-guard, typecheck, lint, format, test, ci-postgres.
|
||||
|
||||
## Budget
|
||||
|
||||
Soft cap 250K. Projected 190K across 10 cards. Track per-card used vs estimate in TASKS.md notes.
|
||||
|
||||
## Progress log
|
||||
|
||||
- 2026-08-16 23:52 — Issue #1275 created (@jarvis verified).
|
||||
- 2026-08-16 23:5x — Bootstrap branch `docs/ri-050-mission-bootstrap` from origin/next@476db12b; PRD section + TASKS.md + this scratchpad written. RI-0-001 in-progress.
|
||||
|
||||
## Wave 1 dispatched (2026-08-17 00:35)
|
||||
|
||||
- RI-1-001 worker: pi glm-5.3:high, pid 2322125, worktree ri-1-001, log /var/tmp/ri-050/ri-1-001-run.log
|
||||
- RI-2-001 worker: pi glm-5.3:high, pid 2322126, worktree ri-2-001, log /var/tmp/ri-050/ri-2-001-run.log
|
||||
- Gotcha recorded: pi has no -f flag (that's pi-do.sh); pass brief as positional message. First launch died "Unknown option: -f" — relaunched.
|
||||
- CI lane: PR #1276 (bootstrap) fails `test` at base like every next PR — fred's green #1270 unblocks (comms sent 2026-08-17T05:21Z, `comms/20260817T052148Z__from-jarvis__650fe8.md`). Merge gate for all RI PRs queues behind #1270.
|
||||
- Live RI-N1 evidence posted to #1275 (comment 22915): pipeline 2439 publish-next-npm SUCCESS beside build-gateway FAILURE.
|
||||
|
||||
---
|
||||
|
||||
# HANDOFF — RI-050 continuation (written 2026-08-17 ~08:45 UTC, jarvis/dragon-lin)
|
||||
|
||||
You are taking over the alpha 0.0.50 release-integrity workstream in place. Everything you
|
||||
need is on the remote. Read this whole file, then `docs/release-integrity/TASKS.md` (same
|
||||
branch), then the PRD section (`docs/PRD.md` § Release Integrity Workstream, same branch).
|
||||
|
||||
## Identity / mode
|
||||
|
||||
- Orchestrator identity: `jarvis` (dragon-lin). You continue as the RI-050 orchestrator under
|
||||
whatever identity Jason gives you — if you are NOT jarvis, say so in comms and PR bodies.
|
||||
- Jason's standing directives for this mission: work happens on THIS repo (mosaicstack/stack),
|
||||
PRs target `next` (NOT main), workers are local pi headless sessions on
|
||||
`zai/glm-5.3:high`. Do not hand this to mos-claude. Do not borrow other seats' lanes.
|
||||
- All wrapper ops: pin `GITEA_LOGIN=mosaicstack-jarvis` (issue #1275 was verified authored by
|
||||
@jarvis; keep identity consistent or verify yours with issue-view and READ BACK user.login).
|
||||
- CI substitution rule (this host's ci-queue-wait.sh is fail-open; fix #1032 not installed):
|
||||
judge CI by SHA-status via `/api/v1/repos/mosaicstack/stack/commits/{sha}/status` or the
|
||||
woodpecker API (`pipeline-status.sh -r mosaicstack/stack -n N -f json`), and DIFF THE
|
||||
FAILING STEP NAMES rather than trusting rc.
|
||||
|
||||
## Mission state at handoff
|
||||
|
||||
Mission: alpha 0.0.50 release-integrity floor. Issue #1275 (open, has live-evidence comment).
|
||||
Decisions SDLC-D-033..038 live in jarvis-brain
|
||||
`docs/plans/2026-08-16_mosaic-stack-sdlc-protocol.md` (normative text also mirrored in the
|
||||
PRD section on this branch, so this repo is self-sufficient).
|
||||
|
||||
Base: `origin/next` @ 476db12b. NOTE: `main` and `next` have DIVERGED — never base on main.
|
||||
|
||||
Branches (all pushed, all clean trees):
|
||||
|
||||
- `docs/ri-050-mission-bootstrap` @ 5114faa2 → PR #1276 (open, mergeable) — bootstrap docs +
|
||||
this scratchpad + TASKS.md DAG. STATUS: CI red on `test` only, which is the known lane-wide
|
||||
failure (see blocker below); own prettier issue already fixed.
|
||||
- `feat/ri-050-publish-gate` @ 0aa5ed35 → PR #1277 (open, mergeable) — RI-1-001 COMPLETE
|
||||
(worker reported success, orchestrator review PASSED: verify step asserts CI_COMMIT_SHA ==
|
||||
git rev-parse HEAD then runs canonical `pnpm verify:release`; every publish/image step
|
||||
depends_on verify directly, confirmed by parsing the DAG: publish-npm, publish-next-npm,
|
||||
build-gateway/appservice/web all -> [build, verify]; invariant test
|
||||
scripts/verify-release.test.mjs passes 7/7 locally with negative fixtures). CI: same known
|
||||
lane-red `test` step only.
|
||||
- `fix/ri-050-forge-fail-closed` @ 99b8f6ea → PR #1278 (open, mergeable) — RI-2-001 worker
|
||||
reported success (typed `FORGE_*` capability errors, --simulate typed simulated everywhere,
|
||||
vacuous true/echo gates replaced, closed ForgeOutcome set, 116 tests green incl. 16 new).
|
||||
ORCHESTRATOR REVIEW NOT YET DONE — your first job. Review the diff
|
||||
(1391 insertions across forge src), check the fail-closed paths and that simulated
|
||||
results cannot satisfy any consumer, run `pnpm --filter @mosaicstack/forge test`.
|
||||
|
||||
## The one blocker
|
||||
|
||||
Every `next` PR pipeline is red on ONE assertion:
|
||||
`packages/mosaic/framework/tools/fleet/test-start-agent-session.sh:103` ("host provides 'pi'
|
||||
in the system path"). Pre-existing at base; affects PRs #1276/#1277/#1278 identically.
|
||||
fred's PR #1270 ("unblocks every PR on next") is green and open — it is HIS to merge; do not
|
||||
merge it yourself. jarvis sent comms (`comms/20260817T052148Z__from-jarvis__650fe8.md` in
|
||||
jarvis-brain) asking merge timing; no reply yet as of handoff. Merge gates for ALL RI PRs
|
||||
queue behind #1270 landing. Until then: review/develop freely, merge nothing that needs the
|
||||
green gate (docs-only #1276 arguably could merge red-lane with Jason's explicit call — ask,
|
||||
don't assume).
|
||||
|
||||
## Remaining DAG (docs/release-integrity/TASKS.md is canonical)
|
||||
|
||||
Wave 2 (next): RI-2-002 MACP fail-closed (brief pattern: mirror RI-2-001 for
|
||||
packages/macp/src/gate-runner.ts — empty commands, stub executors, unimplemented CI-provider
|
||||
gates fail closed; explicit simulate) and RI-4-001 PRD authority (one PRD service;
|
||||
@mosaicstack/prdy docs/prdy authoritative via `mosaic mission --plan`; `mosaic prdy` routes
|
||||
or becomes named Markdown adapter; mission<->PRD linkage persists — see PRD RI-N3).
|
||||
Wave 3: RI-3-001 probe inventory (docs), RI-5-001 web stale-safety.
|
||||
Wave 4: RI-1-002 negative-control tests, RI-3-002 TS evaluator absorbs shell probes.
|
||||
Final: RI-V-001 evidence pack (real green next publish run post-gate + all cards verified).
|
||||
|
||||
## Worker mechanics (measured, reuse)
|
||||
|
||||
- Dispatch: create worktree `git -C /home/jwoltje/src/mosaic-stack worktree add
|
||||
/home/jwoltje/src/mosaic-stack-worktrees/<id> -b <branch> origin/next`, write a brief to
|
||||
/var/tmp/ri-050/, then run from INSIDE the worktree:
|
||||
`pi -p --no-session --model zai/glm-5.3:high --tools read,bash,edit,write "$(cat brief.md)"`
|
||||
(pi has NO -f flag — pass the brief as a positional message; first dispatch died on that).
|
||||
- Briefs for 1-001/2-001 are at /var/tmp/ri-050/ on dragon-lin (may not survive; the
|
||||
pattern is fully described above and in TASKS.md).
|
||||
- Briefs must carry: worktree path, branch, base, requirements, known base-red list (so the
|
||||
worker doesn't chase it), gates to run, PR creation command with GITEA_LOGIN pin, "do NOT
|
||||
merge, do NOT touch docs/TASKS.md", and the JSON report format.
|
||||
- Verify worker claims: read the PR, run their tests yourself, parse pipeline step names.
|
||||
|
||||
## Do-not-touch
|
||||
|
||||
- Main checkout at /home/jwoltje/src/mosaic-stack (dirty diverged main) — never touch.
|
||||
- fred's open PRs (#1270 and others) — review evidence welcome, merging his is not yours.
|
||||
- Other RI PRs' authors' lanes: #1277/#1278 are yours to gate and merge ONCE lane is green
|
||||
and review is recorded.
|
||||
- Never `--no-verify`; never bypass the wrapper-fails-closed rule (wrapper failure ⇒
|
||||
`blocked + report exact command + stop`).
|
||||
|
||||
## Session-restore command sequence
|
||||
|
||||
1. `git -C /home/jwoltje/src/mosaic-stack-worktrees/ri-050 fetch origin --prune`
|
||||
2. Read this file + `docs/release-integrity/TASKS.md` + PRD section.
|
||||
3. Check PR states (#1270, #1276, #1277, #1278) and lane CI (SHA-status per above).
|
||||
4. Review RI-2-001 (PR #1278) if not yet done; then dispatch wave 2.
|
||||
|
||||
— jarvis, 2026-08-17
|
||||
|
||||
---
|
||||
|
||||
# CONTINUATION — fargo (sb-it-1-dt)
|
||||
|
||||
Orchestrator seat is now **fargo** on sb-it-1-dt (Jason, 2026-08-17): Claude seat, worktree discipline
|
||||
per fred's ruling (`~/agent-work/<slug>`, create → work → commit → push → remove as one act; the
|
||||
helper's `/src` refusal is a web1 convention, does not bind here). fred supports; lane rulings are
|
||||
his. Workers remain local pi `zai/glm-5.3:high` + limited Claude per Jason.
|
||||
|
||||
## 2026-08-17 — RI-2-001 independent review DONE
|
||||
|
||||
- **PR #1278 APPROVED** (Gitea review 172, pinned to head 99b8f6ea). Executed evidence, not read-only:
|
||||
forge suite 116/116 at head (matches PR claim), forge lint green, forge typecheck green after
|
||||
building `@mosaicstack/macp` dist (TS2307 on bare `pnpm install --frozen-lockfile` is a
|
||||
minimal-install build-order artifact — the macp import is type-only, vitest passes unbuilt; CI
|
||||
installs build workspace deps, hence green there), **workspace typecheck 45/45 at head**,
|
||||
consumer sweep: no external type consumers of RunManifest/StageStatus/ForgeTaskResult/
|
||||
TaskExecutor; only importer of the package is packages/mosaic via registerForgeCommand
|
||||
(smoke test asserts registration/help only — cannot break). Digest gate (shaggy's) before==after
|
||||
with both-arm reactivity controls.
|
||||
- CI red on #1276/#1277/#1278: lane-wide `test` failure only
|
||||
(test-start-agent-session.sh:103, fred's guard mis-wired; #1270 unwires it). Fred measured log
|
||||
content: one real byte-identical failure per pipeline (2456/2457/2458); 13 of ~14 `FAIL` grep
|
||||
hits are passing fail-loud test NAMES. **The red carries no information about the RI changes.**
|
||||
- Non-blocking finding: README L141-143 + skills/mosaic-forge/SKILL.md document bare
|
||||
`mosaic forge run`/`resume`, which now exits 1 FORGE_NO_EXECUTOR — fast-follow docs touch.
|
||||
- **Identity incident, ruled on by fred:** review 172 recorded under shared host principal
|
||||
mos-dt-0, not fargo. Mechanism (measured, wrapper source): pr-review.sh resolves its acting login
|
||||
from the tea login list only; no fargo tea login on this host → silent host-default fallback;
|
||||
MOSAIC_GIT_IDENTITY is only read in detect-platform.sh get_gitea_token's fallback arm, never
|
||||
reached. Exact-id read-back verifies against the writing token, so it passed while attribution
|
||||
was wrong — durable-provenance machinery proves the write, not the seat. Fred's ruling: review
|
||||
172 stands (substance/verdict/pin correct; label wrong); NO re-approval (one approval,
|
||||
annotated, is the stronger record); fred posts the provenance correction under @fred with
|
||||
--login fred-ms (hard-fail path); no fargo tea login ever (freeze + Jason's to authorize);
|
||||
tooling gap filed by fred. Also explains (does not reopen) #1228's mos-dt-0 attribution.
|
||||
- Merge gate: all RI PRs queue behind fred's green #1270 (Jason's call).
|
||||
|
||||
## Next
|
||||
|
||||
1. Wave 2 dispatch: RI-2-002 (MACP fail-closed, mirror RI-2-001 pattern for
|
||||
packages/macp/src/gate-runner.ts) + RI-4-001 (PRD authority). Two parallel workers max.
|
||||
2. Docs fast-follow (README + mosaic-forge skill) — fold into #1276 or a tiny docs card.
|
||||
3. RI-V-001 evidence at the end.
|
||||
|
||||
— fargo, 2026-08-17
|
||||
|
||||
---
|
||||
|
||||
# RESUMPTION + DAILY-HANDOFF PROTOCOL (Jason, 2026-08-17)
|
||||
|
||||
Orchestrator seat is back with **jarvis** (dragon-lin). Expect daily handoff between jarvis
|
||||
and fargo. Protocol (both seats, every handoff):
|
||||
|
||||
1. **This file is the shared mission log.** Append a dated section per session: state
|
||||
measured, actions taken, PR/review states, next actions. Never rewrite prior sections.
|
||||
2. **TASKS.md stays current within one session** — status, PR number in notes, review
|
||||
evidence. Stale rows are handoff debt.
|
||||
3. **Cross-review rule (SDLC-D-011 in practice):** the reviewing seat must differ from the
|
||||
producing seat. jarvis reviews fargo-dispatched PRs, fargo reviews jarvis-dispatched
|
||||
PRs. Producers are always pi workers; dispatching seats verify before push; the other
|
||||
seat records the Gitea review.
|
||||
4. Handoff = append here + push + (optional) issue #1275 comment if a decision changed.
|
||||
|
||||
## RESUMED — jarvis/dragon-lin, 2026-08-17 (afternoon)
|
||||
|
||||
- Measured: next = 8199261c (#1270 merged — lane unblocked for new PRs). #1293/#1294
|
||||
(fargo, wave 2) CI-green, mergeable, no recorded reviews. #1276/#1277/#1278 still based
|
||||
on 476db12b with stale red CI → need rebase onto 8199261c. #1278 review pinned to old
|
||||
head 99b8f6ea by @mos-dt-0 (fargo's, mis-attributed per his note) — rebase will dismiss
|
||||
it; re-approval must come from fargo/fred (author is @jarvis, cannot self-approve).
|
||||
- Live evidence #2: push pipeline 2462 (the #1270 merge itself) ran publish-next-npm
|
||||
SUCCESS beside build-gateway FAILURE again.
|
||||
- Plan: rebase the three original branches; independently review #1293/#1294; merge order
|
||||
once green+reviewed: #1276 (docs) → #1277 (publish gate) → #1278/#1293/#1294 (code).
|
||||
After #1277 merges, watch the next push pipeline prove the verify gate live.
|
||||
- fargo's non-RI PRs (#1291/#1296/#1297/#1281) stay strictly his lane.
|
||||
|
||||
## jarvis session 2026-08-17 (evening) — reviews, rebases, merge plan
|
||||
|
||||
- Rebased #1276/#1277/#1278 onto 8199261c (heads 59e2c460 / 46784c8d / 4917df1f);
|
||||
invariant tests 7/7 and forge 116/116 re-run green at new heads. #1270 touched
|
||||
test-enumeration-exclusions.txt + package.json, NOT ci.yml — no semantic overlap with
|
||||
#1277's ci.yml changes (checked, was a real concern).
|
||||
- Independent reviews recorded: #1293 APPROVED (review 173; macp 109/109; fail-closed paths
|
||||
+ aggregate state machine verified), #1294 APPROVED (review 174; prdy 20/20 + command
|
||||
specs 9/9; single-writer + linkage persistence + labeled export + conflict-aware import
|
||||
verified). Note: 19 unrelated mosaic suites fail on bare minimal install (known workspace
|
||||
build-order artifact, documented by fargo) — not this change.
|
||||
- Measured: `next` has NO branch protection (API: only main listed). Cross-seat review
|
||||
discipline is protocol-enforced, not Gitea-enforced. Flagged to fargo for Jason: direct
|
||||
pushes to next trigger ungated publishes; protection is Jason's call (#1231 adjacent).
|
||||
- Merge order planned: #1276 (docs-only — no publish run) -> #1277 (first gated publish)
|
||||
-> #1278 -> #1293 -> #1294. Sent fargo review requests with pinned head SHAs
|
||||
(comms/20260818T011932Z__from-jarvis__a9c02b.md). Not merging #1293/#1294 before my three
|
||||
clear fargo's review — order optimality beats speed; every pre-#1277 merge publishes ungated.
|
||||
- CI on the three rebased heads: pending at time of this entry.
|
||||
@@ -0,0 +1,104 @@
|
||||
---
|
||||
kind: record
|
||||
status: active
|
||||
---
|
||||
|
||||
# P3-R1 — Routing Health Enum + `/mcp` Wiring Scratchpad
|
||||
|
||||
**Task:** P3 hands-on acceptance blockers #1 and #5
|
||||
**Mission:** `mvp-20260312` (active)
|
||||
**Branch:** `feat/webui-p3r1-routing-mcp` from `origin/next`
|
||||
**Required base:** `20718b5a273d243363a4f5cbef5bbf692a805bdb`
|
||||
**Tracking ref:** Direct P3-R1 author brief; no provider issue supplied; no PR or merge authorized
|
||||
**Started:** 2026-08-11T14:52:52-05:00
|
||||
|
||||
## Objective
|
||||
|
||||
Fix exactly two P3 acceptance blockers:
|
||||
|
||||
1. Make routing consume the canonical `ProviderHealthStatus` enum, with `healthy` and `degraded` routable and `down` non-routable, at both routing decision sites.
|
||||
2. Wire `McpClientModule` into `CommandsModule`, make `McpClientService` required, remove the unreachable unavailable-service branch, and prove `/mcp status` reaches the client.
|
||||
|
||||
Explicitly excluded: provider registry/adapters, `provider.service.ts`, `agent.service.ts`, `chat.gateway.ts`, fallback membership, task classification, selector UI, conversation resume, reload UX, WS/origin/handshake behavior, dependencies/lockfile, and `apps/web/**` changes.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Confirm exact base/branch and inspect every cited source/test anchor plus all direct `CommandExecutorService` construction sites.
|
||||
2. Record baseline gateway and focused routing/commands/MCP test totals.
|
||||
3. Add regression tests first and run focused tests to capture expected RED failures.
|
||||
4. Apply only the typed routing helper/signature changes and required MCP module/constructor/guard changes; update impossible `up` fixtures.
|
||||
5. Run focused tests, all user-required verification gates, lockfile/scope/diff checks, and record counts.
|
||||
6. Obtain independent spec and code/security review; remediate any findings and repeat affected gates.
|
||||
7. Commit conventionally, run the pre-push queue guard, and push only the feature branch (no PR or merge).
|
||||
|
||||
## Budget
|
||||
|
||||
No explicit token cap supplied. Working soft cap: **30K tokens**, based on two bounded gateway bug fixes, focused TDD, full gateway/root verification, independent review, and branch delivery. One coding worker will execute serially; reviews will be independent and serial to avoid worktree collisions.
|
||||
|
||||
## Startup Evidence
|
||||
|
||||
- `git fetch origin` rc=0.
|
||||
- `origin/next` confirmed exactly `20718b5a273d243363a4f5cbef5bbf692a805bdb`.
|
||||
- Local and remote `feat/webui-p3r1-routing-mcp` were absent before creation.
|
||||
- Branch creation rc=0; HEAD equals the required base.
|
||||
- Harness-owned `.mosaic/orchestrator/session.lock` was already dirty and remains excluded from staging/commit.
|
||||
|
||||
## Baseline Evidence
|
||||
|
||||
- Gateway full suite: rc=0; **64 files / 693 tests passed**, 7 files / 17 tests skipped (71 files / 710 tests total).
|
||||
- Routing sub-suite (`src/agent/routing`): rc=0; **3 files / 105 tests passed**.
|
||||
- Commands/MCP sub-suite (`src/commands`, `src/mcp-client`): rc=0; **6 files / 76 tests passed**.
|
||||
|
||||
## TDD and Implementation Evidence
|
||||
|
||||
- Routing RED: after canonical fixture/test changes but before the service fix, focused routing run returned rc=1 with **15 failed / 91 passed (106)** because the old `up`/`ok` gates rejected `healthy` and `degraded`.
|
||||
- Routing GREEN: canonical `ProviderHealthStatus` map types, one `isRoutable` helper, and both comparison sites corrected; focused routing suite passed.
|
||||
- MCP behavior test now drives `/mcp status` through a required mock client and asserts the client is called, success is returned for zero servers, and the former unavailable message is absent.
|
||||
- MCP wiring mutation RED used the final `Reflect.getMetadata('imports', CommandsModule)` assertion with only the production `McpClientModule` import/registration temporarily removed: rc=1, exact failure `expected [GCModule, …] to include McpClientModule`.
|
||||
- MCP wiring GREEN after byte-for-byte production restoration: rc=0. Temporary mutation did not remain.
|
||||
- Every direct `new CommandExecutorService(...)` test construction now supplies a non-null MCP client mock.
|
||||
- Initial Codex worker launch failed rc=1 from missing OpenAI bearer authentication. First Mosaic Claude launch failed rc=1 because Distrobox-local runtime contracts were absent; retry with the supported host `MOSAIC_HOME=/home/jwoltje/.config/mosaic` succeeded.
|
||||
|
||||
## Review Evidence
|
||||
|
||||
- Independent spec review: **approve**, 0 blockers, scope OK.
|
||||
- Independent code/security review: **approve**, 0 blockers, 0 critical/high security findings. It suggested an actual module-wiring assertion, which was added with valid mutation RED/GREEN evidence.
|
||||
- Independent final re-review after remediation: **approve**, 0 blockers, 0 critical/high security findings, no remaining findings.
|
||||
- Optional missing-provider/`undefined` test suggestion was not adopted: the brief explicitly requires the three canonical statuses (`healthy`, `degraded`, `down`) and forbids scope expansion; runtime behavior for absent keys remains `undefined` → non-routable through the required helper signature.
|
||||
|
||||
## Documentation Assessment
|
||||
|
||||
- `docs/PRD.md` already requires provider fallback/routing and MCP capability; this increment restores implementation to those existing contracts.
|
||||
- No public API endpoint, payload schema, auth/permission rule, navigation, deployment procedure, or new user workflow changes. OpenAPI, endpoint index, user/admin/developer guides, and sitemap are therefore N/A for this bounded repair.
|
||||
- This append-only scratchpad is the implementation, TDD, review, and verification record. Canonical docs remain in-repo; no publishing action is in scope.
|
||||
|
||||
## Final Verification Evidence
|
||||
|
||||
All required and repository-situational gates completed with rc=0:
|
||||
|
||||
| Gate | Result |
|
||||
| --- | --- |
|
||||
| `pnpm install --frozen-lockfile` | rc=0 |
|
||||
| Gateway typecheck | rc=0 |
|
||||
| Gateway lint | rc=0 |
|
||||
| Routing focused suite | rc=0; 3 files / 106 tests |
|
||||
| Commands/MCP focused suite | rc=0; 6 files / 78 tests |
|
||||
| Gateway full suite | rc=0; 64 files / 696 tests passed; 7 files / 17 tests skipped |
|
||||
| Gateway build | rc=0 |
|
||||
| Root typecheck | rc=0; 45/45 tasks |
|
||||
| Web test | rc=0; 19 files / 154 tests |
|
||||
| Root lint | rc=0; 25/25 tasks |
|
||||
| Root format check | rc=0 |
|
||||
| `git diff --check` | rc=0 |
|
||||
|
||||
- Gateway suite before→after: **693→696 passing tests**; skipped remained 17 (total 710→713).
|
||||
- Routing focused before→after: **105→106 passing tests**.
|
||||
- Commands/MCP focused before→after: **76→78 passing tests**.
|
||||
- `pnpm-lock.yaml` SHA-256 before/after frozen install: `9acaa89d213b3281e757b6edf6fdb8727176570d725b78a0de234c61a7f3c332`; diff versus `origin/next` rc=0.
|
||||
- Verified no changed path under `apps/web/**`, provider service/adapters, `agent.service.ts`, `chat.gateway.ts`, or lockfile.
|
||||
- Verified both `McpClientModule` production wiring lines remain and no impossible `up`/`ok` routing status checks/fixtures remain.
|
||||
- Verified code/test diff SHA-256: `27b41a855084b9dd85a7bc2a79fa3251d114ee226a4f1b835e65134c25a4f5a8`.
|
||||
|
||||
## Delivery State
|
||||
|
||||
Implementation, testing, documentation assessment, and independent review are complete. Remaining authorized actions: format this final scratchpad append, create one conventional commit, run the required push queue guard, and push only `feat/webui-p3r1-routing-mcp`; no PR or merge.
|
||||
@@ -0,0 +1,276 @@
|
||||
---
|
||||
kind: record
|
||||
status: active
|
||||
---
|
||||
|
||||
# WebUI Phase P — P4-1 Projects + Tasks SPA Scratchpad
|
||||
|
||||
**Task ID:** P4-1
|
||||
**Tracking ref:** Phase P RFC §6.4 / §2.4 author brief; no provider issue supplied
|
||||
**Mission context:** `mvp-20260312` (active)
|
||||
**Branch:** `feat/webui-p4-1` from `origin/next`
|
||||
**Started:** 2026-08-11
|
||||
**Role:** orchestrator-controlled author worker; `docs/TASKS.md` remains orchestrator-only and is not part of this increment
|
||||
|
||||
## Original tasking
|
||||
|
||||
Implement the bounded P4-1 SPA parity slice exactly as briefed: real authenticated `/projects`, `/projects/:id`, and `/tasks` React Router pages ported from the existing Next baseline; reuse existing project/task components; preserve relative same-origin REST access; support only the existing project/task PATCH edit flows; add route error boundaries and page tests; pin Vite strict port 3100 and legacy Next dev/start to 3101; make no gateway, package, dependency, nav-shell, chat, settings, or admin changes; verify, commit, and push only `feat/webui-p4-1` (no PR or merge). If any required REST endpoint is absent, stop as `BLOCKED:` rather than inventing a workaround.
|
||||
|
||||
## Objective and acceptance map
|
||||
|
||||
- A: `/projects` list with loading, cards, empty, and surfaced API-error states; defer MissionStatus side panel.
|
||||
- B: `/projects/:id` detail with overview/tasks/missions tabs, parallel project/mission/task load, bounded project and task PATCH edits.
|
||||
- C: `/tasks` list/kanban with bounded task PATCH edits.
|
||||
- D: replace the three route placeholders and add route error boundaries without changing chat.
|
||||
- E: use only `@/lib/types` and `@/lib/api`; relative `/api/...` REST paths only.
|
||||
- F: Vite `strictPort: true`; Next dev/start pinned to 3101; no proxy/dependency changes.
|
||||
- G: fixture-backed Vitest coverage for lists, states, tabs/toggles, PATCH calls, and real route elements; all named verification gates pass.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Verify the required gateway REST routes and inspect the exact `origin/next` SPA, Next baseline pages, shared components, types, API helper, and P3 test conventions.
|
||||
2. Record the pre-change web test count and add required page/route tests first, observing expected RED failures.
|
||||
3. Port the three pages and shared route error boundary, then wire routes and bounded PATCH flows.
|
||||
4. Apply only the two dev-port pin changes.
|
||||
5. Run focused tests, all user-required gates, lockfile and same-origin checks, and `git diff --check`.
|
||||
6. Obtain independent spec/code/security review; remediate and repeat affected gates until clear.
|
||||
7. Commit conventionally, run the required pre-push queue guard, push only the feature branch, and record exact evidence here.
|
||||
|
||||
## Testing strategy
|
||||
|
||||
TDD is applied because this adds user-visible data/edit behavior. Component tests mock only the existing API boundary and exercise rendered behavior and PATCH payloads. Primary situational evidence is the required page interaction suite plus route-resolution checks; baseline evidence is typecheck, lint, full web test, build, frozen install, formatting/diff hygiene, and same-origin grep.
|
||||
|
||||
## Budget
|
||||
|
||||
No explicit token cap was supplied. Working soft cap: **50K tokens**, derived from three coupled React pages, route/error wiring, interaction tests, port config, review/remediation, and full verification. One Codex implementation worker and independent review workers will be used serially to avoid worktree collisions.
|
||||
|
||||
## Base evidence
|
||||
|
||||
- `git fetch origin` rc=0.
|
||||
- `origin/next` and branch start: `e00cc475a2b1e9866bd4e2f8df80aff640c3a543`.
|
||||
- Branch created: `feat/webui-p4-1` tracking `origin/next`.
|
||||
- Harness-owned `.mosaic/orchestrator/session.lock` is dirty and must remain unstaged/uncommitted.
|
||||
|
||||
## Progress / evidence
|
||||
|
||||
- [x] Loaded active mission manifest, latest scratchpad, top-level tasks, PRD, orchestration/delivery/frontend/QA/documentation/review/TypeScript guides, and matching implementation skills.
|
||||
- [x] Confirmed exact base SHA and created the feature branch.
|
||||
- [x] Required REST endpoints verified in Gateway source: project list/detail/PATCH, task list/filter/detail/PATCH, and mission list all exist.
|
||||
- [x] Scope assumption check found a blocking contradiction before source implementation.
|
||||
- [ ] Pre-change web test count recorded.
|
||||
- [ ] RED tests observed.
|
||||
- [ ] Implementation complete.
|
||||
- [ ] Independent review clear.
|
||||
- [x] Required verification gates run against the unchanged web baseline; exact leak-grep expectation is independently blocked by 12 pre-existing matches.
|
||||
- [x] Blocker record committed as `5ede86a5` and feature branch pushed; no PR opened and no merge performed.
|
||||
|
||||
## Blocker — 2026-08-11
|
||||
|
||||
`P4-1` is blocked because the bounded edit UX asserted by the brief does not exist at the confirmed `origin/next` base (`e00cc475`):
|
||||
|
||||
- `apps/web/src/components/tasks/task-detail-modal.tsx` is read-only. Its props are only `task` and `onClose`; it contains no input/select/textarea, update callback, or `api()`/PATCH call.
|
||||
- `apps/web/src/app/(dashboard)/projects/[id]/page.tsx` contains no project edit controls and no project/task PATCH call.
|
||||
- `apps/web/src/app/(dashboard)/tasks/page.tsx` does not open `TaskDetailModal`; its click handler only logs that a future detail view will be added.
|
||||
- A repository grep over those reference/component paths finds zero `method: 'PATCH'` calls and zero edit/save form controls.
|
||||
- The required leak grep also disproves the brief's baseline claim that `apps/web/src` is clean: the exact command returns rc=0 with 12 pre-existing matches at `origin/next` (external font links, an avatar placeholder, an SVG namespace, and test fixtures). There are zero new matches in the worktree, but making the exact grep empty would require unrelated changes the brief forbids.
|
||||
|
||||
The brief simultaneously requires tests proving task/project PATCH edits and forbids inventing edit UX, fields, or flows beyond what those references expose. Adding controls or callback contracts would therefore be new design outside the authorized port/wiring scope. Per the explicit stop rule, no SPA source, route, config, package, lockfile, or test implementation was started.
|
||||
|
||||
## Verification evidence on unchanged web baseline
|
||||
|
||||
These gates were still run to distinguish the brief contradiction from a broken base:
|
||||
|
||||
- `pnpm --filter @mosaicstack/web typecheck` — rc=0.
|
||||
- `pnpm --filter @mosaicstack/web lint` — rc=0.
|
||||
- `pnpm --filter @mosaicstack/web test` — rc=0; 15 files, 133 tests passed. Before→after remains 133→133 because implementation was halted.
|
||||
- `pnpm --filter @mosaicstack/web build` — rc=0; Next production build completed, 10/10 static pages generated.
|
||||
- `pnpm install --frozen-lockfile` — rc=0; lock SHA-256 remained `9acaa89d213b3281e757b6edf6fdb8727176570d725b78a0de234c61a7f3c332`; `git diff` for the lockfile rc=0.
|
||||
- `git grep -nE "http://|https://" -- apps/web/src` — rc=0 with 12 pre-existing matches; `origin/next` count=12, current HEAD count=12, new worktree additions=0.
|
||||
- `pnpm format:check` — rc=0.
|
||||
- `git diff --check` — rc=0.
|
||||
|
||||
## Delivery evidence
|
||||
|
||||
- Initial queue-guard invocation through shell `~` failed rc=127 because this Distrobox resolves `HOME` to `/home/jwoltje/distrobox-homes/mosaic-dev`, where the injected fleet status already reports the tools installation missing.
|
||||
- Correct supported host-tool invocation `/home/jwoltje/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B feat/webui-p4-1` — rc=0; branch absent remotely and queue clear.
|
||||
- `git push -u origin feat/webui-p4-1` — rc=0. The push hook additionally ran repository preflight, typecheck (45/45 tasks), lint (25/25 tasks), and format check successfully.
|
||||
- No PR was opened and no merge was attempted, per the brief.
|
||||
|
||||
## Risks / blockers
|
||||
|
||||
- The active harness mutates `.mosaic/orchestrator/session.lock`; it is excluded from staging.
|
||||
- The Phase P §6.4 prose is absent from this checkout, so the brief-named route spec and existing Next pages are the bounded implementation anchors.
|
||||
- The MissionStatus `/api/coord/status` panel is explicitly deferred to a follow-up and must not enter P4-1.
|
||||
|
||||
## REV 2 continuation — 2026-08-10T21:59:17-05:00
|
||||
|
||||
REV 2 supersedes the original tasking above. The independent check confirmed that the Next reference pages and `task-detail-modal.tsx` are read-only, so project/task editing is deliberately deferred to P4-1b. Do not re-litigate or implement the former PATCH requirements.
|
||||
|
||||
### Revised objective and acceptance map
|
||||
|
||||
- A: `/projects` read-only SPA list with loading, cards, empty, and surfaced API-error states; card navigation to `/projects/:id`; no MissionStatus panel.
|
||||
- B: `/projects/:id` read-only SPA detail using `useParams`, `useNavigate`, and the specified three-request `Promise.all`; preserve reference overview/tasks/missions tabs and read-only task modal.
|
||||
- C: `/tasks` read-only SPA list/kanban view with the existing read-only task modal.
|
||||
- D: replace only the three route placeholders and add page-local route error boundaries without modifying chat.
|
||||
- E: use only `@/lib/types` and `@/lib/api` with relative `/api/...` REST paths.
|
||||
- F: add Vite `strictPort: true` and pin legacy Next dev/start to 3101 without dependency or proxy changes.
|
||||
- G: add fixture-backed page tests and route-resolution assertions; run every user-specified verification gate and the narrowed new-code origin check.
|
||||
|
||||
### Revised plan
|
||||
|
||||
1. Reset `feat/webui-p4-1` to the exact `origin/next` base and independently verify the read-only reference/component/API assumptions.
|
||||
2. Record the pre-change web suite count; write and run focused page/route tests first to observe expected RED failures.
|
||||
3. Port the three read-only pages, add independent route error boundaries, wire routes, and apply only the two dev-port pins.
|
||||
4. Run focused tests, full required web gates, frozen install/lockfile proof, origin check, format/diff hygiene, and accessibility/state-transition sanity checks.
|
||||
5. Obtain independent spec/code/security review, remediate every blocker, and repeat affected gates.
|
||||
6. Commit conventionally, run the supported pre-push queue guard, and push only `feat/webui-p4-1`; no PR and no merge.
|
||||
|
||||
### Revised budget and session state
|
||||
|
||||
- No explicit token cap was supplied. Working soft cap remains **50K tokens**.
|
||||
- TDD is required by the user and frontend skill for the new SPA behavior; tests must fail for missing pages before production implementation.
|
||||
- Documentation assessment: this is a parity port of existing read-only behavior, not a new public workflow or API contract; the task scratchpad is the required delivery record, with no user/developer/API documentation changes in this bounded increment.
|
||||
- Exact base confirmed after fresh fetch/reset: `e00cc475a2b1e9866bd4e2f8df80aff640c3a543`.
|
||||
- Remote `feat/webui-p4-1` is absent; the eventual push is a fresh branch creation.
|
||||
- Harness-owned `.mosaic/orchestrator/session.lock` remains excluded from staging.
|
||||
|
||||
## REV 2 implementation pass — 2026-08-11T22:05:00Z
|
||||
|
||||
### Startup verification
|
||||
|
||||
- Loaded required startup files: `/home/jwoltje/.config/mosaic/CONSTITUTION.md`, `/home/jwoltje/.config/mosaic/SOUL.md`, project `AGENTS.md`, `/home/jwoltje/.config/mosaic/guides/E2E-DELIVERY.md`, `docs/PRD.md`, and this scratchpad.
|
||||
- Loaded required skills: `test-driven-development`, `vitest`, `vite`, `next-best-practices`, and `verification-before-completion`.
|
||||
- Loaded required runtime guide: `/home/jwoltje/.config/mosaic/runtime/codex/RUNTIME.md`.
|
||||
- Structured reasoning tool availability verified through the harness before planning.
|
||||
- `git rev-parse HEAD` confirmed exact required base: `e00cc475a2b1e9866bd4e2f8df80aff640c3a543`.
|
||||
- `git status --short` at startup showed only the expected untracked append-only scratchpad; `.mosaic/orchestrator/session.lock` did not appear and must remain unstaged if it changes later.
|
||||
|
||||
### Current plan
|
||||
|
||||
1. Record baseline evidence.
|
||||
2. Add focused failing SPA page/route specs first.
|
||||
3. Run focused RED command and record the missing-page failure.
|
||||
4. Implement the bounded read-only SPA pages, boundaries, route wiring, and the two dev-port pins.
|
||||
5. Run the required verification matrix and inspect diff hygiene.
|
||||
|
||||
### Pre-change baseline
|
||||
|
||||
- Command: `pnpm --filter @mosaicstack/web test`
|
||||
- rc=0
|
||||
- File/test totals before changes: `15 files / 133 tests`
|
||||
- Notes: baseline already includes `/chat` SPA route coverage and raw React `createRoot`/`act` page specs that this pass should mirror.
|
||||
|
||||
### RED evidence before production implementation
|
||||
|
||||
- Command: `pnpm --filter @mosaicstack/web test -- src/spa/pages/projects.spec.tsx src/spa/pages/project-detail.spec.tsx src/spa/pages/tasks.spec.tsx src/spa/pages/resource-route-boundaries.spec.tsx src/spa/routes.spec.tsx`
|
||||
- rc=1
|
||||
- Expected missing-feature reason confirmed:
|
||||
- `src/spa/pages/projects.spec.tsx`, `src/spa/pages/project-detail.spec.tsx`, `src/spa/pages/tasks.spec.tsx`, and `src/spa/routes.spec.tsx` fail import resolution because the SPA page modules do not exist yet.
|
||||
- `src/spa/pages/resource-route-boundaries.spec.tsx` fails because the current `/projects`, `/projects/:id`, and `/tasks` routes still render placeholders without route-level alert fallbacks.
|
||||
|
||||
### Implementation summary
|
||||
|
||||
- Added SPA pages:
|
||||
- `apps/web/src/spa/pages/projects.tsx`
|
||||
- `apps/web/src/spa/pages/project-detail.tsx`
|
||||
- `apps/web/src/spa/pages/tasks.tsx`
|
||||
- Added page-local route boundary components in `apps/web/src/spa/pages/resource-route-error-boundaries.tsx`.
|
||||
- Wired `/projects`, `/projects/:id`, and `/tasks` in `apps/web/src/routes.tsx` with real elements and `errorElement`s.
|
||||
- Added fixture-backed raw React Vitest coverage plus route assertions for the three pages and their boundaries.
|
||||
- Applied only the requested dev topology pins:
|
||||
- `apps/web/vite.config.ts`: `server.strictPort = true`
|
||||
- `apps/web/package.json`: `next dev -p 3101`, `next start -p 3101`
|
||||
|
||||
### Post-implementation verification
|
||||
|
||||
- Focused changed specs:
|
||||
- Command: `pnpm --filter @mosaicstack/web exec vitest run src/spa/pages/projects.spec.tsx src/spa/pages/project-detail.spec.tsx src/spa/pages/tasks.spec.tsx src/spa/pages/resource-route-boundaries.spec.tsx src/spa/routes.spec.tsx`
|
||||
- rc=0
|
||||
- Result: `5 files / 26 tests` passed.
|
||||
- `pnpm --filter @mosaicstack/web typecheck` — rc=0.
|
||||
- `pnpm --filter @mosaicstack/web lint` — rc=0.
|
||||
- `pnpm --filter @mosaicstack/web test` — rc=0; post-change totals `19 files / 153 tests`.
|
||||
- `pnpm --filter @mosaicstack/web build` — rc=1.
|
||||
- Limitation: Next/Turbopack hit a sandbox/runtime failure while processing `apps/web/src/app/globals.css`: `creating new process`, `binding to a port`, `Operation not permitted (os error 1)`. This appears environmental, not route-code-specific.
|
||||
- `pnpm --filter @mosaicstack/web build:vite` — rc=0.
|
||||
- `pnpm install --frozen-lockfile` — rc=1.
|
||||
- Limitation: repo `prepare` hook attempted to lock `/home/jwoltje/distrobox-homes/mosaic-dev/src/stack/.git/config`, which is read-only in this harness.
|
||||
- `pnpm-lock.yaml` SHA-256 before/after install attempt: `9acaa89d213b3281e757b6edf6fdb8727176570d725b78a0de234c61a7f3c332`.
|
||||
- `origin/next` `pnpm-lock.yaml` SHA-256: `9acaa89d213b3281e757b6edf6fdb8727176570d725b78a0de234c61a7f3c332`.
|
||||
- `git diff -- pnpm-lock.yaml` — rc=0 (unchanged).
|
||||
- `git diff -- apps/web/src | grep -nE '^\+.*(fetch|io|api)\(\s*[\x27\"]https?://'` — rc=1 (empty, as required).
|
||||
- `pnpm format:check` — rc=0.
|
||||
- `git diff --check` — rc=0.
|
||||
|
||||
### Final worktree check
|
||||
|
||||
- `git status --short` shows only the authorized web files plus this scratchpad.
|
||||
- `.mosaic/orchestrator/session.lock` remains unstaged.
|
||||
- Current changed file set:
|
||||
- `apps/web/package.json`
|
||||
- `apps/web/src/routes.tsx`
|
||||
- `apps/web/src/spa/routes.spec.tsx`
|
||||
- `apps/web/vite.config.ts`
|
||||
- `apps/web/src/spa/pages/page-errors.ts`
|
||||
- `apps/web/src/spa/pages/page-fixtures.ts`
|
||||
- `apps/web/src/spa/pages/project-detail.spec.tsx`
|
||||
- `apps/web/src/spa/pages/project-detail.tsx`
|
||||
- `apps/web/src/spa/pages/projects.spec.tsx`
|
||||
- `apps/web/src/spa/pages/projects.tsx`
|
||||
- `apps/web/src/spa/pages/resource-route-boundaries.spec.tsx`
|
||||
- `apps/web/src/spa/pages/resource-route-error-boundaries.tsx`
|
||||
- `apps/web/src/spa/pages/tasks.spec.tsx`
|
||||
- `apps/web/src/spa/pages/tasks.tsx`
|
||||
- `docs/scratchpads/webui-p4-1.md`
|
||||
|
||||
## P4-1 REV 2 Final Delivery Verification — 2026-08-10T22:23:00Z
|
||||
|
||||
### Spec/Security Review Verdicts (Independent Reviews)
|
||||
|
||||
Both independent reviews cleared P4-1 REV 2 implementation without blockers:
|
||||
- **Spec review:** approved; 0 blockers, 0 should-fix findings
|
||||
- **Code/security review:** approved; 0 blockers, 0 critical/high findings, 0 should-fix recommendations
|
||||
|
||||
### Final Fresh Gate Verification (This Session)
|
||||
|
||||
All verification gates executed sequentially with rc=0 (except where noted):
|
||||
|
||||
1. `pnpm --filter @mosaicstack/web typecheck` — rc=0
|
||||
2. `pnpm --filter @mosaicstack/web lint` — rc=0
|
||||
3. `pnpm --filter @mosaicstack/web test` — rc=0; **19 files / 153 tests** (baseline: 15 files / 133 tests; added: 4 files / 20 tests)
|
||||
4. `pnpm --filter @mosaicstack/web build` — rc=0; Next production build completed, 10/10 static pages generated
|
||||
5. `pnpm --filter @mosaicstack/web build:vite` — rc=0; Vite production bundle generated
|
||||
6. Lockfile integrity:
|
||||
- Before install: SHA-256 `9acaa89d213b3281e757b6edf6fdb8727176570d725b78a0de234c61a7f3c332`
|
||||
- After frozen install: SHA-256 `9acaa89d213b3281e757b6edf6fdb8727176570d725b78a0de234c61a7f3c332`
|
||||
- Equality: ✓ verified
|
||||
- `git diff --quiet origin/next -- pnpm-lock.yaml` rc=0 ✓
|
||||
7. `pnpm format:check` — rc=0; all matched files use Prettier code style
|
||||
8. `git diff --check` — rc=0; no trailing whitespace or merged conflict markers
|
||||
9. New-code origin check: `git diff -- apps/web/src | grep -nE '^\+.*(fetch|io|api)\(\s*[\x27\"]https?://'` — rc=1 (empty result, as required)
|
||||
10. `pnpm --filter @mosaicstack/web exec vitest run src/spa/pages/projects.spec.tsx src/spa/pages/project-detail.spec.tsx src/spa/pages/tasks.spec.tsx src/spa/pages/resource-route-boundaries.spec.tsx src/spa/routes.spec.tsx` — rc=0; 5 files / 26 tests passed
|
||||
|
||||
### Scope Audit
|
||||
|
||||
**Authorized in-scope changes:**
|
||||
- ✓ `apps/web/package.json` — dev port pins only
|
||||
- ✓ `apps/web/vite.config.ts` — strictPort flag only
|
||||
- ✓ `apps/web/src/routes.tsx` — route wiring with errorElements
|
||||
- ✓ `apps/web/src/spa/pages/projects.tsx` — read-only SPA list
|
||||
- ✓ `apps/web/src/spa/pages/project-detail.tsx` — read-only SPA detail
|
||||
- ✓ `apps/web/src/spa/pages/tasks.tsx` — read-only SPA list/kanban
|
||||
- ✓ `apps/web/src/spa/pages/resource-route-error-boundaries.tsx` — page-local error components
|
||||
- ✓ `apps/web/src/spa/pages/*.spec.tsx` — fixture-backed tests (4 new)
|
||||
- ✓ `docs/scratchpads/webui-p4-1.md` — append-only record
|
||||
|
||||
**Out-of-scope verification:**
|
||||
- `.mosaic/orchestrator/session.lock` — not modified/staged ✓
|
||||
- `pnpm-lock.yaml` — not modified ✓
|
||||
- `apps/gateway/**` — not modified ✓
|
||||
- `packages/**` — not modified ✓
|
||||
- Chat SPA — not modified ✓
|
||||
- Settings, admin, navigation, or auth flow — not modified ✓
|
||||
|
||||
### Next Action
|
||||
|
||||
Commit, run authorized queue guard, and push only `feat/webui-p4-1` (no PR, no merge).
|
||||
Reference in New Issue
Block a user