arreio 1.0.0-dev.1

package/skills/plan/references/high-risk-detection.md

@@ -0,0 +1,111 @@
+---
+title: High-Risk Area Detection
+description: "Scan the task description and scoped context for high-risk keywords across six areas: Security, Payments, APIs, Migrations, Complex Logic, and Infrastructure."
+type: reference
+version: 1.1
+timestamp: "2026-08-07"
+---
+
+# High-Risk Area Detection
+
+This file documents the keyword-based detection system for identifying high-risk areas during the research phase. It includes the risk keyword table, area definitions, and the heuristic for mapping detected areas to risk levels.
+
+## Risk Keywords Table
+
+Scan the task description and scoped context for these keywords to identify high-risk areas:
+
+| Area           | Keywords                                                                                               | Risk Category |
+| -------------- | ------------------------------------------------------------------------------------------------------ | ------------- |
+| Security       | auth, jwt, oauth, session, encryption, ssl, tls, certificate, permission, rbac, acl, audit, credential | CRITICAL      |
+| Payments       | payment, billing, stripe, checkout, invoice, refund, transaction, subscription, pci, card              | CRITICAL      |
+| APIs           | api, rest, graphql, endpoint, integration, webhook, rate-limit, versioning                             | HIGH          |
+| Migrations     | migration, upgrade, data, schema, version, backward-compat, deprecation                                | HIGH          |
+| Complex Logic  | algorithm, analysis, processing, computation, ml, analytics, optimization                              | HIGH          |
+| Infrastructure | deploy, kubernetes, docker, scaling, network, cdn, load-balance, failover, disaster-recovery           | HIGH          |
+
+## Area Definitions
+
+### Security (CRITICAL)
+
+Involves authentication, authorization, session management, encryption, or credential handling.
+
+- **Examples:** JWT implementation, OAuth integration, session cookies, SSL certificates, password hashing
+- **Why critical:** Security breaches can compromise the entire system
+- **Escalation:** Always recommend external research unless extensive local patterns exist
+
+### Payments (CRITICAL)
+
+Involves payment processing, billing, invoicing, or financial transactions.
+
+- **Examples:** Stripe integration, checkout flow, refund logic, subscription management
+- **Why critical:** Payment systems have strict compliance requirements (PCI DSS); errors cause financial loss
+- **Escalation:** Always recommend external research; verify compliance requirements
+
+### APIs (HIGH)
+
+Involves REST, GraphQL, or other API design and integration.
+
+- **Examples:** RESTful endpoint design, GraphQL schema, third-party API integration, versioning
+- **Why high:** Poor API design can create compatibility issues; integration errors block downstream work
+- **Escalation:** Recommend external research if designing new APIs or integrating unfamiliar third-party services
+
+### Migrations (HIGH)
+
+Involves schema changes, version upgrades, or data migration with impact on production.
+
+- **Examples:** Database schema migration, framework upgrade, data format change, breaking API changes
+- **Why high:** Migrations can cause data loss or downtime if not carefully planned
+- **Escalation:** Recommend external research for migrations without local patterns
+
+### Complex Logic (HIGH)
+
+Involves algorithms, machine learning, complex computations, or analysis.
+
+- **Examples:** Sorting/searching algorithms, ML model selection, financial calculations, performance-critical code
+- **Why high:** Bugs in complex logic can cascade; optimization mistakes are hard to reverse
+- **Escalation:** Recommend external research if no local examples exist
+
+### Infrastructure (HIGH)
+
+Involves deployment, container orchestration, scaling, or network architecture.
+
+- **Examples:** Kubernetes deployment, Docker setup, load balancing, CDN configuration, disaster recovery
+- **Why high:** Infrastructure mistakes can cause downtime or security vulnerabilities
+- **Escalation:** Recommend external research for infrastructure patterns not yet documented
+
+## Risk Level Determination
+
+After identifying which areas the task touches, assign a risk level using this logic:
+
+```
+risk_level = determine_risk(areas_detected, high_risk_count)
+
+if any_area_is_security_or_payments:
+  risk_level = CRITICAL
+  reason = "Critical area detected: " + critical_area
+elif high_risk_count >= 2:
+  risk_level = HIGH
+  reason = "Multiple high-risk areas: " + areas_detected.join(", ")
+elif any_area_is_api_migration_logic_infra:
+  risk_level = MEDIUM
+  reason = "High-risk area detected: " + area_name
+else:
+  risk_level = LOW
+  reason = "No high-risk areas detected"
+```
+
+## Mapping to Research Decision
+
+> **Authoritative.** The Research phase (Step 3) looks up its external-research decision directly in the matrix below, using the detected **risk level** and the **patterns found count**. Do not apply a separate formula — this matrix is the single source of truth.
+
+Use risk level to determine if external research should be recommended:
+
+| Risk Level | Patterns Found | Decision           | Notes                                        |
+| ---------- | -------------- | ------------------ | -------------------------------------------- |
+| CRITICAL   | 0-2            | Recommend external | Insufficient local patterns; must research   |
+| CRITICAL   | 3+             | Recommend external | Critical area; external research required    |
+| HIGH       | 0-2            | Recommend external | Insufficient local patterns; must research   |
+| HIGH       | 3+             | Optional external  | Strong local patterns; external optional     |
+| MEDIUM     | 0-1            | Recommend external | Limited local examples; external recommended |
+| MEDIUM     | 2+             | Optional external  | Adequate local patterns; external optional   |
+| LOW        | any            | Skip external      | Low risk; no external research needed        |

package/skills/plan/references/id-generation.md

@@ -0,0 +1,55 @@
+---
+title: Artifact ID Generation
+description: Reference for Scope, Research, Design, and Generate phases. Defines the daily-counter algorithm for unique artifact IDs, the recycle-on-edit rule, and the plan-id counting skip-list.
+type: reference
+version: 1.0
+timestamp: "2026-08-07"
+---
+
+# Artifact ID Generation
+
+Shared ID algorithm for the `scope`, `research`, `design`, and `generate` phases. Each phase assigns exactly one ID per newly produced artifact; the ID is reused (never re-incremented) when the user picks **Edit & Retry** at the phase confirmation.
+
+## ID Format by Phase
+
+| Phase    | ID format                            | Saved to                         |
+| -------- | ----------------------------------- | -------------------------------- |
+| Scope    | `YYYY-MM-DD-NNN-scope`              | `docs/plans/.scope/<id>.md`      |
+| Research | `YYYY-MM-DD-NNN-research`            | `docs/plans/.research/<id>.md`  |
+| Design   | `YYYY-MM-DD-NNN-design`             | `docs/plans/.design/<id>.md`     |
+| Generate | `YYYY-MM-DD-NNN` (= `plan-id`)       | `docs/plans/<id>-<kebab-name>.md`|
+
+`<kebab-name>` is the plan title in lowercase-hyphen form (no stopwords).
+
+## Algorithm (new artifact)
+
+```
+1. Get the current date in UTC (e.g., 2026-07-03)
+2. List existing files for today in the phase's save directory
+   - scope   -> docs/plans/.scope/   matching YYYY-MM-DD-*.md
+   - research-> docs/plans/.research/matching YYYY-MM-DD-*.md
+   - design  -> docs/plans/.design/  matching YYYY-MM-DD-*.md
+   - generate-> docs/plans/           matching YYYY-MM-DD-*.md
+                EXCLUDE the .scope/, .research/, .design/ subdirectories
+3. NNN = (count + 1), zero-padded to 3 digits (001, 002, ..., 010, ...)
+4. id = "<date>-<NNN>-<phase>"  (or "<date>-<NNN>" for plan-id)
+```
+
+If two scope artifacts were created today, the next one is `2026-07-03-003-scope`. Counters are independent per phase; each phase counts only its own files.
+
+## Recycle on Edit & Retry
+
+When the user picks **Edit & Retry** at the phase confirmation, **reuse the original ID** and overwrite the existing artifact file. Do **not** increment the counter. This keeps IDs stable across iterations and prevents orphaned artifacts.
+
+## Error Handling
+
+| Trigger                                         | Action                                       |
+| ----------------------------------------------- | -------------------------------------------- |
+| Phase save directory does not exist              | Create it; treat count as 0; start from 001  |
+| Directory exists but no files match today's date | Start counter at 001                          |
+| Write permission denied                         | Log error; ask the user; retry once          |
+
+## Notes
+
+- IDs are reused for cross-phase chaining: `research-id` carries the `scope-id`, `design-id` carries both, and `plan-id` carries `scope-id`, `research-id`, and `design-id` (see [error-handling.md](error-handling.md) "Cross-Phase Consistency Checks").
+- Counter collisions are impossible within a date because each phase writes to its own directory and recomputes the count from the directory listing.

package/skills/plan/references/interaction-mode-propagation.md

@@ -0,0 +1,75 @@
+---
+title: Interaction Mode Propagation
+description: Reference for how `interactionMode` propagates through the Plan pipeline (Scope → Research → Design → Generate → Tasks). Set at Orchestrator; each phase reads and applies mode-specific behavior.
+type: reference
+version: 1.1
+timestamp: "2026-08-07"
+---
+
+# Interaction Mode Propagation
+
+Reference for how `interactionMode` propagates through the Plan pipeline (Scope → Research → Design → Generate → Tasks). Set at Orchestrator; each phase reads and applies mode-specific behavior.
+
+## Modes
+
+| Mode          | Behavior                                              | Use Case                             |
+| ------------- | ----------------------------------------------------- | ------------------------------------ |
+| **Detailed**  | Pause at each phase; show artifacts; require approval | Complex work, unfamiliar codebases   |
+| **Smart**     | Auto-proceed; pause only on HIGH-risk flags           | Familiar codebases with guardrails   |
+| **Autopilot** | Run all phases auto (except Tasks, which always asks) | Straightforward work, time-sensitive |
+
+## Phase Behavior by Mode
+
+| Phase        | Detailed                                         | Smart                                                                                                  | Autopilot                         |
+| ------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | --------------------------------- |
+| **Scope**    | Present artifact; ask Proceed/Edit/Abort         | Auto-proceed; pause if 3+ learning gaps, non-software domain, or conflicting requirements              | Auto-proceed                      |
+| **Research** | Show findings; ask Proceed/Edit/Abort           | Auto-proceed; pause if HIGH/CRITICAL risk with <3 patterns, or zero patterns found                    | Auto-proceed                      |
+| **Design**   | Show units; ask Proceed/Edit/Abort              | Auto-proceed; pause if VERY_HIGH complexity, HIGH risk + <3 patterns, 3+ scope gaps, or Novelty=3      | Auto-proceed                      |
+| **Generate** | Show plan; ask Proceed/Edit/Skip/Abort          | Auto-proceed; pause if tier=Deep, tier preference conflicts with risk floor, or CRITICAL risk          | Auto-proceed                      |
+| **Tasks**    | Ask Create/Review/No (full file content shown)  | Ask Create/Review/No (summary shown)                                                                   | Ask Create/Review/No (always asks) |
+
+**Smart mode pauses only on each phase's documented triggers above** (the canonical list lives in each module's confirmation step; this table is a summary).
+
+## Artifact Schema
+
+All phase artifacts (Scope 1-4) include:
+
+```yaml
+type: scope | research | design | plan
+scope-id: 2026-07-02-001-scope
+interactionMode: detailed | smart | autopilot # Passed from previous phase
+status: pending | complete | failed
+```
+
+## Implementation
+
+**Each phase must:**
+
+1. Read `interactionMode` from incoming artifact (or context for Scope)
+2. Apply mode-specific behavior per table above
+3. Include `interactionMode` in output artifact
+
+**Phase 5 (Tasks):** Always ask user about task slicing, even in Autopilot mode.
+
+## Example
+
+**SMART mode on complex codebase task:**
+
+- Scope detects 3 learning gaps → pauses (HIGH-risk)
+- User approves → Research runs
+- Research detects unfamiliar framework → pauses (HIGH-risk)
+- User approves → Design runs
+- Design complexity MEDIUM → auto-proceeds
+- Generate renders → auto-proceeds
+- Tasks asks user → user chooses yes
+
+**Result:** Paused only for critical decisions; faster than Detailed with safety guardrails.
+
+## Error Handling
+
+| Scenario                    | Recovery                              |
+| --------------------------- | ------------------------------------- |
+| Mode missing                | Default to "smart"; log warning       |
+| Invalid mode value          | Reject; re-prompt Orchestrator        |
+| Artifact missing mode field | Assume "smart"; log warning; continue |
+| Timeout/connection lost     | Pause; ask user to retry or abort     |

package/skills/plan/references/learnings-gate-logic.md

@@ -0,0 +1,93 @@
+---
+title: Learnings Gate Logic
+description: Reference for Scope Phase Step 4. Defines keyword matching, relevance scoring, gap identification, and inclusion criteria.
+type: reference
+version: 1.1
+timestamp: "2026-08-07"
+---
+
+# Learnings Gate Logic
+
+Reference for **Scope Phase Step 4**. Defines keyword matching, relevance scoring, gap identification, and inclusion criteria.
+
+## Algorithm
+
+1. **Extract keywords** — Tokenize task description/intended behavior (remove stop words, normalize to lowercase, keep domain terms)
+2. **Match learnings** — Exact match: keyword in learning title/summary; Fuzzy match: Levenshtein ≤2 for variants (e.g., "auth" vs "authentication")
+3. **Score relevance** — HIGH/MEDIUM/LOW based on domain match and applicability
+4. **Filter** — Include only HIGH/MEDIUM in Scoped Context
+5. **Identify gaps** — For each task domain not covered by HIGH/MEDIUM learnings, document gap
+
+**Example:** Task "Add WebSocket collaboration"
+
+- Extract: `websocket`, `collaboration`, `synchronization`
+- Match: `websocket-best-practices.md` (exact), `concurrent-edits.md` (fuzzy)
+- Skip: `ci-cd-pipelines.md` (no match)
+
+## Relevance Scoring
+
+| Level      | Criteria                                                                                                | Example                                                                                |
+| ---------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| **HIGH**   | Exact domain match + DIRECT/CRITICAL applicability. Learning directly applies to explicit task goal.    | Task: "Migrate REST→gRPC" + Learning: `grpc-performance-tuning.md` (DIRECT) → HIGH     |
+| **MEDIUM** | Related domain + RECOMMENDED/CONTEXTUAL applicability. Learning provides context or potential solution. | Task: "Reduce API latency" + Learning: `caching-strategies.md` (RECOMMENDED) → MEDIUM  |
+| **LOW**    | Distant domain or HISTORICAL/INFORMATIONAL. Exclude from scope.                                         | Task: "Add dark mode UI" + Learning: `backend-load-balancing.md` (unrelated) → EXCLUDE |
+
+**Inclusion:** Add HIGH/MEDIUM learnings to `Related Learnings` in Scoped Context. Exclude LOW.
+
+## Gap Identification
+
+A **learning gap** is a task domain with no HIGH/MEDIUM relevance learning.
+
+**Algorithm:**
+
+1. Extract task domains (from description, goals, constraints)
+2. For each domain: check if HIGH/MEDIUM learning exists
+3. If not, document gap with: name, domain, relevance to task, suggested action
+
+**Format:**
+
+```yaml
+- gap_name: "[Domain] — [what's missing]"
+  domain: [primary domain]
+  relevance: why this matters for the task
+  suggested_action: "Research external resource" or "Document post-implementation"
+```
+
+**Example:** Task "Implement multi-user undo/redo"
+
+- Domains: `undo-redo`, `collaboration`, `conflict-resolution`
+- Learning found: `ot-basics.md` (covers conflicts)
+- Gap: "Undo/Redo Coordination — No learning on undo behavior in collaborative environments"
+  → Suggested action: "Research Google Docs model; document post-implementation"
+
+## Learning Entry Format (index.md)
+
+Learnings must include:
+
+```yaml
+filename: docs/learn/xxx.md
+domain: [primary domain]
+tags: [related_domain_1, related_domain_2]
+applicability: DIRECT | RECOMMENDED | CONTEXTUAL | HISTORICAL | INFORMATIONAL
+summary: [1-2 sentence summary]
+```
+
+## Scope Phase Integration
+
+**Scope Step 4** executes:
+
+1. Extract keywords from task + intended behavior
+2. Keyword match against `docs/learn/index.md` (exact + fuzzy)
+3. Score matches: HIGH/MEDIUM/LOW per table above
+4. Filter: keep HIGH/MEDIUM only
+5. Identify gaps: domains not covered
+6. Output: `Related Learnings` + `Learning Gaps` in Scoped Context
+
+## Error Handling
+
+| Error            | Recovery                             |
+| ---------------- | ------------------------------------ |
+| index.md missing | Skip; set empty learnings & gaps     |
+| Malformed entry  | Log warning; skip entry; continue    |
+| No matches       | Set `Related Learnings: []`; proceed |
+| >10 matches      | Trim to top 5-7 by relevance score   |

package/skills/plan/references/plan-tier-selection.md

@@ -0,0 +1,174 @@
+---
+title: Plan Tier Selection
+description: Reference for the Generate phase. Defines the Fast/Standard/Deep tier model, the selection algorithm that combines complexity, risk, and user preference, and the template sections each tier requires.
+type: reference
+version: 1.1
+timestamp: "2026-08-07"
+---
+
+# Plan Tier Selection
+
+This file documents the tier system used by the **Generate** phase (Phase 4) to right-size the final plan document. It defines three tiers, the selection algorithm, the template sections each tier requires, and how tier choice interacts with the interaction mode.
+
+## When to Apply
+
+Tier selection happens at the start of the Generate phase, after reading the Design Artifact (which carries the `complexity` field) and the Research Findings (which carry the `risk_level`). The chosen tier determines which sections of the [Final Plan template](templates/artifacts/final-plan.md) are rendered and how much structure the plan contains.
+
+## The Three Tiers
+
+| Tier         | Use When                                           | Length    | Sections Included                                                |
+| ------------ | -------------------------------------------------- | --------- | ---------------------------------------------------------------- |
+| **Fast**     | Trivial/low complexity, straightforward work       | 1–2 pages | Overview, High-Level Design, Units (single phase), Risks (brief) |
+| **Standard** | Medium complexity, typical feature work            | 2–4 pages | All template sections, phased units, full risk table             |
+| **Deep**     | High/very-high complexity, cross-system, high-risk | 4+ pages  | All template sections + alternatives + rollout ops + monitoring  |
+
+## Selection Algorithm
+
+```
+function select_tier(complexity, risk_level, user_preference):
+  # 1. Start from complexity-driven default
+  if complexity in [TRIVIAL, LOW]:
+    base_tier = Fast
+  elif complexity == MEDIUM:
+    base_tier = Standard
+  else:  # HIGH or VERY_HIGH
+    base_tier = Deep
+
+  # 2. Upgrade tier if risk warrants it
+  if risk_level == HIGH and base_tier == Fast:
+    base_tier = Standard
+  if risk_level == CRITICAL:
+    base_tier = Deep
+
+  # 3. Honor explicit user preference (never downgrade below risk floor)
+  if user_preference == "fast" and risk_level not in [HIGH, CRITICAL]:
+    return Fast
+  if user_preference == "deep":
+    return Deep
+  if user_preference == "standard" and risk_level != CRITICAL:
+    return Standard
+
+  return base_tier
+```
+
+### Inputs
+
+| Input             | Source                          | Values                                |
+| ----------------- | ------------------------------- | ------------------------------------- |
+| `complexity`      | Design Artifact                 | TRIVIAL, LOW, MEDIUM, HIGH, VERY_HIGH |
+| `risk_level`      | Research Findings Artifact      | LOW, MEDIUM, HIGH, CRITICAL           |
+| `user_preference` | User (asked in Generate Step 1) | `fast`, `standard`, `deep`, or `auto` |
+
+### Risk Floor
+
+The risk level sets a **minimum tier** that user preference cannot override:
+
+| Risk Level | Minimum Tier |
+| ---------- | ------------ |
+| LOW        | Fast         |
+| MEDIUM     | Fast         |
+| HIGH       | Standard     |
+| CRITICAL   | Deep         |
+
+Rationale: High/critical risk mandates enough structure to capture alternatives, rollout, and rollback — even if the user wants a short plan.
+
+## Tier Section Requirements
+
+### Fast Tier
+
+Required sections:
+
+- Overview (1–2 sentences)
+- High-Level Technical Design (one of: Mermaid, pseudo-code, or data-flow map)
+- Implementation Units (single phase, 1–3 units)
+- Risk Analysis & Mitigation (brief table, 1–2 rows)
+- Related Learnings
+
+Optional (skip if not applicable): Alternative Approaches, Operational Notes, Learning Gaps.
+
+### Standard Tier
+
+Required sections (all template sections):
+
+- Overview
+- High-Level Technical Design
+- Implementation Units (phased, 2+ phases)
+- Alternative Approaches Considered (at least 1)
+- Risk Analysis & Mitigation (full table)
+- Operational / Rollout Notes
+- Related Learnings
+- Learning Gaps
+
+### Deep Tier
+
+Required sections (all Standard sections, plus):
+
+- Alternative Approaches Considered (at least 2, with side-by-side comparison)
+- Risk Analysis & Mitigation (full table with impact ratings)
+- Operational / Rollout Notes (must include: feature flags, monitoring, data migration, rollback plan, performance baseline)
+- Explicit complexity and tier in frontmatter
+- Cross-system integration map (data-flow or sequence diagram)
+
+## Interaction Mode Behavior
+
+| Mode      | Tier Selection Behavior                                                                             |
+| --------- | --------------------------------------------------------------------------------------------------- |
+| Detailed  | Ask the user to confirm the selected tier; offer to override                                        |
+| Smart     | Auto-select; pause **only** if selected tier is Deep (or user preference conflicts with risk floor) |
+| Autopilot | Auto-select with `user_preference = auto`; never pause                                              |
+
+**Smart mode pause triggers:**
+
+- Selected tier is Deep (signals complex work worth a review)
+- User preference conflicts with risk floor (e.g., user wants Fast but risk is HIGH)
+- Research phase reported CRITICAL risk (Security or Payments)
+
+## Asking the User for Preference
+
+In Detailed mode (or when Smart mode pauses), ask the user one question:
+
+```
+Based on the design complexity (HIGH) and risk level (HIGH), I recommend the Standard tier.
+Which tier would you like for the plan?
+  - Fast: Short plan, minimal structure (1-2 pages)
+  - Standard: Full plan with phased units and risk table (2-4 pages) [Recommended]
+  - Deep: Comprehensive plan with alternatives and rollout ops (4+ pages)
+  - Auto: Let the algorithm decide (result: Standard)
+```
+
+Record the user's choice as the selected **`tier`** in the final plan frontmatter; preserve the algorithm's suggestion as **`tier_recommended`** so an override is auditable.
+
+## Worked Examples
+
+### Example 1: Low complexity, low risk
+
+- `complexity = LOW`, `risk_level = LOW`, `user_preference = auto`
+- Base tier: Fast. No risk upgrade. Auto preference → **Fast**.
+
+### Example 2: Medium complexity, high risk, user wants fast
+
+- `complexity = MEDIUM`, `risk_level = HIGH`, `user_preference = fast`
+- Base tier: Standard. Risk upgrade: already Standard (HIGH floor). User wants Fast but HIGH risk floor is Standard → **Standard**.
+- Smart mode would pause (preference conflicts with risk floor).
+
+### Example 3: High complexity, critical risk (payments)
+
+- `complexity = HIGH`, `risk_level = CRITICAL`, `user_preference = auto`
+- Base tier: Deep. CRITICAL forces Deep. Auto preference → **Deep**.
+- Smart mode pauses (Deep tier + CRITICAL risk).
+
+## Error Handling
+
+| Scenario                                | Recovery                                        |
+| --------------------------------------- | ----------------------------------------------- |
+| `complexity` field missing from Design  | Default to MEDIUM; log warning                  |
+| `risk_level` missing from Research      | Default to MEDIUM; log warning                  |
+| User provides invalid preference value  | Treat as `auto`; log warning                    |
+| Selected tier conflicts with risk floor | Enforce risk floor; inform user of the override |
+
+## Notes
+
+- Tier choice is recorded in the final plan's frontmatter as `tier: fast | standard | deep`
+- The tier also influences the Tasks phase: Fast tier often produces 1–3 tasks; Standard 4–8; Deep 8+
+- If the user overrides the tier, preserve the algorithm's recommendation in a `tier_recommended` field for audit
+- Tier selection is the primary "right-sizing" mechanism — Small tasks → short plans; complex work → more structure (per Plan Skill core principles)