kenaz 0.0.0-stage → 0.3.2

package/core/.rule/general/memory-source-priority.yaml

@@ -0,0 +1,207 @@
+# .rule/general/memory-source-priority.yaml
+# Memory Source Priority and Recall Trigger Rules (TASK_1077)
+#
+# Formalizes the deterministic priority ordering and mandatory trigger points
+# for specialist memory recall. Prevents the "last-source-wins" silent failure
+# mode where overlapping claims from different memory layers are resolved by
+# load order rather than evidence quality.
+#
+# Priority: This rule applies to all specialists (Ansuz, Amelia, Huginn)
+#           that use the memory stack (Synapse + Hippocampus + Handoff).
+# Conflicts: This rule supersedes ad-hoc recall decisions in phase files.
+#            Phase files may define WHEN to recall; this file defines
+#            HOW to arbitrate when sources disagree.
+
+_meta:
+  category: "general"
+  priority: 1
+  applies_to:
+    - "ai_agent"
+    - "ansuz"
+    - "amelia"
+    - "huginn"
+  last_updated: "2026-04-11"
+  created_by: "TASK_1077 — Memory source priority and trigger map"
+  contract_file: ".kenaz/specialist/memory_source_priority.yaml"
+  trigger_map: ".specialist/tools/MEMORY_RECALL_TRIGGERS.md"
+
+rules:
+
+  # =============================================================================
+  # MSP-001: Priority Ordering is Mandatory
+  # =============================================================================
+  - id: "MSP-001"
+    title: "Memory source priority ordering must be applied at every conflict"
+    description: |
+      When two or more recalled items address the same topic (symbol, file, or
+      decision), the agent MUST resolve the conflict using the priority order
+      defined in `.kenaz/specialist/memory_source_priority.yaml`.
+
+      Priority order (high → low):
+        100  user_session_context     (current conversation — beats all)
+         90  verified_decision_rune   (shipped architectural commitments)
+         80  session_handoff          (uncommitted work from prior session)
+         70  self_model_lesson        (identity-layer learning)
+         60  risk_or_fix_rune         (active risk warnings and fixes)
+         50  sigil                    (architectural patterns, general)
+         40  insight_or_pattern_rune  (observations)
+         30  episode                  (raw narrative)
+         20  summary_or_ash_rune      (distilled principles)
+         10  lesson_guard             (advisory checklist, already surfaced by phase-gate)
+
+      Silent "last source wins" is a violation of this rule.
+    severity: "must"
+    rationale: |
+      Without explicit ordering, the agent silently prefers whichever source
+      happened to load last. This produces non-deterministic decisions that
+      cannot be reviewed or debugged. Deterministic ordering makes
+      disagreements visible and auditable.
+    test: |
+      Given two recalled items on the same topic, can the agent name the winning
+      source, its priority_rank, and the conflict_mode applied?
+      YES → compliant. NO → violation.
+
+  # =============================================================================
+  # MSP-002: Conflict Mode Must Be Honoured
+  # =============================================================================
+  - id: "MSP-002"
+    title: "strict vs advisory conflict modes must be applied as specified"
+    description: |
+      Each source type has a conflict_mode in memory_source_priority.yaml:
+        - strict:    highest-priority item wins; competing view hidden from agent
+                     but logged with conflict_with: <winner_id>
+        - advisory:  highest-priority item wins; competing view surfaced to agent
+                     labelled as "competing view (rank: N)"
+
+      Agents must NOT:
+        - apply advisory mode to a strict-mode source
+        - apply strict mode when the source specifies advisory
+        - silently ignore either the winner or the loser
+
+      Overriding a strict-mode winner requires an explicit user statement in the
+      current session (user_session_context, rank 100).
+    severity: "must"
+    rationale: |
+      Strict mode exists precisely for risk/fix runes: an agent that surfaces a
+      risk warning as a "competing view" invites rationalizing it away. Advisory
+      mode exists for cases where nuance matters more than uniformity.
+    test: |
+      When a risk_or_fix_rune (strict) conflicts with an episode (advisory),
+      does the agent follow the rune without showing the episode as an option?
+      YES (unless user overrides) → compliant.
+
+  # =============================================================================
+  # MSP-003: Required Recall Triggers Must Fire
+  # =============================================================================
+  - id: "MSP-003"
+    title: "Required recall triggers must execute at their specified phase boundary"
+    description: |
+      The following triggers are non-optional; skipping them requires an explicit
+      documented reason (analogous to CANARY_CHECK — "SKIP — reason"):
+
+      Phase 0 (Boot):
+        - cortex_recall(type=ash, limit=5) → load ash runes
+        - synapse_sigils(projectPath) → load sigils
+        - Read ansuz_self_model.json → load self_model_lesson
+
+      Phase 1 (Requirements):
+        - synapse_recall(query=task_title+scope_keywords) → check rune history
+
+      Before editing a non-trivial symbol (> 5 lines, non-config):
+        - synapse_recall(symbol_name) → check risk/fix runes; kenaz_lsp_references(symbol_name) → check blast radius
+
+      Phase 3 (Decomposition):
+        - kenaz_lsp_references on the key scope symbols → check blast radius; synapse_recall(scope keywords) → check risk runes
+
+      Phase 9 (Verification):
+        - synapse_recall on touched symbols → check risk runes post-edit
+
+      Phase-gate blocked exit:
+        - lesson_guards auto-surfaced by phase-gate.js (agent does NOT need to call manually)
+
+      Optional (conditional):
+        - session_handoff: load only if a per-session slot exists under
+          .kenaz/specialist/handoffs/ (latest generated_at wins; resolved via
+          handoff-resolver readLatestHandoff — the legacy singular
+          ansuz_session_handoff.json is retired read-only fallback, M3/TASK_1760)
+          AND its generated_at is within ttl_hours: 72
+        - episode: load at Phase 0 if hippocampus_episode_recall returns ≥ 1 result;
+          at Phase 1 if relevant task_id appears in Phase 0 summary
+    severity: "must"
+    rationale: |
+      FAIL-009 records cases where the pre-edit impact check was skipped under time pressure
+      and caused regressions. Required triggers exist because their decision-point
+      value is unconditional — the question is not "might this matter?" but "this
+      always matters."
+    test: |
+      Did the agent fire cortex_recall(ash) and synapse_sigils during Phase 0?
+      Did it call synapse_recall (and check kenaz_lsp_references) before modifying a non-trivial symbol?
+      YES → compliant. NO → violation (must state SKIP reason if consciously skipping).
+
+  # =============================================================================
+  # MSP-004: TTL Violations Must Be Caught at Load Time
+  # =============================================================================
+  - id: "MSP-004"
+    title: "Expired memory items must not be used as primary evidence"
+    description: |
+      Each source type has a TTL (time-to-live):
+        user_session_context:    24h
+        verified_decision_rune:  180 days
+        session_handoff:          72h
+        self_model_lesson:       365 days
+        risk_or_fix_rune:         90 days
+        sigil:                   180 days
+        insight_or_pattern_rune:  90 days
+        episode:                  30 days
+        summary_or_ash_rune:      45 days
+        lesson_guard:            180 days
+
+      An item past its TTL:
+        - MAY be shown to the agent as background context
+        - MUST NOT be treated as primary evidence for a current decision
+        - MUST be labelled as "expired (N days old)" when shown
+
+      TTL expiration does NOT mean the information is wrong — it means
+      the information has not been refreshed and may be stale relative
+      to current code. The agent should re-verify before acting on it.
+    severity: "should"
+    rationale: |
+      A 90-day-old risk rune may have been resolved by a later fix. A 72h+
+      handoff describes a session context that is no longer the active cycle.
+      TTLs prevent stale guidance from silently overriding fresh evidence.
+    test: |
+      Does the agent check freshness_seconds against source TTL before
+      treating a recalled item as primary evidence?
+      YES → compliant. Stale item used without staleness label → violation.
+
+  # =============================================================================
+  # MSP-005: Conflict Audit Trail Must Exist
+  # =============================================================================
+  - id: "MSP-005"
+    title: "Conflict arbitration outcomes must be traceable"
+    description: |
+      When a conflict is resolved (winner selected over loser), the losing
+      item must be recorded in a way that can be audited later:
+        - In strict mode: log conflict_with: <winner_source_id> to the event log
+        - In advisory mode: surface the competing view in agent output so the
+          user can observe that a conflict existed and how it was resolved
+
+      Silent conflict resolution — where the agent picks a winner and shows
+      nothing about the loser — is a violation of this rule, even in strict mode
+      (the log entry must still exist).
+
+      Instrumentation: .specialist/tools/memory-action-log.js (TASK_1072)
+      exposes `recordConflict()` for this purpose. If unavailable, a plain
+      in-response note is sufficient — the key is that the conflict is visible.
+    severity: "should"
+    rationale: |
+      Without an audit trail, post-hoc review cannot determine whether a bad
+      decision was caused by wrong priority ordering, wrong source data, or
+      correct reasoning from correct data. The audit trail makes the arbitration
+      falsifiable.
+    test: |
+      After a conflict resolution event, can a reviewer identify:
+        (a) which sources conflicted?
+        (b) which won and why (priority_rank + conflict_mode)?
+        (c) what happened to the loser?
+      ALL YES → compliant. Any NO → violation.

package/core/.rule/general/pipeline.yaml

@@ -0,0 +1,246 @@
+# Pipeline 系統規則
+# 定義任務管理、佇列、統計的標準規範
+
+_meta:
+  version: "1.0.0"
+  category: "general"
+  last_updated: "2026-02-05"
+  description: |
+    Pipeline 系統的核心規則，確保任務管理的一致性和可追溯性。
+
+# ============================================================
+# PPL-001: 統計數據必須累積制
+# ============================================================
+PPL-001:
+  title: "統計數據必須採用累積制"
+  severity: must
+  applies_to: [ai_agent, human_developer]
+
+  description: |
+    TASK_QUEUE.json 的統計數據必須反映**整體專案進度**，
+    而非僅當前佇列狀態。
+
+  rationale: |
+    - Agent 需要了解專案的整體進度（已完成多少任務）
+    - 只顯示當前佇列會誤導 Agent 認為專案剛開始
+    - 累積統計幫助評估專案成熟度和風險
+
+  rules:
+    - id: "PPL-001.1"
+      rule: "`total` 必須包含所有任務（佇列 + 已完成）"
+      example: "total = 52 (2 pending + 50 completed)"
+
+    - id: "PPL-001.2"
+      rule: "`completed` 必須從 .memory/COMPLETED_TASKS.json 計算"
+      example: "completed = 50"
+
+    - id: "PPL-001.3"
+      rule: "`pending/in_progress/blocked` 反映當前佇列狀態"
+      example: "pending = 2 (只計算 tasks 陣列中的 pending 任務)"
+
+    - id: "PPL-001.4"
+      rule: "metadata 必須包含 `completed_archive` 指向封存位置"
+      example: 'metadata.completed_archive = ".memory/COMPLETED_TASKS.json"'
+
+  correct_example: |
+    {
+      "statistics": {
+        "total": 52,
+        "pending": 2,
+        "in_progress": 0,
+        "blocked": 0,
+        "completed": 50,
+        "cancelled": 0
+      },
+      "metadata": {
+        "completed_archive": ".memory/COMPLETED_TASKS.json"
+      }
+    }
+
+  incorrect_example: |
+    {
+      "statistics": {
+        "total": 2,        // ❌ 只計算當前佇列
+        "completed": 0     // ❌ 忽略已完成任務
+      }
+    }
+
+# ============================================================
+# PPL-002: 已完成任務必須封存
+# ============================================================
+PPL-002:
+  title: "已完成任務必須封存到 .memory/"
+  severity: must
+  applies_to: [ai_agent, human_developer]
+
+  description: |
+    TASK_QUEUE.json 只保留 active 任務（pending/in_progress/blocked），
+    已完成任務必須移到 .memory/COMPLETED_TASKS.json。
+
+  rationale: |
+    - 保持 TASK_QUEUE.json 精簡，提升載入和解析效率
+    - 已完成任務的元數據仍需保留以供查詢和統計
+    - 避免 Scheduler 重複載入已完成任務
+
+  rules:
+    - id: "PPL-002.1"
+      rule: "TASK_QUEUE.json 的 tasks 陣列只包含 active 任務"
+      definition: "active = pending | in_progress | blocked"
+
+    - id: "PPL-002.2"
+      rule: "completed 任務移動流程"
+      steps:
+        - "從 dev/pipeline/tasks/ 移到 dev/pipeline/completed/"
+        - "從 TASK_QUEUE.json tasks 陣列移除"
+        - "新增到 .memory/COMPLETED_TASKS.json"
+        - "更新 statistics.completed 計數"
+
+    - id: "PPL-002.3"
+      rule: "定期執行清理腳本"
+      frequency: "當 TASK_QUEUE.json 中有 completed 任務時"
+
+  cleanup_script: |
+    const data = JSON.parse(fs.readFileSync('dev/pipeline/TASK_QUEUE.json', 'utf8'));
+    const completed = JSON.parse(fs.readFileSync('.memory/COMPLETED_TASKS.json', 'utf8'));
+
+    // 只保留 active 任務
+    data.tasks = data.tasks.filter(t =>
+      ['pending', 'in_progress', 'blocked'].includes(t.status)
+    );
+
+    // 更新統計
+    data.statistics = {
+      total: data.tasks.length + completed.length,
+      pending: data.tasks.filter(t => t.status === 'pending').length,
+      in_progress: data.tasks.filter(t => t.status === 'in_progress').length,
+      blocked: data.tasks.filter(t => t.status === 'blocked').length,
+      completed: completed.length,
+      cancelled: 0
+    };
+
+# ============================================================
+# PPL-003: COMPLETED_TASKS.json 格式規範
+# ============================================================
+PPL-003:
+  title: "已完成任務封存格式規範"
+  severity: must
+  applies_to: [ai_agent, human_developer]
+
+  description: |
+    .memory/COMPLETED_TASKS.json 必須包含足夠的元數據，
+    以便查詢和分析歷史任務。
+
+  required_fields:
+    - field: "id"
+      type: "string"
+      example: "TASK_075"
+
+    - field: "title"
+      type: "string"
+      example: "Agents Page 組件化重構"
+
+    - field: "priority"
+      type: "string"
+      example: "P1"
+
+    - field: "agent_type"
+      type: "string"
+      example: "frontend"
+
+    - field: "source"
+      type: "string"
+      example: "User Request - Code Architecture"
+
+    - field: "estimated_hours"
+      type: "number"
+      example: 3
+
+    - field: "complexity"
+      type: "string"
+      example: "medium"
+
+    - field: "source_file"
+      type: "string"
+      example: "TASK_075_agents_page_component_refactor.yaml"
+
+  optional_fields:
+    - "completed_at"
+    - "description"
+    - "scope_paths"
+
+  format_example: |
+    [
+      {
+        "id": "TASK_075",
+        "title": "Agents Page 組件化重構",
+        "priority": "P1",
+        "agent_type": "frontend",
+        "source": "User Request",
+        "estimated_hours": 3,
+        "complexity": "medium",
+        "source_file": "TASK_075_agents_page_component_refactor.yaml"
+      }
+    ]
+
+# ============================================================
+# PPL-004: Scheduler 同步規則
+# ============================================================
+PPL-004:
+  title: "Scheduler 只從 tasks/ 同步"
+  severity: must
+  applies_to: [ai_agent]
+
+  description: |
+    Multi-Agent Scheduler 同步任務時，只應從 dev/pipeline/tasks/
+    讀取，不應從 completed/ 同步歷史任務。
+
+  rationale: |
+    - 避免將已完成任務重新加入佇列
+    - 防止統計數據污染
+    - 保持 TASK_QUEUE.json 精簡
+
+  rules:
+    - id: "PPL-004.1"
+      rule: "Scheduler 啟動時只掃描 tasks/ 目錄"
+      path: "dev/pipeline/tasks/*.yaml"
+
+    - id: "PPL-004.2"
+      rule: "忽略 completed/ 目錄"
+      path: "dev/pipeline/completed/*.yaml"
+
+    - id: "PPL-004.3"
+      rule: "任務完成後立即移動文件"
+      steps:
+        - "mv dev/pipeline/tasks/TASK_XXX.yaml dev/pipeline/completed/"
+        - "從 TASK_QUEUE.json 移除該任務"
+
+# ============================================================
+# PPL-005: PROGRESS.md 精簡原則
+# ============================================================
+PPL-005:
+  title: "PROGRESS.md 只保留必要資訊"
+  severity: should
+  applies_to: [ai_agent, human_developer]
+
+  description: |
+    PROGRESS.md 應簡潔明瞭，避免冗長的歷史記錄。
+    詳細歷史資料應查詢 .memory/COMPLETED_TASKS.json。
+
+  required_sections:
+    - section: "Statistics"
+      content: "累積統計數據（含完成率）"
+
+    - section: "Current Queue"
+      content: "當前待處理和執行中任務"
+
+    - section: "Recent Activity"
+      content: "最近 5-10 條活動記錄"
+
+    - section: "Notes"
+      content: "封存位置、文件結構說明"
+
+  max_length: "100 lines"
+
+  deprecated_sections:
+    - "完整歷史任務列表（改用 .memory/COMPLETED_TASKS.json）"
+    - "詳細依賴圖（過於複雜，改用任務文件內的 dependencies）"

package/core/.rule/general/principles.yaml

@@ -0,0 +1,77 @@
+# .rule/general/principles.yaml
+# 核心原則 - 所有規則的基礎
+
+_meta:
+  category: "general"
+  priority: 0  # 最高優先
+  applies_to:
+    - "ai_agent"
+    - "human_developer"
+  last_updated: "2026-02-05"
+
+rules:
+  - id: "GEN-001"
+    title: "規格優先原則"
+    description: |
+      所有開發工作必須以 dev/PRODUCT_SPEC.md 為依據。
+      不可自行發揮或添加規格外的功能。
+    severity: "must"
+    rationale: "確保產品方向一致，避免 scope creep"
+
+  - id: "GEN-002"
+    title: "簡單優於複雜"
+    description: |
+      選擇最簡單的解決方案。
+      不過度工程化，不預先優化。
+    severity: "should"
+    rationale: "降低維護成本，提高可讀性"
+
+  - id: "GEN-003"
+    title: "明確優於隱晦"
+    description: |
+      程式碼意圖要清晰明確。
+      變數命名要能自我解釋。
+      避免魔術數字和隱藏邏輯。
+    severity: "should"
+    rationale: "提高程式碼可讀性和可維護性"
+
+  - id: "GEN-004"
+    title: "一致性原則"
+    description: |
+      遵循專案既有的風格和模式。
+      新程式碼要與現有程式碼風格一致。
+    severity: "must"
+    rationale: "降低認知負擔，提高團隊協作效率"
+
+  - id: "GEN-005"
+    title: "漸進式改進"
+    description: |
+      大改動拆成小步驟。
+      每次提交都應該是可運行的狀態。
+    severity: "should"
+    rationale: "降低風險，便於追蹤和回滾"
+
+  - id: "GEN-010"
+    title: "證據優先原則"
+    description: |
+      當證據與任何人（用戶、規則、自身假設）矛盾時，跟隨證據。
+      收到糾正時，先檢視自己行為的原因和證據，再決定是否調整。
+      規則是經驗的編碼，不是思考的替代品。當規則與當前情境的證據衝突時，
+      以證據為準，並記錄為什麼規則在此情境不適用。
+    severity: "must"
+    rationale: "規則累積會導致服從取代思考。第一性原理 + 批判性思維是認知系統的基礎。"
+
+  - id: "GEN-006"
+    title: "開發範圍限定 app/ 資料夾"
+    description: |
+      所有開發與設計相關的檔案，只能放在 app/ 資料夾底下。
+      包括：前端程式碼、樣式、靜態資源、設計檔案。
+    severity: "must"
+    rationale: "統一專案結構，避免檔案散落各處"
+    allowed_paths:
+      - "app/"
+    exceptions:
+      - "dev/ - Pipeline 和開發工具"
+      - ".rule/ - 規則定義"
+      - ".claude/ - Agent 定義"
+      - "根目錄設定檔（package.json、tsconfig.json 等）"