oryon-framework 1.0.0

package/.claude/hooks/code-intel-pretool.cjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Code-Intel PreToolUse Hook — Auto-injects code intelligence context
+ * when an agent is about to Write or Edit a file.
+ *
+ * Protocol:
+ * - Reads JSON from stdin (Claude Code PreToolUse event)
+ * - Filters: only acts on Write and Edit tools
+ * - Queries RegistryProvider for entity, references, dependencies
+ * - Outputs JSON with additionalContext containing <code-intel-context> XML
+ * - Silent exit on any error (never blocks the tool call)
+ *
+ * @module code-intel-pretool-hook
+ */
+
+const path = require('path');
+
+/** Tools that trigger code-intel injection. */
+const TARGET_TOOLS = new Set(['Write', 'Edit']);
+
+/** Safety timeout (ms) — defense-in-depth. */
+const HOOK_TIMEOUT_MS = 4000;
+
+/**
+ * Read all data from stdin as a JSON object.
+ * @returns {Promise<object>}
+ */
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('error', (e) => reject(e));
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => {
+      try { resolve(JSON.parse(data)); }
+      catch (e) { reject(e); }
+    });
+  });
+}
+
+/**
+ * Main hook pipeline.
+ */
+async function main() {
+  const input = await readStdin();
+
+  // Filter: only act on Write/Edit tools
+  const toolName = input && input.tool_name;
+  if (!toolName || !TARGET_TOOLS.has(toolName)) return;
+
+  // Extract file_path from tool input
+  const toolInput = input.tool_input;
+  if (!toolInput) return;
+  const filePath = toolInput.file_path;
+  if (!filePath) return;
+
+  // Resolve project root from hook cwd or process.cwd()
+  const cwd = input.cwd || process.cwd();
+
+  // Load hook-runtime (lazy — only when we actually need it)
+  const { resolveCodeIntel, formatAsXml } = require(
+    path.join(__dirname, '..', '..', '.aios-core', 'core', 'code-intel', 'hook-runtime.js'),
+  );
+
+  const intel = await resolveCodeIntel(filePath, cwd);
+  const xml = formatAsXml(intel, filePath);
+  if (!xml) return;
+
+  // Output in Claude Code hook format
+  const output = JSON.stringify({
+    hookSpecificOutput: {
+      additionalContext: xml,
+    },
+  });
+
+  const flushed = process.stdout.write(output);
+  if (!flushed) {
+    await new Promise((resolve) => process.stdout.once('drain', resolve));
+  }
+}
+
+/**
+ * Safely exit — no-op inside Jest workers.
+ * @param {number} code
+ */
+function safeExit(code) {
+  if (process.env.JEST_WORKER_ID) return;
+  process.exit(code);
+}
+
+/** Entry point runner. */
+function run() {
+  const timer = setTimeout(() => safeExit(0), HOOK_TIMEOUT_MS);
+  timer.unref();
+  main()
+    .then(() => safeExit(0))
+    .catch(() => {
+      // Silent exit — stderr output triggers "hook error" in Claude Code UI
+      safeExit(0);
+    });
+}
+
+if (require.main === module) run();
+
+module.exports = { readStdin, main, run, HOOK_TIMEOUT_MS, TARGET_TOOLS };

package/.claude/hooks/precompact-session-digest.cjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * Claude Code Hook: PreCompact Session Digest
+ *
+ * Registered as PreCompact event — fires before context compaction.
+ * Reads JSON from stdin (Claude Code hook protocol), delegates to
+ * the unified hook runner in oryon-core.
+ *
+ * Stdin format (PreCompact):
+ * {
+ *   "session_id": "abc123",
+ *   "transcript_path": "/path/to/session.jsonl",
+ *   "cwd": "/path/to/project",
+ *   "hook_event_name": "PreCompact",
+ *   "trigger": "auto" | "manual"
+ * }
+ *
+ * @see .oryon-core/hooks/unified/runners/precompact-runner.js
+ * @see Story MIS-3 - Session Digest (PreCompact Hook)
+ * @see Story MIS-3.1 - Fix Session-Digest Hook Registration
+ */
+
+'use strict';
+
+const path = require('path');
+
+// Resolve project root via __dirname (same pattern as synapse-engine.cjs)
+// More robust than input.cwd — doesn't depend on external input
+const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
+
+/** Safety timeout (ms) — defense-in-depth; Claude Code also manages hook timeout. */
+const HOOK_TIMEOUT_MS = 9000;
+
+/**
+ * Read all data from stdin as a JSON object.
+ * Same pattern as synapse-engine.cjs.
+ * @returns {Promise<object>} Parsed JSON input
+ */
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('error', (e) => reject(e));
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => {
+      try { resolve(JSON.parse(data)); }
+      catch (e) { reject(e); }
+    });
+  });
+}
+
+/** Main hook execution pipeline. */
+async function main() {
+  const input = await readStdin();
+
+  // Resolve path to the unified hook runner via __dirname (not input.cwd)
+  // Same pattern as synapse-engine.cjs — robust against incorrect cwd
+  const runnerPath = path.join(
+    PROJECT_ROOT,
+    '.oryon-core',
+    'hooks',
+    'unified',
+    'runners',
+    'precompact-runner.js',
+  );
+
+  // Build context object expected by onPreCompact
+  const context = {
+    sessionId: input.session_id,
+    projectDir: input.cwd || PROJECT_ROOT,
+    transcriptPath: input.transcript_path,
+    trigger: input.trigger || 'auto',
+    hookEventName: input.hook_event_name || 'PreCompact',
+    permissionMode: input.permission_mode,
+    conversation: input,
+    provider: 'claude',
+  };
+
+  const { onPreCompact } = require(runnerPath);
+  await onPreCompact(context);
+}
+
+/** Entry point runner — sets safety timeout and executes main(). */
+function run() {
+  // Safety timeout — force exit only as last resort (no stdout to flush at this point).
+  const timer = setTimeout(() => {
+    process.exit(0);
+  }, HOOK_TIMEOUT_MS);
+  timer.unref();
+
+  main()
+    .then(() => {
+      clearTimeout(timer);
+      // Let event loop drain naturally — process.exitCode allows stdout flush
+      process.exitCode = 0;
+    })
+    .catch(() => {
+      clearTimeout(timer);
+      // Silent exit — never write to stderr (triggers "hook error" in Claude Code)
+      process.exitCode = 0;
+    });
+}
+
+if (require.main === module) run();
+
+module.exports = { readStdin, main, run, HOOK_TIMEOUT_MS };

package/.claude/hooks/synapse-engine.cjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * SYNAPSE Hook Entry Point — UserPromptSubmit
+ *
+ * Thin wrapper that reads JSON from stdin, delegates to SynapseEngine,
+ * and writes <synapse-rules> context to stdout.
+ *
+ * - Silent exit on missing .synapse/ directory
+ * - Silent exit on any error (never blocks the user prompt)
+ * - 5s safety timeout as defense-in-depth
+ *
+ * @module synapse-engine-hook
+ */
+
+const path = require('path');
+const { resolveHookRuntime, buildHookOutput } = require(
+  path.join(__dirname, '..', '..', '.oryon-core', 'core', 'synapse', 'runtime', 'hook-runtime.js'),
+);
+
+/** Safety timeout (ms) — defense-in-depth; Claude Code also manages hook timeout. */
+const HOOK_TIMEOUT_MS = 5000;
+
+/**
+ * Read all data from stdin as a JSON object.
+ * @returns {Promise<object>} Parsed JSON input
+ */
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('error', (e) => reject(e));
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => {
+      try { resolve(JSON.parse(data)); }
+      catch (e) { reject(e); }
+    });
+  });
+}
+
+/** Main hook execution pipeline. */
+async function main() {
+  const input = await readStdin();
+  const runtime = resolveHookRuntime(input);
+  if (!runtime) return;
+
+  const result = await runtime.engine.process(input.prompt, runtime.session);
+
+  // QW-1: Wire updateSession() — persist bracket transitions after each prompt
+  if (runtime.sessionId && runtime.sessionsDir) {
+    try {
+      const { updateSession } = require(
+        path.join(runtime.cwd, '.oryon-core', 'core', 'synapse', 'session', 'session-manager.js'),
+      );
+      updateSession(runtime.sessionId, runtime.sessionsDir, {
+        context: { last_bracket: result.bracket || 'FRESH' },
+      });
+    } catch (_err) {
+      // Fire-and-forget — never block the prompt
+    }
+  }
+
+  const output = JSON.stringify(buildHookOutput(result.xml));
+
+  // Write output robustly across real process.stdout and mocked Jest streams.
+  // Some mocks return boolean but never invoke callback; handle both patterns.
+  await new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (err) => {
+      if (settled) return;
+      settled = true;
+      if (err) reject(err);
+      else resolve();
+    };
+
+    try {
+      const flushed = process.stdout.write(output, (err) => finish(err));
+      if (flushed) {
+        setImmediate(() => finish());
+      } else if (typeof process.stdout.once === 'function') {
+        process.stdout.once('drain', () => finish());
+      }
+    } catch (err) {
+      finish(err);
+    }
+  });
+}
+
+/**
+ * Safely exit the process — no-op inside Jest workers to prevent worker crashes.
+ * @param {number} code - Exit code
+ */
+function safeExit(code) {
+  if (process.env.JEST_WORKER_ID) return;
+  process.exit(code);
+}
+
+/** Entry point runner — sets safety timeout and executes main(). */
+function run() {
+  const timer = setTimeout(() => safeExit(0), HOOK_TIMEOUT_MS);
+  timer.unref();
+  main()
+    .then(() => safeExit(0))
+    .catch(() => {
+      // Silent exit — stderr output triggers "hook error" in Claude Code UI
+      safeExit(0);
+    });
+}
+
+if (require.main === module) run();
+
+module.exports = { readStdin, main, run, HOOK_TIMEOUT_MS };

package/.claude/rules/agent-memory-imports.md

@@ -0,0 +1,15 @@
+---
+paths: .oryon-core/development/agents/**
+---
+
+# Agent Memory Imports
+
+Each Oryon agent has a canonical MEMORY.md containing persistent knowledge.
+These are the canonical locations — agents should read their memory on activation.
+
+@import .oryon-core/development/agents/dev/MEMORY.md
+@import .oryon-core/development/agents/qa/MEMORY.md
+@import .oryon-core/development/agents/architect/MEMORY.md
+@import .oryon-core/development/agents/devops/MEMORY.md
+@import .oryon-core/development/agents/pm/MEMORY.md
+@import .oryon-core/development/agents/po/MEMORY.md

package/.claude/rules/coderabbit-integration.md

@@ -0,0 +1,101 @@
+---
+paths:
+  - ".oryon-core/**"
+  - "tests/**"
+  - "packages/**"
+  - "bin/**"
+---
+
+# CodeRabbit Integration — Detailed Rules
+
+## Self-Healing Configuration
+
+### Dev Phase (@dev — Story Development Cycle Phase 3)
+
+```yaml
+mode: light
+max_iterations: 2
+timeout_minutes: 30
+severity_filter: [CRITICAL, HIGH]
+behavior:
+  CRITICAL: auto_fix
+  HIGH: auto_fix (iteration < 2) else document_as_debt
+  MEDIUM: document_as_debt
+  LOW: ignore
+```
+
+**Flow:**
+```
+RUN CodeRabbit → CRITICAL found?
+  YES → auto-fix (iteration < 2) → Re-run
+  NO → Document HIGH as debt, proceed
+After 2 iterations with CRITICAL → HALT, manual intervention
+```
+
+### QA Phase (@qa — QA Loop Pre-Review)
+
+```yaml
+mode: full
+max_iterations: 3
+timeout_minutes: 30
+severity_filter: [CRITICAL, HIGH]
+behavior:
+  CRITICAL: auto_fix
+  HIGH: auto_fix
+  MEDIUM: document_as_debt
+  LOW: ignore
+```
+
+**Flow:**
+1. Pre-commit review scan
+2. Self-healing loop (max 3 iterations)
+3. Manual QA analysis (architectural, traceability, NFR)
+4. Gate decision (verdict)
+
+## Severity Handling Summary
+
+| Severity | Dev Phase | QA Phase |
+|----------|-----------|----------|
+| CRITICAL | auto_fix, block if persists | auto_fix, block if persists |
+| HIGH | auto_fix, document if fails | auto_fix, document if fails |
+| MEDIUM | document_as_tech_debt | document_as_tech_debt |
+| LOW | ignore | ignore |
+
+## WSL Execution (Windows)
+
+```bash
+# Self-healing mode (automatic in dev tasks)
+wsl bash -c 'cd /mnt/c/.../oryon-core && ~/.local/bin/coderabbit --severity CRITICAL,HIGH --auto-fix'
+
+# Manual review
+wsl bash -c 'cd /mnt/c/.../oryon-core && ~/.local/bin/coderabbit -t uncommitted'
+
+# Prompt-only mode
+wsl bash -c 'cd /mnt/c/.../oryon-core && ~/.local/bin/coderabbit --prompt-only -t uncommitted'
+```
+
+## Integration Points
+
+| Workflow | Phase | Trigger | Agent |
+|----------|-------|---------|-------|
+| Story Development Cycle | 3 (Implement) | After task completion | @dev |
+| QA Loop | 1 (Review) | At review start | @qa |
+| Standalone | Any | `*coderabbit-review` command | Any |
+
+## Focus Areas by Story Type
+
+| Story Type | Primary Focus |
+|-----------|--------------|
+| Feature | Code patterns, test coverage, API design |
+| Bug Fix | Regression risk, root cause coverage |
+| Refactor | Breaking changes, interface stability |
+| Documentation | Markdown quality, reference validity |
+| Database | SQL injection, RLS coverage, migration safety |
+
+## Report Location
+
+CodeRabbit reports saved to: `docs/qa/coderabbit-reports/`
+
+## Configuration Reference
+
+Full config in `.oryon-core/core-config.yaml` under `coderabbit_integration` section.

package/.claude/rules/ids-principles.md

@@ -0,0 +1,119 @@
+---
+paths:
+  - ".oryon-core/**"
+  - "packages/**"
+  - "bin/**"
+---
+
+# IDS Principles — Detailed Rules
+
+> Status: Planned (IDS epic is Draft — principles apply as aspirational guidance)
+
+## Decision Hierarchy: REUSE > ADAPT > CREATE
+
+### REUSE (Relevance >= 90%)
+- Use existing artifact directly without modification
+- Import/reference existing entity
+- No justification needed beyond confirming match
+
+### ADAPT (Relevance 60-89%)
+- Adaptability score >= 0.6
+- Changes MUST NOT exceed 30% of original artifact
+- Changes MUST NOT break existing consumers (check usedBy list)
+- Document changes in artifact's change log
+- Update registry relationships
+- Impact analysis required
+
+### CREATE (No suitable match)
+Required justification:
+- `evaluated_patterns`: Existing entities you considered
+- `rejection_reasons`: Why each was rejected (technical reasons)
+- `new_capability`: What unique capability this provides
+- Register in Entity Registry within 24 hours
+- Establish relationships with existing entities
+- Define adaptability constraints for future reuse
+
+## Verification Gates G1-G6
+
+### G1: Epic Creation (@pm)
+- **Type:** Human-in-loop, Advisory
+- **Trigger:** `*create-epic` workflow
+- **Action:** Query registry for related entities, display potentially reusable artifacts
+- **Latency:** < 24h (async)
+- **Blocking:** No
+
+### G2: Story Creation (@sm)
+- **Type:** Human-in-loop, Advisory
+- **Trigger:** `*draft` workflow
+- **Action:** Check existing tasks/templates matching story work
+- **Latency:** < 24h (async)
+- **Blocking:** No
+
+### G3: Story Validation (@po)
+- **Type:** Human-in-loop, Soft Block
+- **Trigger:** `*validate-story-draft` workflow
+- **Action:** Verify referenced artifacts exist, detect potential duplication
+- **Latency:** < 4h (async)
+- **Blocking:** Soft (can override with reason)
+
+### G4: Dev Context (@dev)
+- **Type:** Automated, Informational
+- **Trigger:** Story assignment / `*develop` start
+- **Action:** Display matching patterns as reminder
+- **Latency:** < 2s
+- **Blocking:** NO (logged only for metrics)
+
+### G5: QA Review (@qa)
+- **Type:** Automated, Blocks Merge
+- **Trigger:** PR/merge request
+- **Action:** Check if new artifacts could have reused existing
+- **Latency:** < 30s
+- **Blocking:** YES if new entity without registry entry or justification
+
+### G6: CI/CD (@devops)
+- **Type:** Automated, Blocks Merge
+- **Trigger:** CI pipeline
+- **Action:** Registry integrity check + sync
+- **Latency:** < 60s
+- **Blocking:** YES on CRITICAL, WARN on MEDIUM/LOW
+
+## Override Policy
+
+**Command:** `--override-ids --override-reason "explanation"`
+
+**Permitted when:**
+- Time-critical fix requires immediate creation
+- Adaptation would introduce unacceptable risk
+- Existing artifact is deprecated/frozen
+
+**Requirements:**
+- Logged for audit trail
+- Reviewed within 7 days
+- Include override reason in gate verification log
+
+## Graceful Degradation
+
+All gates implement circuit breaker:
+- **Timeout:** 2s default
+- **On timeout:** warn-and-proceed
+- **On error:** log-and-proceed
+- **Key principle:** Development NEVER blocked by IDS failures
+
+```yaml
+circuit_breaker:
+  failure_threshold: 5
+  success_threshold: 3
+  reset_timeout_ms: 60000
+```
+
+## Article IV-A: Incremental Development (Constitution Amendment)
+
+**Severity:** MUST
+
+**Four Core Rules:**
+1. **Registry Consultation Required** — Query before creating
+2. **Decision Hierarchy** — REUSE > ADAPT > CREATE strictly
+3. **Adaptation Limits** — Changes < 30%, don't break consumers
+4. **Creation Requirements** — Full justification, register within 24h
+
+**Reference:** `docs/stories/epics/epic-ids-incremental-development/`