Phase 1 handshake

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,21 @@
+## Summary
+- **Scope:** Concise description of the atomic change
+- **Intent ID:** Link or identifier (e.g., INT-YYYY-MM-DD-####)
+- **Context:** Why this change matters and how it aligns with governance
+
+## Checklist
+- [ ] Atomic change (single clear purpose, minimal unrelated edits)
+- [ ] Tests added/updated (unit/e2e, governance invariants)
+- [ ] Docs/diagrams updated (if user-facing or architecture-affecting)
+- [ ] Intent verified (PreHook pass; scope constraints respected)
+- [ ] Ledger trace validated (PostHook appends with content_hash + intent_id)
+
+## Verification
+- **Steps:**
+  - Run `pnpm lint && pnpm build && pnpm test`
+  - Execute feature locally; observe HookEngine pre/post behavior
+  - Confirm `.orchestration/agent_trace.jsonl` has expected entry
+- **Risk:** Low / Medium / High (brief note)
+
+## Notes
+- **Related PRs/Docs:** Links to diagrams and specs

.github/pull_request_template.md

@@ -1,3 +1,31 @@
+## Summary
+
+Describe the change succinctly: what, why, and the governance impact.
+
+## Architecture & Governance
+
+- Intent checkout enforced (PreHook)
+- Trace ledger appended with content-hash (PostHook)
+- Privilege separation respected (Webview ↔ Extension Host ↔ Hook Engine)
+
+## Implementation Details
+
+- Entry points (tools) wrapped via IoC adapter
+- Prompt interception point identified; context dynamically injected
+- No tight coupling; hooks are isolated and composable
+
+## Tests & Verification
+
+- Unit/e2e around Point-of-No-Return intercepts
+- Scope enforcement validations
+- Ledger append assertions
+
+## Checklist
+
+- [ ] Intent selected and validated
+- [ ] Scope enforced for all writes
+- [ ] Ledger includes `intent_id` and `content_hash`
+- [ ] Docs updated (`ARCHITECTURE_NOTES.md`)
 <!--
 Thank you for contributing to Roo Code!
 

.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+
+      - name: Setup PNPM
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.8.1
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Type Check
+        run: pnpm check-types
+
+      - name: Build
+        run: pnpm build
+
+      - name: Test
+        run: pnpm test

.github/workflows/commitlint.yml

@@ -0,0 +1,30 @@
+name: Commitlint
+on:
+  pull_request:
+    types: [opened, synchronize, edited]
+
+jobs:
+  commitlint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+
+      - name: Install commitlint
+        run: |
+          npm i -D @commitlint/cli @commitlint/config-conventional
+
+      - name: Run commitlint on PR commits
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          COMMITS=$(gh pr view ${{ github.event.pull_request.number }} --json commits --jq '.commits[].oid')
+          for c in $COMMITS; do
+            git show --quiet --pretty=format:%B $c > .git/COMMIT_MSG
+            npx commitlint --config commitlint.config.cjs --verbose --from $c --to $c --edit .git/COMMIT_MSG
+          done

.github/workflows/pr-size.yml

@@ -0,0 +1,48 @@
+name: PR Size Labeler
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  size:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Compute diff size
+        id: diff
+        run: |
+          echo "files=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | wc -l | tr -d ' ')" >> $GITHUB_OUTPUT
+          echo "lines=$(git diff --numstat origin/${{ github.base_ref }}...HEAD | awk '{added+=$1;deleted+=$2} END {print added+deleted}')" >> $GITHUB_OUTPUT
+
+      - name: Ensure size labels exist
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const labels = [
+              { name: 'size/XS', color: 'ededed' },
+              { name: 'size/S', color: 'c2e0c6' },
+              { name: 'size/M', color: 'fbca04' },
+              { name: 'size/L', color: 'b60205' },
+              { name: 'size/XL', color: 'd93f0b' }
+            ];
+            for (const l of labels) {
+              try {
+                await github.rest.issues.getLabel({ owner: context.repo.owner, repo: context.repo.repo, name: l.name });
+              } catch (e) {
+                await github.rest.issues.createLabel({ owner: context.repo.owner, repo: context.repo.repo, name: l.name, color: l.color });
+              }
+            }
+
+      - name: Apply size label
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const files = parseInt('${{ steps.diff.outputs.files }}', 10);
+            const lines = parseInt('${{ steps.diff.outputs.lines }}', 10);
+            let label = 'size/XS';
+            if (lines > 50) label = 'size/S';
+            if (lines > 200) label = 'size/M';
+            if (lines > 500) label = 'size/L';
+            if (lines > 1000) label = 'size/XL';
+            await github.rest.issues.addLabels({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.issue.number, labels: [label] });

.husky/commit-msg

@@ -0,0 +1,8 @@
+#!/usr/bin/env sh
+. "$(dirname "$0")/_/husky.sh"
+
+# Enforce Conventional Commits via commitlint
+npx --no-install commitlint --edit "$1" || {
+  echo "\nCommit message must follow Conventional Commits (e.g., feat(hooks): ...).";
+  exit 1;
+}

ARCHITECTURE_NOTES.md

@@ -0,0 +1,85 @@
+# Architectural Deep-Dive & Governance Blueprint
+
+This document maps Roo Code’s tool loop, pinpoints side-effect boundaries (Point of No Return), and proposes a decoupled governance middleware to satisfy the TRP1 “Master Thinker” rubric.
+
+## Tool Loop Anatomy
+
+- **`execute_command` path**:
+  - Entry: [src/core/tools/ExecuteCommandTool.ts](src/core/tools/ExecuteCommandTool.ts)
+    - Signature: `ExecuteCommandTool.execute(params: { command: string, cwd?: string }, task: Task, callbacks: ToolCallbacks): Promise<void>`
+    - Governance hooks: `PreHook.validate(...)` and `PostHook.log(...)` integrated.
+  - Terminal dispatch: [src/integrations/terminal/Terminal.ts](src/integrations/terminal/Terminal.ts#L79)
+    - Signature: `Terminal.runCommand(command: string, callbacks: RooTerminalCallbacks): RooTerminalProcessResultPromise`
+    - PONR: `process.run(command)` triggers VS Code shell execution.
+  - Shell execution: [src/integrations/terminal/Ter​minalProcess.ts](src/integrations/terminal/TerminalProcess.ts#L90-L105)
+    - Side-effect: `terminal.shellIntegration.executeCommand(command)`; fallback `terminal.sendText(...)` when integration absent.
+
+- **`write_to_file` path**:
+  - Entry: [src/core/tools/WriteToFileTool.ts](src/core/tools/WriteToFileTool.ts)
+    - Signature: `WriteToFileTool.execute(params: { path: string, content: string }, task: Task, callbacks: ToolCallbacks): Promise<void>`
+    - Governance hooks: `PreHook.validate(...)` (intent + scope), `PostHook.log(...)` (trace + hash).
+  - Diff-stream path (editor memory edits): [src/integrations/editor/DiffViewProvider.ts](src/integrations/editor/DiffViewProvider.ts#L150-L188)
+    - Side-effect (memory): `vscode.workspace.applyEdit(...)` repeatedly.
+    - Disk PONR (diff path): [src/integrations/editor/DiffViewProvider.ts](src/integrations/editor/DiffViewProvider.ts#L213) → `updatedDocument.save()`.
+  - Direct save path (prevent focus disruption): [src/integrations/editor/DiffViewProvider.ts](src/integrations/editor/DiffViewProvider.ts#L660)
+    - Disk PONR: `fs.writeFile(absolutePath, content, "utf-8")`.
+
+## Dependency Graph (condensed)
+
+- `Task` → Tools (`ExecuteCommandTool`, `WriteToFileTool`)
+- `ExecuteCommandTool` → `TerminalRegistry.getOrCreateTerminal()` → `Terminal.runCommand()` → `TerminalProcess.run()` → VS Code terminal shell integration
+- `WriteToFileTool` → `DiffViewProvider` (`open`/`update`/`saveChanges` or `saveDirectly`) → `workspace.applyEdit` → `updatedDocument.save()` or `fs.writeFile`
+- Governance: `PreHook` (intent checkout + scope) and `PostHook` (trace ledger + hashing) already imported by both tools.
+
+## Point of No Return (explicit)
+
+- Commands: [process run](src/integrations/terminal/Terminal.ts#L79) → [shell exec](src/integrations/terminal/TerminalProcess.ts#L90-L105)
+- Files (diff path): [applyEdit](src/integrations/editor/DiffViewProvider.ts#L150-L188) then [save](src/integrations/editor/DiffViewProvider.ts#L213)
+- Files (direct path): [writeFile](src/integrations/editor/DiffViewProvider.ts#L660)
+
+## Risk Assessment
+
+- **Race conditions**: Concurrent terminal runs and parallel file edits; editor memory vs disk divergence before save.
+- **Unauthorized writes**: Writes outside intended scope; missing intent checkout; lack of HITL on destructive commands.
+- **Context rot**: Tool execution without curated intent context; agent acts on stale state.
+- **Trace gaps**: Unlogged side effects (e.g., terminal commands) or missing content-hash linkage to intent.
+
+## Privilege Separation & Intercepts
+
+- **Webview (UI)**: Emits messages only; no secrets or side-effects.
+- **Extension Host (Logic)**: Executes tools; must route through middleware.
+- **Hook Engine (Middleware)**: Intercepts all tool calls.
+  - Pre: intent checkout (`select_active_intent`), scope enforcement (`owned_scope` glob), HITL authorization.
+  - Post: ledger append (`agent_trace.jsonl`), content hashing, state evolution (`active_intents.yaml`).
+
+## IoC Middleware Blueprint (decoupled)
+
+- **ToolAdapter**: Wraps all tool `execute()` calls.
+  - `beforeExecute(ctx)`: intent validation, scope check, HITL gate.
+  - `run(ctx)`: delegate to tool implementation.
+  - `afterExecute(ctx)`: compute hash, serialize trace, update orchestration artifacts.
+- **Registration**: Tool registry binds adapters, not tools directly.
+- **Contracts**: Minimal `ToolContext { toolName, params, targetPaths, mutationClass }` to bind governance, independent of tool internals.
+- **Failure semantics**: Adapter must be fail-safe; rejection returns standardized JSON error to the agent.
+
+## Governance Data Model (artifacts)
+
+- `.orchestration/active_intents.yaml`: IN_PROGRESS intent, `owned_scope`, constraints, DoD.
+- `.orchestration/agent_trace.jsonl`: Append-only; `{ intent_id, content_hash, ranges, contributor.model_identifier }`.
+- `.orchestration/intent_map.md`: Intent → files/AST nodes; updated on `INTENT_EVOLUTION`.
+- `CLAUDE.md`: Shared brain; lessons learned on verification failure.
+
+## Evaluation Alignment (Score 5 targets)
+
+- **Hook Architecture**: Clean middleware adapters; tools isolated and composable; pre/post hooks mandatory.
+- **Context Engineering**: Dynamic intent injection; agent cannot act without context; curated constraints (not dumps).
+- **Intent-AST Correlation**: `agent_trace.jsonl` links intent IDs to content hashes; classifies `AST_REFACTOR` vs `INTENT_EVOLUTION`.
+- **Orchestration**: Optimistic locking on writes; shared `CLAUDE.md` prevents collisions; multi-agent “hive mind”.
+
+## Implementation Notes
+
+- Intercept points are stable and testable:
+  - Commands: `ExecuteCommandTool.execute()` and terminal dispatch.
+  - Files: `WriteToFileTool.execute()` → `DiffViewProvider.saveChanges()` / `saveDirectly()`.
+- Use dependency injection to bind hooks; avoid touching tool internals beyond adapter wiring.
+- Provide unit/e2e tests around PONR to assert governance invariants (intent required, scope enforced, ledger append).