This document defines how Melta uses loops, pipelines, and scheduled checks. It is not a license for agents to change the design system authority. It is a control plane for what can be automated, what must be escalated, and what evidence each run must leave behind.
Melta does not treat every repeated workflow as an agent loop.
| Level | Name | Model in the loop | Substrate | Workflows |
|---|---|---|---|---|
| Level 1 | Deterministic pipelines | No | npm scripts / GitHub Actions | Drift repair, release readiness |
| Level 2 | Model loops | Yes | Claude Code session / worktree | UI self-repair, red-team |
| Level 3 | Observation cron | Generation only | schedule / local cron | Benchmark reports |
Loops and pipelines may write only generated files, derived files, reports, and proposal diffs. The following changes always require a human gate:
design/contracts/**design/contracts/tokens.jsondesign/contracts/rules.jsondesign/schemas/*.schema.jsondesign/authority.mdDESIGN.mdbody, principles, and Quick Reference meaningAGENTS.mdworkflow rules, loading paths, and human-gate meaning.design-baseline.json- test deletion or assertion weakening
- existing rule severity, detector, pattern, or alternative edits
- MCP public contract changes: tool names, input schemas, output shapes, resource URIs, and externally visible response semantics
- publish, deploy, version bump, protected-branch commit, and push
DESIGN.md is two-layered:
- Generated front matter is a generated view from
design/contracts/tokens.jsonand may be regenerated by deterministic tooling. - The constitution body, principles, and Quick Reference meaning are human-gated.
- Quick Reference crosses values and meaning. Token-derived value refreshes may be regenerated, but changes to UI semantics or generation guidance require a human gate.
Hooks are tripwires, not loop engines. PostToolUse / PreToolUse hooks may detect, block, or add context. They must not own multi-step repair, repeated execution, worktree management, or scheduled work.
check_html.passed means only "lint-clean draft". It does not prove Melta
brand quality, spacing judgment, warmth, information hierarchy, or product fit.
UI self-repair output must be labeled lint-clean draft / brand未承認 until a
human reviews the result. Brand review is not optional for user-facing UI.
Red-team work intentionally creates invalid UI. It must run in an isolated
worktree or an explicitly hook-excluded output path. Invalid red-team artifacts
must not be mixed into main docs/, examples, or shipped generated views.
W4 implementation prerequisite: choose one red-team output path, add it to the hook exclusion list, and add a self-drift check that the chosen path is actually excluded. Until that wiring exists, W4 remains manual / isolated only.
Every loop or pipeline run should emit one JSONL record to an ignored runtime log
path, for example .melta-loop/runs.jsonl.
Required fields:
{"run_id":"2026-06-18T10:00:00Z-drift","workflow":"drift-repair","level":"pipeline","status":"passed|escalated|failed","trigger":"manual|ci|schedule","commands":["npm run design:drift"],"changed_paths":[],"escalation":null}The log is an audit trail, not an authoritative design source.
Loop learnings are proposals until reviewed. Write them under
docs/loop-learnings/ or another explicitly non-authoritative quarantine area.
They become authoritative only after a human moves the learning into
DESIGN.md, design/contracts/, design/authority.md, or another SSOT file.
When a workflow cannot proceed safely, it must stop and provide this payload:
{
"workflow": "ui-self-repair",
"stuck_reason": "manual brand decision required",
"severity": "warn|error|blocking",
"proposed_diff": "summary or path to patch",
"evidence": ["command output summary", "changed paths", "violations"],
"human_question": "Should this become a new rule, or is this an acceptable exception?"
}Human gates have two enforcement levels. Hard gates are path-based and can be checked mechanically before a loop writes or commits. Soft gates are semantic: they require human judgment, and they need separate tests or review workflows to gain mechanical teeth.
| Area | Automation may do | Human gate required |
|---|---|---|
| Generated views | Regenerate and report diffs | Commit decision when generated output is large or ambiguous |
| SSOT paths | Read and cite | Any write to design/contracts/**, design/contracts/tokens.json, design/contracts/rules.json, design/authority.md, or DESIGN.md body |
| Schemas | Read and validate | Any change to design/schemas/*.schema.json |
| Baseline | Compare against current baseline | --baseline-write or any baseline relaxation |
| Tests | Run tests and report failures | Delete tests, weaken assertions, reduce coverage |
| Release | Pack, boot, and report readiness | Publish, deploy, version bump, protected branch commit or push |
| Memory | Write quarantined proposals | Promote proposal into authoritative docs or contracts |
| Area | Automation may do | Human gate required |
|---|---|---|
| Entrypoints | Read and cite | AGENTS.md workflow rules, loading paths, and human-gate meaning changes |
DESIGN.md meaning |
Regenerate front matter and cite guidance | Body, principles, Quick Reference meaning, UI semantics, generation guidance |
| MCP public contract | Preserve existing contract | Tool names, input schemas, output shapes, resource URIs, externally visible response semantics |
| Rules | Propose new rules or report gaps | Add/modify rule, change severity, weaken detector, change alternative |
| UI | Produce lint-clean draft | Brand approval, visual judgment, product fit |
CI failure triage is a shared intake, not an independent repair loop. It routes failures to the narrowest existing workflow and escalates anything that would tempt a model to weaken tests, rules, or baselines.
| CI failure | Route | Automation limit |
|---|---|---|
npm run design:drift |
Drift repair pipeline | Regenerate derived files, then escalate if drift remains |
npm run design:lint-generated |
UI self-repair or lint fix proposal | Fix generated UI; do not relax rules or baseline |
npm run design:check |
Deterministic investigation | Report schema / contract issue; SSOT writes need human gate |
npm run validate |
Deterministic investigation | Report token implementation mismatch; SSOT writes need human gate |
npm run build |
Deterministic investigation | Report compile error; broad refactors need human gate |
npm test |
Evidence report | Do not auto-weaken tests or snapshots |
| dependency / environment / flaky | Human escalation | No autonomous repair |
W# are stable workflow IDs and are independent of the automation Level. A
workflow's tier is given by its Classification row (e.g. W1 UI Self-Repair is a
Level 2 model loop). Do not read W1 as Level 1.
| Field | Definition |
|---|---|
| Classification | Level 2 model loop |
| Trigger | UI generation request, generated UI file change, check_html failure |
| Substrate | Claude Code session; existing hook is only a tripwire |
| Context | DESIGN.md, relevant component contracts, design/contracts/rules.json, MCP get_component, MCP get_rules, MCP check_html |
| Action | Generate UI, run check_html, revise violations, repeat up to the retry limit |
| Verify | check_html for source snippets; npm run design:lint-generated -- <file> for files |
| Stop | Error 0 after at most 3 repair attempts, then report as lint-clean draft / brand未承認 |
| Human Gate | Brand approval, manual rules, subjective layout quality, product fit |
| Escalation payload | Violations remaining, attempted fixes, source snippet or changed file, human question |
| Memory | Quarantined learnings under docs/loop-learnings/; no direct SSOT update |
| Field | Definition |
|---|---|
| Classification | Level 1 deterministic pipeline |
| Trigger | npm run design:drift failure, npm run design:drift-heal, or generated-view freshness failure |
| Substrate | npm script / CI |
| Context | design/authority.md, DESIGN.md, design/contracts/, scripts/design/drift-check.ts |
| Action | Run drift check, regenerate derived views, re-run checks, report diff (npm run design:drift-heal) |
| Verify | npm run design:check, npm run design:build, npm run design:drift, npm run build |
| Stop | Drift 0 and generated-only diff, then human commit decision |
| Human Gate | Any SSOT diff, unresolved drift, generated diff that changes public meaning |
| Escalation payload | Drift log, changed paths, SSOT-touch status, question on generation bug vs specification change |
| Memory | Runtime log plus optional quarantined learning |
Playbook drift is not repairable by regeneration. If this playbook references a missing command or falls out of sync with CI, drift repair must escalate rather than rewrite policy.
| Field | Definition |
|---|---|
| Classification | Level 3 observation cron |
| Trigger | Weekly schedule, release candidate, DESIGN.md / contracts / MCP tool changes |
| Substrate | local cron, Claude schedule, or manual run |
| Context | design/benchmarks/, latest report, benchmark prompts and scoring code |
| Action | Run benchmark conditions, compare only with reports sharing the same benchmarkProtocolVersion, summarize changes |
| Verify | Benchmark report includes its protocol version and cold / designmd / contracts / mcp-raw / full conditions |
| Stop | Report produced; no autonomous product or rule change |
| Human Gate | Score interpretation, rubric changes, priority decisions |
| Escalation payload | Regression summary, changed prompts or score code, suggested investigation path |
| Memory | Store report in design/benchmarks/results/; learnings remain quarantined |
| Field | Definition |
|---|---|
| Classification | Level 2 model loop |
| Trigger | Release candidate, new component, new rule, monthly manual run |
| Substrate | Claude Code session in isolated worktree or hook-excluded output path |
| Context | Red-team prompts, check_html, Playwright / axe, rules, prior audits |
| Action | Intentionally generate Melta-breaking UI, run checks, identify escapes |
| Verify | check_html, npm test when applicable, axe evidence, benchmark proxy if useful |
| Stop | Report holes and proposed rule/test additions; do not auto-adopt them |
| Human Gate | New rule adoption, severity, false-positive acceptance, test additions |
| Escalation payload | Repro artifact path, detector gap, proposed rule/test, false-positive risk |
| Memory | Quarantined red-team learnings until promoted by a human |
| Field | Definition |
|---|---|
| Classification | Level 1 deterministic pipeline |
| Trigger | Release candidate, npm publish preparation, deployment preparation |
| Substrate | GitHub Actions plus local release script |
| Context | package.json, .github/workflows/design-check.yml, MCP server, docs site, package files |
| Action | Run existing CI checks, add package and MCP smoke checks, produce readiness report |
| Verify | npm run design:check, npm run design:lint-generated -- --baseline .design-baseline.json examples/*.html docs/*.html, npm run design:drift, npm run design:compat, npm run design:llms, npm run validate, npm run build, npm test, npm pack, MCP boot smoke |
| Stop | All checks pass and report says release ready; publish/deploy remains human action |
| Human Gate | Publish, deploy, version bump, protected branch commit or push |
| Escalation payload | Failing command, package/MCP smoke evidence, changed paths, release decision question |
| Memory | Runtime log and release readiness report |
npm run design:drift should keep this playbook executable-adjacent.
| Check | Severity | Reason |
|---|---|---|
| Playbook file exists | error | Missing governance breaks every loop |
Referenced npm run ... scripts exist in package.json |
error | Dead commands make the playbook non-executable |
| Release readiness includes current CI command set | error | Release policy must not omit CI gates |
| Required governance markers exist | error | SSOT protection, brand gate, logs, and memory quarantine are safety invariants |
| Classification wording differs from README or other docs | warn | Naming drift is confusing but should not block routine CI by default |
Phase 2 backlog:
- Verify that required markers have non-empty body text before the next heading.
- Generate the CI command block from
.github/workflows/design-check.yml. - Add MCP public contract snapshot / golden-file tests for tool schemas and externally visible output shapes.
- Share implementation core between W1 UI Self-Repair and W4 Red-Team.
- Wire the W4 red-team output path into the hook exclusion list and self-drift.
- Self-drift check that
SSOT_PROTECTED_PATHSinscripts/design/loops/drift-heal.tsstays aligned with the Hard Gates / SSOT Write-Protection paths in this playbook (the const is currently a second copy of that path list).
Current required CI command set:
npm run design:checknpm run design:lint-generatednpm run design:driftnpm run design:llmsnpm run validatenpm run buildnpm test