34e55d4a2e
Invert the framework updater from a denylist ("framework owns everything unless
preserved") to an explicit allow-list manifest ("operator owns everything unless
framework"). A path the manifest never anticipated resolves to operator-owned by
the fail-safe default, so it is structurally unreachable by any write or prune.
Root cause (#791): `mosaic update` re-seeds via `install.sh` keep-mode, whose
`rsync -a --delete` + hand-maintained PRESERVE_PATHS denylist wiped operator
paths the denylist forgot (agents/*.conf, policy/*.md, *.local.md, harvester
SOP, tools/_lib/credentials.json, unanticipated fleet files).
- framework-manifest.txt: single SSOT ([framework]/[operator], deny-wins,
UNKNOWN=>operator fail-safe), read by BOTH installers.
- src/framework/manifest.ts: pure resolver (parse/matchGlob/resolveOwnership/
frameworkSubtreeRoots/planPrune) — the testable seam.
- tools/_lib/manifest.sh: bash resolver (compiled globs, fork-free hot path),
sourced by install.sh; parity-tested against the TS resolver.
- install.sh keep mode is now manifest-driven (no --delete): overlay-copy
framework files, scoped-prune only retired framework files inside shipped
subtrees. Operator + unknown paths are never written or deleted.
- file-ops.syncDirectory gains an isOperatorOwned guard; file-adapter derives it
from the shared manifest, replacing the drifted hardcoded preservePaths.
Tests (TDD, red->green):
- HARD GATE test-upgrade-manifest-guard.sh: 10 operator sentinels (incl. an
unanticipated one) survive a keep-mode reseed byte-identical + mtime-unchanged;
retired framework file pruned; secret value absent from output. RED 31 fail on
the old installer -> GREEN 48 pass. Wired merge-blocking into CI.
- manifest-parity.spec.ts (§6.1): bash<->TS agree on 34 paths + subtree roots.
- manifest.spec.ts: 18 tests incl. planPrune property test + shipped-tree
completeness (§6.2).
- test-install-migration.sh F6 flipped: an unanticipated operator fleet file now
MUST survive keep-mode reseed.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Quality Rails
Portable quality enforcement for TypeScript, Python, and Node.js projects.
🎯 What This Prevents
Based on real-world validation of 50 issues in a production codebase:
- ❌ Hardcoded passwords
- ❌ SQL injection vulnerabilities
- ❌ Type safety violations (
anytypes) - ❌ Missing test coverage
- ❌ Build failures
- ❌ Dependency vulnerabilities
70% of these issues are prevented mechanically with quality-rails.
⚡ Quick Start (Mosaic)
New Project
# Apply template from Mosaic
~/.config/mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/project
# Install dependencies
cd /path/to/project
npm install
# Initialize git hooks
npx husky install
# Verify enforcement is working
~/.config/mosaic/bin/mosaic-quality-verify --target /path/to/project
Existing Project
# Same as above - works for new or existing projects
~/.config/mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/existing-project
🛡️ What You Get
✅ TypeScript strict mode - All type checks enabled
✅ ESLint blocking any types - no-explicit-any: error
✅ Pre-commit hooks - Type check + lint + format before commit
✅ Secret scanning (gitleaks) - Block hardcoded passwords/API keys (pre-commit + CI)
✅ CI/CD templates - Woodpecker, GitHub Actions, GitLab
✅ Test coverage enforcement - 80% threshold
✅ Security scanning - npm audit, OWASP checks
📦 Available Templates
| Template | Language | Framework | Status |
|---|---|---|---|
typescript-node |
TypeScript | Node.js | ✅ Ready |
typescript-nextjs |
TypeScript | Next.js | ✅ Ready |
monorepo |
TypeScript | TurboRepo + pnpm | ✅ Ready |
python |
Python | - | 🚧 Coming Soon |
Monorepo Template
Perfect for projects combining Next.js frontend + NestJS backend in one repository.
Features:
- 🎯 Multi-package aware - lint-staged only checks changed packages
- ⚡ TurboRepo caching - Faster builds and tests
- 🔀 Parallel dev servers - Run web + API simultaneously
- 📦 pnpm workspaces - Efficient dependency management
- 🛡️ Package-specific rules - Next.js and NestJS get appropriate ESLint configs
Example structure:
monorepo/
├── apps/
│ ├── web/ # Next.js frontend
│ └── api/ # NestJS backend
└── packages/
├── shared-types/
├── ui/
└── config/
🧪 How It Works
Pre-Commit (Local Enforcement)
# You try to commit code with a type error
git commit -m "Add feature"
# Quality rails blocks it:
❌ Type error: Type 'number' is not assignable to type 'string'
❌ ESLint: Unexpected any. Specify a different type.
✋ Commit blocked - fix errors and try again
CI/CD (Remote Enforcement)
# Woodpecker pipeline runs:
✓ gitleaks (secret scanning — parallel, no deps)
✓ npm audit (dependency security)
✓ eslint (code quality)
✓ tsc --noEmit (type checking)
✓ jest --coverage (tests + coverage)
✓ npm run build (compilation — gates on all above)
# If any step fails, merge is blocked
🎓 Philosophy
Process compliance doesn't work.
Instructing AI agents to "do code review" or "run tests" fails. They claim to follow processes but output quality doesn't match claims.
Mechanical enforcement works.
Quality rails don't ask agents to follow processes. They block commits that don't pass automated checks.
- Type errors? → Commit blocked
- Hardcoded secrets? → Commit blocked
- Test failures? → Commit blocked
- Missing coverage? → Commit blocked
This works for any agent runtime (Codex, Claude, OpenCode, Gemini, etc.) because enforcement is mechanical, not instructional.
📖 Documentation
🔧 Scripts
| Script | Purpose |
|---|---|
scripts/install.sh |
Install template to project (Linux/Mac) |
scripts/install.ps1 |
Install template to project (Windows) |
scripts/verify.sh |
Verify enforcement is working (Linux/Mac) |
scripts/verify.ps1 |
Verify enforcement is working (Windows) |
🚀 Roadmap
- TypeScript/Node template
- Pre-commit enforcement (husky + lint-staged)
- CI/CD templates (Woodpecker, GitHub Actions)
- Installation scripts
- Verification testing
- Next.js template
- Monorepo template
- Python template
- Coverage visualization
- IDE integration (VSCode extension)
🤝 Contributing
Quality Rails is based on lessons learned from real production codebases. Contributions welcome!
📝 License
MIT License - See LICENSE file for details
🙏 Credits
Built to solve real problems discovered in AI-assisted development workflows.
Based on validation findings from a production patch milestone.