Skip to content
Uvilo OS
archived Visibility internal Owner erik@uvilo.com Approver _ Created 2026-06-26 Updated 2026-06-26

Forge Project Cleanup Plan 4

Scope: Complete the infrastructure inventory and verification evidence, Charter alignment matrix, ambiguity handling, and final acceptance verification across the entire project system.

Spec: Forge Project Cleanup Spec Prior plan: Plan 3

Task 1 — Build the project system infrastructure inventory

Spec §7 requires an inventory of every active project-system component with verification evidence.

  1. Inventory the following component categories and record each item’s name, location, status, and verification method:

    Published project Knowledge and Guides:

    • Forge/Forge_Project_Workflow.md — verify status: published in frontmatter
    • Forge/Forge_Project_User_Guide.md — verify status: published in frontmatter
    • Forge/Forge_Agent_Orchestration.md — verify status: published in frontmatter
    • Forge/Forge_Agent_Architecture.md — verify status: published in frontmatter
    • Forge/Forge_Document_Structure.md — verify status: published in frontmatter
    • Forge/Forge_Charter.md — verify status: published in frontmatter
    • Any other published Knowledge/Guide files under Forge/ that relate to the project system

    Project Skills:

    • List every Skill in Forge/Skills/ with project in its name or tags
    • For each, verify the SKILL.md exists and has status: published or status: draft (draft is acceptable for Skills being updated)
    • Verify each Skill’s procedure reflects the updated workflow (no Erik_Todo, no WIP)

    Project work-product templates:

    • List every template in Forge/Skills/Project_Create/templates/
    • Verify each template exists and is consistent with the updated Workflow document
    • Verify the WIP_Template.md has been removed (done in Plan 2)

    Project bot records, prompt records, and prompt versions:

    • List the four project bots: project-runner, project-thinker, project-worker, project-evaluator
    • For each, record: bot id, prompt id, current prompt version number, last updated date
    • Verify prompt versions are inspectable through prompt-version artifacts created in Plan 3

    Workflow schedules, Inngest functions, or phase triggers:

    • Search for Inngest function definitions or scheduled triggers related to project workflow
    • Record what exists and its current configuration
    • If none exist, record “No Inngest/project workflow triggers found — project phases are driven by agent invocation”

    Todo lists/items used for human and agent gates:

    • Use findTodoLists to find any project-related todo lists
    • Use findTodoItems to find any project-related todo items
    • Record what exists

    Generated Astro/Starlight pages and sidebar entries for active project docs:

    • Run cd .internal && pnpm run build to verify the build passes
    • Check the generated sidebar for project-related entries
    • Verify no WIP or Erik_Todo entries appear in the active sidebar

    Lifecycle files, phase files, run logs, verification reports, and audit reports:

    • List all active project folders under Forge/Projects/ (non-archived)
    • For each, record the Phase file and its current phase value

  2. Save the complete inventory as Forge_Project_Cleanup_Infrastructure_Inventory.md in the project folder with status draft.

Task 2 — Collect verification evidence for each component type

Spec §7 requires verification evidence for each component type. Valid evidence includes file inspection results, search results showing removal of stale active references, prompt diff review, tool inventory or smoke-test output, generated site/sidebar inspection, lifecycle routing checks, build results, and documented manual checks.

  1. For each component category in the inventory, collect and record verification evidence:

    Knowledge and Guides: File inspection results showing status: published and no remaining active Erik_Todo or WIP instructional references. Use grep search results as evidence.

    Skills: File inspection results showing SKILL.md files are updated. Use grep search results showing no remaining active Erik_Todo or WIP instructional references in project Skills.

    Templates: Directory listing of Forge/Skills/Project_Create/templates/ showing WIP_Template.md is absent. Content inspection of remaining templates showing they are consistent.

    Bot prompts: Prompt-version artifacts from Plan 3 showing the before/after diff. Read the current prompt for each bot and verify it matches the Knowledge.

    Workflow triggers: If Inngest functions exist, record their configuration. If not, record that project phases are agent-driven.

    Todo items: Results of findTodoLists and findTodoItems showing the todos system is functional and being used.

    Generated pages/sidebar: Build output showing successful build. Sidebar inspection showing no WIP or Erik_Todo entries.

    Lifecycle files: Phase file inspection for each active project showing correct phase values.

  2. For run/cost evidence (Spec §7): Record the available job/session context for the spawned project-agent work in this project. If exact cost/token/run metadata is unavailable, state that explicitly and record the available context (convo id, job ids, dates).

  3. Append the verification evidence to the infrastructure inventory document.

Task 3 — Build the Charter alignment matrix

Spec §9 requires a Charter alignment matrix that records every relevant Forge Charter principle or constraint reviewed, the compliance status, the active evidence, any gap, and the correction or user decision that resolves the gap. The cleaned workflow must have no known unaddressed Charter violations.

  1. Read Forge/Forge_Charter.md in full.
  2. For each Charter principle, guideline, goal, requirement, scope statement, and constraint, create a row in the alignment matrix with these columns:
    • Charter principle/constraint — the specific Charter text or summary
    • Compliance status — ✅ Compliant, ⚠️ Partial, or ❌ Violation
    • Active evidence — what in the current (post-Plans 1-3) project system demonstrates compliance
    • Gap — any remaining gap or risk, or “None” if fully compliant
    • Correction — what was done to address the gap, or what user decision is needed
  3. Use the Research document’s Charter alignment matrix as the starting point (it was the pre-cleanup assessment). Update each row to reflect the post-cleanup state.
  4. For any principle that is still ⚠️ Partial or ❌ Violation after Plans 1-3:
    • Determine what additional correction is needed
    • If the correction is within this project’s scope, implement it
    • If the correction requires a user decision, create a todo item and record the ambiguity
    • If the correction is out of scope, record it as a known gap with rationale
  5. Save the matrix as Forge_Project_Cleanup_Charter_Alignment.md in the project folder with status draft.

Task 4 — Record and resolve ambiguities

Spec §10 requires that ambiguities are not resolved by agent assumption. Each ambiguity is recorded in a durable work-product with the affected area, decision needed, options considered, recommended option if any, responsible owner, status, and link to any related todo item.

  1. Review all work done in Plans 1-3 and the current Plan for any ambiguities encountered:
    • Places where the Spec was unclear and a reasonable interpretation was chosen
    • Places where multiple approaches were possible and one was selected
    • Places where Knowledge documents conflict and one was chosen as authoritative
    • Places where a user decision is needed but hasn’t been obtained yet
  2. For each ambiguity found, create an entry in Forge_Project_Cleanup_Ambiguities.md with:
    • # — sequential number
    • Affected area — which Spec section, Knowledge doc, Skill, or bot prompt
    • Decision needed — what needs to be decided
    • Options considered — what alternatives were available
    • Recommended option — if any
    • Resolution — what was actually done, or “Pending user decision”
    • Responsible owner — who should decide
    • Status — Resolved or Pending
    • Related todo item — link to any todo item created for this ambiguity
  3. For any Pending ambiguities that require a user decision, create a user-owned todo item using createTodoItem with the structured body content per Spec §2.
  4. Save the ambiguities document with status draft.

Task 5 — Final acceptance verification

Spec §14 defines the acceptance criteria. This task verifies each criterion is met.

  1. Verify each acceptance criterion from Spec §14:

    “Active project Skills, Knowledge, Guides, bot prompts, templates, workflow configuration, generated pages/sidebar entries, and project files reflect the target state above”:

    • Run comprehensive grep searches for Erik_Todo, Agent_Todo, and WIP instructional references
    • Verify all four bot prompts have been updated (read each current prompt)
    • Verify all project Skills have been updated
    • Verify Knowledge and Guide documents have been updated

    “Active references to flat-file todos and WIP recovery are absent”:

    • Grep verification with zero instructional results

    “All four project bots match canonical Knowledge or have recorded user-approved exceptions”:

    • Review the compliance audit from Plan 3 Task 6
    • Verify no unresolved discrepancies remain

    “The project system inventory and verification evidence are complete”:

    • Review the infrastructure inventory from Task 1-2 of this Plan
    • Verify every component category has evidence

    “Charter alignment has no unaddressed gaps”:

    • Review the Charter alignment matrix from Task 3
    • Verify no ❌ Violation rows remain without correction or user decision

    “Every unresolved ambiguity is represented by a durable work-product entry and a todo item for the responsible user”:

    • Review the ambiguities document from Task 4
    • Verify every Pending ambiguity has a corresponding todo item

    “Project names follow the {Department}/{ProjectShortName} naming convention”:

    • Verify this project itself follows the convention (it does: Forge/Project_Cleanup)
    • Verify the project-runner prompt enforces this (done in Plan 3)

    “Human gates are user-configurable with a documented default set and enforcement by the Runner”:

    • Verify the project-runner prompt includes gate options and defaults (done in Plan 3)
    • Verify the Phase file supports human_gates frontmatter

  2. Record the verification results in Forge_Project_Cleanup_Verification.md with status draft.

  3. If any criterion is not met, record the gap and determine whether it can be fixed within this Plan or requires a new Plan.

  4. Build, commit, push.

Task 6 — Update project README and AGENTS

The project README and AGENTS should reflect the current state of the project after all Plans are complete.

  1. Update Forge_Project_Cleanup_README.md to reflect the completed work: what was changed, the key outcomes, and links to the inventory, Charter alignment, and verification documents.
  2. Update Forge_Project_Cleanup_AGENTS.md to point to the updated Skills, Knowledge, and the new reference documents.
  3. Set status to review on all Plan documents.
  4. Build, commit, push.