@williambeto/ai-workflow 2.4.9 → 2.6.3

package/core/index.d.ts

@@ -0,0 +1,440 @@
+interface RequestUnderstanding {
+    rawRequest: string;
+    taskGoal: string;
+    requestedActor?: string;
+    invalidActor?: string;
+    requestedCapability?: string;
+    operationType: string;
+    mutationIntent: "readonly" | "write" | "publish";
+    riskLevel: "low" | "medium" | "high";
+    requiredEvidence: string[];
+    safetyConstraints: string[];
+    specPolicy?: "none" | "required";
+    matchedSignals?: string[];
+    riskDrivers?: string[];
+}
+interface RoutingDecision {
+    requestedActor?: string;
+    selectedActor?: string;
+    operationType: string;
+    mutationIntent: "readonly" | "write" | "publish";
+    permissionDecision: "allowed" | "rerouted" | "blocked";
+    reason: string;
+    workflowPath: string[];
+}
+
+interface RequestClassifierResult {
+    request: string;
+    profile: string;
+    owner: string;
+    intent: "read-only" | "write";
+    /** @deprecated Use riskLevel, specPolicy, and evidencePolicy instead */
+    mode: "quick" | "standard" | "full";
+    risk: "low" | "medium" | "high";
+    specPolicy: "none" | "required";
+    evidencePolicy: "optional" | "required";
+    remediationLimit: number;
+    riskDrivers: string[];
+    matchedSignals: string[];
+    specNeeded: boolean;
+    validationNeeded: boolean;
+    skills: string[];
+    requestUnderstanding: RequestUnderstanding;
+    routingDecision: RoutingDecision;
+}
+/**
+ * RequestClassifier - Classifies natural requests into structured, testable contracts.
+ */
+declare class RequestClassifier {
+    /**
+     * Classifies a natural request.
+     */
+    classify(request?: string, options?: {
+        cwd?: string;
+    }): RequestClassifierResult;
+}
+
+interface ExecutionPlan {
+    objective: string;
+    scope: string;
+    restrictions: string[];
+    owner: string;
+    skills: string[];
+    branchNeeded: boolean;
+    branchName: string | null;
+    validationsExpected: string[];
+    remediationLimit: number;
+    specPath: string | null;
+    specPolicy: "none" | "required";
+    evidencePolicy: "optional" | "required";
+    riskLevel: "low" | "medium" | "high";
+    /** @deprecated use specPolicy, evidencePolicy and riskLevel instead */
+    mode: "quick" | "standard" | "full";
+    profile: string;
+}
+/**
+ * ExecutionPlanner - Formulates a minimum operational plan based on classification.
+ */
+declare class ExecutionPlanner {
+    cwd: string;
+    constructor({ cwd }?: {
+        cwd?: string;
+    });
+    /**
+     * Generates an execution plan.
+     */
+    plan(classification: RequestClassifierResult, taskSlug?: string): ExecutionPlan;
+}
+
+type WorkflowState = "RECEIVED" | "CLASSIFIED" | "PLANNED" | "BRANCH_READY" | "DELEGATED" | "IMPLEMENTING" | "IMPLEMENTED" | "VALIDATING" | "REMEDIATING" | "REVALIDATING" | "COMPLETED" | "COMPLETED_WITH_NOTES" | "BLOCKED";
+interface StateHistoryEntry {
+    state: WorkflowState;
+    timestamp: string;
+}
+
+/**
+ * WorkflowStateMachine - Enforces state transitions for the AI Workflow loop.
+ */
+declare class WorkflowStateMachine {
+    private state;
+    private history;
+    private validTransitions;
+    constructor();
+    /**
+     * Transitions the machine to a new state.
+     * @param newState - The state to transition to.
+     */
+    transitionTo(newState: WorkflowState): void;
+    getCurrentState(): WorkflowState;
+    getHistory(): StateHistoryEntry[];
+}
+
+interface LedgerEvent {
+    workflowId: string;
+    timestamp: string;
+    actor: string;
+    actorType?: string;
+    observed?: any;
+    runtime?: any;
+    eventType: string;
+    provenance: string;
+    data: any;
+}
+interface RoleConfinementResult {
+    passed: boolean;
+    status: "PASS" | "BLOCKED";
+    reason: string;
+    violations: string[];
+}
+/**
+ * EvidenceLedger - Traces structural workflow events to make delegation observable.
+ */
+declare class EvidenceLedger {
+    cwd: string;
+    workflowId: string;
+    events: LedgerEvent[];
+    constructor({ cwd, workflowId }?: {
+        cwd?: string;
+        workflowId?: string;
+    });
+    /**
+     * Logs a workflow event to the ledger.
+     */
+    logEvent({ actor, eventType, provenance, data, actorType, observed, runtime }: {
+        actor: string;
+        eventType: string;
+        provenance: string;
+        data?: any;
+        actorType?: string;
+        observed?: any;
+        runtime?: any;
+    }): LedgerEvent;
+    getEvents(): LedgerEvent[];
+    /**
+     * Saves the ledger events to a JSON file.
+     */
+    save(filePath: string): Promise<void>;
+    verifyRoleConfinement(): Promise<RoleConfinementResult>;
+}
+
+interface InspectResult {
+    available: boolean;
+    supports: {
+        run: boolean;
+        formatJson: boolean;
+        agent: boolean;
+        model: boolean;
+    };
+}
+interface ExecuteOptions {
+    agent?: string | null;
+    model?: string | null;
+    readOnly?: boolean;
+    fastTrack?: boolean;
+}
+interface ExecuteResult {
+    success: boolean;
+    status?: string;
+    commandsRun: string[];
+    eventCount: number;
+    error?: string;
+    runtimeAgentRequested?: string | null;
+    runtimeAgentApplied?: string | null;
+    runtimeAgentSupported?: boolean;
+    runtimeAgentSelectionMode?: string;
+}
+/**
+ * OpenCodeAdapter - Real runtime integration with the OpenCode CLI.
+ */
+declare class OpenCodeAdapter {
+    cwd: string;
+    constructor({ cwd }?: {
+        cwd?: string;
+    });
+    /**
+     * Inspects the availability and capability of the OpenCode CLI.
+     */
+    inspect(): Promise<InspectResult>;
+    /**
+     * Runs opencode with a prompt and options.
+     */
+    execute(message: string, { agent, model, readOnly, fastTrack }?: ExecuteOptions): Promise<ExecuteResult>;
+}
+
+interface DelegationControllerOptions {
+    cwd?: string;
+    ledger?: EvidenceLedger;
+    adapter?: OpenCodeAdapter;
+}
+/**
+ * DelegationController - Manages and logs coordination between Atlas, Astra, Sage, and Phoenix.
+ */
+declare class DelegationController {
+    cwd: string;
+    ledger?: EvidenceLedger;
+    adapter: OpenCodeAdapter;
+    lastRoutingDecision: RoutingDecision | null;
+    constructor({ cwd, ledger, adapter }?: DelegationControllerOptions);
+    /**
+     * Logs routing decision by Atlas.
+     */
+    route(naturalRequest: string, classification: RequestClassifierResult): Promise<void>;
+    /**
+     * Logs and executes the implementation process by Astra.
+     */
+    implement(promptMsg: string, owner: string, options?: Record<string, unknown>): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Runs validation locally without logging Sage since no validation agent runtime was executed.
+     */
+    validate(taskSlug: string, profile: string, verifyFn: () => Promise<Record<string, unknown>>, evidencePolicy?: "optional" | "required" | null): Promise<Record<string, unknown>>;
+}
+
+interface HandoffGenerateOptions {
+    taskId: string;
+    author?: string;
+    status: string;
+    specPaths?: string[];
+    nextActions?: string;
+    evidence?: any;
+}
+/**
+ * HandoffEngine - Bundles project context into a single Markdown packet.
+ */
+declare class HandoffEngine {
+    cwd: string;
+    constructor({ cwd }: {
+        cwd: string;
+    });
+    /**
+     * Generates a handoff packet.
+     */
+    generate({ taskId, author, status, specPaths, nextActions, evidence }: HandoffGenerateOptions): Promise<string>;
+}
+
+interface HealerEngineOptions {
+    cwd: string;
+    /** @deprecated use remediationLimit instead */
+    mode?: "quick" | "standard" | "full";
+    taskSlug?: string;
+    /** @deprecated use remediationLimit instead */
+    maxAttempts?: number | null;
+    remediationLimit?: number | null;
+    ledger?: EvidenceLedger | null;
+}
+declare class HealerEngine {
+    cwd: string;
+    /** @deprecated use remediationLimit instead */
+    mode: "quick" | "standard" | "full";
+    taskSlug: string;
+    maxAttempts: number;
+    ledger: EvidenceLedger | null;
+    constructor({ cwd, mode, taskSlug, maxAttempts, remediationLimit, ledger }: HealerEngineOptions);
+    get statePath(): string;
+    fingerprint(result: any): string;
+    blockingCount(result: any): number;
+    affectedChecks(result: any): string[];
+    hasProgress(before: any, after: any, remediation?: any): boolean;
+    writeState(state: any): Promise<void>;
+    resetState(): Promise<void>;
+    writeRemediationRequest({ attempt, result }: {
+        attempt: number;
+        result: any;
+    }): Promise<string>;
+    run({ initialResult, validate, remediate }: {
+        initialResult: any;
+        validate: (options: {
+            affectedChecks: string[];
+            attempt: number;
+        }) => Promise<any>;
+        remediate: (options: {
+            attempt: number;
+            maxAttempts: number;
+            mode: string;
+            taskSlug: string;
+            result: any;
+            affectedChecks: string[];
+            requestPath: string;
+        }) => Promise<any>;
+    }): Promise<any>;
+}
+
+interface SnapshotFile {
+    sha256: string;
+    mode: string;
+}
+interface WorkspaceSnapshotData {
+    branch: string;
+    head: string;
+    indexTree: string;
+    files: Record<string, SnapshotFile>;
+    stagedDiffHash: string;
+    unstagedDiffHash: string;
+    untrackedFilesHash: string;
+}
+declare class WorkspaceSnapshot {
+    cwd: string;
+    fastTrack: boolean;
+    constructor({ cwd, fastTrack }?: {
+        cwd?: string;
+        fastTrack?: boolean;
+    });
+    isIgnored(relativePath: string): boolean;
+    capture(): Promise<WorkspaceSnapshotData>;
+    scanDir(dir: string, filesMap: Record<string, SnapshotFile>): Promise<void>;
+    calculateHash(snapshot: WorkspaceSnapshotData): string;
+}
+
+interface VerifyFidelityResult {
+    passed: boolean;
+    status: string;
+    reason?: string;
+    deliveryClass: string;
+    requestFidelity: any;
+}
+interface VerifyIntegrityResult {
+    valid: boolean;
+    changes: {
+        added: string[];
+        modified: string[];
+        deleted: string[];
+    };
+}
+declare class Finalizer {
+    cwd: string;
+    snapshotManager: WorkspaceSnapshot;
+    fastTrack: boolean;
+    constructor({ cwd, fastTrack }?: {
+        cwd?: string;
+        fastTrack?: boolean;
+    });
+    getChangedFilesFromGit(): string[];
+    verifyFidelity(arg: any): Promise<VerifyFidelityResult>;
+    /**
+     * Compares the current workspace state with a previously captured snapshot.
+     */
+    verifyIntegrity(previousSnapshot: WorkspaceSnapshotData): Promise<VerifyIntegrityResult>;
+}
+
+interface DirtyState {
+    clean: boolean;
+    tracked: string[];
+    untracked: string[];
+    lines: string[];
+}
+interface BranchGateCheckResult {
+    blocked: boolean;
+    branch: string;
+    recovered?: boolean;
+    branchBefore?: string;
+    readOnly?: boolean;
+    reason?: string;
+    dirtyState?: DirtyState;
+    error?: string;
+}
+/**
+ * BranchGate - Protects main/master and can recover safely onto a scoped branch.
+ */
+declare class BranchGate {
+    protectedBranches: string[];
+    logPath: string | null;
+    cwd: string;
+    constructor({ protectedBranches, memoryDir, cwd }?: {
+        protectedBranches?: string[];
+        memoryDir?: string;
+        cwd?: string;
+    });
+    run(command: string): string;
+    log(event: string): void;
+    getDirtyState(): DirtyState;
+    createScopedBranch(taskSlug: string): string;
+    getCurrentBranch(): string;
+    /**
+     * Strictly verifies branch safety without any override bypasses.
+     */
+    check(overrideIgnored?: string, { taskSlug, readOnly }?: {
+        taskSlug?: string;
+        readOnly?: boolean;
+    }): BranchGateCheckResult;
+}
+
+interface MergeGateResult {
+    status: "PASS" | "FAIL_QUALITY_GATE" | "ERROR";
+    reason?: string;
+}
+/**
+ * MergeGate verifies that commit history on integration branches respects
+ * the non-fast-forward (--no-ff) merge strategy, preserving feature branch
+ * topology instead of flattening/fast-forwarding.
+ */
+declare class MergeGate {
+    cwd: string;
+    constructor({ cwd }?: {
+        cwd?: string;
+    });
+    runGit(command: string): string;
+    /**
+     * Checks the commit history of the repository/branch.
+     */
+    check(branchName: string): MergeGateResult;
+}
+
+interface SpecValidationResult {
+    valid: boolean;
+    reason?: string;
+    tier?: string;
+}
+/**
+ * SpecValidator - Enforces "No Spec, No Code" rule.
+ * Validates existence, structure, and approval status of specifications.
+ */
+declare class SpecValidator {
+    /**
+     * Validates a specification file.
+     */
+    validate(filePath: string): Promise<SpecValidationResult>;
+}
+
+export { BranchGate, DelegationController, EvidenceLedger, ExecutionPlanner, Finalizer, HandoffEngine, HealerEngine, MergeGate, OpenCodeAdapter, RequestClassifier, SpecValidator, WorkflowStateMachine };

package/core/index.js

@@ -0,0 +1,32 @@
+import {
+  BranchGate,
+  DelegationController,
+  EvidenceLedger,
+  ExecutionPlanner,
+  Finalizer,
+  HandoffEngine,
+  HealerEngine,
+  OpenCodeAdapter,
+  RequestClassifier,
+  SpecValidator,
+  WorkflowStateMachine
+} from "../chunk-UHLZX2EG.js";
+import {
+  MergeGate
+} from "../chunk-2AOV2ATY.js";
+import "../chunk-5WRI5ZAA.js";
+export {
+  BranchGate,
+  DelegationController,
+  EvidenceLedger,
+  ExecutionPlanner,
+  Finalizer,
+  HandoffEngine,
+  HealerEngine,
+  MergeGate,
+  OpenCodeAdapter,
+  RequestClassifier,
+  SpecValidator,
+  WorkflowStateMachine
+};
+//# sourceMappingURL=index.js.map

package/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist-assets/AGENTS.md

@@ -16,19 +16,36 @@ Deliver useful software through proportionate workflow, minimum diff, observed v
 
 ## Routing & Delegation
 
-Atlas routes. Nexus owns discovery, requirements, and spec authoring. Orion owns planning, PR sequencing, and release strategy. Astra implements substantial scoped work. Sage independently validates when risk or full mode justifies separation. Phoenix performs bounded remediation. Delegation must improve the result; do not create agent theatre or claim handoffs that did not occur.
+Atlas routes. Nexus owns discovery, requirements, and spec authoring. Orion owns planning, PR sequencing, and release strategy. Astra implements substantial scoped work. Sage independently validates when high risk or required evidence policy justifies separation. Phoenix performs bounded remediation. Delegation must improve the result; do not create agent theatre or claim handoffs that did not occur.
 
-## Modes
+## Proportional Execution Policies
 
-- quick: small change, targeted validation, short summary;
-- standard: scoped feature, relevant validation, optional delegation;
-- full: formal planning, specialist implementation, independent validation, persisted evidence.
+The AI Workflow Kit enforces a single, mandatory execution path (Request → Planning → Branch Gate → Delegation → Implementation → Validation → Evidence). Steps are never bypassed, but operational constraints adapt proportionally:
+
+- **Risk Level (low | medium | high):** Controls merge gate checks, branch protection verification, and validation depth. High risk tasks require independent auditor review.
+- **Specification Policy (none | required):** Dictates whether a formal specification document (SDD) is required before implementation.
+- **Evidence Policy (optional | required):** Determines whether observed execution validation must be saved as a persisted EVIDENCE.json artifact.
+- **Remediation Limit (number):** Enforces a strict attempt threshold (e.g., 1 for low risk, 3 for high risk) for Phoenix automatic healing.
 
 ## Evidence
 
-Quick and standard work require only branch, changed areas, commands/results, and limitations in the handoff. Full/release/audit/security work may persist machine-generated evidence.
+Low and medium risk tasks require only branch, changed areas, commands/results, and limitations in the handoff. High risk or publish tasks require persisted machine-generated EVIDENCE.json.
 
 ## Core Concept
 
 AI Workflow is an npm CLI that installs agents, commands, skills, policies and templates into your repository.
 It guides coding agents from request to implementation, validation and evidence. AI Workflow Kit preserves workflow integrity so coding agents cannot skip from request to code to success without an explicit implementation path, proportional validation, and final evidence.
+
+## Available skills not exposed as subagents
+
+The following skills ship in `dist-assets/skills/` but are intentionally **not registered as subagents** in `opencode-merge.ts`. They operate as contextual lenses — activated by existing actors (Astra, Sage, Backend-Engineer, etc.) when the request profile warrants it — rather than as autonomous actors that could compete with or duplicate the core delegation chain.
+
+| Skill | Activated by | Rationale |
+|---|---|---|
+| `cyber-security` | Sage (audit), Astra (hardening tasks) | Security is a review lens, not an actor. Sage already owns independent audits. |
+| `database` | Backend-Engineer, Astra | DB schema work is covered by the backend actor. Separate actor would duplicate scope. |
+| `devops` | Deployment-Specialist, Astra | CI/CD and container work is already covered by Deployment-Specialist. |
+| `localization` | Astra (i18n tasks), Full-Stack-Engineer | Narrow domain; rarely an isolated request. Astra activates this skill when needed. |
+| `performance` | Astra (optimization tasks), QA-Engineer | Optimization is embedded in implementation and QA passes, not a separate actor. |
+
+**Decision rule:** If a future request requires one of these skills to act as an autonomous, persistent actor with its own evidence trail, promote it to a subagent in `opencode-merge.ts` with explicit justification. Do not promote by default.

package/dist-assets/agents/atlas.md

@@ -19,7 +19,7 @@ Atlas must:
 * Produce routing/evidence decisions.
 
 ## Responsibilities
-* Classify requests and select the lowest safe mode (`readonly`, `quick`, `standard`, `full`).
+* Classify requests and select the lowest safe proportional policies (riskLevel, evidencePolicy, specPolicy).
 * Enforce protected-branch safety before writes.
 * Route to specialists only when useful.
 * Require observed validation and prevent false success.
@@ -38,7 +38,7 @@ Atlas must:
 * Explicit actor or capability signals from the user.
 
 ## Constraints
-* **Full Mode Sequence Enforcement**: In `full` mode, Atlas must strictly enforce that the workflow runs sequentially through `discover`, `spec-create`, `spec-review`, and `plan` phases before any implementation or coding starts. Jumping directly to implementation is forbidden.
+* **High-Risk Sequence Enforcement**: For high-risk tasks (specPolicy: required), Atlas must strictly enforce that the workflow runs sequentially through `discover`, `spec-create`, `spec-review`, and `plan` phases before any implementation or coding starts. Jumping directly to implementation is forbidden.
 * **Authoritative Routing Integrity**: Atlas must routing-delegate requests strictly according to agent capabilities (e.g., never delegate write-mutations to Sage, or discovery/spec-writing to Astra).
 * **Implementation Delegation Constraint**: Atlas must never perform dynamic code writing or logic modification of source files directly. Any code changes (excluding pure documentation, README updates, or spelling typos) must be delegated to Astra.
 * **Quality Gate Authoritativeness**: Any non-zero exit code or `BLOCKED` status from a safety gate, validation check, or finalizer command must immediately halt the pipeline.
@@ -72,27 +72,27 @@ Atlas must:
 * Claiming success without evidence.
 
 ## Operating procedure
-1. classify requests and select the lowest safe mode.
+1. classify requests and select the lowest safe proportional policies.
 2. Delegate to specialist actors:
    * Delegation is proportional, not ceremonial.
    * Use Astra for substantial implementation work.
-   * Use Sage for independent validation when risk or full mode justifies it.
+   * Use Sage for independent validation when high risk justifies it.
    * Use Phoenix only for concrete findings that need remediation.
    * Do not claim that an agent acted unless that handoff actually occurred.
-3. For quick or standard tasks:
+3. For low or medium risk tasks:
    * Inspect status.
    * Recover branch if needed.
    * Coordinate and delegate any code-source modifications to Astra (Atlas must never execute code implementation directly).
    * Run validation.
-   * For every write-capable quick or standard task, Atlas must run the package finalizer after the final implementation changes and before reporting success:
+   * For every write-capable low or medium risk task, Atlas must run the package finalizer after the final implementation changes and before reporting success:
      ```bash
-     npx ai-workflow collect-evidence --mode=<quick|standard> --task=<short-task-slug>
+     npx ai-workflow collect-evidence --evidence-policy=optional --task=<short-task-slug>
      ```
      The finalizer exit code and printed status are authoritative:
      * exit code `0` with `COMPLETED` or `COMPLETED_WITH_NOTES`: Atlas may report that exact public state;
      * non-zero exit code or `BLOCKED`: remediate within the configured bound or report `BLOCKED`;
      * Atlas must never infer, upgrade, or replace the finalizer result from screenshots, manual checks, build output, or its own judgement.
-4. For full mode tasks, use the full workflow/orchestrator so persisted evidence and independent validation remain available.
+4. For high-risk tasks requiring evidence (evidencePolicy: required), use the full workflow/orchestrator so persisted evidence and independent validation remain available.
 
 ## Expected output schema
 Must include:

package/dist-assets/agents/nexus.md

@@ -15,7 +15,7 @@ Nexus must inspect project structure, identify stack, entry points, scripts, con
 ## Responsibilities
 * Inspect relevant project context.
 * Clarify objective, scope, constraints, risks, and acceptance criteria.
-* Recommend quick, standard, or full mode.
+* Recommend riskLevel, evidencePolicy, and specPolicy.
 * Define meaningful validation.
 * Identify assumptions and stop conditions.
 
@@ -31,13 +31,13 @@ Nexus must inspect project structure, identify stack, entry points, scripts, con
 * Natural language requests, product requirements, user goals, or bug reports.
 
 ## Constraints
-* **Traceability Matrix Enforcement**: Specifications created for full or standard tasks must include a traceability matrix mapping each business requirement to a specific automated verification method and DoD.
+* **Traceability Matrix Enforcement**: Specifications created for medium or high risk tasks must include a traceability matrix mapping each business requirement to a specific automated verification method and DoD.
 * **Strict Read-Only Discovery**: Under no circumstances should Nexus write, edit, or delete files in the repository during discovery or specification creation.
 * **Measurable Acceptance (DoD)**: All acceptance criteria (DoD) must be concrete, binary, and verifiable through test suites, linting checks, or visual reports. Prohibit qualitative/subjective terms.
 * Do not mutate files during discovery.
 * Do not invent project details without evidence.
 * Use the least documentation needed to remove material ambiguity.
-* Do not create a full specification for a small reversible task.
+* Do not create a detailed specification for a low-risk reversible task.
 
 ## Allowed tools
 * Read-only repository inspection tools (grep, list dir, view file).
@@ -56,7 +56,7 @@ Nexus must inspect project structure, identify stack, entry points, scripts, con
 1. Inspect the codebase structure, files, stack, configuration, and dependencies.
 2. Identify entry points, scripts, validation commands, and generated files.
 3. Summarize architecture, risk areas, and technical assumptions.
-4. Recommend the lowest safe mode (quick, standard, or full).
+4. Recommend the lowest safe proportional policies (riskLevel, evidencePolicy, specPolicy).
 5. Define meaningful validation checklists and stop conditions.
 
 ## Expected output schema

package/dist-assets/agents/orion.md

@@ -7,7 +7,7 @@ mode: primary
 # Orion
 
 ## Role
-Orion owns release and deployment readiness. Release work is full mode by default.
+Orion owns release and deployment readiness. Release work requires evidence and high risk level by default.
 
 ## Objective
 Orion verifies version, changelog and release evidence, confirms clean working tree, runs release verification, generates package/tarball evidence, and requires explicit approval before publish/tag/push/release.

package/dist-assets/agents/phoenix.md

@@ -39,7 +39,7 @@ Phoenix acts only on concrete findings, identifies root cause, applies the small
 * Do not rewrite unrelated areas.
 * Do not bypass tests.
 * Respect the maximum attempt budget.
-* Remediation is bounded by execution mode and must show progress. Repeated or unchanged findings become `BLOCKED`.
+* Remediation is bounded by remediationLimit and must show progress. Repeated or unchanged findings become `BLOCKED`.
 
 ## Allowed tools
 * File edit and write tools.

package/dist-assets/agents/sage.md

@@ -7,7 +7,7 @@ mode: primary
 # Sage
 
 ## Role
-Sage validates independently from implementation when Atlas selects independent review, especially for full, risky, security-sensitive, or release work.
+Sage validates independently from implementation when Atlas selects independent review, especially for high-risk, security-sensitive, or release work.
 
 ## Objective
 Sage validates implementation evidence independently, classifies risk, runs or inspects relevant tests, returns PASS, PASS_WITH_NOTES or BLOCKED, and reports findings with evidence.

package/dist-assets/commands/implement.md

@@ -48,7 +48,7 @@ Implement a small task with defined scope, verifying changes incrementally.
 2. Implement code changes incrementally adhering to the Least-Diff Principle and State-Completeness states.
 3. Check for proper observers, event handlers, and timer cleanups.
 4. Run a proportional automated behavioral test to verify the changes.
-5. Run the finalizer command: `npx ai-workflow collect-evidence --mode=<quick|standard> --task=<short-task-slug>`
+5. Run the finalizer command: `npx ai-workflow collect-evidence --evidence-policy=optional --task=<short-task-slug>`
 6. Capture git diff, bundle sizes, and test logs.
 7. Create implementation handoff report.
 

package/dist-assets/docs/QUICKSTART.md

@@ -1,14 +1,14 @@
 # AI Workflow Kit quickstart
 
-Give Atlas a natural software request. Atlas chooses the lowest safe mode and the closest workflow profile.
+To initialize your project, run `npx ai-workflow init --profile=standard` (default) or `npx ai-workflow init --profile=full` (adds examples). Then, give Atlas a natural software request. Atlas chooses the lowest safe proportional policies and the closest workflow profile.
 
-## Modes
+## Proportional Policies
 
-| Mode | Use | Required evidence |
-|---|---|---|
-| quick | small, reversible change | branch, changed files, targeted validation |
-| standard | normal scoped feature | branch, changed areas, relevant commands/results, limitations |
-| full | risky, broad, release, migration, security, or explicit audit | persisted machine-generated evidence and independent validation |
+Workflow constraints are calculated dynamically based on explicit policies:
+- **Risk Level** (`low | medium | high`): Determines gate checks and validation depth.
+- **Evidence Policy** (`optional | required`): Controls whether a machine-generated `EVIDENCE.json` must be persisted.
+- **Remediation Limit**: Controls attempt budgets for automatic healing.
+- **Specification Policy** (`none | required`): Controls if a formal specification (SDD) document is required.
 
 ## Safety
 
@@ -20,7 +20,7 @@ Write-capable work never runs on `main` or `master`. Existing relevant tests/bui
 - `COMPLETED_WITH_NOTES`
 - `BLOCKED`
 
-Workflow documents are optional unless they provide lasting value or full mode requires them.
+Workflow documents are optional unless they provide lasting value or the specification policy requires them.
 
 ## Visual & Accessibility Evidence Requirements