raptor-aios 0.1.0

package/dist/_core/templates/ghaWorkflow.yml.hbs

@@ -0,0 +1,58 @@
+# RAPTOR verification workflow — installed by `raptor init`
+# Runs project gates, constitution integrity (strict), and audit trail validation (strict)
+# on every pull_request that touches .raptor/, and on pushes to main.
+#
+# Customize the "Install RAPTOR CLI" step below if you install @raptor/cli differently
+# (e.g., as a repo dev-dependency via pnpm/yarn, a git submodule, or a pinned fork).
+name: raptor-verify
+
+on:
+  pull_request:
+    paths:
+      - '.raptor/**'
+      - '.github/workflows/raptor-verify.yml'
+  push:
+    branches: [main]
+    paths:
+      - '.raptor/**'
+
+jobs:
+  verify:
+    name: RAPTOR verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install RAPTOR CLI
+        run: npm install -g @raptor/cli@{{raptorVersion}}
+
+      - name: Set git identity (C5 requires actor.email for critical events)
+        run: |
+          git config --global user.name "raptor-ci"
+          git config --global user.email "raptor-ci@users.noreply.github.com"
+
+      - name: Verify project + feature gates
+        run: raptor verify
+
+      - name: Verify constitution (strict)
+        run: raptor verify constitution --strict
+
+      - name: Verify audit trails (strict)
+        shell: bash
+        run: |
+          set -e
+          shopt -s nullglob
+          found=0
+          for dir in .raptor/specs/*/; do
+            found=1
+            slug=$(basename "$dir")
+            echo "--- $slug ---"
+            raptor verify audit "$slug" --strict
+          done
+          if [ $found -eq 0 ]; then
+            echo "(no features to verify)"
+          fi

package/dist/_core/templates/hotfix.md.hbs

@@ -0,0 +1,39 @@
+---
+id: "{{id}}"
+slug: {{slug}}
+article: {{article}}
+severity: {{severity}}
+status: open
+created: {{createdAt}}
+{{#if incident}}incident: {{incident}}
+{{/if}}{{#if reconcileBy}}reconcile_by: {{reconcileBy}}
+{{/if}}---
+
+# Hotfix {{id}}: {{slug}}
+
+> **⚠ SDD bypass — this feature was delivered outside the normal spec/plan/tasks cycle.**
+> A hotfix is an exception that MUST be reconciled with a formal feature later.
+
+## Justification
+
+{{justification}}
+
+## Constitutional article bypassed
+
+- **{{article}}** ({{severity}})
+
+## Files changed
+
+{{#each outputs}}
+- `{{path}}` (`{{hash}}`)
+{{/each}}
+
+## Reconciliation TODO
+
+- [ ] Open a regular feature (`raptor new <slug>`) that backfills the spec/plan/tasks for this change.
+- [ ] Link the hotfix: record the feature id in `meta.reconciled_by` when marking `hotfix.reconciled`.
+- [ ] Run `raptor verify` to confirm `gate.hotfix.unreconciled` drops this entry.
+
+## Notes
+
+<!-- Free-form post-incident notes, links to tickets, timelines. -->

package/dist/_core/templates/plan.md.hbs

@@ -0,0 +1,212 @@
+---
+id: "{{id}}"
+slug: {{slug}}
+spec_hash: {{specHash}}
+spec_ref: specs/{{feature}}/spec.md
+constitution_hash: {{constitutionHash}}
+created: {{createdAt}}
+status: draft
+phase_minus_one: pending
+approved_by: ~
+approved_at: ~
+audit_ref: ~
+---
+
+<!--
+REQUIRED FRONTMATTER (add to the block above before `raptor approve` — gates read these):
+  privacy:                          # M2 — LGPD/GDPR
+    lawful_basis: "LGPD Art. 7 ..."
+    residency: "br-southeast"
+    retention: "..."
+  os_matrix:                        # M4 — must be >= raptor.yml baseline
+    ios_min: "15.1"
+    android_min: "8.0"
+  perf_budget:                      # M5 — (or perf_budget: { scope: none })
+    ttfi_ms: 2000
+    interactions_ms: 100
+  crash_free_slo: 99.9              # M6 — must be >= 99.5
+  observability:                    # M6
+    provider: "Sentry"
+(Frontmatter comments are stripped on approve, so this guidance lives here in the body.)
+-->
+
+
+<!--
+Raptor plan template — translate spec into technical approach.
+Rules for the agent:
+  1. Section "Phase -1 — Constitutional Gates" is MANDATORY and MUST precede any technical design.
+  2. For each core article (C1–C5), report one of: `[x] passes`, `[ ] violated` + justification in Complexity Tracking.
+  3. Use [NEEDS CLARIFICATION: ...] wherever the spec is ambiguous and the decision is non-reversible.
+  4. Do NOT write tasks here. Tasks live in `tasks.md` and are produced only AFTER this plan is approved.
+-->
+
+# Plan {{id}}: {{slug}}
+
+## Phase -1 — Constitutional Gates
+
+<!--
+Each gate checks a core article. Mark PASS or VIOLATED; violations MUST be justified below.
+Level `critical` gates cannot be silenced at runtime. A violation here means the plan CANNOT be approved
+without a framework-level amendment (C4).
+-->
+
+### Gate C1 — Spec exists and governs this plan
+
+- [ ] Spec `specs/{{feature}}/spec.md` exists, is in status `approved` or `draft`, and is hashed above.
+- Level: `critical`
+- Status: `pending` <!-- change to `pass` | `violated` -->
+
+### Gate C2 — Audit trail complete
+
+- [ ] `specs/{{feature}}/audit.jsonl` exists and will receive a `plan.generated` event from this run.
+- Level: `critical`
+- Status: `pending`
+
+### Gate C3 — Plan approval will precede tasks
+
+- [ ] Nothing in this plan assumes `tasks.md` or `/implement` will run before human approval of this file.
+- Level: `critical`
+- Status: `pending`
+
+### Gate C4 — Constitution integrity
+
+- [ ] `.raptor/constitution.md` RAPTOR-CORE block is unmodified (`raptor verify constitution` passes).
+- Level: `critical`
+- Status: `pending`
+
+### Gate C5 — Human approval on criticals
+
+- [ ] This plan declares that the final approval will be performed by an identified human (not a bot/agent).
+- Level: `critical`
+- Status: `pending`
+
+### Project / preset gates
+
+<!-- Generated from `raptor.yml` preset and project extensions. Leave empty if none. -->
+
+{{presetGatesBlock}}
+
+## Constitution Check
+
+<!--
+Spec Kit E02: Read `.raptor/memory/constitution.md` and evaluate EACH principle.
+This check is performed TWICE:
+  1. INITIAL CHECK — Before technical design (here). Pre-flight validation.
+  2. POST-DESIGN CHECK — After Phase 1 design is complete. Confirm no violations introduced.
+
+For each principle, mark:
+  - [x] PASSES — design is compatible with this principle.
+  - [ ] VIOLATED — explain why and what compensating control is proposed.
+
+Violations without justification = ERROR. Plan cannot be approved.
+-->
+
+### Initial Check (pre-design)
+
+| Principle | Status | Notes |
+|-----------|--------|-------|
+| *Read from `.raptor/memory/constitution.md`* | pending | *Agent fills this table after reading the constitution* |
+
+### Post-Design Check (after Phase 1)
+
+| Principle | Status | Notes |
+|-----------|--------|-------|
+| *Re-evaluate after architecture/data-model/contracts are drafted* | pending | *Agent fills this table after design phases* |
+
+
+## Complexity Tracking
+
+<!--
+Only relevant when one or more `required` or `advisory` gates were flagged VIOLATED.
+For each, write: gate id, justification, compensating control, incident/PR link.
+Core (critical) gates CANNOT appear here — violations of C1–C5 require framework amendment.
+-->
+
+*(none)*
+
+## 1. Context & Constraints
+
+- **Spec hash:** `{{specHash}}`
+- **Constitution hash:** `{{constitutionHash}}`
+- **Platforms:** [NEEDS CLARIFICATION — inherit from spec or restrict]
+- **Non-functional envelope:** [NEEDS CLARIFICATION — summarize NFR budget]
+
+## 2. Architecture Overview
+
+<!-- High-level approach. One paragraph + diagram (mermaid or ASCII). -->
+
+[NEEDS CLARIFICATION]
+
+```mermaid
+flowchart LR
+  user[User] --> ui[Screen]
+  ui --> core[Feature core]
+  core --> backend[(Backend)]
+```
+
+## 3. Data Model
+
+<!-- Entities, ownership, lifecycle. Use a table. -->
+
+| Entity | Fields | Owner | Lifecycle |
+|--------|--------|-------|-----------|
+| [NEEDS CLARIFICATION] | | | |
+
+## 4. Contracts
+
+<!-- Public APIs / events / deep links this feature exposes or consumes. Put full schemas in `specs/{{feature}}/contracts/`. -->
+
+- **Exposes:** [NEEDS CLARIFICATION]
+- **Consumes:** [NEEDS CLARIFICATION]
+
+## 5. Decisions
+
+<!-- Numbered, each with rationale. These are the only legitimate source for "why it was built this way". -->
+
+- **D1.** [NEEDS CLARIFICATION: decision] — *Rationale:* [NEEDS CLARIFICATION]
+- **D2.** [NEEDS CLARIFICATION]
+
+## 6. Alternatives considered
+
+<!-- Brief list, why rejected. -->
+
+- **Alt A:** [NEEDS CLARIFICATION] — rejected because [...]
+- **Alt B:** [NEEDS CLARIFICATION]
+
+## 7. Risks & Mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| [NEEDS CLARIFICATION] | | | |
+
+## 8. Rollout & Reversibility
+
+- **Release channel:** [NEEDS CLARIFICATION — store / staged / remote-config flag]
+- **Kill switch:** [NEEDS CLARIFICATION]
+- **Backout plan:** [NEEDS CLARIFICATION]
+
+## 9. Observability
+
+- **Events:** [NEEDS CLARIFICATION]
+- **Alarms / SLOs:** [NEEDS CLARIFICATION]
+
+## 10. Requirements Traceability
+
+<!--
+gate.plan.coverage_complete requires this plan to MENTION every [US#] and [FR-#]
+declared in spec.md. Map each to a decision (D#) / component so nothing is dropped.
+-->
+
+| Story / FR | Covered by (D#) | Where |
+|------------|-----------------|-------|
+| [US1] / [FR-1] | D1 | [NEEDS CLARIFICATION] |
+
+---
+
+## Checkpoints (agent report)
+
+- [ ] Phase -1 gates are all marked (pass or violated); none left `pending`.
+- [ ] Any `required`/`advisory` violation has a Complexity Tracking entry.
+- [ ] No core (`critical`) gate is marked violated (if so — STOP, this plan cannot proceed).
+- [ ] All technical decisions have rationale.
+- [ ] Rollout and observability sections are not empty.

package/dist/_core/templates/preCommitHook.sh.hbs

@@ -0,0 +1,30 @@
+#!/usr/bin/env sh
+# RAPTOR pre-commit hook — installed by `raptor init`.
+# Runs `raptor verify` if staged changes touch .raptor/.
+# Bypass with: SKIP_RAPTOR=1 git commit ...
+
+if [ -n "$SKIP_RAPTOR" ]; then
+  exit 0
+fi
+
+if [ ! -d ".raptor" ]; then
+  exit 0
+fi
+
+staged=$(git diff --cached --name-only --diff-filter=ACM | grep -E '^\.raptor/' || true)
+if [ -z "$staged" ]; then
+  exit 0
+fi
+
+if ! command -v raptor >/dev/null 2>&1; then
+  echo "⚠ RAPTOR pre-commit: \`raptor\` not on PATH; skipping (install @raptor/cli to enforce gates locally)."
+  exit 0
+fi
+
+echo "→ RAPTOR pre-commit: running \`raptor verify\`..."
+if ! raptor verify; then
+  echo ""
+  echo "✗ RAPTOR pre-commit failed. Fix the gate errors above, or bypass with SKIP_RAPTOR=1."
+  exit 1
+fi
+exit 0

package/dist/_core/templates/prePushHook.sh.hbs

@@ -0,0 +1,45 @@
+#!/usr/bin/env sh
+# RAPTOR pre-push hook — installed by `raptor init`.
+# Runs the full strict verification suite before allowing a push.
+# Bypass with: SKIP_RAPTOR=1 git push ...
+
+if [ -n "$SKIP_RAPTOR" ]; then
+  exit 0
+fi
+
+if [ ! -d ".raptor" ]; then
+  exit 0
+fi
+
+if ! command -v raptor >/dev/null 2>&1; then
+  echo "⚠ RAPTOR pre-push: \`raptor\` not on PATH; skipping (install @raptor/cli to enforce gates locally)."
+  exit 0
+fi
+
+echo "→ RAPTOR pre-push: strict verification..."
+failed=0
+
+if ! raptor verify constitution --strict; then
+  failed=1
+fi
+
+if ! raptor verify; then
+  failed=1
+fi
+
+for dir in .raptor/specs/*/; do
+  [ -d "$dir" ] || continue
+  slug=$(basename "$dir")
+  echo "--- audit: $slug ---"
+  if ! raptor verify audit "$slug" --strict; then
+    failed=1
+  fi
+done
+
+if [ $failed -eq 1 ]; then
+  echo ""
+  echo "✗ RAPTOR pre-push failed. Fix the errors above, or bypass with SKIP_RAPTOR=1."
+  exit 1
+fi
+
+exit 0

package/dist/_core/templates/raptor.yml.hbs

@@ -0,0 +1,24 @@
+version: {{raptorVersion}}
+project:
+  name: {{projectName}}
+  created: {{createdAt}}
+
+preset: {{preset}}
+
+# Agent configuration lives in agents.yml — do not add agents here.
+# Run 'raptor add-agent <key>' to configure agents.
+
+git:
+  branch_per_feature: true
+  branch_prefix: raptor/
+  commit_trailer: Raptor-Feature
+
+jira:
+  enabled: false
+  # base_url: https://your-org.atlassian.net
+  # project_key: APP
+
+gates:
+  # Critical gates from the RAPTOR-CORE (C1–C5) are always enforced and cannot be skipped.
+  # Project-level overrides apply only to `required` and `advisory` gates added via presets/extensions.
+  critical_require_human: true

package/dist/_core/templates/spec.md.hbs

@@ -0,0 +1,127 @@
+---
+id: "{{id}}"
+slug: {{slug}}
+platform: {{platform}}
+{{#if jira}}jira: {{jira}}
+{{/if}}created: {{createdAt}}
+status: draft
+audit_ref: ~
+---
+
+<!--
+REQUIRED FRONTMATTER (add to the block above before `raptor approve` — gates read these):
+  acceptance:                       # used by analyze + M7 coverage
+    ids: [AC-1, AC-2]
+  stores:                           # M1 — store-level permission strings
+    ios_permissions: ["NSCameraUsageDescription — why"]
+    android_permissions: ["android.permission.CAMERA — why"]
+  a11y:                             # M3 — WCAG AA (or wcag_level: n/a + justification)
+    wcag_level: "AA"
+    criteria: ["All controls have accessible labels", "Contrast >= 4.5:1"]
+(Frontmatter comments are stripped on approve, so this guidance lives here in the body.)
+-->
+
+
+<!--
+Raptor spec template — capture **intent**, not technical design.
+Rules for the agent filling this file:
+  1. This document SHOULD NOT prescribe implementation technology. Keep code/SDK choices to plan.md.
+  2. When information is missing or ambiguous, write [NEEDS CLARIFICATION: your question] — DO NOT guess.
+  3. Fill sections in order. Each section is numbered deliberately.
+  4. Report checkpoints at the end of the file before handing back to the human.
+-->
+
+# Feature {{id}}: {{slug}}
+
+## 1. Problem Statement
+
+[NEEDS CLARIFICATION: What specific user or business problem does this feature solve? Who is affected today and how?]
+
+## 2. Users & Scenarios
+
+<!-- Describe the primary user(s) and the top 1–3 scenarios this feature must support. -->
+
+- **Primary user:** [NEEDS CLARIFICATION]
+- **Secondary users:** [NEEDS CLARIFICATION]
+
+### Scenario A — [name]
+
+[NEEDS CLARIFICATION: narrative of the happy path]
+
+### Scenario B — [name]
+
+[NEEDS CLARIFICATION]
+
+## 3. User Stories
+
+<!-- Each story SHOULD be independently valuable and testable. Label with [US1], [US2]... -->
+
+- **[US1]** As a [user], I want [capability], so that [outcome].
+- **[US2]** [NEEDS CLARIFICATION]
+
+## 4. Functional Requirements
+
+<!-- One bullet per requirement. Avoid prescribing UI/tech. Use MUST/SHOULD/MAY. -->
+
+- [FR-1] The system MUST [NEEDS CLARIFICATION].
+- [FR-2] [NEEDS CLARIFICATION]
+
+## 5. Non-Functional Requirements
+
+### 5.1 Performance & resource
+
+- [NFR-1] p95 end-to-end latency: [NEEDS CLARIFICATION].
+- [NFR-2] Cold-start / interaction budget: [NEEDS CLARIFICATION].
+
+### 5.2 Accessibility
+
+- [NFR-3] WCAG AA parity on key flows: [NEEDS CLARIFICATION which flows].
+
+### 5.3 Privacy / Compliance
+
+{{#if platform}}- [NFR-4] Platform scope: **{{platform}}**.
+{{/if}}- [NFR-5] Data classification (PII / sensitive / public): [NEEDS CLARIFICATION].
+- [NFR-6] Applicable regulation (LGPD / GDPR / sectorial): [NEEDS CLARIFICATION].
+
+### 5.4 Platform constraints
+
+- [NFR-7] App Store / Play Store guidelines impacted: [NEEDS CLARIFICATION].
+- [NFR-8] Minimum OS versions supported: [NEEDS CLARIFICATION].
+
+### 5.5 Reliability
+
+- [NFR-9] Crash-free sessions target: [NEEDS CLARIFICATION: e.g., 99.9%].
+
+## 6. Out of Scope
+
+<!-- List what this feature explicitly does NOT address. Makes review cheaper. -->
+
+- [NEEDS CLARIFICATION]
+
+## 7. Dependencies & Assumptions
+
+- **Depends on:** [NEEDS CLARIFICATION — other features, backends, third-party services]
+- **Assumes:** [NEEDS CLARIFICATION]
+
+## 8. Acceptance Criteria
+
+<!-- Measurable, testable, linked to user stories. -->
+
+- [AC-1] Given [state], when [action], then [observable outcome]. (covers [US1])
+- [AC-2] [NEEDS CLARIFICATION]
+
+## 9. Open Questions
+
+<!-- Consolidated list of every [NEEDS CLARIFICATION] above plus anything else the agent couldn't resolve. -->
+
+1. [NEEDS CLARIFICATION]
+
+---
+
+## Checkpoints (agent report)
+
+- [ ] All `NEEDS CLARIFICATION` blocks are explicit and narrowly scoped (not "clarify section 3").
+- [ ] No implementation-level detail present (no framework names, no code snippets).
+- [ ] Functional vs. non-functional split is clean.
+- [ ] Acceptance criteria reference user stories by id.
+- [ ] Out-of-scope section has at least one item (avoid empty).

package/dist/_core/templates/tasks.md.hbs

@@ -0,0 +1,71 @@
+---
+id: "{{id}}"
+slug: {{slug}}
+plan_hash: {{planHash}}
+plan_ref: specs/{{feature}}/plan.md
+created: {{createdAt}}
+status: draft
+audit_ref: ~
+---
+
+<!--
+Raptor tasks template — decompose approved plan into executable work units.
+Rules for the agent:
+  1. This file MAY only be generated when plan.md is `status: approved` (enforced by gate.plan.approved).
+  2. Tag each task with the user story it serves: [US1], [US2]...
+  3. Tag parallel-safe tasks with [P]. Default is sequential.
+  4. Keep tasks atomic: one task = one reviewable commit.
+  5. NO implementation inline — tasks describe WHAT, plan explains WHY, code is produced by /implement.
+-->
+
+# Tasks {{id}}: {{slug}}
+
+## 1. User Stories in Scope
+
+<!-- Pull directly from spec.md. -->
+
+| Id | Story | Priority |
+|----|-------|----------|
+| US1 | [NEEDS CLARIFICATION] | must |
+
+## 2. Task List
+
+<!--
+Format: T### — <short imperative> [US#] [P?]
+Each task SHOULD fit into a single commit and be individually testable.
+-->
+
+- **T001** — [NEEDS CLARIFICATION: first task] [US1]
+- **T002** — [NEEDS CLARIFICATION] [US1] [P]
+- **T003** — [NEEDS CLARIFICATION] [US2]
+
+## 3. Dependency Graph
+
+```mermaid
+flowchart LR
+  T001 --> T002
+  T001 --> T003
+```
+
+## 4. Acceptance Check
+
+<!-- One line per acceptance criterion from spec.md — map to the task(s) that deliver it. -->
+
+| AC | Delivered by |
+|----|--------------|
+| [AC-1] | T001, T002 |
+
+## 5. Out of Scope Reminder
+
+<!-- Mirror the spec's out-of-scope list. If a task looks like it drifts into it, flag and pause. -->
+
+- [NEEDS CLARIFICATION]
+
+---
+
+## Checkpoints (agent report)
+
+- [ ] Every task carries a user-story tag.
+- [ ] Parallelizable tasks marked with [P] and have no implicit ordering dependency.
+- [ ] Each acceptance criterion has at least one delivering task.
+- [ ] No task introduces work not grounded in the plan.

package/dist/commands/add-agent.d.ts

@@ -0,0 +1,22 @@
+import { Command } from "@oclif/core";
+/**
+ * add-agent — Register a new AI agent integration in the project.
+ *
+ * Unlike before, this actually registers the agent in agents.yml AND
+ * materializes its slash commands — it no longer just prints a message
+ * telling the user to run `init --force` (B5).
+ *
+ * Spec Kit ref: E03 — "raptor add-agent"
+ */
+export default class AddAgent extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        key: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        "set-primary": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}
+//# sourceMappingURL=add-agent.d.ts.map

package/dist/commands/add-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-agent.d.ts","sourceRoot":"","sources":["../../src/commands/add-agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAe,MAAM,aAAa,CAAC;AAWnD;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,OAAO,QAAS,SAAQ,OAAO;IAC3C,OAAgB,WAAW,SACoF;IAE/G,OAAgB,QAAQ,WAGtB;IAEF,OAAgB,IAAI;;MAKlB;IAEF,OAAgB,KAAK;;MAKnB;IAEI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CA6G3B"}