automaton/tasks/framework-audit/RESEARCH.md

Framework Self-Consistency Audit

Principle Inventory

Extracted from all framework files. Each principle is a rule the framework prescribes for project work.

#	Principle	Source	Applied to Framework?
P1	Task-driven development: All changes go through tasks (SPEC → phases → VERDICT)	onboarding.md, workflow.md, .rules.md	❌ No rule enforces this for framework itself
P2	VRAM-aware task sizing: Tasks must fit system context limits; check before scoping	config.md, orchestrate.md:21-101	❌ Never checked when creating framework tasks
P3	Layered filesystem: Project overrides global, read project first then fallback to global	orchestrate.md:5-19, README.md:177-202	⚠️ Broken design — project-first read encourages full copies
P4	Minimal project footprint: Projects should only have .agent.md + .rules.md	onboarding.md:42, README.md:188	⚠️ Violated by P3's project-first read order
P5	No manual task creation: Orchestrator creates task folders, never the user	workflow.md:22	❌ No rule forbids manual mkdir tasks/
P6	Agent reads rules at startup: Must read .agent.md + .rules.md before working	system-prompt.md, session-starter.md	⚠️ Doesn't read global .rules.md, only project's
P7	Stop condition enforcement: "CONTRACT_MET" prevents early termination	references/stop-hook-pattern.md, various prompts	✅ Phase-level prompts have stop conditions
P8	Self-improving rules: .rules.md is a living document, add rules per failure mode	.rules.md:3-5	❌ No rules were added for any of these gaps
P9	Customization via extension, not copy: Override additively, never duplicate	Implicit from design intent	❌ Not codified anywhere
P10	Changelog/release notes: Changes should be recorded for release notes	Not stated anywhere	❌ No changelog exists
P11	One-time setup, then task flow: Onboarding is one-time, normal task flow after	onboarding.md:95	✅ Framework itself doesn't need onboarding

Gap Analysis

Category Definitions

• Self-reference gap: Framework doesn't apply rule to itself
• Missing rule: Principle isn't codified where agents can read it
• Enforcement gap: Rule exists but nothing checks compliance
• Lifecycle gap: Feature exists but follow-up step is missing
• Design flaw: Architecture encourages violation of own principles

Gap Details

#	Principle Violated	Category	Description	Covered By
G1	P1 (Task-driven)	Self-reference + Missing rule	No rule says "create task before editing framework files"	framework-self-enforcement
G2	P2 (VRAM check)	Self-reference + Missing rule	No rule says "check config.md VRAM before scoping tasks"	framework-self-enforcement (new rule)
G3	P3/P4 (Layered filesystem)	Design flaw	orchestrate.md reads prompts/contracts/scripts from project first, encouraging full copies instead of minimal footprint	additive-extension-model
G4	P5 (No manual task creation)	Missing rule + Enforcement	No rule forbids mkdir tasks/ — tasks should be created by Orchestrator	framework-self-enforcement (new rule)
G5	P6 (Agent reads rules)	Missing rule	system-prompt.md doesn't instruct agent to read global .rules.md	framework-self-enforcement
G6	P8 (Self-improving rules)	Enforcement	Gaps G1-G9 exist but no rules were added to prevent recurrence	framework-self-enforcement
G7	P9 (Extension model)	Missing rule	No documentation or rule says "additive overrides only, never copy"	additive-extension-model
G8	P10 (Changelog)	Lifecycle	VERDICT.md written per-task but no aggregate changelog	changelog
G9	None (missing feature)	Missing feature	No project migration path for existing projects with stale copies	project-migration
G10	None (missing feature)	Missing feature	No dashboard-based task review/approval workflow	dashboard-task-review

Impact/Effort Matrix

High Impact
  │
  │  G3 (design flaw)     G1 (self-ref)
  │  G2 (VRAM check)      G5 (rules)
  │  G7 (extension doc)
  │
  │  G10 (review UI)      G4 (manual mkdir)
  │  G8 (changelog)       G6 (living rules)
  │  G9 (migration)
  │
  └─────────────────────────────→
  Low Effort                  High Effort

Task Structure Validation

Existing tasks vs. gaps covered

Task	Gaps Covered
additive-extension-model	G3, G7
framework-self-enforcement	G1, G2, G4, G5, G6
changelog	G8
project-migration	G9

New tasks needed

Task	Gap	Reason for separate task
dashboard-task-review	G10	UI feature, not a rule change. Separate from framework-self-enforcement which is about rules/docs only.

Merged into framework-self-enforcement

G2, G4, G6 are all rule additions to .rules.md — they fit naturally in that single task alongside G1 and G5. No need to split further.

Recommendations

1. Keep existing 4 tasks as-is — each covers its gaps cleanly
2. Add dashboard-task-review as a new task (G10 — user requested feature)
3. Expand framework-self-enforcement spec to include VRAM check rule (G2), no-manual-creation rule (G4), and living-rules reminder (G6)
4. Mark framework-audit as complete once RESEARCH.md is written and tasks are validated