mosaicstack/stack
1
0
Fork 0
Code Issues 26 Pull Requests 2 Actions Packages Projects Releases 14 Wiki Activity
Files
319e21ddc0589a900d291282f45e8d423e74aeda
stack/docs/audits/AUDIT-2026-02-17-framework-consistency.md
Jason Woltje 319e21ddc0
Some checks failed
ci/woodpecker/push/ci Pipeline was canceled
Details
ci/woodpecker/pr/ci Pipeline was canceled
Details
feat(framework): P3 — extract Constitution (L0) + gut AGENTS dispatcher 
Splits the 155-line thin-core AGENTS.md into:
- defaults/CONSTITUTION.md (L0): gates + integrity + escalation + block-vs-done
  + mode + two-axis precedence + hooks-are-the-gate + framework-PR firewall +
  structured-reasoning capability + tier-aware self-load. Capability-verb authored.
- defaults/AGENTS.md gutted to an ~80-line load-order dispatcher + guide table
  (kills the false "already in context, do not re-read" line).
- constitution/LAYER-MODEL.md: source-only governance spec (layers + precedence).

Non-regression wiring (fresh-install functional; upgrade-safety is P4):
- launch.ts injects CONSTITUTION.md before AGENTS.md (tolerant of un-reseeded installs)
- install.sh + file-adapter.ts seed CONSTITUTION.md (+ test fixture updated)

Runtime adapters: capability-verb the sequential-thinking binding; claude/codex/
opencode restate the REQUIRED hard-stop, pi binds to native thinking (gate=false)
— restores the force the adversarial review flagged as weakened.

Gate hardening (dual-engine review): identity denylist now covers examples/
(closes the Codex open-source gap), self-test-first, *.json in scope, ci.yml
typecheck depends on sanitization (fail-fast), L0 line-count ceiling (<=120).

Adversarial gate-preservation review: every original rule traced to L0, the
dispatcher, or a routed guide — nothing lost.

Refs #542, closes #574

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-20 21:55:18 -05:00

4.9 KiB
Raw Blame History

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