Skip to content
Uvilo OS
approved Visibility internal Owner erik@uvilo.com Approver _ Created _ Updated _

Knowledge Consistency Plan 6

Plan 6 — Forge_Project and Documentation Content Corrections

Scope: Correct content in Forge_Project documentation and related docs: update Changelog references, align default human gates, remove “Pending” phase state, update Project_Flow skill, replace Manage_Pages references in documentation files, and consolidate README/AGENTS pairs where content overlaps.

Spec sections covered: S1.10 (docs only — Forge/README.md and Forge/Output/Admin_Panel_Plan.md), S3.1 (Forge_Project docs only), S6.1, S6.3, S10.1, S12.1 (Forge_Project docs only), S12.3 (Forge_Project docs and Project_Flow/SKILL.md).

Prerequisite: None.

Task Ordering Note (E6 fix): Task 4 (S1.10 doc edits) MUST execute before Task 5 (S10.1 README/AGENTS consolidation). Task 4 edits Forge/README.md to replace Manage_Pages references; Task 5 may consolidate or eliminate Forge/README.md. If Task 5 eliminates the file, the S1.10 edits from Task 4 must already be applied (or the consolidation must carry forward the corrected content into AGENTS.md).

Task 1 — Update Forge_Project_User_Guide.md

Spec S6.3: “Forge_Project_User_Guide.md references {Project}_Changelog.md (not {Project}_Summary.md) as the document created in the Create phase.” Also Spec S6.1: “{Project}_Summary.md is not used. The file change manifest is {Project}_Changelog.md.” Spec S3.1: “The default human gates are consistent across all sources: Vision_Eval, Spec_Eval, Plan_Eval, Verify. Vision_Eval is included as a default gate in the Workflow and User Guide docs.” Spec S12.1: “The valid Phase: value statuses are Started, Completed, and Blocked only. There is no Pending state.” Spec S12.3: “Forge/Forge_Project/Forge_Project_User_Guide.md — the phase-state table row _Pending | Waiting for the agent to start is removed. The table lists Started, Completed, and Blocked only.”

Steps

  1. Edit Forge/Forge_Project/Forge_Project_User_Guide.md.
  2. S6.3/S6.1: Replace references to {Project}_Summary.md with {Project}_Changelog.md as the document created in the Create phase.
  3. S3.1: Ensure the default human gates listed are Vision_Eval, Spec_Eval, Plan_Eval, Verify. Add Vision_Eval if missing from the default gates list.
  4. S12.1/S12.3: Remove the phase-state table row _Pending | Waiting for the agent to start. The table should list only Started, Completed, and Blocked.

Verify

  • grep -r 'Summary.md' Forge/Forge_Project/Forge_Project_User_Guide.md returns no matches (replaced with Changelog.md)
  • The default human gates include Vision_Eval, Spec_Eval, Plan_Eval, Verify
  • grep -ri '_Pending\|Pending.*Waiting' Forge/Forge_Project/Forge_Project_User_Guide.md returns no matches
  • The phase-state table lists only Started, Completed, and Blocked

Task 2 — Update Forge_Project_Workflow.md

Spec S3.1: “The default human gates are consistent across all sources: Vision_Eval, Spec_Eval, Plan_Eval, Verify.” Spec S12.1: “The valid Phase: value statuses are Started, Completed, and Blocked only. There is no Pending state.” Spec S12.3: “Forge/Forge_Project/Forge_Project_Workflow.md — the phase-state table row for _Pending is removed.”

Steps

  1. Edit Forge/Forge_Project/Forge_Project_Workflow.md.
  2. S3.1: Ensure the default human gates listed are Vision_Eval, Spec_Eval, Plan_Eval, Verify. Add Vision_Eval if missing.
  3. S12.1/S12.3: Remove any _Pending phase-state references. The valid phase states are Started, Completed, and Blocked only.

Verify

  • The default human gates include Vision_Eval, Spec_Eval, Plan_Eval, Verify
  • grep -ri '_Pending' Forge/Forge_Project/Forge_Project_Workflow.md returns no matches (except “Pending user decision” which is a scope-decision status, not a phase state — retained per Spec)

Task 3 — Update Project_Flow/SKILL.md

Spec S12.3: “Forge/Forge_Project/Skills/Project_Flow/SKILL.md — the Phase Detection convention is updated to remove the {Phase}_Pending → waiting for agent to start clause. The convention reads: {Phase}_Started → in progress → use Project_{Phase} skill; {Phase}_Blocked → blocked (Runner creates a todo item); {Phase}_Completed → done → start next phase.”

Steps

  1. Edit Forge/Forge_Project/Skills/Project_Flow/SKILL.md.
  2. Update the Phase Detection convention to remove the {Phase}_Pending → waiting for agent to start clause.
  3. The convention should read: {Phase}_Started → in progress → use Project_{Phase} skill; {Phase}_Blocked → blocked (Runner creates a todo item); {Phase}_Completed → done → start next phase.

Verify

  • grep -ri '_Pending.*waiting\|Pending.*agent to start' Forge/Forge_Project/Skills/Project_Flow/SKILL.md returns no matches
  • The Phase Detection convention lists only Started, Blocked, and Completed

Task 4 — Replace Manage_Pages References in Documentation Files

Spec S1.10: “Affected documentation files: Forge/README.md — ‘use the Manage Pages skill and Forge Document Structure’; Forge/Output/Admin_Panel_Plan.md — ‘per the manage-pages skill’.” These references are replaced with the canonical Page Manager spawn pattern.

Steps

  1. Edit Forge/README.md: replace “use the Manage Pages skill and Forge Document Structure” with instructions to spawn the Page Manager bot via spawnAgent with { botGroup: 'forge', botHandle: 'page-manager' } for page operations.
  2. Edit Forge/Output/Admin_Panel_Plan.md: replace “per the manage-pages skill” with “per the Page Manager bot (spawned via spawnAgent with { botGroup: 'forge', botHandle: 'page-manager' }).”

Verify

  • grep -ri 'manage.pages skill\|Manage_Pages skill\|manage-pages skill' Forge/README.md Forge/Output/Admin_Panel_Plan.md returns no matches
  • Both files reference the Page Manager bot spawn pattern

Task 5 — Consolidate README.md and AGENTS.md Pairs

Spec S10.1: “Evaluate each README.md and AGENTS.md pair in Forge folders. Where content overlaps, consolidate into AGENTS.md (which has richer structure: related skills, documents, knowledge sources) and eliminate README.md. For project folders, AGENTS.md serves as the canonical context file for both agents and humans.”

Output Record (E8 fix): Write the consolidation summary to Forge/Projects/Knowledge_Consistency/Knowledge_Consistency_README_Consolidation.md. This file records which README/AGENTS pairs were evaluated, which were consolidated, which were eliminated, and the rationale for each decision.

Steps

  1. Identify all README.md and AGENTS.md pairs in Forge folders. The known pairs are:
    • Forge/README.md and Forge/AGENTS.md
    • Forge/Forge_Project/README.md and Forge/Forge_Project/AGENTS.md
  2. For each pair, evaluate content overlap. Where content overlaps, consolidate into AGENTS.md (which has richer structure: related skills, documents, knowledge sources) and eliminate README.md.
  3. For Forge/README.md: this file was edited in Task 4 (S1.10 doc edits). If consolidating, carry forward the corrected Page Manager spawn pattern content into Forge/AGENTS.md before eliminating README.md.
  4. For Forge/Forge_Project/README.md: evaluate overlap with Forge/Forge_Project/AGENTS.md. Consolidate if overlapping.
  5. If a README.md contains unique content not in AGENTS.md, merge that content into AGENTS.md before eliminating README.md.
  6. Use the forge-filesystem trash tool to eliminate consolidated README.md files (never use bash rm).
  7. Spawn the Page Manager bot via spawnAgent with { botGroup: 'forge', botHandle: 'page-manager' } to update sidebar entries if any README.md sidebar entries need to be removed or redirected.
  8. Write the consolidation summary to Forge/Projects/Knowledge_Consistency/Knowledge_Consistency_README_Consolidation.md with the following content for each pair evaluated:
    • Folder path
    • README.md content summary
    • AGENTS.md content summary
    • Decision: consolidated or retained both
    • Rationale
    • If consolidated: what content was merged, what was eliminated

Verify

  • Forge/Projects/Knowledge_Consistency/Knowledge_Consistency_README_Consolidation.md exists and documents all evaluated pairs
  • For each consolidated pair, AGENTS.md contains the merged content and README.md no longer exists (trashed)
  • For each retained pair, both files exist with distinct, non-overlapping content
  • If Forge/README.md was eliminated, Forge/AGENTS.md contains the Page Manager spawn pattern from Task 4

Task 6 — Build, Commit, and Push

Spec S1.10, S3.1, S6.1, S6.3, S10.1, S12.1, S12.3: This Plan implements Forge_Project and documentation content corrections. After all tasks are complete, commit and push the changes. Per Known Infrastructure Context, npm run build is expected to fail; proceed with git operations regardless.

Steps

  1. Run npm run build from the repo root. This is known to fail. Proceed regardless.
  2. git add all modified files: Forge/Forge_Project/Forge_Project_User_Guide.md, Forge/Forge_Project/Forge_Project_Workflow.md, Forge/Forge_Project/Skills/Project_Flow/SKILL.md, Forge/README.md (if not eliminated), Forge/Output/Admin_Panel_Plan.md, Forge/AGENTS.md (if consolidated), Forge/Forge_Project/AGENTS.md (if consolidated), Forge/Forge_Project/README.md (if not eliminated), Forge/Projects/Knowledge_Consistency/Knowledge_Consistency_README_Consolidation.md, and any sidebar changes.
  3. git commit -m "Plan 6: Forge_Project and documentation content corrections (S1.10, S3.1, S6.1, S6.3, S10.1, S12.1, S12.3)"
  4. git push origin dev

Verify

  • All modified files are committed and pushed to dev
  • git log --oneline -1 shows the commit

Plan 6 Completion Criteria

  • Forge_Project_User_Guide.md references {Project}_Changelog.md (not Summary.md), includes Vision_Eval in default gates, and has no _Pending phase-state row
  • Forge_Project_Workflow.md includes Vision_Eval in default gates and has no _Pending phase-state references (except “Pending user decision” scope-decision label)
  • Project_Flow/SKILL.md Phase Detection convention lists only Started, Blocked, and Completed
  • Forge/README.md and Forge/Output/Admin_Panel_Plan.md reference the Page Manager bot spawn pattern, not Manage_Pages skill
  • README/AGENTS pairs evaluated and consolidated where overlapping; consolidation summary written to Knowledge_Consistency_README_Consolidation.md
  • Changes committed and pushed to dev

Dependencies

  • Requires: None
  • Blocks: None