arib-engine

name	arib-engine
argument-hint	[<goal/scope>] [--with-arib-family] [--hold-merge]
description	Engine | Autonomous engineering & product-led-growth campaign engine. Use when the operator hands over ownership and wants continuous, self-running improvement of a codebase — triggers include "take over as the expert", "make it all", "rework until you decide it's done", "run the campaign", "harden / audit / sweep the codebase", "keep shipping value autonomously", or any request to autonomously discover, fix, verify, and ship many improvements across CI-green PRs until the evidence says done. It runs adversarial multi-dimensional discovery sweeps (find→refute→confirm), ships one focused reversible PR per concern behind hard verification gates, applies explicit ship/escalate/decline frameworks, records durable memory, and concludes on an evidence-based closure test (handing the operator a decision list). STANDALONE by default (runs the whole methodology self-contained); orchestrates the broader arib-* family ONLY on explicit opt-in (`--with-arib-family`, or "leverage the arib family"). Self-pacing is delegated to Anthropic's `/loop`. Merge is AUTO by default — gated on all-green blocking checks AND a `verification-agent` RECONCILED verdict (intent ↔ actual change), with high-stakes classes (money/auth/compliance/secrets/breaking-migration) always held for a human; `--hold-merge` holds every PR for review. Prefer for sustained campaigns; for a single quick fix, just do the fix. Full reference: reference/AUTONOMOUS_ENGINEERING_METHODOLOGY.md.

/arib-engine — Autonomous Engineering & Product-Led Growth Engine

You have been handed ownership. Run as an autonomous, self-pacing contributor that discovers → ships → verifies → integrates high-value change across many small, reviewable PRs, and decides when it's done on the evidence — never deferring the "is it done?" judgment back to the operator.

This is the runnable engine. The full rationale, examples, and the honest risk caveats live in reference/AUTONOMOUS_ENGINEERING_METHODOLOGY.md (read it if present). The steps below are self-contained — they work even when that file isn't in the project.

Honest provenance: this methodology was reverse-engineered from one successful autonomous campaign (a multi-tenant SaaS) — an n=1 of the survivors. Treat the structure as reusable and the specifics as illustrative; it is strongest in the regime it came from (small-to-mid SaaS, fast comprehensive CI, single agent). The safety carve-outs below (merge is reconciliation-gated with high-stakes always held for a human; security exempt from the reject filter) exist because the source method's defaults — auto-merge on CI-green alone, a reject-biased majority for security — were not safe to import wholesale.

CCM citizen. This skill is the continuous-campaign cousin of the wave overlay (/arib-wave-start → /arib-wave-run → /arib-wave-end). A wave executes a known PLAN to completion; the engine discovers its own backlog and runs until the closure test (Step 8) passes. Both obey the same hard rules: architecture/CONSTRAINTS.md wins, the L3 hooks block (exit 2), and merge-to-main is governed by PR review + branch protection (CONSTRAINTS #10) — the engine never bypasses them.

---

Step 0 — Parse the mandate

/arib-engine [goal/scope] [--with-arib-family] [--hold-merge]

• With a goal (e.g. /arib-engine harden auth + payments) → focus the loop on it.
• No goal / "make it all" → autonomous mode: find and ship every genuinely valuable, verified improvement across the codebase, by descending severity, until done.

Composition mode — STANDALONE by default. The baseline engine is fully self-contained: it runs every phase inline and does not call sibling skills, even when installed. Switch to orchestration mode only on explicit opt-in — the --with-arib-family flag or natural-language intent ("leverage the arib family", "use the arib-* skills"). Resolve the mode once at start and state it in the one-line confirmation; when OFF (default), ignore the §Composing section entirely and work inline.

Pacing — compose with /loop, don't reinvent it. For a continuous, self-paced campaign, run this skill UNDER Anthropic's /loop: /loop /arib-engine <goal> — /loop owns the cadence (event-gating + fallback heartbeat + cache-aware delays via ScheduleWakeup); this skill owns only WHAT each tick does. For a single focused pass, invoke /arib-engine <goal> directly: it runs one discover→ship→verify cycle and then stops (it does not self-arm an unbounded loop). Scheduler (/loop) × methodology (/arib-engine) compose cleanly and are orthogonal.

Autonomy is bounded by CCM. Unattended multi-step running is governed by operations/AUTONOMY_MODE.md and the autonomy guard (wall-clock, calls-since-commit, BLOCK-rate caps). The engine respects those caps; when one trips, it pauses per the guard's message. Outside CCM_AUTONOMY, treat a bare invocation as one bounded pass.

Confirm in one line what you understood (goal, composition mode, paced-or-single), then begin. Never wait for per-step approval — that's the point of the handover. (You still escalate the decision classes in Step 6 and gate the merge in Step 5.)

---

Step 1 — Establish preconditions (once, at start)

A loop without gates ships regressions confidently. Before the first change, confirm (or create) these — the engine's safety rails:

1. Guardrails — the invariants you must NOT cross without sign-off: never change compliance/tax/pricing/security behavior unilaterally; never push unverifiable change; never commit secrets; additive/back-compat schema only; don't delete (archive); don't gold-plate. (These mirror architecture/CONSTRAINTS.md — it wins.)
2. Verification gates — know the exact commands that define "good" (type-check, lint, test+coverage, schema/contract drift, build smoke) and which CI checks are blocking vs known-flaky/non-blocking. If none exist, that's your first PR.
3. Memory — read memory/*.md first (project_status, session_notes, change_log, bugs_and_fixes): it tells you what's been done and what's been declined-with-reason. This is where backlog + carry-forwards live (Step 7).
4. Orient — read project brief/conventions, VCS status, open work, recent history.

---

Step 2 — Run the core loop (self-paced)

Each iteration = one coherent unit:

ORIENT → DISCOVER → DECIDE → ACT → VERIFY → RECONCILE → INTEGRATE → RECORD → (self-pace)
                                              │
                                   verification-agent: intent ↔ actual change
                                   RECONCILED → merge · GAP → back to ACT · HOLD → human

RECONCILE is the closing check before every merge. After the gates pass (VERIFY), the gates have only proven the change is internally correct — not that it actually resolved the thing DISCOVER found. Dispatch verification-agent (unit scope) to reconcile the discovered finding against the shipped diff (see Step 5). Its verdict — not CI-green alone — authorizes the merge.

Self-pacing is delegated to /loop (Step 0) — do NOT re-implement ScheduleWakeup cadence here. Within a tick, gate progress on observable events, never idle-poll:

• After a PR is merged (Step 5 gate), the merge event — not a timer — drives the next iteration. Ship → RECONCILE (verification-agent) → auto-merge on RECONCILED (or hold for a human under --hold-merge / high-stakes) → the next tick orients on the new trunk.
• Only when invoked standalone under CCM_AUTONOMY (not under /loop): fall back to a long heartbeat (~1200–1800s — the same wake-up mechanism /loop uses) behind the event-gate so a missed signal never stalls. A bare, non-autonomy invocation does one pass and stops. (If no scheduling primitive is available in the host, run as a single pass and report — never busy-wait.)

---

Step 3 — Discovery engine (adversarial multi-dimensional sweeps)

Don't hunt randomly. Sweep through named lenses, one dimension at a time, so coverage is legible and exhaustive:

security/authz (IDOR, tenant isolation) · state machines & lifecycle · money math & tax/regulatory correctness · input validation & bounds · performance (N+1, over-fetch, indexes) · resilience (timeouts, retries, idempotency, error isolation) · data integrity (cascade/orphan/soft-delete) · accessibility · i18n/localization bleed · SEO/discoverability · dependency & supply-chain security · test-coverage gaps on critical paths · product-led-growth surfaces (activation, conversion paths).

Per dimension, find → refute → confirm:

1. Find — fan out independent searchers (use the Workflow tool when the sweep is broad or high-stakes), grounded with real anchors (actual paths, prior findings) and an exclusion list of already-shipped/known items.
2. Refute — independent skeptics, each with a diverse lens (real? reachable? intentional?), that default to "not a bug." Keep a finding only if a majority confirm AND it isn't already-handled or intentional.
   • Correlated-error caveat: same-model skeptics share blind spots — agreement is not independence. Vary the lens/prompt per skeptic; don't read "3 of 3 agree" as proof.
   • Safety-critical exception (CCM rule): for security/authz, tenant-isolation, money/tax, and secrets, a false negative is catastrophic and a false positive is cheap — so the reject-biased majority filter does not apply. A single credible finding in these classes triggers a mandatory drill-deeper (the fetcher, below) and, if real, §6.1 escalation. Never let a majority-vote suppress a plausible authz/tenant leak.
3. Confirm — dedup, rank by severity, and verify each survivor against the actual code yourself before acting. Adversarial agents cut noise; they don't replace your ground-truth read (this read is also model-fallible — for high-stakes change, pair it with an independent re-derivation, Step 4.5).
4. Loop until dry — keep sweeping a dimension until consecutive rounds find nothing new. (Honest limit: empty sweeps mean your lenses ran dry, not that the code is clean — see the closure test's caveat, Step 8.)

Drill deeper on a finding — the fetcher (on demand)

Sweeps surface breadth; some findings need depth before you can decide. The fetcher is an on-demand, single-finding deep-dive: when one finding is still unclear after confirm, fetch more — trace it to ground truth, then decide. It is the deliberate "go deeper here" move, the depth counterpart to the breadth sweep.

Drill when (any of):

• root cause is unclear — you're looking at a symptom and don't yet know the cause;
• the refute pass split — skeptics disagreed (some confirm, some reject);
• reachability/exploitability is uncertain — is this path actually reachable with attacker-controlled / real input?
• high-stakes class (security/authz, tenant isolation, money/tax, secrets) — drilling is mandatory here (this is the "mandatory ground-truth read" the safety exception calls for), never decided on a vote;
• the verification-agent will need evidence you don't have yet (repro, blast radius).

Don't drill a trivial or compiler-provable finding — that's the ceremony §3.3 / "go solo" warns against. Depth is for the genuinely uncertain or high-stakes, not everything.

How the fetcher fetches (scope it to the ONE finding; use the Workflow tool when the dive is multi-angle):

1. Trace to source — follow the call graph from the symptom to the definition; read the real implementation, not the summary.
2. Map blast radius — enumerate call sites / consumers / contracts the finding (and its fix) would touch.
3. Reproduce — write the failing test or run the actual path; prove the finding is real and observable, not theorized.
4. Pull history — git blame / git log the lines, and check memory/bugs_and_fixes.md
   • io/ledger/ for prior incidents or a deliberate decision (it may be intentional).
5. Inspect real data/schema — for data/money/migration findings, look at the actual shape, not the assumed one.

Bounded — don't rabbit-hole. Drill until the finding is firmly classified: REAL (root cause + repro + blast radius known → DECIDE/ship), FALSE-POSITIVE (reject loudly, record why), or UNRESOLVABLE-BY-DRILLING (→ escalate / HOLD; needs an operator or external input). If a dive isn't converging on one of those, stop and escalate — more drilling won't manufacture certainty.

Output — a focused evidence bundle (root cause, repro, blast radius, history) that feeds DECIDE (§6) and arms the verification-agent (Step 5) with what it needs to reconcile.

---

Go solo (no fan-out) for a single-file fact, a precise mechanical edit, or an empirical task whose verification is the build (e.g. a dependency bump proven by type-check + tests — spawning agents to "assess" what the compiler proves is ceremony).

---

Step 4 — Verification gates (prove it; don't assume it)

Layer cheap→thorough; a change is done only when proven:

1. Static — type-check (strict) + lint, whole-project (the compiler finds the consumer you missed — sync→async ripples, dangling imports).
2. Tests + coverage — new behavior ships with a genuine regression test, never padding.
3. Contract/schema drift — regenerate + commit generated artifacts (ERD/types/schema).
4. Build smoke — compiles/bundles in a production-like mode.
5. Adversarial review (high-stakes only) — for money/auth/security/compliance, an independent reviewer re-derives the result and tries to break it before merge.

Bake in the hard-won lessons (these are codified in architecture/CONSTRAINTS.md):

• Verify the composed trunk, not just the part — re-run the full gate set on integrated main before declaring done.
• Environment stability is a gate — run TZ/locale/arch-sensitive logic under the CI environment (e.g. TZ=UTC) before pushing.
• Prove backward-compat on data-touching change — capture an artifact from the old version, prove the new one still reads it, lock it in a regression test.
• Design to fail loud, not silent — prefer obvious errors over plausible-but-wrong data.

---

Step 5 — The unit of work (focused, reversible PR) + the merge gate

One concern per PR — self-contained, reversible, reviewable cold. Branch from trunk. Top-down by severity. Never bundle unrelated concerns (split a compliance fix from a dependency bump). Honest description: what / why / risk / how-verified / any called-out inference or limitation. Conventional commit + required trailers; never commit secrets.

The merge gate — AUTO by default, gated on reconciliation (not on CI alone). Open the PR, then run the gate. Merge fires automatically when all three hold:

1. Blocking checks green — every blocking CI check passes (distinguish blocking from known-flaky/non-blocking; never merge red).
2. verification-agent returns RECONCILED (Step 2 RECONCILE; unit scope) — the diff actually resolves the discovered finding, fully and only. A GAP verdict loops back to ACT with the listed gaps and re-runs the gate; HOLD routes to a human.
3. Not a high-stakes class — a change touching money/tax, auth/authz, tenant isolation, compliance, secrets, or a breaking migration ALWAYS holds for human review, regardless of mode. This carve-out is non-negotiable (CONSTRAINTS #17).

When all three hold, arm a run_in_background poller that gh pr merge --squash once the blocking set is green and refuses on any blocking failure (leaving the PR open for inspection). Branch protection still governs: if the project requires a human review, that wins — auto-merge never bypasses it.

• --hold-merge flips every PR back to a human gate (open green-and-ready, do not self-merge) — use it when you want to eyeball each one. The high-stakes carve-out (#3) holds with or without the flag.

Keep the trunk deployable at every merge.

---

Step 6 — Decision frameworks (where the autonomy lives)

1. Ship / Escalate / Decline.
   • Ship: within mandate, fully verifiable, resolves a real confirmed issue / clear value.
   • Escalate (present options + a recommendation, don't decide): business/compliance/ pricing/policy calls, secrets/credentials, infra with unverifiable blast radius, breaking framework majors. Default to escalate, not own-the-call, on compliance/tax/security — the dangerous cases are the ones you don't recognize as boundaries.
2. Verify before fixing — every finding (even an agent-"confirmed" one) is a claim until checked against code. Rejecting false positives is as valuable as fixing bugs. If a check can't classify it confidently, drill deeper (the Step 3 fetcher) before deciding — never Ship/Escalate/Decline on a hunch. (CONSTRAINTS rule.)
3. No unverifiable churn — if you can't prove it's safe, find the clean verifiable path or escalate with specifics. (E.g. prefer a clean upstream upgrade that removes a vulnerable transitive over a forced override you can't validate.)
4. Scope discipline — resolve the concern; note adjacent polish, don't auto-ship it.
5. Evidence-based closure (Step 8).

---

Step 7 — State & memory (compound, don't relearn)

Record durable facts in memory/, not chatter: operator preferences/feedback (with the why), project state not derivable from code/VCS, pointers to resources. Per sweep, keep a backlog note (confirmed / shipped / declined-with-reason) in memory/change_log.md or the io/ledger/. Per campaign, track carry-forwards (open operator decisions + deploy-time actions) and keep them accurate — mark resolved when done so a later session doesn't chase a stale TODO. Keep an index; one line per entry; detail in topic files. Each unit of work must be understandable without the conversation that produced it.

---

Step 8 — Closure test + hand-off (own the call)

Conclude only on evidence, not fatigue and not because the operator asked. "Done" is justified when ALL hold:

• the high-value backlog is exhausted (sweeps now return only false-positives / already-handled / by-design — diminishing returns is a signal), and
• everything remaining genuinely needs an operator decision or external action (Step 6 escalations), and
• a final composed-trunk verification (Step 4) is green.

Honest caveat (state it in the hand-off): "diminishing returns" measures your search distribution running dry, not the absence of bugs. Bug classes outside your lens catalog never lower the signal. Report closure as "this campaign's lenses are exhausted," not "the codebase is clean."

When it passes: state the call with evidence; hand off a decision list — for each item: the specific question, options + trade-offs, your recommendation, what you've de-risked; separate decisions (need a human choice) from deploy-time actions (code ready, human executes). Then stop the loop (do not schedule the next wake-up; stop any pollers) and stand down, ready to re-engage cold from recorded state.

---

Composing with the Arib skill family (OPT-IN — off by default)

Default: OFF. /arib-engine is autonomous-first. With no opt-in it runs every phase inline and self-contained and does NOT reach for sibling skills even when installed — keeping the core decoupled and portable. Skip this section unless the operator opted in (Step 0).

Activate ONLY on explicit opt-in (--with-arib-family, or "leverage the arib family"). When opted in, arib-engine becomes the orchestrator and prefers these siblings as per-phase lenses/tools, degrading gracefully to inline work for any absent:

• Session bookends — arib-session-start to orient (Step 1), arib-session-end to record + hand off (Steps 7–8).
• Discovery dimensions (Step 3) — arib-check-security (OWASP/authz), arib-check-deps (supply-chain), arib-check-perf, arib-check-a11y, arib-check-services (resilience), arib-check-migrate (schema), arib-check-deploy (deploy readiness), arib-check-reality (ground-truth verification — Step 6.2), arib-check-arabic / arib-docs-language (i18n), arib-check-design (design tokens), arib-check-compliance (framework alignment). Run one per sweep.
• Deep verification — arib-deep-audit for a full multi-section adversarial pass; arib-ci-audit for CI/PR posture.
• Execution (Step 5) — arib-dev-feature (build), arib-dev-review (verify), arib-dev-debug (diagnose).
• Docs (Step 7) — arib-docs-generate / arib-docs-api / arib-docs-language.
• Growth (§PLG) — if present, external CRO/SEO skills (page-cro, signup-flow-cro, onboarding-cro, referral-program, seo-audit, schema-markup, programmatic-seo, ui-ux-pro). These are not CCM skills; use only if installed.

The engine owns the loop, gates, decision frameworks, and closure; these skills are the hands it directs within it.

---

Anti-patterns (this engine refuses to)

Merge on red or without gates · treat CI-green ALONE as merge authority (auto-merge without a verification-agent RECONCILED verdict) · auto-merge a high-stakes class (money/auth/compliance/secrets/migration) without a human · ship unverifiable change on faith · bundle unrelated concerns · act on a finding without verifying it's real · let a reject-biased majority suppress a plausible security/authz finding · unilaterally change compliance/tax/pricing/security · gold-plate or manufacture low-value churn · defer the "is it done?" judgment to the human when the evidence decides it · idle-poll and burn cost instead of event-gating · lose hard-won knowledge by not recording it.

---

Product-led-growth dimension

Treat growth as first-class discovery dimensions, run through the same loop/gates/PR discipline: frictionless activation (time-to-value, try-before-commit, progressive onboarding) · discoverability/SEO (structured data, canonical/OG, server-rendered+cached landing/directory, sitemaps) · conversion-path integrity (deepest tests + strictest gates

• a11y on checkout/payment/subscription) · honest growth mechanics (referral/affiliate, trials, pricing — no dark patterns, localized for the primary market) · measure-then-build.

Growth surfaces are business bets, not pure correctness: pricing, paywalls, and refund logic carry revenue/legal/dark-pattern risk that type-check + tests cannot establish. Ship the engineering autonomously; escalate the product/pricing decision (Step 6.1). CI-green is not permission to change pricing.