raptor-aios 0.6.3 → 0.7.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.7.0] - 2026-06-08
+
+### Added
+
+- **Governed gate waivers sourced from ADRs.** `raptor verify` (and `checklist`) now read `.raptor/memory/decisions.md`: an accepted ADR that declares an `Overrides: gate.id` line downgrades a failing **required/advisory** gate to a non-blocking `overridden` result, recorded in the report as `⊝ overridden by ADR-NNN: <justification>`. **Critical** gates can never be waived this way — they keep requiring human sign-off (C4/C5), and an ADR aimed at one is explicitly reported as ignored. The ADR shape is deliberately tolerant (any heading level, `Status:` defaults to accepted, multiple `Overrides:` lines per ADR), but gate ids are matched strictly (`gate.<seg>.<seg>`) so prose bullets and version tokens (`v1.2`, `ADR-1.2`) are never parsed as gates.
+- **Honest M1 store opt-out.** A feature that genuinely touches no restricted OS API no longer needs invented permissions: keep the lists empty and declare `stores.no_restricted_apis: "<reason>"`. The M1 gate (`gate.mobile.stores`) then passes — mirroring `a11y.wcag_level: "n/a"` (M3) and `perf_budget.scope: "none"` (M5). An empty `stores:` block with no opt-out and no ADR still fails.
+
+### Internal
+
+- New `gates/adr-overrides.ts` (`parseAdrOverrides` / `readAdrOverrides`); `runGates` gains an `overrides` option and an `overridden` status/summary count; `GateOverride` type added. `verify` warns when an ADR override targets an unknown gate id. The runner no longer mutates a gate's own result object when reporting an ignored critical override. Spec templates and the mobile-opinionated preset document both opt-out paths.
+
 ## [0.6.3] - 2026-06-06
 
 ### Fixed

package/README.md

@@ -360,7 +360,7 @@ Cada gate exige campos no *frontmatter* de `spec.md` ou `plan.md` — declarativ
 
 |                     Gate                      | Nível |                     Exige no frontmatter                     |  Verificável por   |
 | --------------------------------------------- | ----- | ------------------------------------------------------------ | ------------------ |
-| **M1 — App/Play Store Compliance**            | 🟡     | `spec.stores.ios_permissions`, `.android_permissions`        | `verify stores`    |
+| **M1 — App/Play Store Compliance**            | 🟡     | `spec.stores.ios_permissions`, `.android_permissions` (ou `stores.no_restricted_apis: "<motivo>"` p/ opt-out honesto) | `verify stores`    |
 | **M2 — Privacidade & Residência (LGPD/GDPR)** | 🟡     | `plan.privacy.lawful_basis`, `.residency`, `.retention`      | —                  |
 | **M3 — Acessibilidade (WCAG AA)**             | 🟡     | `spec.a11y.wcag_level`, `.criteria`                          | `verify a11y`      |
 | **M4 — Matriz de SO**                         | 🟡     | `plan.os_matrix.ios_min`, `.android_min`                     | `verify os-matrix` |
@@ -419,6 +419,17 @@ observability:
 
 </details>
 
+> 🧯 **Feature sem APIs restritas?** Não invente permissões. Há dois caminhos honestos e auditáveis para o M1:
+> 1. **Opt-out no spec** — deixe as listas vazias e declare `stores.no_restricted_apis: "<motivo>"` (espelha `a11y.wcag_level: "n/a"` e `perf_budget.scope: "none"`).
+> 2. **Override por ADR** — registre um ADR aceito em `.raptor/memory/decisions.md` com `Overrides: gate.mobile.stores`; o `verify` o lê em runtime e marca o gate como `⊝ overridden by ADR-NNN`. Gates **críticos** nunca são waivados por ADR (exigem assinatura humana).
+>
+> ```markdown
+> ## ADR-001: Feature sem APIs restritas de OS
+> - Status: accepted
+> - Overrides: gate.mobile.stores
+> - Justification: Regras de negócio puras; não toca camera/location/etc.
+> ```
+
 ---
 
 ## 🔬 A ponta de verificação (`verify`)

package/dist/_core/dist/gates/adr-overrides.js

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const INACTIVE_STATUS = new Set([
+    "proposed",
+    "draft",
+    "rejected",
+    "superseded",
+    "deprecated",
+    "withdrawn",
+]);
+function extractAdrLabel(heading) {
+    const m = heading.match(/\bADR[-\s]?([\w.]+)/i);
+    if (!m)
+        return null;
+    return `ADR-${m[1]}`;
+}
+const HEADING_RE = /^#{1,}\s+(.*)$/;
+const OVERRIDES_RE = /^[-*\s]*overrides\s*:\s*(.+)$/i;
+const STATUS_RE = /^[-*\s]*status\s*:\s*(.+)$/i;
+const JUSTIFICATION_RE = /^[-*\s]*justification\s*:\s*(.+)$/i;
+const GATE_ID_RE = /^gate\.[a-z0-9_]+(?:\.[a-z0-9_]+)+$/i;
+function fieldValue(line, re) {
+    const m = line.match(re);
+    return m ? m[1].trim() : null;
+}
+function parseGateIds(values) {
+    const ids = [];
+    for (const value of values) {
+        for (const t of value.split(/[,\s]+/)) {
+            const id = t.trim();
+            if (GATE_ID_RE.test(id) && !ids.includes(id))
+                ids.push(id);
+        }
+    }
+    return ids;
+}
+export function parseAdrOverrides(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    const out = [];
+    let label = null;
+    let status = null;
+    let overridesLines = [];
+    let justification = null;
+    const flush = () => {
+        if (!label || overridesLines.length === 0)
+            return;
+        if (status && INACTIVE_STATUS.has(status.toLowerCase()))
+            return;
+        const gates = parseGateIds(overridesLines);
+        const reason = justification?.trim() || label;
+        for (const gate of gates) {
+            out.push({ gate, adr: label, justification: reason });
+        }
+    };
+    for (const line of lines) {
+        const heading = line.match(HEADING_RE);
+        if (heading) {
+            flush();
+            label = extractAdrLabel(heading[1]);
+            status = null;
+            overridesLines = [];
+            justification = null;
+            continue;
+        }
+        if (!label)
+            continue;
+        const ov = fieldValue(line, OVERRIDES_RE);
+        if (ov !== null)
+            overridesLines.push(ov);
+        const st = fieldValue(line, STATUS_RE);
+        if (st !== null)
+            status = st;
+        const ju = fieldValue(line, JUSTIFICATION_RE);
+        if (ju !== null)
+            justification = ju;
+    }
+    flush();
+    return out;
+}
+export function readAdrOverrides(projectRoot) {
+    const path = join(projectRoot, ".raptor", "memory", "decisions.md");
+    if (!existsSync(path))
+        return {};
+    const raw = readFileSync(path, "utf8");
+    const map = {};
+    for (const o of parseAdrOverrides(raw)) {
+        map[o.gate] = { adr: o.adr, justification: o.justification };
+    }
+    return map;
+}

package/dist/_core/dist/gates/index.js

@@ -6,3 +6,4 @@ export * from "./phase-gates.js";
 export * from "./m7-gates.js";
 export * from "./design-gates.js";
 export { runGates, formatReport } from "./runner.js";
+export { parseAdrOverrides, readAdrOverrides, } from "./adr-overrides.js";

package/dist/_core/dist/gates/runner.js

@@ -1,5 +1,6 @@
 export async function runGates(gates, ctx, opts = {}) {
     const skip = opts.skip ?? new Set();
+    const overrides = opts.overrides ?? {};
     const results = [];
     for (const gate of gates) {
         if (skip.has(gate.id)) {
@@ -26,6 +27,23 @@ export async function runGates(gates, ctx, opts = {}) {
         }
         try {
             const res = await gate.run(ctx);
+            const ovr = overrides[gate.id];
+            if (res.status === "fail" && ovr) {
+                if (gate.level === "critical") {
+                    results.push({
+                        ...res,
+                        message: `${res.message ?? "failed"} — ADR override ${ovr.adr} ignored: critical gates require human sign-off (C4/C5)`,
+                    });
+                }
+                else {
+                    results.push({
+                        ...res,
+                        status: "overridden",
+                        message: `overridden by ${ovr.adr}: ${ovr.justification}`,
+                    });
+                }
+                continue;
+            }
             results.push(res);
         }
         catch (err) {
@@ -43,6 +61,7 @@ export async function runGates(gates, ctx, opts = {}) {
         pass: results.filter((r) => r.status === "pass").length,
         fail: results.filter((r) => r.status === "fail").length,
         skipped: results.filter((r) => r.status === "skipped").length,
+        overridden: results.filter((r) => r.status === "overridden").length,
     };
     const blocked = results.some((r) => r.status === "fail" && (r.level === "critical" || r.level === "required"));
     return { results, blocked, summary };
@@ -50,7 +69,13 @@ export async function runGates(gates, ctx, opts = {}) {
 export function formatReport(report) {
     const lines = [];
     for (const r of report.results) {
-        const mark = r.status === "pass" ? "✓" : r.status === "skipped" ? "⊘" : "✗";
+        const mark = r.status === "pass"
+            ? "✓"
+            : r.status === "skipped"
+                ? "⊘"
+                : r.status === "overridden"
+                    ? "⊝"
+                    : "✗";
         const art = r.article ? ` [${r.article}]` : "";
         const lvl = r.level.toUpperCase();
         lines.push(`${mark} ${lvl.padEnd(9)}${art.padEnd(5)} ${r.id} — ${r.title}`);
@@ -58,6 +83,9 @@ export function formatReport(report) {
             lines.push(`    ${r.message}`);
     }
     lines.push("");
-    lines.push(`Summary: ${report.summary.pass} pass, ${report.summary.fail} fail, ${report.summary.skipped} skipped${report.blocked ? " — BLOCKED" : ""}`);
+    const overriddenPart = report.summary.overridden > 0
+        ? `, ${report.summary.overridden} overridden`
+        : "";
+    lines.push(`Summary: ${report.summary.pass} pass, ${report.summary.fail} fail, ${report.summary.skipped} skipped${overriddenPart}${report.blocked ? " — BLOCKED" : ""}`);
     return lines.join("\n");
 }

package/dist/_core/dist/presets/gates.js

@@ -55,10 +55,16 @@ export const gateMobileStores = {
         if (!spec.exists)
             return fail(this, "spec.md missing");
         const s = spec.data.stores;
-        const iosCount = s?.ios_permissions?.length ?? 0;
-        const androidCount = s?.android_permissions?.length ?? 0;
-        if (!s || (iosCount === 0 && androidCount === 0)) {
-            return fail(this, "spec frontmatter missing stores.ios_permissions / stores.android_permissions");
+        if (!s)
+            return fail(this, "spec frontmatter missing the stores block");
+        const iosCount = s.ios_permissions?.length ?? 0;
+        const androidCount = s.android_permissions?.length ?? 0;
+        if (iosCount === 0 && androidCount === 0) {
+            const optOutRaw = s.no_restricted_apis;
+            const optOut = typeof optOutRaw === "string" ? optOutRaw.trim() : "";
+            if (optOut)
+                return pass(this, { no_restricted_apis: optOut });
+            return fail(this, 'spec declares no store permissions — list them under stores.ios_permissions / stores.android_permissions, or declare stores.no_restricted_apis: "<why this feature touches no restricted OS API>" to opt out (M1)');
         }
         return pass(this, { ios: iosCount, android: androidCount });
     },

package/dist/_core/dist/presets/mobile-opinionated.js

@@ -5,10 +5,10 @@ const articles = [
         title: "App Store & Play Store Compliance",
         statement: "Every feature that touches restricted OS APIs (camera, microphone, contacts, location, photos, notifications, biometrics, health, HomeKit, etc.) MUST declare the exact store-level permission strings and the corresponding `NSxxxUsageDescription` / Android manifest permission in its `spec.md` frontmatter under `stores:`.",
         rationale: "App Store and Play Store rejections are the single largest source of mobile release delays and often surface only during submission review — after the code has been merged and the release train is in motion. Declaring permissions at spec time forces the conversation before engineering cost is sunk.",
-        enforcement: "`gate.mobile.stores` (level `required`) validates that `spec.stores.ios_permissions` and `spec.stores.android_permissions` are declared and non-empty whenever a feature targets mobile.",
+        enforcement: '`gate.mobile.stores` (level `required`) validates that `spec.stores.ios_permissions` / `spec.stores.android_permissions` are declared whenever a feature touches restricted OS APIs. A feature that genuinely touches none opts out honestly by declaring `stores.no_restricted_apis: "<reason>"` — mirroring `a11y.wcag_level: "n/a"` (M3) and `perf_budget.scope: "none"` (M5).',
         violation: {
             level: "required",
-            description: "Spec cannot be approved until the `stores:` frontmatter is populated. An ADR in `memory/decisions.md` MAY override with explicit justification (e.g., pure business logic with no platform API).",
+            description: 'Spec cannot be approved with an empty `stores:` block unless it declares `stores.no_restricted_apis` with a reason. Alternatively, an accepted ADR in `memory/decisions.md` that lists `Overrides: gate.mobile.stores` waives the gate at verify time (the override is recorded as `overridden by ADR-NNN`).',
         },
     },
     {

package/dist/_core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raptor/core",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "type": "module",
   "main": "dist/index.js"
 }

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

@@ -12,6 +12,8 @@ acceptance:
 stores:
   ios_permissions: []
   android_permissions: []
+  # If the feature touches NO restricted OS API, keep the lists empty and add:
+  # no_restricted_apis: "<why — e.g. pure business logic, no camera/location>"
 a11y:
   wcag_level: "AA"
   criteria: []
@@ -20,7 +22,7 @@ a11y:
 <!--
 REQUIRED FRONTMATTER (gates read the keys above — fill before `raptor approve`):
   acceptance.ids: [AC-1, AC-2]            # every AC heading must be listed (analyze + M7)
-  stores.ios_permissions / android_permissions   # M1, mobile: "PERMISSION — why"
+  stores.ios_permissions / android_permissions   # M1, mobile: "PERMISSION — why" (or stores.no_restricted_apis: "<reason>")
   a11y.wcag_level + a11y.criteria         # M3 (use "n/a" + justification when non-visual)
 (Frontmatter comments are stripped on approve, so this guidance lives in the body.)
 -->

package/dist/commands/checklist.js

@@ -2,7 +2,7 @@ import { Args, Flags } from "@oclif/core";
 import { BaseCommand } from "../base-command.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
-import { appendAuditEvent, buildCanonicalPrompt, discoverChecklists, formatReport, gateChecklistFrontmatter, gateChecklistLinksToDecisions, gateChecklistNonEmpty, generateChecklistFrontmatter, hashString, loadAgentsConfig, parseChecklistItems, parsePlan, runGates, selectAgent, summarizeChecklist, } from "../_core/dist/index.js";
+import { appendAuditEvent, buildCanonicalPrompt, discoverChecklists, formatReport, gateChecklistFrontmatter, gateChecklistLinksToDecisions, gateChecklistNonEmpty, generateChecklistFrontmatter, hashString, loadAgentsConfig, parseChecklistItems, parsePlan, readAdrOverrides, runGates, selectAgent, summarizeChecklist, } from "../_core/dist/index.js";
 import { parseFrontmatter } from "../_core/dist/index.js";
 import { currentActor, featureDir, requireProjectRoot, } from "../shared/project.js";
 import { writeFeaturePrompt } from "../shared/feature-prompt.js";
@@ -171,7 +171,7 @@ export default class Checklist extends BaseCommand {
             const report = await runGates(gates, {
                 projectRoot: root,
                 featureDir: dir,
-            });
+            }, { overrides: readAdrOverrides(root) });
             this.log(`=== Checklist Gates for ${featureName} ===`);
             this.log(formatReport(report));
             if (report.blocked)

package/dist/commands/verify.js

@@ -2,7 +2,7 @@ import { Args, Flags } from "@oclif/core";
 import { BaseCommand } from "../base-command.js";
 import { existsSync, readdirSync } from "node:fs";
 import { basename, join } from "node:path";
-import { BUILTIN_GATES, formatReport, gateById, getPreset, PROJECT_GATES, runGates, } from "../_core/dist/index.js";
+import { BUILTIN_GATES, formatReport, gateById, getPreset, PROJECT_GATES, readAdrOverrides, runGates, } from "../_core/dist/index.js";
 const PROJECT_GATE_IDS = new Set(PROJECT_GATES.map((g) => g.id));
 import { featureDir, readConfig, requireProjectRoot, } from "../shared/project.js";
 export default class Verify extends BaseCommand {
@@ -43,8 +43,14 @@ export default class Verify extends BaseCommand {
         if (flags.justification)
             for (const id of skipSet)
                 skipJustifications[id] = flags.justification;
+        const overrides = readAdrOverrides(root);
+        const knownGateIds = new Set([...BUILTIN_GATES, ...PROJECT_GATES, ...presetGates].map((g) => g.id));
+        for (const id of Object.keys(overrides)) {
+            if (!knownGateIds.has(id))
+                this.warn(`ADR override targets unknown gate id "${id}" — ignored (check the spelling in memory/decisions.md).`);
+        }
         if (!args.feature) {
-            const projectReport = await runGates(PROJECT_GATES, { projectRoot: root }, { skip: skipSet, skipJustifications });
+            const projectReport = await runGates(PROJECT_GATES, { projectRoot: root }, { skip: skipSet, skipJustifications, overrides });
             this.log("=== Project gates ===");
             this.log(formatReport(projectReport));
             const specs = join(root, ".raptor", "specs");
@@ -63,7 +69,7 @@ export default class Verify extends BaseCommand {
                         ...BUILTIN_GATES.filter((g) => !PROJECT_GATE_IDS.has(g.id)),
                         ...presetGates,
                     ];
-                    const r = await runGates(featureGates, { projectRoot: root, featureDir: dir }, { skip: skipSet, skipJustifications });
+                    const r = await runGates(featureGates, { projectRoot: root, featureDir: dir }, { skip: skipSet, skipJustifications, overrides });
                     this.log(`\n--- ${f} ---`);
                     this.log(formatReport(r));
                     if (r.blocked)
@@ -88,7 +94,7 @@ export default class Verify extends BaseCommand {
                 this.warn(`--skip=${id} ignored: critical gates cannot be skipped (see C4/C5).`);
             }
         }
-        const report = await runGates(gatesToRun, { projectRoot: root, featureDir: dir }, { skip: skipSet, skipJustifications });
+        const report = await runGates(gatesToRun, { projectRoot: root, featureDir: dir }, { skip: skipSet, skipJustifications, overrides });
         this.log(`=== Gates for feature ${featureName}${preset ? ` (preset: ${preset.id})` : ""} ===`);
         this.log(formatReport(report));
         if (report.blocked)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "raptor-aios",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Raptor — Spec-Driven Development (SDD) CLI for modern mobile apps. Constitutional gates, audit trail, real verification (a11y/perf/stores/OS matrix), and AI-agent slash commands.",
   "type": "module",
   "bin": {

package/scripts/prepare-npm.mjs

@@ -29,7 +29,7 @@ const CLI = join(ROOT, "packages", "cli");
 const CORE = join(ROOT, "packages", "core");
 const OUT = join(ROOT, "build", "npm");
 
-const VERSION = "0.6.3";
+const VERSION = "0.7.0";
 
 function log(msg) {
   process.stdout.write(`  ${msg}\n`);

package/templates/spec-template.md

@@ -10,9 +10,12 @@ audit_ref: ~
 # --- Gates read the keys below. Fill them before `raptor approve`. ---
 acceptance:
   ids: [] # e.g. [AC-1, AC-2] — every AC heading below must also appear here (analyze + M7)
-stores: # M1 — store-level permission strings (mobile). Use [] when not applicable.
+stores: # M1 — store-level permission strings (mobile).
   ios_permissions: [] # e.g. ["NSCameraUsageDescription — scan delivery QR codes"]
   android_permissions: [] # e.g. ["android.permission.CAMERA — scan delivery QR codes"]
+  # If this feature touches NO restricted OS API, leave the lists empty AND set
+  # no_restricted_apis to the reason (honest opt-out — mirrors a11y "n/a"):
+  # no_restricted_apis: "Pure business logic — no camera/location/etc."
 a11y: # M3 — WCAG target (set wcag_level: "n/a" + a justification when truly non-visual)
   wcag_level: "AA"
   criteria: [] # e.g. ["All controls have accessible labels", "Contrast >= 4.5:1"]