Trp1 week1 architecture

.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+  workflow_dispatch:
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Setup Node.js and pnpm
+        uses: ./.github/actions/setup-node-pnpm
+      - name: Run linter
+        run: pnpm lint
+
+  type-check:
+    name: Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Setup Node.js and pnpm
+        uses: ./.github/actions/setup-node-pnpm
+      - name: Check TypeScript types
+        run: pnpm check-types
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Setup Node.js and pnpm
+        uses: ./.github/actions/setup-node-pnpm
+      - name: Run tests
+        run: pnpm test
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Setup Node.js and pnpm
+        uses: ./.github/actions/setup-node-pnpm
+      - name: Build project
+        run: pnpm build
+
+  format-check:
+    name: Format Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Setup Node.js and pnpm
+        uses: ./.github/actions/setup-node-pnpm
+      - name: Check code formatting
+        run: npx prettier --check "**/*.{js,jsx,ts,tsx,json,css,md}" --ignore-path .gitignore || (echo "Code formatting check failed. Run 'pnpm format' to fix." && exit 1)
+

.gitignore

@@ -6,7 +6,7 @@ node_modules
 package-lock.json
 coverage/
 mock/
-
+TRP1 Challenge Week 1_ Architecting the AI-Native IDE & Intent-Code Traceability.docx
 .DS_Store
 
 # IDEs

.husky/pre-commit

@@ -24,4 +24,7 @@ else
 fi
 
 $npx_cmd lint-staged
-$pnpm_cmd lint
+
+# Skip full repo lint on pre-commit (lint-staged already linted staged files)
+# Full linting happens in CI for comprehensive coverage
+echo "Pre-commit checks complete. Full lint runs in CI."

.orchestration/AGENT.md

@@ -0,0 +1,36 @@
+# Shared Knowledge Base
+
+This file contains persistent knowledge shared across parallel sessions (Architect/Builder/Tester). Contains "Lessons Learned" and project-specific stylistic rules.
+
+## Lessons Learned
+
+<!-- 
+Example entry:
+### 2026-02-16: Authentication Refactoring
+- **Issue:** Initial JWT implementation caused circular dependency
+- **Solution:** Extracted token validation to separate utility module
+- **Impact:** Reduced coupling, improved testability
+- **Related Intent:** INT-001
+-->
+
+## Project-Specific Rules
+
+<!-- 
+Example entry:
+### Code Style
+- Always use async/await, never raw Promises
+- Prefer named exports over default exports
+- Use TypeScript strict mode
+-->
+
+## Architectural Decisions
+
+<!-- 
+Example entry:
+### 2026-02-16: Database Schema Change
+- **Decision:** Migrate from SQLite to PostgreSQL
+- **Rationale:** Need better concurrent access for parallel agents
+- **Impact:** All database queries must be updated
+- **Related Intent:** INT-002
+-->
+

.orchestration/active_intents.yaml

@@ -0,0 +1,222 @@
+active_intents:
+  - id: INT-001
+    name: INT-001 — Intent-Code Traceability (Spec)
+    status: IN_PROGRESS
+    owned_scope:
+      - src/core/assistant-message/**
+      - src/core/tools/**
+      - src/core/hooks/**
+      - src/core/orchestration/**
+      - src/core/prompts/**
+      - .orchestration/**
+    constraints:
+      - Must enforce **intent selection before any destructive tool**
+        (`write_to_file`, `edit_file`, `apply_diff`, etc.).
+      - "Must keep **privilege separation**: UI emits events; extension host
+        executes privileged actions; hooks are middleware."
+      - Must log **spatially independent** traces via content hashing.
+    acceptance_criteria:
+      - Agent cannot write code before calling `select_active_intent(intent_id)`.
+      - "When a file is written, a JSONL entry is appended to
+        `.orchestration/agent_trace.jsonl` that includes:"
+      - intent id
+      - file path
+      - line range (best-effort)
+      - "`sha256:` content hash of the modified block"
+      - "`.orchestration/active_intents.yaml` exists and contains this intent."
+    created_at: 2026-02-18T08:56:57.063Z
+    updated_at: 2026-02-18T08:56:57.086Z
+    spec_hash: sha256:7966563e9a7886587d3c421761708195d8a1ce21addd4632f560965411fd839b
+    spec_file: specs/INT-001-intent-code-traceability.md
+  - id: INT-002
+    name: INT-002 — Hook System Implementation
+    status: IN_PROGRESS
+    owned_scope:
+      - src/core/hooks/**
+      - src/core/assistant-message/presentAssistantMessage.ts
+      - src/core/tools/**
+      - .orchestration/**
+    constraints:
+      - Must integrate with existing `presentAssistantMessage()` function
+        without breaking current tool execution flow.
+      - Pre-hooks must run **before** `tool.handle()` is called.
+      - Post-hooks must run **after** `tool.execute()` completes but before
+        result is returned.
+      - Hook system must be non-blocking for non-destructive tools (read-only
+        operations).
+      - Must maintain backward compatibility with existing tools.
+    acceptance_criteria:
+      - "`HookEngine` class exists in `src/core/hooks/HookEngine.ts`."
+      - Pre-hook validates intent selection for destructive tools
+        (`write_to_file`, `edit_file`, `execute_command`, etc.).
+      - Pre-hook enforces scope validation (file path must be within intent's
+        `owned_scope`).
+      - Post-hook logs trace entries to `.orchestration/agent_trace.jsonl` for
+        mutating actions.
+      - "`presentAssistantMessage()` integrates `HookEngine` with Pre-Hook and
+        Post-Hook calls."
+      - All existing tests pass after hook integration.
+    created_at: 2026-02-18T08:56:57.094Z
+    updated_at: 2026-02-18T08:56:57.094Z
+    spec_hash: sha256:e10e923c607996643684be16016bc8305d7259b543eae623e92b5e49db8b902c
+    spec_file: specs/INT-002-hook-system-implementation.md
+  - id: INT-003
+    name: INT-003 — Two-Stage Reasoning Loop
+    status: IN_PROGRESS
+    owned_scope:
+      - src/core/hooks/HookEngine.ts
+      - src/core/prompts/sections/tool-use-guidelines.ts
+      - src/core/tools/SelectActiveIntentTool.ts
+      - src/core/task/Task.ts
+    constraints:
+      - "**Stage 1 (Reasoning Intercept):** Agent MUST call
+        `select_active_intent(intent_id)` before any destructive tool."
+      - "**Stage 2 (Contextualized Action):** Agent receives intent context and
+        must include it when making code changes."
+      - System prompt must enforce this protocol in tool-use guidelines.
+      - Intent context must be injected into the agent's context before code
+        generation.
+    acceptance_criteria:
+      - System prompt includes instructions requiring `select_active_intent`
+        before code changes.
+      - "`SelectActiveIntentTool` returns XML `<intent_context>` block with
+        scope, constraints, and acceptance criteria."
+      - Pre-hook blocks destructive tools if no active intent is selected.
+      - Agent receives intent context in subsequent tool calls.
+      - Intent context is logged in `agent_trace.jsonl` entries.
+    created_at: 2026-02-18T08:56:57.098Z
+    updated_at: 2026-02-18T08:56:57.098Z
+    spec_hash: sha256:a75817698c5b1479c68e43dd41b04752d3a6df7c4af71f3ab60fdedf705e4dda
+    spec_file: specs/INT-003-reasoning-loop.md
+  - id: INT-004
+    name: INT-004 — Orchestration Directory Management
+    status: IN_PROGRESS
+    owned_scope:
+      - src/core/orchestration/OrchestrationDataModel.ts
+      - .orchestration/active_intents.yaml
+      - .orchestration/agent_trace.jsonl
+      - .orchestration/intent_map.md
+      - .orchestration/AGENT.md
+    constraints:
+      - "`.orchestration/` directory must be machine-managed (not user-edited
+        directly)."
+      - "`active_intents.yaml` must be valid YAML and follow the schema defined
+        in `document.md`."
+      - "`agent_trace.jsonl` must be append-only (no modifications, only
+        appends)."
+      - All file operations must be atomic (write to temp file, then rename).
+      - Directory and files must be initialized on first use.
+    acceptance_criteria:
+      - "`OrchestrationDataModel` class provides methods:"
+      - "`initialize()`: Creates directory and initializes files if missing."
+      - "`readActiveIntents()`: Parses and returns active intents."
+      - "`appendAgentTrace()`: Appends trace entry to JSONL file."
+      - "`updateIntentMap()`: Updates intent-to-file mapping."
+      - "`appendAgentKnowledge()`: Appends to AGENT.md."
+      - All methods handle errors gracefully and log failures.
+      - Files are created with proper templates if missing.
+      - YAML parsing validates schema and reports errors clearly.
+    created_at: 2026-02-18T08:56:57.099Z
+    updated_at: 2026-02-18T08:56:57.099Z
+    spec_hash: sha256:659bd435cecc3223171c3fce81f671c26baac9ce354c9a6e3c967164983ed9fb
+    spec_file: specs/INT-004-orchestration-directory.md
+  - id: INT-005
+    name: INT-005 — Logging & Traceability
+    status: IN_PROGRESS
+    owned_scope:
+      - src/core/hooks/HookEngine.ts` (Post-Hook implementation)
+      - src/core/orchestration/OrchestrationDataModel.ts
+      - .orchestration/agent_trace.jsonl
+      - src/utils/git.ts` (for VCS revision tracking)
+    constraints:
+      - Trace entries must include `sha256:` content hash of modified code
+        blocks.
+      - Line ranges must be best-effort (may be approximate for complex edits).
+      - "Each trace entry must link to:"
+      - Intent ID
+      - File path (relative to workspace root)
+      - VCS revision (Git SHA)
+      - Timestamp
+      - Model identifier
+      - Content hashing must be spatially independent (same code block = same
+        hash regardless of file location).
+    acceptance_criteria:
+      - Post-hook computes SHA-256 hash of modified content for file tools.
+      - "Trace entry includes all required fields per `document.md` schema:"
+      - "`id` (UUID)"
+      - "`timestamp` (ISO 8601)"
+      - "`vcs.revision_id` (Git SHA)"
+      - "`files[]` with `relative_path`, `conversations[]`, `ranges[]`,
+        `content_hash`"
+      - Trace entries are appended atomically to `agent_trace.jsonl`.
+      - "Content hash format: `sha256:<hex>`."
+      - Git SHA is retrieved from workspace root (handles non-Git repos
+        gracefully).
+    created_at: 2026-02-18T08:56:57.099Z
+    updated_at: 2026-02-18T08:56:57.099Z
+    spec_hash: sha256:2b3421a22c9e27a817e27aea652f3332cdbc821338b52e112ff654ff88c36317
+    spec_file: specs/INT-005-logging-traceability.md
+  - id: INT-006
+    name: INT-006 — Testing & Validation
+    status: IN_PROGRESS
+    owned_scope:
+      - src/core/hooks/**/*.test.ts
+      - src/core/orchestration/**/*.test.ts
+      - src/core/tools/SelectActiveIntentTool.test.ts
+      - tests/integration/hook-system.test.ts
+      - tests/e2e/intent-traceability.test.ts
+    constraints:
+      - Tests must not modify production `.orchestration/` files (use temp
+        directories).
+      - Tests must be deterministic and isolated (no shared state).
+      - Integration tests must verify hook system works with real tool execution.
+      - E2E tests must simulate full agent workflow (intent selection → code
+        change → trace logging).
+    acceptance_criteria:
+      - Unit tests for `HookEngine.preHook()` and `HookEngine.postHook()`.
+      - Unit tests for `OrchestrationDataModel` file operations.
+      - Unit tests for `SelectActiveIntentTool` intent loading and context
+        generation.
+      - "Integration test: Verify Pre-Hook blocks destructive tool without
+        intent."
+      - "Integration test: Verify Post-Hook logs trace entry after file write."
+      - "E2E test: Full workflow from intent selection to trace logging."
+      - All tests pass in CI/CD pipeline.
+      - Test coverage > 80% for hook and orchestration modules.
+    created_at: 2026-02-18T08:56:57.099Z
+    updated_at: 2026-02-18T08:56:57.100Z
+    spec_hash: sha256:f8343d2839370244e2f1d7b6622494a96438c86b21f42b98b159eb34e33a59c6
+    spec_file: specs/INT-006-testing-validation.md
+  - id: INT-007
+    name: INT-007 — Documentation & Knowledge Base
+    status: IN_PROGRESS
+    owned_scope:
+      - ARCHITECTURE_NOTES.md
+      - README.md` (Intent-Code Traceability section)
+      - .orchestration/AGENT.md
+      - docs/intent-traceability/
+      - CHANGELOG.md` (relevant entries)
+    constraints:
+      - "`ARCHITECTURE_NOTES.md` must document all injection points and hook
+        integration."
+      - '`AGENT.md` must be append-only knowledge base for "Lessons Learned".'
+      - Documentation must be kept in sync with code changes.
+      - API documentation must include examples for each public method.
+    acceptance_criteria:
+      - "`ARCHITECTURE_NOTES.md` includes:"
+      - Tool execution flow diagram
+      - Hook injection points with line numbers
+      - System prompt modification points
+      - Data model schemas
+      - "`AGENT.md` includes:"
+      - Lessons learned from implementation
+      - Common pitfalls and solutions
+      - Performance optimizations
+      - Stylistic rules for intent specifications
+      - README includes setup instructions and usage examples.
+      - All public APIs are documented with JSDoc comments.
+      - Documentation is reviewed and updated with each major change.
+    created_at: 2026-02-18T08:56:57.100Z
+    updated_at: 2026-02-18T08:56:57.100Z
+    spec_hash: sha256:50566c7bdbddce41c4f739cab9631172321f2880e8cb7a35fdf8c0d1a1aa56b4
+    spec_file: specs/INT-007-documentation.md

.orchestration/agent_trace.jsonl

@@ -0,0 +1,7 @@
+# Agent Trace Ledger (JSONL format - one JSON object per line)
+# Append-only, machine-readable history of every mutating action.
+# Links abstract Intent to concrete Code Hash for spatial independence.
+#
+# Example entry:
+# {"id":"trace-1234567890-abc","timestamp":"2026-02-16T12:00:00Z","vcs":{"revision_id":"abc123def456"},"files":[{"relative_path":"src/auth/middleware.ts","conversations":[{"url":"task-xyz","contributor":{"entity_type":"AI","model_identifier":"claude-3-5-sonnet"},"ranges":[{"start_line":15,"end_line":45,"content_hash":"sha256:a8f5f167f44f4964e6c998dee827110c"}],"related":[{"type":"intent","value":"INT-001"}]}]}]}
+

.orchestration/intent_map.md

@@ -0,0 +1,19 @@
+# Intent Map
+
+This file maps high-level business intents to physical files and AST nodes. When a manager asks, "Where is the billing logic?", this file provides the answer.
+
+## Intents
+
+<!-- 
+Example entry:
+## INT-001: JWT Authentication Migration
+- **Status:** IN_PROGRESS
+- **Files:**
+  - `src/auth/middleware.ts` (lines 15-45)
+  - `src/middleware/jwt.ts` (entire file)
+- **AST Nodes:**
+  - `JwtAuthMiddleware` class
+  - `validateToken()` function
+- **Last Updated:** 2026-02-16T12:00:00Z
+-->
+