90 lines
5.6 KiB
Markdown
90 lines
5.6 KiB
Markdown
# 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
|