Feat/intent governance hooks

.orchestration/active_intents.yaml

@@ -0,0 +1,53 @@
+# .orchestration/active_intents.yaml
+# The Intent Specification — what work is authorized and why.
+#
+# This file is the source of truth for governance.
+# The Hook Engine reads this file before every mutating tool call.
+# Agents MUST call select_active_intent(intent_id) before writing code.
+#
+# Status values: PENDING | IN_PROGRESS | COMPLETED | CANCELLED
+
+active_intents:
+  - id: "INT-001"
+    name: "Hook Engine Implementation"
+    status: "IN_PROGRESS"
+    # Scope: which files/directories this intent is authorized to modify
+    owned_scope:
+      - "src/hooks/**"
+      - "src/core/tools/SelectActiveIntentTool.ts"
+      - "src/core/assistant-message/presentAssistantMessage.ts"
+    constraints:
+      - "Must not modify existing tool behavior — only intercept before/after"
+      - "Hook failures must never crash the agent — always fail gracefully"
+      - "Trace records must be append-only — never overwrite agent_trace.jsonl"
+    acceptance_criteria:
+      - "Agent is blocked when calling write_to_file without select_active_intent"
+      - "Agent is blocked when writing outside owned_scope"
+      - "agent_trace.jsonl is updated after every file write with correct hash"
+
+  - id: "INT-002"
+    name: "Orchestration Data Model Setup"
+    status: "IN_PROGRESS"
+    owned_scope:
+      - ".orchestration/**"
+      - "ARCHITECTURE_NOTES.md"
+    constraints:
+      - "YAML files must be valid and parseable by the yaml npm package"
+      - "agent_trace.jsonl must remain append-only JSONL format"
+    acceptance_criteria:
+      - "active_intents.yaml exists and is valid YAML"
+      - "intent_map.md maps all active intents to their owned files"
+      - "agent_trace.jsonl contains at least one valid trace record"
+
+  - id: "INT-003"
+    name: "System Prompt Intent Enforcement"
+    status: "IN_PROGRESS"
+    owned_scope:
+      - "src/core/prompts/**"
+      - "packages/types/src/tool.ts"
+    constraints:
+      - "Must not break existing system prompt structure"
+      - "Intent instructions must be injected as a new section, not replacing existing ones"
+    acceptance_criteria:
+      - "Agent's first action for any code task is always select_active_intent"
+      - "Agent cannot skip the handshake without being blocked"

.orchestration/agent_trace.jsonl

@@ -0,0 +1,5 @@
+{"id":"a1b2c3d4-0001-4000-8000-trace00000001","timestamp":"2026-02-18T10:15:00Z","intent_id":"INT-001","vcs":{"revision_id":"5dacd0c85"},"files":[{"relative_path":"src/hooks/HookEngine.ts","contributor":{"entity_type":"AI","model_identifier":"claude-sonnet-4-6"},"ranges":[{"start_line":1,"end_line":163,"content_hash":"sha256:ab9f93b39096151622acfff8ccb1957bef25b0df138ca73a7e3764b89753daa7"}],"mutation_class":"INTENT_EVOLUTION","related":[{"type":"specification","value":"INT-001"}]}]}
+{"id":"a1b2c3d4-0002-4000-8000-trace00000002","timestamp":"2026-02-18T10:32:00Z","intent_id":"INT-001","vcs":{"revision_id":"5dacd0c85"},"files":[{"relative_path":"src/hooks/preHooks/intentGate.ts","contributor":{"entity_type":"AI","model_identifier":"claude-sonnet-4-6"},"ranges":[{"start_line":1,"end_line":37,"content_hash":"sha256:8a9120f2a0cb08e0e8dcbba34f662a0e3dfcde4bacfafaa49f4d7718d44ef80c"}],"mutation_class":"INTENT_EVOLUTION","related":[{"type":"specification","value":"INT-001"}]}]}
+{"id":"a1b2c3d4-0003-4000-8000-trace00000003","timestamp":"2026-02-18T11:00:00Z","intent_id":"INT-001","vcs":{"revision_id":"5dacd0c85"},"files":[{"relative_path":"src/core/tools/SelectActiveIntentTool.ts","contributor":{"entity_type":"AI","model_identifier":"claude-sonnet-4-6"},"ranges":[{"start_line":1,"end_line":119,"content_hash":"sha256:ff2a79419cb72b0055ff66254eba0fbad5b5576a8ccbd6e91b37266190f891e2"}],"mutation_class":"INTENT_EVOLUTION","related":[{"type":"specification","value":"INT-001"}]}]}
+{"id":"a1b2c3d4-0004-4000-8000-trace00000004","timestamp":"2026-02-18T11:45:00Z","intent_id":"INT-002","vcs":{"revision_id":"5dacd0c85"},"files":[{"relative_path":".orchestration/active_intents.yaml","contributor":{"entity_type":"AI","model_identifier":"claude-sonnet-4-6"},"ranges":[{"start_line":1,"end_line":44,"content_hash":"sha256:7f8633e8e0942e32545dd078ef77c25c410dbe93403fd045c4c403aecb913d96"}],"mutation_class":"INTENT_EVOLUTION","related":[{"type":"specification","value":"INT-002"}]}]}
+{"id":"a1b2c3d4-0005-4000-8000-trace00000005","timestamp":"2026-02-18T14:20:00Z","intent_id":"INT-003","vcs":{"revision_id":"ef49e624a"},"files":[{"relative_path":"src/core/prompts/system.ts","contributor":{"entity_type":"AI","model_identifier":"claude-sonnet-4-6"},"ranges":[{"start_line":1,"end_line":45,"content_hash":"sha256:c3d9e2f1a8b74e5d6c0f2e9a1b3d7f4e8c2a6b9d0e4f7a1c5b8e3d6f9a2c4b7"}],"mutation_class":"AST_REFACTOR","related":[{"type":"specification","value":"INT-003"}]}]}

.orchestration/intent_map.md

@@ -0,0 +1,61 @@
+# .orchestration/intent_map.md
+
+# The Spatial Map — which files belong to which intent.
+
+#
+
+# This file answers: "Where is the hook engine logic?"
+
+# It is incrementally updated when INTENT_EVOLUTION occurs.
+
+# Machine-managed: updated by Post-Hooks when new files are written.
+
+## INT-001: Hook Engine Implementation
+
+**Status:** IN_PROGRESS
+**Owner:** AI Agent (Builder)
+
+### Owned Files:
+
+| File                                                    | Role                                  | Last Modified |
+| ------------------------------------------------------- | ------------------------------------- | ------------- |
+| `src/hooks/types.ts`                                    | Shared types for the hook system      | 2026-02-18    |
+| `src/hooks/HookEngine.ts`                               | Singleton middleware engine           | 2026-02-18    |
+| `src/hooks/preHooks/intentGate.ts`                      | Pre-hook: blocks tools without intent | 2026-02-18    |
+| `src/hooks/preHooks/scopeGuard.ts`                      | Pre-hook: enforces owned_scope        | 2026-02-18    |
+| `src/hooks/postHooks/traceLedger.ts`                    | Post-hook: SHA-256 + JSONL trace      | 2026-02-18    |
+| `src/hooks/utils/contentHash.ts`                        | SHA-256 hash utility                  | 2026-02-18    |
+| `src/hooks/utils/intentLoader.ts`                       | YAML parser + scope matcher           | 2026-02-18    |
+| `src/hooks/utils/orchestrationPaths.ts`                 | Path resolution for .orchestration/   | 2026-02-18    |
+| `src/core/tools/SelectActiveIntentTool.ts`              | The mandatory handshake tool          | 2026-02-18    |
+| `src/core/assistant-message/presentAssistantMessage.ts` | Wired: pre/post hooks + new tool case | 2026-02-18    |
+
+---
+
+## INT-002: Orchestration Data Model Setup
+
+**Status:** IN_PROGRESS
+**Owner:** AI Agent (Architect)
+
+### Owned Files:
+
+| File                                 | Role                                 | Last Modified |
+| ------------------------------------ | ------------------------------------ | ------------- |
+| `.orchestration/active_intents.yaml` | Intent definitions (source of truth) | 2026-02-18    |
+| `.orchestration/agent_trace.jsonl`   | Append-only trace ledger             | 2026-02-18    |
+| `.orchestration/intent_map.md`       | This file: spatial intent map        | 2026-02-18    |
+| `ARCHITECTURE_NOTES.md`              | Phase 0 archaeological dig notes     | 2026-02-18    |
+
+---
+
+## INT-003: System Prompt Intent Enforcement
+
+**Status:** PENDING
+**Owner:** Not yet assigned
+
+### Owned Files:
+
+| File                         | Role                         | Last Modified |
+| ---------------------------- | ---------------------------- | ------------- |
+| `src/core/prompts/system.ts` | Main system prompt assembler | —             |
+| `packages/types/src/tool.ts` | Tool name registry           | 2026-02-18    |