mosaicstack/stack
13
0
Fork 1
Code Issues 304 Pull Requests 10 Actions Packages Projects Releases 15 Wiki Activity
Files
ff40794bfeddc05a2789800a875cce49136c4a06
stack/docs/reports/documentation/AUDIT-2026-02-17-framework-consistency.md
T
veronica f0d2dd9920 docs(W4): stamp kind and status front matter on 104 live documents 
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`.
2026-08-20 19:30:25 -05:00

5.0 KiB
Raw Blame History

kind, status
kind status
record 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.
Reference in New Issue View Git Blame Copy Permalink