icdev 1.0.0__py3-none-any.whl

icdev/data/goals/build_app.md

@@ -0,0 +1,544 @@
+# Build App — ATLAS Workflow
+
+## Goal
+
+Build full-stack applications using AI assistance within the GOTCHA framework. This workflow ensures apps are production-ready, not just demos.
+
+**ATLAS** is a 5-step process (6 steps with optional Critique phase):
+
+| Step | Phase | What You Do |
+|------|-------|-------------|
+| **A** | Architect | Define problem, users, success metrics |
+| **T** | Trace | Data schema, integrations map, stack proposal |
+| **L** | Link | Validate ALL connections before building |
+| **A** | Assemble | Build with layered architecture |
+| **C** | Critique | *(Optional)* Adversarial multi-agent plan review |
+| **S** | Stress-test | Test functionality, error handling |
+
+When the Critique phase is enabled (`atlas_critique.enabled: true` in `args/atlas_critique_config.yaml`), the workflow becomes **ATLAS-CR**:
+
+```
+A(rchitect) → T(race) → L(ink) → A(ssemble) → C(ritique) → S(tress-test)
+```
+
+```mermaid
+flowchart LR
+    A["A: Architect\nDefine problem, users,\nsuccess metrics"]
+    T["T: Trace\nData schema,\nintegrations, stack"]
+    L["L: Link\nValidate connections,\ntest APIs"]
+    As["A: Assemble\nBuild layers\nDB → Backend → UI"]
+    C["C: Critique\nAdversarial\nmulti-agent review"]
+    S["S: Stress-test\nFunctional, integration,\nedge case tests"]
+    A --> T --> L --> As --> C --> S
+    C -.->|CONDITIONAL\nrevise| As
+    C -.->|NOGO\nescalate| Stop["Human\nEscalation"]
+    S -.->|Issues found| As
+    style A fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+    style T fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+    style L fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+    style As fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+    style C fill:#3a1a3a,stroke:#9b59b6,color:#e0e0e0
+    style S fill:#1a3a2d,stroke:#28a745,color:#e0e0e0
+    style Stop fill:#3a1a1a,stroke:#e74c3c,color:#e0e0e0
+```
+
+If the Critique phase is disabled, ATLAS operates as the original 5-step process (backward compatible).
+
+## For prod builds when asked specifically add:
++ V - Validate (security/input sanitization, edge cases, unit tests)
++ M - Monitor (logging, observability, alerts)
+
+---
+
+## A — Architect
+
+**Purpose:** Know exactly what you're building before touching code.
+
+### Step 0: Agentic Fitness Assessment (Phase 19)
+
+Before answering architecture questions, evaluate the component's fitness for agentic architecture:
+
+```bash
+python tools/builder/agentic_fitness.py --spec "<component description>" --project-id "<id>" --json
+```
+
+The assessor scores 6 dimensions (data_complexity, decision_complexity, user_interaction, integration_density, compliance_sensitivity, scale_variability) and recommends: **agent**, **hybrid**, or **traditional** architecture. Use the scorecard to guide all downstream decisions (scaffolding, code generation, infrastructure).
+
+See `context/agentic/fitness_rubric.md` for the scoring rubric.
+
+### Questions to Answer
+
+1. **What problem does this solve?**
+   - One sentence. If you can't say it simply, you don't understand it.
+
+2. **Who is this for?**
+   - Specific user: "Me" / "Sales team" / "YouTube subscribers"
+   - Not "everyone"
+
+3. **What does success look like?**
+   - Measurable outcome: "I can see my metrics in one dashboard"
+   - Not vague: "It works"
+
+4. **What are the constraints?**
+   - Budget (API costs)
+   - Time (MVP vs full build)
+   - Technical (must use Supabase, must integrate with X)
+
+### Output
+
+```markdown
+## App Brief
+- **Problem:** [One sentence]
+- **User:** [Who specifically]
+- **Success:** [Measurable outcome]
+- **Constraints:** [List]
+```
+
+---
+
+## T — Trace
+
+**Purpose:** Design before building. This is where most "vibe coders" fail.
+
+### Data Schema
+
+Define your source of truth BEFORE building:
+
+```
+Tables:
+- users (id, email, name, created_at)
+- saved_items (id, user_id, title, content, source, created_at)
+- metrics (id, user_id, platform, value, date)
+
+Relationships:
+- users 1:N saved_items
+- users 1:N metrics
+```
+
+### Integrations Map
+
+List every external connection:
+
+| Service | Purpose | Auth Type | MCP Available? |
+|---------|---------|-----------|----------------|
+| Supabase | Database | API Key | Yes |
+| YouTube API | Metrics | OAuth | Via MCP |
+| Notion | Save items | API Key | Yes |
+
+### Technology Stack Proposal
+
+Based on requirements, propose:
+- Database (Supabase, Firebase, Postgres, etc.)
+- Backend (Supabase Functions, n8n, custom API)
+- Frontend (React, Next.js, vanilla, etc.)
+- Any other services needed
+
+User approves or overrides before proceeding.
+
+### Edge Cases
+
+Document what could break:
+
+- API rate limits (YouTube: 10,000 quota/day)
+- Auth token expiry
+- Database connection timeout
+- Invalid user input
+- MCP server unavailability
+
+### Output
+
+- Data schema diagram or markdown table
+- Technology stack (approved by user)
+- Integrations checklist
+- Edge cases documented
+
+---
+
+## L — Link
+
+**Purpose:** Validate all connections BEFORE building. Nothing worse than building for 2 hours then discovering the API doesn't work.
+
+### Connection Validation Checklist
+
+```
+[ ] Database connection tested
+[ ] All API keys verified
+[ ] MCP servers responding
+[ ] OAuth flows working
+[ ] Environment variables set
+[ ] Rate limits understood
+```
+
+### How to Test
+
+**Database:**
+```bash
+# Test via MCP or direct API call
+# Should return empty array or existing data, not error
+```
+
+**APIs:**
+```bash
+# Make a simple GET request
+# Verify response format matches expectations
+```
+
+**MCPs:**
+```
+# List available tools
+# Test one simple operation
+```
+
+### Output
+
+All green checkmarks. If anything fails, fix it before proceeding.
+
+---
+
+## A — Assemble
+
+**Purpose:** Build the actual application with proper architecture.
+
+### Architecture Layers
+
+Follow GOTCHA separation:
+
+1. **Frontend** (what user sees)
+   - UI components
+   - User interactions
+   - Display logic
+
+2. **Backend** (what makes it work)
+   - API routes
+   - Business logic
+   - Data validation
+
+3. **Database** (source of truth)
+   - Schema implementation
+   - Migrations
+   - Indexes
+
+### Build Order
+
+1. Database schema first
+2. Backend API routes second
+3. Frontend UI last
+
+This order prevents building UI for data structures that don't exist.
+
+### Component Strategy
+
+- Use existing component libraries (don't reinvent buttons)
+- Keep components small and focused
+- Document any non-obvious logic
+
+### Output
+
+Working application with:
+- Functional database
+- API endpoints responding
+- UI rendering correctly
+
+---
+
+## C — Critique (Optional, Phase 61)
+
+**Purpose:** Adversarial multi-agent review of the Assemble output before stress-testing. Catches security, compliance, and architectural issues early through independent parallel review.
+
+This phase is **optional** and controlled by `atlas_critique.enabled` in `args/atlas_critique_config.yaml`. When disabled, ATLAS proceeds directly from Assemble to Stress-test (backward compatible).
+
+### How It Works
+
+1. The Assemble-phase output (plan/implementation) is dispatched to **3 critic agents** in parallel:
+   - **Security Agent** — Reviews for vulnerabilities, attack surface, OWASP Top 10, STIG compliance
+   - **Compliance Agent** — Reviews for NIST 800-53 gaps, FedRAMP requirements, CUI markings, audit trail
+   - **Knowledge Agent** — Reviews for architecture flaws, performance risks, maintainability, testing gaps
+
+2. Each agent independently produces findings classified by severity: **critical**, **high**, **medium**, **low**
+
+3. A **consensus vote** determines the outcome:
+   - **GO** (0 critical, 0 high) — Proceed to Stress-test
+   - **CONDITIONAL** (0 critical, >0 high) — Loop back to Assemble with fix list (max 3 rounds)
+   - **NOGO** (>0 critical) — Stop, escalate to human
+
+4. If CONDITIONAL, the architect revises and resubmits. Up to `max_rounds` (default 3) revision cycles.
+
+### Running the Critique
+
+```bash
+# Run critique on plan text
+python tools/agent/atlas_critique.py --project-id "proj-123" \
+    --phase-output "plan text here" --json
+
+# Run critique on a file
+python tools/agent/atlas_critique.py --project-id "proj-123" \
+    --phase-output /path/to/plan.md --json
+
+# Check session status
+python tools/agent/atlas_critique.py --project-id "proj-123" \
+    --session-id "crit-abc123" --status --json
+
+# View critique history for a project
+python tools/agent/atlas_critique.py --project-id "proj-123" \
+    --history --json
+```
+
+### Finding Types
+
+| Type | Description |
+|------|-------------|
+| `security_vulnerability` | Security weakness or attack vector |
+| `compliance_gap` | Missing or incomplete compliance control |
+| `architecture_flaw` | Design pattern violation or structural issue |
+| `performance_risk` | Potential performance bottleneck |
+| `maintainability_concern` | Code quality or maintainability issue |
+| `testing_gap` | Missing or inadequate test coverage |
+| `deployment_risk` | Deployment or operational risk |
+| `data_handling_issue` | Data classification, encryption, or handling gap |
+
+### Configuration
+
+See `args/atlas_critique_config.yaml` for:
+- Critic agent assignments and focus areas
+- Consensus rules (GO/NOGO/CONDITIONAL thresholds)
+- Revision prompt template
+- Max rounds
+
+### Output
+
+Critique result with:
+- Consensus decision (GO/NOGO/CONDITIONAL)
+- All findings with severity, type, and suggested fixes
+- Revision summary (if CONDITIONAL with revisions)
+- Round count
+
+---
+
+## S — Stress-test
+
+**Purpose:** Test before shipping. This is the step most "vibe coding" tutorials skip entirely.
+
+### Functional Testing
+
+Does it actually work?
+
+```
+[ ] All buttons do what they should
+[ ] Data saves to database
+[ ] Data retrieves correctly
+[ ] Navigation works
+[ ] Error states handled
+```
+
+### Integration Testing
+
+Do the connections hold?
+
+```
+[ ] API calls succeed
+[ ] MCP operations work
+[ ] Auth persists across sessions
+[ ] Rate limits not exceeded
+```
+
+### Edge Case Testing
+
+What breaks?
+
+```
+[ ] Invalid input handled gracefully
+[ ] Empty states display correctly
+[ ] Network errors show feedback
+[ ] Long text doesn't break layout
+```
+
+### Acceptance Criteria Validation (V&V)
+
+Validate that what was built matches what was required. This is a **mandatory gate** — not a soft checklist.
+
+```bash
+python tools/testing/acceptance_validator.py \
+    --plan <plan_file> \
+    --test-results .tmp/test_runs/<run_id>/state.json \
+    --base-url <app_url if applicable> \
+    --pages <list of pages from plan> \
+    --json
+```
+
+**GATE (per `security_gates.yaml` `acceptance_validation`):**
+- 0 failed acceptance criteria
+- 0 pages rendering with error patterns (500, tracebacks, JS errors)
+- Plan MUST have `## Acceptance Criteria` section
+
+If gate fails: review the plan's acceptance criteria against actual implementation, fix gaps, and re-run.
+
+### Output
+
+Test report with:
+- What passed
+- What failed
+- What needs fixing
+- Acceptance criteria verification results
+
+---
+
+## M-ATLAS Variant (MBSE-Enabled Projects)
+
+If the project has `mbse_enabled=1`, use the **M-ATLAS** workflow which adds a **Model** pre-phase:
+
+| Step | Phase | What You Do |
+|------|-------|-------------|
+| **M** | Model | Import XMI/ReqIF, build digital thread, generate code scaffolding |
+| **A** | Architect | System design informed by model elements |
+| **T** | Trace | Data schema + integrations (augmented with model traceability) |
+| **L** | Link | Validate connections including model-code mappings |
+| **A** | Assemble | Build with model-generated scaffolding as starting point |
+| **C** | Critique | *(Optional)* Adversarial multi-agent plan review |
+| **S** | Stress-test | Test including model-generated test stubs |
+
+```mermaid
+flowchart LR
+    Check{"MBSE\nenabled?"}
+    M["M: Model\nImport XMI/ReqIF,\ndigital thread,\ncode scaffolding"]
+    A["A: Architect\nSystem design informed\nby model elements"]
+    T["T: Trace\nData schema +\nmodel traceability"]
+    L["L: Link\nValidate connections +\nmodel-code mappings"]
+    As["A: Assemble\nBuild with model-generated\nscaffolding"]
+    C["C: Critique\nAdversarial\nmulti-agent review"]
+    S["S: Stress-test\nTest including\nmodel-generated stubs"]
+    Check -->|Yes| M --> A
+    Check -->|No| A
+    A --> T --> L --> As --> C --> S
+    C -.->|CONDITIONAL| As
+    S -.->|Issues found| As
+    style Check fill:#3a3a1a,stroke:#ffc107,color:#e0e0e0
+    style M fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+    style A fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+    style T fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+    style L fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+    style As fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+    style C fill:#3a1a3a,stroke:#9b59b6,color:#e0e0e0
+    style S fill:#1a3a2d,stroke:#28a745,color:#e0e0e0
+```
+
+### M — Model Phase
+
+**Purpose:** Import authoritative system model and establish digital thread before design.
+
+1. Import latest XMI from Cameo: `python tools/mbse/xmi_parser.py --project-id X --file model.xmi`
+2. Import latest ReqIF from DOORS NG: `python tools/mbse/reqif_parser.py --project-id X --file reqs.reqif`
+3. Build digital thread: `python tools/mbse/digital_thread.py --project-id X auto-link`
+4. Generate code scaffolding: `python tools/mbse/model_code_generator.py --project-id X --language python --output ./src`
+5. Map model to NIST controls: `python tools/mbse/model_control_mapper.py --project-id X --map-all`
+
+If no model exists, skip this phase — ATLAS starts at Architect (backward compatible).
+
+---
+
+## Note: Deployment
+
+Deployment is **not part of this workflow**. It's a separate, user-initiated action.
+
+When you're ready to deploy, explicitly ask. This keeps deployment decisions in your control, not automated.
+
+---
+
+## Anti-Patterns (What NOT to Do)
+
+These are the mistakes "vibe coders" make:
+
+1. **Building before designing** — You end up rewriting everything
+2. **Skipping connection validation** — Hours wasted on broken integrations
+3. **No data modeling** — Schema changes cascade into UI rewrites
+4. **No testing** — Ship broken code, lose trust
+5. **Hardcoding everything** — No flexibility for changes
+
+---
+
+## GOTCHA Layer Mapping
+
+| ATLAS Step | GOTCHA Layer |
+|------------|--------------|
+| Architect | Goals (define the process) |
+| Trace | Context (reference patterns) |
+| Link | Args (environment setup) |
+| Assemble | Tools (execution) |
+| Critique | Orchestration (multi-agent adversarial review) |
+| Stress-test | Orchestration (AI validates) |
+
+
+---
+
+## Related Files
+
+- **Args:** `args/app_defaults.yaml` (if created)
+- **Context:** `context/ui_patterns/` (design references)
+- **Hard Prompts:** `hardprompts/app_building/` (generation templates)
+
+---
+
+## Mandatory: Child Application Generation Pipeline
+
+When building a **child application** (an application generated by ICDEV), the following rules are **mandatory**:
+
+### 1. Use the Child App Generator Pipeline
+
+All child applications MUST be generated through the `child_app_generator.py` pipeline (`tools/builder/child_app_generator.py`). This pipeline executes 16 steps that ensure every GOTCHA layer is populated:
+
+1. Directory tree creation (all 6 GOTCHA layer directories)
+2. Tool generation (deterministic Python scripts)
+3. Agent infrastructure (agent cards, A2A protocol)
+4. Memory system (MEMORY.md, logs, SQLite)
+5. Database initialization (standalone init script)
+6. Goals and hard prompts (adapted from ICDEV)
+7. Args and context (YAML configs, reference material)
+8. A2A callback client (parent-child communication)
+9. CI/CD setup (GitHub + GitLab)
+10. CSP MCP configuration (cloud provider integration)
+11. Dynamic CLAUDE.md generation (Jinja2)
+12. Audit trail and child registry registration
+13. Production audit (38-check readiness scan)
+14. **GOTCHA compliance validation** (6-layer + 4 meta checks)
+
+**Do NOT manually scaffold child applications.** Manual creation bypasses GOTCHA layer population, ATLAS workflow integration, and compliance validation.
+
+### 2. Post-Generation GOTCHA Validation
+
+After generation, `gotcha_validator.py` (`tools/builder/gotcha_validator.py`) MUST pass with `--gate` mode. This validates:
+
+| Check | GOTCHA Layer | Requirement |
+|-------|-------------|-------------|
+| Goals | G | `goals/manifest.md` exists + at least `build_app.md` + 1 other goal |
+| Orchestration | O | Agent cards in `tools/agent/cards/` OR `args/agent_config.yaml` |
+| Tools | T | `tools/` has at least 3 subdirectories |
+| Args | A | `args/` has at least 1 YAML file |
+| Context | C | `context/` has at least 1 subdirectory with content |
+| Hard Prompts | H | `hardprompts/` has at least 1 `.md` file |
+| CLAUDE.md | meta | Exists and references "GOTCHA" |
+| Memory | meta | `memory/MEMORY.md` exists |
+| Database | meta | `tools/db/` has an init script |
+| ATLAS | meta | `goals/build_app.md` exists |
+
+### 3. BMAD Quality Gates (Recommended)
+
+ICDEV includes BMAD Method tools that SHOULD be used during child app generation:
+
+- **PRD Validator** (`tools/requirements/prd_validator.py`) — Validate requirements quality before building
+- **Complexity Scorer** (`tools/requirements/complexity_scorer.py`) — Assess project complexity to select appropriate pipeline
+- **Elicitation Techniques** (`tools/requirements/elicitation_techniques.py`) — Use structured reasoning (pre-mortem, first principles) during architecture
+- **Adversarial Review** (`.claude/commands/review.md`) — Run adversarial code review with minimum 3 issues per review
+
+### 4. Entry Point
+
+The `/icdev-agentic` command is the standard entry point for generating child applications. It orchestrates:
+1. Requirements gathering
+2. Fitness assessment (6-dimension scoring)
+3. User decision confirmation
+4. Blueprint generation
+5. Child app generation (16-step pipeline)
+6. GOTCHA validation gate
+7. Verification and reporting
+
+---
+
+## Changelog

icdev/data/goals/cicd_integration.md

@@ -0,0 +1,86 @@
+# [TEMPLATE: CUI // SP-CTI]
+# Goal: CI/CD Integration (GitHub + GitLab)
+
+## Purpose
+Enable ICDEV to receive webhook events and poll issues from both GitHub and GitLab,
+classify workflow requests, and execute the full SDLC pipeline autonomously.
+
+## Architecture
+
+### Trigger Layer
+Two trigger mechanisms (choose one or both):
+1. **Webhook Server** (`tools/ci/triggers/webhook_server.py`) — Flask server that receives
+   POST events from GitHub (`/gh-webhook`) and GitLab (`/gl-webhook`)
+2. **Poll Trigger** (`tools/ci/triggers/poll_trigger.py`) — Cron-based polling every 20
+   seconds that checks for new issues or issues with `icdev` comments
+
+### Core Modules
+- **VCS** (`tools/ci/modules/vcs.py`) — Unified abstraction for GitHub (`gh` CLI) and GitLab (`glab` CLI)
+- **Agent Executor** (`tools/ci/modules/agent.py`) — Invokes Claude Code CLI as subprocess
+- **State** (`tools/ci/modules/state.py`) — Persistent state at `agents/{run_id}/icdev_state.json`
+- **Git Ops** (`tools/ci/modules/git_ops.py`) — Branch, commit, push with dual-platform PR/MR
+- **Workflow Ops** (`tools/ci/modules/workflow_ops.py`) — Issue classification, branch naming, commit messages
+
+### Workflow Orchestrators
+| Workflow | Script | Phases |
+|----------|--------|--------|
+| `icdev_plan` | `tools/ci/workflows/icdev_plan.py` | Classify → Branch → Plan → Commit → Push |
+| `icdev_build` | `tools/ci/workflows/icdev_build.py` | Load state → Implement → Commit → Push |
+| `icdev_test` | `tools/ci/workflows/icdev_test.py` | Test suite → Gates → Commit → Push |
+| `icdev_review` | `tools/ci/workflows/icdev_review.py` | Review vs spec → Patches → Commit → Push |
+| `icdev_sdlc` | `tools/ci/workflows/icdev_sdlc.py` | Plan → Build → Test → Review |
+| `icdev_plan_build` | Combined Plan + Build |
+| `icdev_plan_build_test` | Combined Plan + Build + Test |
+| `icdev_plan_build_test_review` | Combined Plan + Build + Test + Review |
+
+### Claude Code Commands (Slash Commands)
+| Command | File | Purpose |
+|---------|------|---------|
+| `/classify_issue` | `.claude/commands/classify_issue.md` | Classify issue as /chore, /bug, /feature, /patch |
+| `/classify_workflow` | `.claude/commands/classify_workflow.md` | Extract ICDEV workflow command from text |
+| `/generate_branch_name` | `.claude/commands/generate_branch_name.md` | Generate standardized branch names |
+| `/implement` | `.claude/commands/implement.md` | Implement a plan with CUI markings |
+| `/commit` | `.claude/commands/commit.md` | Generate git commit messages |
+| `/pull_request` | `.claude/commands/pull_request.md` | Create PR (GitHub) or MR (GitLab) |
+
+## Workflow Triggering
+
+### Via Webhook
+Users trigger workflows by including commands in issue body or comments:
+- `/icdev_plan` — Plan only
+- `/icdev_sdlc` — Full lifecycle
+- `/icdev_build run_id:abc12345` — Build with existing state
+
+### Via Polling
+The poll trigger automatically processes:
+- New issues without comments
+- Issues where the latest comment is `icdev`
+
+### Bot Loop Prevention
+All bot comments include `[ICDEV-BOT]` identifier. Webhooks ignore comments containing
+this identifier to prevent infinite loops.
+
+## Platform Detection
+VCS auto-detects the platform from `git remote get-url origin`:
+- `github.com` → GitHub mode (uses `gh` CLI)
+- Everything else → GitLab mode (uses `glab` CLI)
+
+## State Management
+State persists across workflow phases via `agents/{run_id}/icdev_state.json`.
+Supports piping between scripts via stdin/stdout for chaining.
+
+Core fields: `run_id`, `issue_number`, `branch_name`, `plan_file`, `issue_class`, `platform`, `project_id`
+
+## Security
+- GitHub webhooks validated via HMAC-SHA256 (`WEBHOOK_SECRET`)
+- GitLab webhooks validated via secret token (`GITLAB_WEBHOOK_TOKEN`)
+- Safe subprocess environment filters sensitive env vars
+- `stdin=subprocess.DEVNULL` prevents Claude Code CLI from hanging
+
+## Edge Cases
+- If `icdev_build` is called without a `run_id`, it is rejected (needs prior plan state)
+- If branch already exists, checkout instead of create
+- Always return 200 to webhooks to prevent retries
+- Graceful shutdown via SIGINT/SIGTERM handlers in poll trigger
+
+# [TEMPLATE: CUI // SP-CTI]

icdev/data/goals/claude_dir_maintenance.md

@@ -0,0 +1,77 @@
+# .claude Directory Maintenance — Per-Phase Governance Checklist
+
+**Standards:** NIST 800-53 AU-2 (Auditable Events), CM-3 (Configuration Change Control), SA-11 (Developer Testing)
+
+---
+
+## Purpose
+
+Every new ICDEV phase adds DB tables, dashboard routes, hooks, and commands. Without explicit governance, the `.claude` directory drifts from the codebase — leaving append-only tables unprotected, routes undocumented, and hooks broken. This goal defines the mandatory checklist that must be completed before any phase is declared done.
+
+---
+
+## Mandatory Per-Phase Checklist
+
+Before declaring any phase complete, verify each item:
+
+### Append-Only Tables (D6 — NIST AU)
+- [ ] **New append-only/immutable DB table?** Add the table name to `APPEND_ONLY_TABLES` in `.claude/hooks/pre_tool_use.py`
+- [ ] The table's `CREATE TABLE` statement in `init_icdev_db.py` must include an `-- append-only` or `-- immutable` comment in the 10 preceding lines
+
+### Dashboard Routes
+- [ ] **New dashboard page route?** Add to the `Pages:` line in `.claude/commands/start.md`
+- [ ] Also update the CLAUDE.md `Dashboard pages` section if the route is user-facing
+
+### E2E Test Specs
+- [ ] **New dashboard feature group?** Create an E2E test spec in `.claude/commands/e2e/<name>.md`
+- [ ] The spec must verify CUI banners, core functionality, and navigation
+
+### Hook Files
+- [ ] **New or renamed hook file?** Update the path reference in `.claude/settings.json` under the `hooks` key
+- [ ] All `.claude/hooks/*.py` files must pass `ast.parse()` syntax validation
+
+### Deny Rules
+- [ ] **New destructive operation?** Add a deny pattern to `.claude/settings.json` `permissions.deny` list
+
+### Final Validation
+- [ ] **Run the governance validator:**
+  ```bash
+  python tools/testing/claude_dir_validator.py --json
+  ```
+  Exit code must be `0` (all checks pass). Warnings are acceptable; failures are not.
+
+---
+
+## Validator Details
+
+**Tool:** `tools/testing/claude_dir_validator.py`
+**Tests:** `tests/test_claude_dir_validator.py` (50 tests)
+**Gate:** `claude_config_alignment` in `args/security_gates.yaml`
+
+### 6 Automated Checks
+
+| Check | Severity | What It Validates |
+|-------|----------|-------------------|
+| `append-only` | **Blocking** | All append-only tables in `init_icdev_db.py` are in `pre_tool_use.py` APPEND_ONLY_TABLES |
+| `hooks-syntax` | **Blocking** | All `.claude/hooks/*.py` files parse without SyntaxError |
+| `hooks-refs` | **Blocking** | All hook commands in `settings.json` reference existing files |
+| `routes` | Warning | All `@app.route()` page routes in `app.py` are listed in `start.md` |
+| `e2e` | Warning | Major dashboard page groups have E2E test specs |
+| `settings` | Warning | Required deny patterns (rm -rf, DROP TABLE, etc.) are in settings.json |
+
+### Running Individual Checks
+```bash
+python tools/testing/claude_dir_validator.py --check append-only --json
+python tools/testing/claude_dir_validator.py --check hooks-syntax --json
+python tools/testing/claude_dir_validator.py --check routes --json
+python tools/testing/claude_dir_validator.py --human   # All checks, terminal output
+```
+
+---
+
+## When to Run
+
+1. **After every phase implementation** — before declaring the phase complete
+2. **After modifying `.claude/` files** — hooks, settings, commands
+3. **After adding DB tables** — especially tables with audit/log semantics
+4. **In CI/CD** — as a pre-merge gate check (future integration with test_orchestrator.py)