knowzcode 0.1.0

package/knowzcode/knowzcode_loop.md

@@ -0,0 +1,515 @@
+# KnowzCode - Development Methodology & Operational Protocol
+
+**Target Audience:** Any AI coding assistant (Claude Code, Codex, Gemini, Cursor, Copilot, etc.)
+**Purpose:** This is your primary operational guide for structured, test-driven development using KnowzCode. Follow these phases precisely when working on any feature or change.
+
+## 1. Core Principles
+
+* **Change Set-Driven Development**: Work is performed on a "Change Set" — a group of NodeIDs (new capabilities) and affected files. This ensures system-wide consistency.
+* **Spec-Driven Development**: `knowzcode/specs/[NodeID].md` files define what to build. They are drafted, approved, implemented against, then finalized to "as-built" state.
+* **Mandatory TDD**: Every feature must follow Red-Green-Refactor. No production code without a failing test first.
+* **Quality Gates**: You MUST pause at defined checkpoints for user approval. Never skip phases.
+* **Integrated Version Control**: Strategic commits mark phase transitions.
+* **Proactive Debt Management**: Technical debt is formally tracked, not ignored.
+
+## 2. Core Files Reference
+
+* **`knowzcode/knowzcode_project.md`**: Read-only project context.
+* **`knowzcode/knowzcode_architecture.md`**: Architecture docs. Update for simple consistency changes.
+* **`knowzcode/knowzcode_tracker.md`**: Track NodeID statuses and WorkGroup assignments.
+* **`knowzcode/knowzcode_log.md`**: Prepend log entries. Read reference quality criteria.
+* **`knowzcode/specs/[NodeID].md`**: Create, read, and finalize specifications.
+* **`knowzcode/workgroups/<WorkGroupID>.md`**: Session todo list. Every entry must begin with `KnowzCode:`.
+* **This document (`knowzcode/knowzcode_loop.md`)**: Your primary workflow reference.
+
+## 3. The Main Operational Loop
+
+### Phase 1A: Impact Analysis
+
+Receive the goal from the user. Identify the **Change Set** — all components affected by this change.
+
+**NodeID Granularity**: Create NodeIDs only for NEW capabilities being built, not for every file touched. Files that integrate a new capability are "affected files" — they don't need separate NodeIDs or specs.
+
+**Change Set Format:**
+```markdown
+## Change Set for WorkGroup [ID]
+
+### New Capabilities (NodeIDs)
+| NodeID | Description |
+|--------|-------------|
+| LIB_DateTimeFormat | Timezone formatting utility |
+
+### Affected Files (no NodeIDs needed)
+- JobsPage.tsx - integrate formatDateTime
+- IntakeJobsPage.tsx - integrate formatDateTime
+
+**Specs Required**: 1
+```
+
+**NodeID Naming Convention:**
+NodeIDs must be **domain concepts**, not tasks.
+
+1. **Domain-Area NodeIDs** (default): PascalCase covering cohesive areas
+   - Examples: `Authentication`, `FileManagement`, `Checkout`, `UserProfile`
+   - Covers multiple components: `Authentication` = login form + auth endpoint + token service
+   - Sub-areas when a domain grows large: `Authentication_OAuth`, `Payments_Stripe`
+
+2. **Utility NodeIDs** (exception): For genuinely isolated utilities
+   - `LIB_` prefix: `LIB_DateFormat`, `LIB_Validation`
+   - `CONFIG_` prefix: `CONFIG_FeatureFlags`
+
+3. **Use Case NodeIDs** (optional): `UC_` for cross-domain workflows
+   - Only when genuinely spanning multiple unrelated domains
+
+**Never use task-oriented names**: `FIX-001`, `TASK-X`, `FEATURE-Y`. Tasks belong in WorkGroup files.
+
+**Consolidation Rule:** Before creating a new NodeID, check existing specs. If >50% domain overlap exists with an existing spec, UPDATE that spec instead. Target <20 specs per project.
+
+**Historical Context:** Before proposing the Change Set, scan `knowzcode/workgroups/` for completed WorkGroups that touched similar components. Reference relevant context in your proposal.
+
+#### Quality Gate: Change Set Approval
+Present the proposed Change Set to the user. **PAUSE and await user approval.** Do NOT proceed to Phase 1B until the user explicitly approves.
+
+Upon approval, generate a unique WorkGroupID and update `knowzcode_tracker.md` for all nodes to `[WIP]`.
+
+**WorkGroupID Format**: `kc-{type}-{slug}-YYYYMMDD-HHMMSS`
+- Valid types: `feat`, `fix`, `refactor`, `issue`
+- Slug: 2-4 word kebab-case descriptor from the goal
+- Example: `kc-feat-user-auth-jwt-20250115-143022`
+
+---
+
+### Phase 1B: Specification
+
+Draft or refine `knowzcode/specs/[NodeID].md` for all nodes in the Change Set.
+
+**Spec Template (4-section format):**
+```markdown
+# [NodeID]: [Human-Readable Name]
+
+**Updated:** [timestamp]
+**Status:** Draft | Approved | As-Built
+
+## Rules & Decisions
+Key architectural decisions, business rules, constraints, and purpose.
+- Decision: chose X over Y because Z
+- Rule: must always validate before persisting
+
+## Interfaces
+Public contracts: inputs, outputs, API signatures, dependencies, events.
+- POST /api/users -> { id, email }
+- Depends on: AuthService for token validation
+
+## Verification Criteria
+Testable assertions for implementation and auditing.
+- VERIFY: when valid credentials, returns JWT token
+- VERIFY: when email exists, returns 409
+
+## Debt & Gaps
+Known limitations and future work.
+- TODO: add rate limiting
+```
+
+**Minimum valid spec:** 1+ Rules item, 1+ Interface item, 2+ `VERIFY:` statements.
+
+**Backward compatibility:** Old numbered-section specs remain valid until naturally touched. When finalizing, rewrite in the new format.
+
+#### Quality Gate: Spec Approval
+Present drafted specs to the user. **PAUSE and await user approval.** Log "SpecApproved" events.
+
+**Pre-Implementation Commit:** After specs are approved, commit `knowzcode/` to create a checkpoint before implementation begins.
+
+---
+
+### Phase 2A: Implementation (TDD MANDATORY)
+
+For each NodeID in the approved Change Set:
+
+```
+FOR each feature/criterion in the spec:
+
+    # RED Phase
+    1. Write a failing test that defines expected behavior
+    2. Run test → Confirm it FAILS
+       - If test passes without code, the test is wrong — fix it
+
+    # GREEN Phase
+    3. Write MINIMAL code to make the test pass
+    4. Run test → Confirm it PASSES
+       - If fails, fix code (not test)
+
+    # REFACTOR Phase
+    5. Review code for improvements
+    6. If refactoring: make change, run ALL tests, revert if any fail
+```
+
+**Verification Loop (must pass before claiming complete):**
+```
+WHILE verification not complete:
+    1. Run all tests → If FAIL: fix and restart
+    2. Run static analysis → If issues: fix and restart
+    3. Run build → If FAIL: fix and restart
+    4. Verify all VERIFY: criteria from specs → If unmet: implement and restart
+    5. All checks pass → Report complete
+```
+
+**Maximum iterations**: 10. If exceeded, pause and report blocker.
+
+#### Quality Gate: Implementation Complete
+Report implementation results including test counts, verification iterations, and criteria status. **PAUSE — the user or an auditor will verify completeness.**
+
+---
+
+### Phase 2B: Completeness Audit
+
+An independent, READ-ONLY audit verifying what percentage of specifications were actually implemented.
+
+**Process:**
+- Compare implementation against specifications for all NodeIDs
+- Calculate objective completion percentage
+- Report gaps, orphan code, and risk assessment
+- Do NOT modify any code during this phase
+
+**Outcomes** (user decides):
+- Return to Phase 2A to complete missing requirements
+- Accept current implementation and proceed to finalization
+- Modify specs to match implementation
+- Cancel the WorkGroup
+
+#### Quality Gate: Audit Approval
+Present audit results to the user. **PAUSE for decision.** Only proceed to Phase 3 when the user approves.
+
+---
+
+### Phase 3: Atomic Finalization
+
+Once implementation is verified and approved, execute finalization:
+
+**Step 7: Finalize Specifications**
+Update each `knowzcode/specs/[NodeID].md` to match the verified "as-built" implementation. Always use the 4-section format.
+
+**Step 8: Architecture Check**
+Review `knowzcode/knowzcode_architecture.md` against the Change Set.
+- Simple discrepancies: fix directly and note in log
+- Complex discrepancies: document for user review
+
+**Step 9: Log Entry**
+Prepend a comprehensive `ARC-Completion` entry to `knowzcode/knowzcode_log.md`:
+```markdown
+---
+**Type:** ARC-Completion
+**Timestamp:** [timestamp]
+**WorkGroupID:** [ID]
+**NodeID(s):** [list all]
+**Logged By:** AI-Agent
+**Details:**
+Successfully implemented and verified the Change Set for [goal].
+- **Verification Summary:** [key checks]
+- **Architectural Learnings:** [discoveries]
+- **Unforeseen Ripple Effects:** [affected nodes outside this WorkGroup, or None]
+- **Specification Finalization:** All specs updated to "as-built" state.
+- **Architecture Check Outcome:** [outcome]
+---
+```
+
+**Step 10: Update Tracker & Schedule Debt**
+- Change each NodeID status from `[WIP]` to `[VERIFIED]`, clear WorkGroupID
+- If significant tech debt documented, create `REFACTOR_[NodeID]` tasks
+- Check if changes impact `knowzcode_project.md` (new features, stack changes)
+
+**Step 11: Final Commit**
+Stage and commit all changes (source code + knowzcode files).
+
+**Step 12: Report & Close**
+Report completion, mention any `REFACTOR_` tasks created. WorkGroup is closed.
+
+---
+
+## 4. Micro-Fix Protocol
+
+For single-file, no-ripple-effect changes (results in a single `fix:` commit):
+
+1. Implement the small change
+2. Quick focused verification
+3. Log a `MicroFix` entry:
+```markdown
+---
+**Type:** MicroFix
+**Timestamp:** [timestamp]
+**NodeID(s)/File:** [target]
+**Logged By:** AI-Agent
+**Details:**
+- **User Request:** [description]
+- **Action Taken:** [change made]
+- **Verification:** [method/outcome]
+---
+```
+4. Commit with `fix: [description]`
+
+---
+
+## 5. When to Pause (Quality Gates)
+
+You **MUST** pause and await explicit user approval at:
+* After proposing a Change Set (Phase 1A)
+* After presenting specs for approval (Phase 1B)
+* After reporting implementation complete (Phase 2A) — awaiting audit
+* After audit results — awaiting decision on gaps (Phase 2B)
+* If you encounter a critical, unresolvable issue
+* If an architecture discrepancy is too complex to fix autonomously
+
+---
+
+## 6. MCP Integration (Optional but Recommended)
+
+If KnowzCode MCP server is configured (`knowzcode/mcp_config.md` or `knowzcode/knowzcode_vaults.md`), agents can leverage vault queries to enhance every phase.
+
+### Phase-Specific Usage
+
+| Phase | MCP Tool | Purpose |
+|-------|----------|---------|
+| **1A (Analysis)** | `search_knowledge(research_vault, "past decisions about {domain}")` | Find prior decisions affecting components |
+| **1B (Spec)** | `ask_question(research_vault, "conventions for {component_type}?")` | Check team conventions before drafting |
+| **2A (Build)** | `search_knowledge(code_vault, "{similar_feature} implementation")` | Find reference implementations |
+| **2B (Audit)** | `ask_question(research_vault, "standards for {domain}", researchMode=true)` | Comprehensive standards check |
+| **3 (Close)** | `create_knowledge(research_vault, ...)` | Capture patterns, decisions, workarounds |
+
+### Enterprise: Team Standards
+
+At workflow start, if enterprise vault is configured (`knowzcode/enterprise/compliance_manifest.md` has `mcp_compliance_enabled: true`):
+- Pull team-wide standards and merge into quality gate criteria
+- Push audit results to enterprise vault after Phase 2B
+- Push completion records to enterprise vault after Phase 3
+
+### Graceful Degradation
+
+All phases work without MCP. MCP enhances analysis depth and organizational learning but never blocks workflow progression. When MCP is unavailable, agents use standard file search tools (grep, glob) as fallback.
+
+---
+
+## 7. Learning Capture (Optional)
+
+During finalization, scan the WorkGroup for insight-worthy patterns:
+
+| Signal Type | Examples |
+|-------------|----------|
+| Pattern | "created utility for", "reusable", "abstracted" |
+| Decision | "chose X over Y", "opted for", "trade-off" |
+| Workaround | "workaround", "limitation", "can't do X so" |
+| Performance | "optimized", "reduced from X to Y", "cache" |
+| Security | "vulnerability", "sanitize", "authentication fix" |
+
+### Auto-Capture Triggers
+
+Learning candidates are detected at each quality gate. If MCP is available, write concrete knowledge entries:
+
+**After Phase 1A approval:**
+```
+If MCP available:
+  create_knowledge(research_vault, title="Scope: {goal}",
+    content="[NodeIDs] {list}\n[Risk] {assessment}\n[Decision] {user feedback}",
+    tags=["scope", "change-set"])
+```
+
+**After Phase 2A completion:**
+- Capture implementation patterns and workarounds discovered during TDD cycles
+
+**After Phase 2B audit:**
+```
+If MCP available:
+  create_knowledge(research_vault, title="Audit: {wgid} - {score}%",
+    content="[Findings] {gaps}\n[Security] {issues}\n[Decision] {user choice}",
+    tags=["audit", "quality"])
+If MCP available AND enterprise vault configured:
+  create_knowledge(enterprise_vault, title="Audit: {wgid} - {score}%",
+    content="[Findings] {gaps}\n[Security] {issues}\n[Decision] {user choice}",
+    tags=["audit", "enterprise"])
+```
+
+**After Phase 3 finalization:**
+- Capture architectural learnings and consolidation decisions (handled by closer agent)
+
+### Capture Protocol
+
+If MCP is available:
+1. Detect learning candidates from WorkGroup file content
+2. Check for duplicates via `search_knowledge` — skip if substantially similar exists
+3. Prompt user for approval before saving
+4. Create learning via `create_knowledge` with appropriate title prefix
+
+### Audit Trail (Enterprise)
+
+After Phase 3, if enterprise vault is configured:
+- Push WorkGroup completion record with goal, NodeIDs, audit score, and decisions
+- Push architecture drift findings if any detected during finalization
+
+If MCP is not available, skip learning capture and audit trail — all other phases work normally.
+
+---
+
+## 8. Multi-Agent Execution (Platform-Specific)
+
+Phases can be executed by a single AI sequentially or by specialized agents coordinated by a lead. Quality gates and phase sequence remain the same regardless of execution model.
+
+### Agent-to-Phase Mapping
+
+| Phase | Specialist Agent | Expertise |
+|-------|-----------------|-----------|
+| 1A | analyst | Impact analysis, Change Set proposals |
+| 1B | architect | Specification drafting, architecture review |
+| 2A | builder | TDD implementation, verification loops |
+| 2B | reviewer | Quality audit, security review |
+| 3 | closer | Finalization, learning capture |
+
+### Execution Rules
+
+When using multi-agent execution:
+- Each phase maps to a specialist agent
+- Phase dependencies enforce quality gates (1A must complete before 1B, etc.)
+- User approves transitions between phases at quality gates
+- Agents can communicate about gaps and blockers
+- The lead agent coordinates but does not modify code directly
+- Agents read context files independently — do not duplicate context across agents
+
+### Single-Agent Execution
+
+When a single AI handles all phases sequentially:
+- Follow the same phase sequence and quality gates
+- Pause at each gate for user approval
+- All quality standards apply identically
+
+### Sequential Execution Protocol (for platforms without orchestration)
+
+For platforms like Cursor, Copilot, or Windsurf where there is no agent orchestration:
+
+```
+FOR each phase in [1A, 1B, 2A, 2B, 3]:
+
+    1. Read the phase prompt: knowzcode/prompts/[LOOP_{phase}]__*.md
+    2. Read the WorkGroup file: knowzcode/workgroups/{WorkGroupID}.md
+    3. Execute the phase instructions
+    4. Write output to the WorkGroup file (prefix entries with "KnowzCode:")
+    5. STOP at quality gate — present results to user
+    6. Wait for user approval before reading the next phase prompt
+```
+
+**Key differences from orchestrated execution:**
+- The user manually triggers each phase transition
+- Context is carried via WorkGroup files, not inter-agent messaging
+- All phase prompts are self-contained — they read context from knowzcode/ files
+- Quality gates work identically (user approval required at each gate)
+
+**Minimal viable execution** (no platform adapter needed):
+1. Copy `knowzcode/` directory to your project
+2. Give your AI the Phase 1A prompt with your goal
+3. When the AI pauses, review output and give the next phase prompt
+4. Repeat until Phase 3 completes
+
+See your platform's adapter file for agent configuration details.
+
+---
+
+## 9. Context Handoff Protocol
+
+When phases transition (whether via agents or sequentially), the following data MUST be communicated to the next phase:
+
+### 1A → 1B Handoff
+- WorkGroupID
+- Approved Change Set (NodeIDs + affected files)
+- Risk assessment and classification
+- Historical context from prior WorkGroups
+- User-approved scope boundaries
+
+### 1B → 2A Handoff
+- WorkGroupID
+- Approved specifications (file paths)
+- Tracker state (all NodeIDs marked `[WIP]`)
+- Compliance constraints (if enterprise enabled)
+- Pre-implementation commit hash
+
+### 2A → 2B Handoff
+- WorkGroupID
+- Implementation artifacts (changed files list)
+- Test results (pass counts, coverage)
+- Verification iteration count
+- Any `[SPEC_ISSUE]` tags (see below)
+
+### 2B → 3 Handoff
+- WorkGroupID
+- Audit report with completion percentage
+- Gap list with severity assessment
+- User decision (proceed / return to 2A / modify specs)
+- Security findings summary
+
+On platforms with multi-agent orchestration, the lead agent manages this context. On platforms without orchestration, the user carries context by referencing WorkGroup files between phases.
+
+---
+
+## 10. Spec Issues During Implementation
+
+If the builder discovers a spec is incorrect or incomplete during Phase 2A:
+
+1. **Tag the issue**: Add `[SPEC_ISSUE]` comment in the WorkGroup file with details
+2. **Continue implementing**: Use best judgment for the affected criterion
+3. **Report in completion**: Include spec issues in the Phase 2A completion report
+4. **Phase 2B catches it**: The auditor flags spec-vs-implementation divergences
+5. **User decides**: At the 2B quality gate, the user can update specs or accept the deviation
+
+Builders MUST NOT silently deviate from specs. Every deviation must be tagged and reported.
+
+---
+
+## 11. Blocker Escalation Protocol
+
+When the verification loop reaches the maximum iteration count (10 for implementation, 5 for micro-fix):
+
+### Blocker Report Format
+
+```markdown
+## Blocker Report: {WorkGroupID}
+
+**Phase:** 2A Implementation
+**Iteration Count:** 10 (maximum reached)
+**NodeID(s) Affected:** [list]
+
+### Root Cause Analysis
+- **Failing Check:** [test name / build error / lint issue]
+- **Error Message:** [exact message]
+- **Attempts Made:** [summary of fix attempts]
+
+### Recommended Recovery Options
+1. **Modify spec**: Relax or adjust the criterion that cannot be met
+2. **Change approach**: Use a different implementation strategy
+3. **Split WorkGroup**: Extract the blocked NodeID into a separate WorkGroup
+4. **Accept partial**: Proceed with documented gap (debt item)
+5. **Cancel**: Abandon this WorkGroup
+
+### Files Involved
+- [list of files with the issue]
+```
+
+The user MUST select a recovery option before work continues.
+
+---
+
+## 12. Workflow Abandonment Protocol
+
+If a WorkGroup needs to be abandoned mid-workflow:
+
+1. **Revert uncommitted changes**: If implementation was in progress, revert source code changes (keep knowzcode files)
+2. **Update tracker**: Set all affected NodeIDs back to their pre-WorkGroup status
+3. **Log abandonment**: Create a log entry with type `WorkGroup-Abandoned` including the reason
+4. **Close WorkGroup file**: Mark the WorkGroup file as abandoned with reason
+5. **Preserve learnings**: If any useful patterns were discovered, capture them before closing
+
+```markdown
+---
+**Type:** WorkGroup-Abandoned
+**Timestamp:** [timestamp]
+**WorkGroupID:** [ID]
+**Phase At Abandonment:** [1A/1B/2A/2B/3]
+**Reason:** [user decision / blocker / scope change]
+**NodeID(s) Affected:** [list with their reverted statuses]
+**Learnings Preserved:** [any useful insights, or None]
+---
+```