veronica
f0d2dd9920
Applies the document contract from
docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md section 3, partially:
`kind` and `status` only. `parent` is deliberately held until the flatten in
section 4 lands, so that 127 documents do not have to be re-pointed by hand
when docs/fleet/NORTH_STAR.yaml moves to docs/NORTH_STAR.yaml.
Scope, measured on origin/next at 63069149:
127 live docs = all *.md under docs/ minus docs/archive/ minus docs/_old_structure/
104 stamped here
19 held operator judgement (plan section 9), worklist in the same PR
3 held the SUPERSEDED TASKS.md stamps, which cite the moving path
1 untouched docs/fleet/FLEET-DOCTRINE.md, already stamped in W1
Kinds applied: 54 guide, 34 record, 9 spec, 6 tracking, 1 projection.
Every row carries a confidence and a one-line rationale in the worklist.
Two collisions with the existing state, both flagged rather than resolved:
1. docs/README.md:150-160 already documents a front-matter convention
(title/type/audience/status/source_of_truth) with its own allowed values.
It is applied to 4 of 127 files. Its `status` vocabulary is
current|draft|deprecated|historical; the new contract's is active|superseded-by.
The key collides. This commit lets the new contract win and rewrites
`status: current` to `status: active` on those 4 files, keeping their other
legacy keys untouched. No code reads any of them: `git grep source_of_truth`
outside docs/ returns nothing. docs/README.md still prescribes the old
convention and is an operator row, so it is not edited here.
2. Two of the plan's 20 operator rows are YAML files, not markdown
(docs/fleet/examples/roster-v2.yaml, docs/openapi-tess.yaml), and the
contract's front-matter form has no defined meaning for a .yaml document.
That gap also applies to docs/fleet/NORTH_STAR.yaml, the source of truth
itself. Raised in the worklist.
A third row from the plan, docs/fleet/north-star.md, no longer exists: W1
renamed it to docs/fleet/FLEET-DOCTRINE.md.
Verification: 104/104 parse with the expected kind and status in front matter;
the check was shown to reject a wrong kind before it was trusted. The diff
removes 4 lines total, all of them `status: current`.
145 lines
5.0 KiB
Markdown
145 lines
5.0 KiB
Markdown
---
|
|
kind: record
|
|
status: active
|
|
---
|
|
|
|
# Mosaic Framework Consistency Audit
|
|
|
|
Date: 2026-02-17
|
|
Scope:
|
|
|
|
- `~/src/mosaic-bootstrap`
|
|
- `~/src/agent-skills`
|
|
- Installed runtime check: `~/.config/mosaic`
|
|
|
|
## Findings
|
|
|
|
| ID | Severity | Finding | Status |
|
|
| ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
|
|
| MF-001 | High | QA rails scripts referenced invalid paths (missing `/qa/` segment) for `qa-hook-handler.sh` calls. | Remediated |
|
|
| MF-002 | Medium | Conditional-loading detection was biased to legacy `agent-guides` markers and missed Mosaic `guides`/`Conditional Context` phrasing. | Remediated |
|
|
| MF-003 | Medium | Framework spec text still described detection as `agent-guides`-based only. | Remediated |
|
|
| MF-004 | Medium | Runtime Claude overlay hardcoded skill count, which drifts over time. | Remediated |
|
|
| MF-005 | High | `pr-reviewer` skill used legacy `~/.claude/scripts/git` and `~/.claude/skills` paths. | Remediated |
|
|
| MF-006 | Medium | `using-git-worktrees` prioritized `CLAUDE.md` only and ignored Mosaic-first docs (`AGENTS.md`/`SOUL.md`). | Remediated |
|
|
| MF-007 | Medium | Marketing skills used `.claude/product-marketing-context.md` instead of Mosaic repo-local path. | Remediated |
|
|
| MF-008 | Low | `agent-skills/README.md` manual install/adaptation guidance referenced legacy Claude-only paths. | Remediated |
|
|
| MF-009 | Low | Historical creation-log contained stale Claude-specific path examples. | Remediated |
|
|
|
|
## Remediation Details
|
|
|
|
### MF-001 (QA rails path correction)
|
|
|
|
Updated:
|
|
|
|
- `tools/qa/qa-hook-wrapper.sh`
|
|
- `tools/qa/qa-hook-stdin.sh`
|
|
- `tools/qa/qa-hook-handler.sh`
|
|
- `tools/qa/remediation-hook-handler.sh`
|
|
- `tools/qa/qa-queue-monitor.sh`
|
|
|
|
Change:
|
|
|
|
- Standardized handler paths to `~/.config/mosaic/tools/qa/...`.
|
|
|
|
### MF-002 + MF-003 (conditional loading/context detection)
|
|
|
|
Updated:
|
|
|
|
- `tools/bootstrap/agent-lint.sh`
|
|
- `tools/bootstrap/agent-upgrade.sh`
|
|
- `templates/agent/SPEC.md`
|
|
|
|
Change:
|
|
|
|
- Detection now recognizes both legacy and Mosaic patterns:
|
|
- `agent-guides` (legacy compatibility)
|
|
- `~/.config/mosaic/guides`
|
|
- `Conditional Loading`
|
|
- `Conditional Context`
|
|
|
|
### MF-004 (runtime overlay drift-proofing)
|
|
|
|
Updated:
|
|
|
|
- `runtime/claude/CLAUDE.md`
|
|
|
|
Change:
|
|
|
|
- Removed hardcoded skills count text.
|
|
|
|
### MF-005 (pr-reviewer skill path migration)
|
|
|
|
Updated:
|
|
|
|
- `skills/pr-reviewer/SKILL.md`
|
|
|
|
Change:
|
|
|
|
- Replaced all `~/.claude/scripts/git/...` with `~/.config/mosaic/tools/git/...`.
|
|
- Replaced `~/.claude/skills/...` with `~/.config/mosaic/skills/...`.
|
|
|
|
### MF-006 (worktree skill docs hierarchy)
|
|
|
|
Updated:
|
|
|
|
- `skills/using-git-worktrees/SKILL.md`
|
|
|
|
Change:
|
|
|
|
- Replaced CLAUDE-only checks with `AGENTS.md` / `SOUL.md` (fallback: `CLAUDE.md`).
|
|
|
|
### MF-007 (marketing context path migration)
|
|
|
|
Updated:
|
|
|
|
- `skills/product-marketing-context/SKILL.md`
|
|
- All skills referencing product-marketing-context path (bulk update)
|
|
|
|
Change:
|
|
|
|
- Standardized context path to `.mosaic/product-marketing-context.md`.
|
|
|
|
### MF-008 + MF-009 (repo guidance cleanup)
|
|
|
|
Updated:
|
|
|
|
- `README.md` (agent-skills)
|
|
- `skills/writing-skills/SKILL.md`
|
|
- `skills/writing-skills/examples/CLAUDE_MD_TESTING.md`
|
|
- `skills/systematic-debugging/CREATION-LOG.md`
|
|
|
|
Change:
|
|
|
|
- Standardized references to `~/.config/mosaic/skills`.
|
|
- Removed stale Claude-only wording.
|
|
|
|
## Residual Legacy References (Intentional)
|
|
|
|
The following legacy references remain in `mosaic-bootstrap` by design and are not inconsistencies:
|
|
|
|
- Runtime compatibility tooling for Claude home directory management:
|
|
- `bin/mosaic-link-runtime-assets`
|
|
- `bin/mosaic-clean-runtime`
|
|
- `bin/mosaic-doctor`
|
|
- `bin/mosaic-sync-skills`
|
|
- `bin/mosaic-migrate-local-skills`
|
|
- Documentation explaining Claude runtime overlays:
|
|
- `README.md`
|
|
- `profiles/README.md`
|
|
- `adapters/claude.md`
|
|
- `runtime/claude/settings-overlays/` (sample overlay; now shipped sanitized under `examples/overlays/`)
|
|
|
|
These are required to support existing Claude runtime integration while keeping Mosaic as canonical source.
|
|
|
|
## Verification
|
|
|
|
Executed checks:
|
|
|
|
- `rg -n "~/.claude|\\.claude/|agent-guides" ~/src/agent-skills -S`
|
|
- Result: no matches after remediation.
|
|
- `rg -n "~/.config/mosaic/tools/(qa-hook|remediation-hook|qa-queue-monitor)" ~/src/mosaic-bootstrap -S`
|
|
- Result: no invalid old-style QA rail paths remain.
|
|
- Installed runtime validation:
|
|
- `~/.config/mosaic` contains `tools/git`, `tools/portainer`, `tools/cicd`, `skills`, and `bin` tooling.
|