aiwg 2026.5.4 → 2026.5.6

package/CLAUDE.md

@@ -663,10 +663,10 @@ Before pushing a version tag:
    npm run uat:serve-live
    ```
    Tests skip cleanly when `AIWG_SANDBOX_ENDPOINT` is unset or unreachable, so this is a safe no-op gate. Run before any release that touches `src/serve/`, the executor contract, or the MC ↔ serve bridge.
-5. **Commit and tag** - `git tag -m "vX.X.X" vX.X.X`
-6. **Push tag to Gitea** - `git push origin main --tags` (automatically creates Gitea Release)
-7. **Optionally mirror to GitHub** - `git push github main --tags`
-8. **Update/Create GitHub Release manually** - via `gh release create|edit`
+5. **Commit the release prep** — `git commit` the package.json/CHANGELOG/announcement bump. Do NOT use plain `git tag -a` or `git tag -s` (they sign with `user.signingkey`, which is typically the maintainer's *personal commit-signing key* — wrong key for tags; the supply-chain gate `tools/ci/verify-signed-tag.sh` will reject in CI).
+6. **Cut the tag via the wrapper** — `tools/release/cut-tag.sh <X.Y.Z>`. Runs 10 pre-tag checks (CalVer shape, `package.json` + `marketplace.json` lockstep, CHANGELOG entry, announcement file present, release-signing key both present locally AND published in `.gitea/keys/maintainers.asc`) and signs with `-u <RELEASE_KEY_FINGERPRINT>` (default: `FE9272F0BC5781E1DE77FAAA719AB63879E84CE8`, the `AIWG Release Signing <release@aiwg.io>` key per the two-key model from commit `a13dabc5`). See the v2026.5.5 incident note in `docs/contributing/versioning.md` for what happens when this is skipped.
+7. **Push tag to Gitea** — `git push origin main --tags`. Triggers `gitea-release.yml` + `npm-publish.yml` (both gated on signed-tag verify).
+8. **Mirror to GitHub** — `git push github main --tags`. Triggers `github-mirror.yml` which creates the GitHub Release using `docs/releases/v<version>-announcement.md` as the body. **No manual `gh release create` needed for stable releases** — the workflow handles it. Pre-release tags (`-rc.*`, `-alpha.*`, `-beta.*`, `-nightly.*`) skip GitHub-Release creation by design.
 
 ### Version Format
 

package/README.md

@@ -49,6 +49,17 @@ AIWG is a deployment tool and support utility for AI context. At its core, `aiwg
 
 Around that core, AIWG ships utilities for things the base platforms do not handle on their own: persistent artifact memory (`.aiwg/`), background orchestration (`aiwg mc`), autonomous loops (`aiwg ralph`), artifact indexing (`aiwg index`), cost telemetry, health diagnostics, and more. Most are opt-in. The deployment layer works standalone as plain text files the platform reads natively.
 
+### Project scope (recommended) vs user scope (global)
+
+`aiwg use` writes artifacts at one of two scopes. Both are first-class supported (see ADR-NUA-001 in `.aiwg/studies/novice-user-adoption/`):
+
+- **Project scope** — default. Run `aiwg use sdlc` from a project root and the artifacts land in `./.claude/agents/`, `./.claude/skills/`, etc. One project's agent set never bleeds into another's session. **This is the recommended default for most use cases.**
+- **User scope (global install)** — `aiwg use sdlc --scope user` writes to `~/.claude/agents/`, `~/.claude/skills/`, etc. Same artifact set loads into every session, regardless of project. Fits "AIWG in every conversation" workflows and is the canonical mode for OpenClaw and Hermes (whose primary discovery is user-scope).
+
+The trade-off is real: when the same agent set loads into every session, context from one project can bleed into reasoning about another. Research (REF-720, *Lost in Multi-Turn Conversation*, MSR/Salesforce 2025) measured a 39% capability drop when this happens. The non-blocking project-isolation warning surfaces the trade-off at deploy time so the scope choice is informed. Neither scope is wrong; pick the one that fits the workflow.
+
+See `docs/cli-reference.md` (under `aiwg use` → "Scope models") for the per-provider details and the global-install rough-edge inventory.
+
 ## Simple Building Blocks
 
 AIWG ships five primitive artifact types. All are plain text:

package/agentic/code/addons/agent-loop/agents/ralph-verifier.md

@@ -14,6 +14,12 @@ allowed-tools: Bash, Read, Glob
 
 You verify completion criteria for agent loops - determining if a task iteration succeeded by running verification commands and analyzing their output.
 
+## Companion skill
+
+When the loop is started without explicit `--completion`, the criterion you verify is produced by the `infer-completion-criteria` skill (`@$AIWG_ROOT/agentic/code/addons/agent-loop/skills/infer-completion-criteria/SKILL.md`). It derives a measurable criterion from project docs (CLAUDE.md / AGENTS.md / AIWG.md), package manifests, CI configuration, and `.aiwg/` artifacts.
+
+You do not run that skill yourself — the loop orchestrator (`ralph-loop` agent or external launcher) calls it during initialization. Your job is to take whatever criterion is in the loop state and verify it. The skill writes its rationale into `.aiwg/ralph/<loop-id>/progress.md` (or `.aiwg/ralph-external/<run-id>/inferred-completion.yaml` for external loops); when reporting verification results, you may reference that rationale so the user sees the full evidence chain.
+
 ## Capabilities
 
 ### Verification Methods

package/agentic/code/addons/agent-loop/manifest.json

@@ -50,7 +50,8 @@
     "execute-feedback",
     "reflection-injection",
     "auto-test-execution",
-    "mission-control"
+    "mission-control",
+    "infer-completion-criteria"
   ],
   "agents": [
     "ralph-loop",

package/agentic/code/addons/agent-loop/skills/agent-loop/SKILL.md

@@ -74,7 +74,19 @@ Alternate expressions and non-obvious activations (primary phrases are matched a
 
 ### Completion Inference
 
-When user doesn't specify explicit verification:
+When the user doesn't specify explicit verification, delegate to the **`infer-completion-criteria`** skill (`@$AIWG_ROOT/agentic/code/addons/agent-loop/skills/infer-completion-criteria/SKILL.md`). That skill runs a deterministic 5-layer pipeline:
+
+1. **Task verb** → criterion class (test-pass, type-clean, regression-gate, coverage, lint-clean, build-pass, implement-feature)
+2. **Project context files** (CLAUDE.md / AGENTS.md / AIWG.md) → canonical commands from the Development section
+3. **Package manifests** (`package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `pom.xml`, etc.) → discovered scripts
+4. **CI configuration** (`.github/workflows/`, `.gitea/workflows/`, GitLab/CircleCI/Jenkins) → team's actual "passes" definition
+5. **`.aiwg/` artifacts** (test-strategy, related use cases by ID match, prior progress files) → project-specific gates
+
+Synthesis is validated against the `vague-discretion` rule and emits a structured YAML proposal with criterion, verification command, rationale chain, confidence level, and alternatives considered.
+
+**Use the inline table below ONLY as a last-resort fallback** when the inference skill is unavailable (degraded environment, missing skill deployment). It is intentionally narrow — JavaScript/Node-centric — and represents prior state before `infer-completion-criteria` was added.
+
+Legacy fallback table:
 
 | Task Pattern | Inferred Completion |
 |--------------|---------------------|
@@ -86,6 +98,8 @@ When user doesn't specify explicit verification:
 | "migrate to ESM" | "node runs without errors" |
 | "refactor X" | "npm test passes" (preserve behavior) |
 
+When the inference skill IS available, prefer it. The skill handles multi-language projects, monorepos, CI-defined gates, use-case acceptance criteria, and the refusal case (truly vague tasks like "make it better" that have no measurable criterion).
+
 ### Examples
 
 **User**: "ralph this: migrate all files in lib/ to ESM"
@@ -301,7 +315,9 @@ User: "actually, abort that and just fix the login bug"
 
 ## Related
 
-- `ralph` skill - the iterative loop executor implementation
+- `infer-completion-criteria` skill - derives measurable `--completion` from project state when the user doesn't supply one
+- `ralph` skill - the iterative loop executor implementation (legacy name; `agent-loop` is canonical)
+- `agent-loop-ext` skill - crash-resilient external loop with state persistence
 - `ralph-status` skill - check loop progress
 - `ralph-resume` skill - continue interrupted loops
 - `ralph-abort` skill - abort active loops

package/agentic/code/addons/agent-loop/skills/agent-loop-ext/SKILL.md

@@ -5,7 +5,7 @@ legacyName: ralph-external
 platforms: [all]
 description: Crash-resilient external agent loop with state persistence and CI/CD integration
 commandHint:
-  argumentHint: "\"<objective>\" --completion \"<criteria>\" [--max-iterations N] [--timeout M] [--provider <p>] [--no-commit] [--branch <name>] [--quiet]"
+  argumentHint: "\"<objective>\" [--completion \"<criteria>\"] [--max-iterations N] [--timeout M] [--provider <p>] [--no-commit] [--branch <name>] [--quiet] [--auto-criteria | --no-infer-completion]"
   allowedTools: Bash, Read, Write
   model: sonnet
   category: automation
@@ -60,7 +60,7 @@ Users may say:
 ### Objective (required)
 The task the loop should accomplish. Passed as the first positional argument.
 
-### --completion (required)
+### --completion (optional — inferred when omitted)
 Success criteria as a verifiable command. The loop exits when this command returns exit code 0.
 
 **Good examples**:
@@ -68,6 +68,14 @@ Success criteria as a verifiable command. The loop exits when this command retur
 - `--completion "npx tsc --noEmit exits with code 0"`
 - `--completion "coverage report shows >80%"`
 
+**When omitted**: the launcher invokes the `infer-completion-criteria` skill before the external loop starts. The skill derives a measurable criterion from project state (CLAUDE.md / AGENTS.md / AIWG.md, package manifests, CI configuration, `.aiwg/` artifacts) and emits a structured proposal with rationale. The proposal is written to `.aiwg/ralph-external/<run-id>/inferred-completion.yaml` and used as the loop's gate.
+
+Because `agent-loop-ext` runs externally (potentially headless / in CI), the confirmation flow is:
+- Interactive session (TTY attached): show proposal, accept `Y / n / edit` like the in-session `ralph` skill
+- Non-interactive / `--auto-criteria` / CI environment: use the inferred criterion if confidence is `high`, otherwise fail fast and print the proposal as a diagnostic so the user can re-launch with `--completion` explicitly
+
+Pass `--no-infer-completion` to require explicit `--completion` and fail before launch if missing. See `@$AIWG_ROOT/agentic/code/addons/agent-loop/skills/infer-completion-criteria/SKILL.md`.
+
 ### --max-iterations (default: 10)
 Maximum iterations before the loop halts and saves state for manual review.
 
@@ -90,8 +98,12 @@ Suppress verbose progress output. Completion banner is always shown.
 
 When triggered:
 
-1. Validate that `--completion` criteria are specified and verifiable
-2. Check for an existing `.aiwg/ralph-external/` workspace; create if absent
+1. **Resolve completion criteria**:
+   - If `--completion` is provided → use it directly
+   - Else if `--no-infer-completion` is set → fail fast before launch with a helpful error
+   - Else → invoke `infer-completion-criteria` skill, persist proposal to `.aiwg/ralph-external/<run-id>/inferred-completion.yaml`, confirm or auto-adopt per session-interactivity rules above
+2. Validate the resolved criterion is verifiable (can be checked via command)
+3. Check for an existing `.aiwg/ralph-external/` workspace; create if absent
 3. Generate a unique `loop-id` (8-character hex) and create the loop state file at `.aiwg/ralph-external/loops/<loop-id>.json`
 4. Write the initial state: `{ objective, completionCriteria, maxIterations, timeout, provider, status: "pending", iteration: 0 }`
 5. If `--branch` is specified, create the git branch now

package/agentic/code/addons/agent-loop/skills/infer-completion-criteria/SKILL.md

@@ -0,0 +1,323 @@
+---
+namespace: aiwg
+name: infer-completion-criteria
+aliases: [agent-loop-infer-completion, al-infer-completion, ralph-infer-completion]
+platforms: [all]
+description: Infer measurable completion criteria for an agent-loop task from project docs, code, and AIWG standards when the user has not supplied --completion explicitly
+commandHint:
+  argumentHint: '"<task description>" [--task-type code|test|docs|refactor] [--non-interactive]'
+  allowedTools: "Read, Glob, Grep, Bash"
+  model: sonnet
+  category: automation
+---
+
+# Infer Completion Criteria
+
+## Purpose
+
+When a user starts an `agent-loop` task without supplying `--completion`, this skill derives a measurable, verifiable completion criterion from project state. The output must satisfy the `vague-discretion` rule: a concrete shell command or file-inspection check that returns pass/fail unambiguously.
+
+Iteration is only as good as its gate. A loop with a vague gate ("until it's done") runs forever or exits prematurely. This skill is what turns "agent-loop this" into "agent-loop this until `<measurable thing>`."
+
+The canonical name for the iterative-loop addon is **agent-loop**. `ralph` is the legacy name for the executor skill, retained as an alias; `al` is a short form. The detection/routing skill is `agent-loop` (which delegates to this skill when criteria are missing); the executor is `ralph` (canonical name forthcoming). Everywhere this skill says "agent-loop" you can read "ralph" as the legacy equivalent.
+
+## When This Skill Runs
+
+This skill is invoked by:
+
+- The `agent-loop` detection-and-routing skill when it parses a user request without explicit completion criteria
+- The `ralph` executor skill during Phase 1 initialization when `--completion` is omitted
+- The `agent-loop-ext` external-loop launcher during pre-launch resolution when `--completion` is omitted
+- Direct invocation via `aiwg discover "infer completion"` → `aiwg show skill infer-completion-criteria` when a user wants to preview the inferred criterion before committing to a loop
+
+This skill does **not** run when `--completion` is explicit. The user's word is authoritative.
+
+## Inference Pipeline
+
+The skill is a deterministic walk through five evidence layers, plus one synthesis step. Each layer contributes candidate criteria; the synthesis picks the strongest measurable one and explains the chain of evidence.
+
+### Layer 1 — The task verb
+
+Parse the user's task description for an intent verb. Map to a default criterion class:
+
+| Verb / phrase | Criterion class |
+|---|---|
+| "fix tests", "make tests pass", "test failure" | Test suite passes (exit 0) |
+| "add tests", "increase coverage", "test coverage" | Coverage threshold met |
+| "fix types", "type errors", "migrate to typescript" | Type checker exits 0 |
+| "fix lint", "clean up warnings", "style" | Linter exits 0 |
+| "build", "make it compile" | Build command exits 0 |
+| "refactor", "extract", "rename" | Tests still pass AND build still passes (regression gate) |
+| "implement <X>", "add feature <X>" | Tests for the new code exist and pass |
+| "document", "add docs", "JSDoc" | Coverage check on docstrings/JSDoc presence |
+| "fix bug", "resolve issue #N" | Specific test for that bug passes AND existing suite still green |
+| "migrate", "upgrade" | Build + test + lint all green (no regression) |
+
+If the verb is ambiguous, the skill falls back to "regression gate" (build + test + lint all green) as the safest default.
+
+### Layer 2 — Project conventions in CLAUDE.md / AGENTS.md / AIWG.md
+
+Read the project's context files. AIWG-managed projects often declare commands directly:
+
+```bash
+# Run tests
+npm test
+
+# Type check
+npx tsc --noEmit
+
+# Lint markdown
+npm exec markdownlint-cli2 "**/*.md"
+```
+
+Extract these as the canonical commands for their respective domains. The Development section of `CLAUDE.md` is the highest-trust source here — it's what the project's maintainers run.
+
+Also scan for explicit completion-criterion conventions. Some projects state "a commit is not finished until CI passes" — that signals the CI command (or equivalent local invocation) is the gate.
+
+### Layer 3 — Package manifests and config
+
+Inspect the project's manifest files to discover scripts and tools:
+
+| Manifest | Where to look |
+|---|---|
+| `package.json` | `scripts.test`, `scripts.lint`, `scripts.build`, `scripts.coverage`, `scripts.typecheck` |
+| `Cargo.toml` | implies `cargo test`, `cargo build`, `cargo clippy` |
+| `pyproject.toml` | `[tool.pytest]`, `[tool.ruff]`, `[tool.mypy]`, `scripts.*` |
+| `go.mod` | implies `go test ./...`, `go vet ./...`, `go build ./...` |
+| `Gemfile` | implies `bundle exec rspec`, `bundle exec rubocop` |
+| `pom.xml` / `build.gradle` | `mvn test`, `mvn verify`, `gradle test` |
+| `.tool-versions` / `mise.toml` | language version pins inform which tool is canonical |
+
+When multiple scripts exist (e.g. `test`, `test:unit`, `test:integration`), prefer the script the project's own docs reference. If the docs don't reference any, prefer the most specific match to the task verb (e.g. for "fix integration test" → `test:integration`).
+
+### Layer 4 — CI configuration
+
+CI files encode the team's actual definition of "passes":
+
+| CI system | Scan |
+|---|---|
+| GitHub Actions | `.github/workflows/*.yml` — extract `run:` steps from non-deploy jobs |
+| Gitea Actions | `.gitea/workflows/*.yml` — same |
+| GitLab CI | `.gitlab-ci.yml` — extract `script:` from test/lint jobs |
+| CircleCI | `.circleci/config.yml` |
+| Jenkins | `Jenkinsfile` |
+
+The first non-trivial verification step in the primary workflow is the team's canonical "done" gate. If CI runs `npm test && npm run lint && npm run typecheck` in order, the inferred criterion is "all three exit 0."
+
+### Layer 5 — AIWG artifacts
+
+If the project has a `.aiwg/` directory, scan for relevant context:
+
+- `.aiwg/testing/test-strategy.md` — declared verification approach
+- `.aiwg/architecture/software-architecture-doc.md` — architectural quality gates
+- `.aiwg/security/security-gates.md` — security-related criteria
+- `.aiwg/quality/code-review-guide.md` — code quality bars
+- `.aiwg/activity.log` — recent operations that may indicate what "done" looked like for similar past tasks
+- `.aiwg/working/<related-progress-files>.md` — prior task progress files; mine the "Completion criteria" sections
+
+If the project has a related use case (`.aiwg/requirements/UC-*.md`) whose ID is in the task description, pull that use case's acceptance criteria — those ARE the completion criteria.
+
+### Synthesis step
+
+Combine the layers into a single proposed criterion. The decision logic:
+
+1. If a use case in `.aiwg/requirements/` matches the task, use its acceptance criteria verbatim. Done.
+2. Otherwise, take the verb-class default from Layer 1 and instantiate it using the canonical command from Layer 2 (CLAUDE.md) > Layer 4 (CI) > Layer 3 (manifest).
+3. If the task is in the "regression gate" class, AND the project's CI runs more than one verification, combine them: `command-A passes AND command-B passes AND command-C passes`.
+4. If no canonical command is found in any layer (unusual — typically only on empty-scaffold projects), fall back to:
+   - `<file or change exists in git diff against HEAD~1>` — pure structural check
+   - And inform the user that a substantive verification command should be added.
+
+### Apply AIWG standards (vague-discretion)
+
+Validate the proposal against the `vague-discretion` rule:
+
+- Criterion must be expressible as a shell command (or shell pipeline) that exits 0 on pass, non-zero on fail.
+- Criterion must NOT use the words "good enough", "thorough", "comprehensive", "complete" without a measurable suffix.
+- Criterion must NOT be self-referential ("the agent is satisfied" — no).
+- Criterion must have an implicit or explicit `max-iterations` cap (ralph's default 10 is the floor; very large refactors may need 20).
+
+If the proposal fails any of these, regenerate. If after two regenerations the proposal still fails, surface the problem to the user with the diagnostic ("could not find a measurable verification command — please supply one explicitly").
+
+## Output Contract
+
+The skill emits a single block of structured output for the calling skill (`agent-loop` router, `ralph` executor, or `agent-loop-ext` launcher) to consume:
+
+```yaml
+proposed_completion:
+  criterion: "npm test passes AND npx tsc --noEmit exits 0"
+  verification_command: "npm test && npx tsc --noEmit"
+  rationale:
+    - "Task verb 'refactor' triggers regression gate (Layer 1)"
+    - "package.json scripts.test = 'jest --coverage' (Layer 3)"
+    - "CLAUDE.md Development section references both npm test and npx tsc --noEmit (Layer 2)"
+    - ".github/workflows/ci.yml runs both as required checks (Layer 4)"
+  confidence: high  # high | medium | low
+  alternatives_considered:
+    - criterion: "npm run lint exits 0"
+      rejected_because: "Lint is not in CI required checks for this repo"
+  max_iterations_suggestion: 10
+  needs_human_confirmation: false  # true if confidence == low OR criterion is unusual
+```
+
+When the skill runs in non-interactive mode (via `aiwg al --auto-criteria` or the equivalent on `agent-loop` / `agent-loop-ext`), `needs_human_confirmation: false` proceeds directly. Otherwise the consuming skill (the `agent-loop` router or the `ralph` / `agent-loop-ext` executor) shows the proposal to the user and confirms.
+
+## Interaction With The User
+
+In interactive mode, after running the pipeline, present the proposal:
+
+```
+No --completion criteria was provided. I inferred:
+
+  Criterion: npm test passes AND npx tsc --noEmit exits 0
+  Verification: `npm test && npx tsc --noEmit`
+
+Evidence:
+  - Task verb "refactor" → regression gate
+  - package.json scripts.test = jest --coverage
+  - CLAUDE.md Development section references both checks
+  - .github/workflows/ci.yml requires both
+
+Proceed with this criterion? [Y/n/edit]
+```
+
+User options:
+- `Y` (default): start the loop with the inferred criterion
+- `n`: abort and request the user supply `--completion` explicitly
+- `edit`: accept a manual edit to the criterion before proceeding
+
+Use the platform's native interaction tool when available (per `native-ux-tools` rule). On Claude Code, that means `AskUserQuestion`.
+
+## When Inference Should NOT Run
+
+- `--completion` is explicit → use the user's criterion, don't second-guess
+- `--no-infer-completion` flag is passed → fail fast with a helpful error if `--completion` is also missing
+- The task description is itself a criterion (e.g. "make `npx tsc --noEmit` pass") → extract the command from the task, don't re-infer
+
+## Edge Cases
+
+| Case | Handling |
+|---|---|
+| No `package.json`, no manifest, no CI | Scan project root for any executable test runner (`pytest`, `go test`, `cargo test`, `make test`, `Makefile` target `test`). Fall back to the structural check if none found. |
+| Multiple test commands (`test:unit`, `test:integration`, `test:e2e`) | Prefer the one nearest to the task scope. If task mentions "unit", use `test:unit`. If the task is broad, prefer the union via `&&`. |
+| CI runs tests on multiple OS/Node versions | Use the local invocation (`npm test`), not the matrix runner. The matrix is a deploy concern. |
+| Monorepo with multiple packages | Detect from `pnpm-workspace.yaml` / `lerna.json` / `turbo.json` / workspaces field. If the task scope is one package, infer that package's commands. If the task spans the monorepo, use the top-level `test` script. |
+| Project has no tests at all | This is a finding. The inferred criterion should be "tests exist for the new code AND those tests pass." Surface to the user that the project lacks a baseline test suite — that's important context for the loop's expectations. |
+| Project's tests are currently broken (the task IS to fix them) | Set the criterion to the passing condition. The whole point of the loop is to get from current red state to green. |
+| Conflict between layers (CLAUDE.md says X, CI says Y) | Prefer CLAUDE.md (closer to the maintainer's intent). Note the discrepancy in the rationale. |
+
+## Interaction With Other AIWG Rules
+
+| Rule | How this skill respects it |
+|---|---|
+| `vague-discretion` | The whole point — produces measurable, command-form criteria |
+| `instruction-comprehension` | Reads the task description carefully; doesn't override explicit user instructions |
+| `research-before-decision` | Layer-walk IS research; doesn't propose criteria without evidence |
+| `human-authorization` | Confirms with user before starting loop (unless `--auto-criteria` explicitly granted) |
+| `auto-compact-continue` | The inferred criterion IS what the loop continues toward; no "should I keep working" prompts |
+| `cli-secondary` | Uses `aiwg discover` to find related skills if the task verb is unusual |
+
+## Examples
+
+### Example 1: Simple test task on a TypeScript project
+
+```
+$ agent-loop "fix the failing auth tests"   # or: aiwg al / aiwg ralph (legacy)
+
+Inferring completion criteria...
+  Layer 1 verb: "fix tests" → test-pass class
+  Layer 2 CLAUDE.md: "npm test" is the canonical test command
+  Layer 3 package.json: scripts.test = "jest"
+  Layer 4 CI: .github/workflows/ci.yml runs `npm test`
+  Layer 5: no related use case found
+
+Proposed criterion: npm test passes (exit 0)
+Verification: `npm test`
+Confidence: high
+
+Proceed? [Y/n/edit]
+```
+
+### Example 2: Refactor with no tests
+
+```
+$ agent-loop "extract auth logic into a separate module"
+
+Inferring completion criteria...
+  Layer 1 verb: "extract" → regression gate
+  Layer 2 CLAUDE.md: no Development section
+  Layer 3 package.json: scripts.test = "echo 'no tests'" (degenerate)
+  Layer 4 CI: no workflows found
+  Layer 5: no related use case found
+
+Warning: project has no functional test suite or CI configuration.
+Falling back to structural verification.
+
+Proposed criterion: The new module exists, the original code references it,
+                    AND `npx tsc --noEmit` still exits 0
+Verification: `test -f src/auth/index.ts && grep -q 'from.*src/auth' src/main.ts && npx tsc --noEmit`
+Confidence: low
+
+This is a weak gate. Consider supplying --completion explicitly
+or adding a test suite first.
+
+Proceed? [Y/n/edit]
+```
+
+### Example 3: Task with an explicit use case reference
+
+```
+$ agent-loop "implement UC-AUTH-001"
+
+Inferring completion criteria...
+  Layer 1 verb: "implement" → tests-exist class
+  Layer 5: found .aiwg/requirements/UC-AUTH-001-user-login.md
+
+Using acceptance criteria from UC-AUTH-001:
+  - [ ] User can log in with valid email/password
+  - [ ] Invalid credentials show clear error message
+  - [ ] Account locks after 5 failed attempts
+  - [ ] Login completes within 2 seconds
+
+Proposed criterion: All acceptance criteria from UC-AUTH-001 verified by tests,
+                    AND `npm test -- --testPathPattern=auth` passes
+Verification: `npm test -- --testPathPattern=auth`
+Confidence: high (acceptance criteria are explicit)
+
+Proceed? [Y/n/edit]
+```
+
+### Example 4: Refusal case
+
+```
+$ agent-loop "make the code better"
+
+Inferring completion criteria...
+  Layer 1 verb: "make better" → AMBIGUOUS, no clear criterion class
+  Layer 5: no related use case
+
+Cannot infer measurable criteria for this task.
+
+"Make the code better" is vague (per AIWG vague-discretion rule).
+A loop with no measurable gate runs forever or exits prematurely.
+
+Please supply --completion with a concrete check, e.g.:
+  --completion "npm test passes AND npm run lint exits 0"
+  --completion "all functions in src/utils/ have JSDoc"
+  --completion "complexity score from eslint < 10 for all files"
+
+Or rephrase the task with a concrete intent:
+  agent-loop "reduce cyclomatic complexity in src/utils/"
+  agent-loop "add JSDoc to all exported functions in src/api/"
+```
+
+## References
+
+- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/vague-discretion.md — Measurable criteria requirement
+- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/research-before-decision.md — Layer-walk research pattern
+- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/instruction-comprehension.md — Don't override explicit user criteria
+- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/auto-compact-continue.md — Criterion IS what the loop continues toward
+- @$AIWG_ROOT/agentic/code/addons/agent-loop/skills/agent-loop/SKILL.md — The detection/routing skill that delegates here when `--completion` is missing
+- @$AIWG_ROOT/agentic/code/addons/agent-loop/skills/ralph/SKILL.md — The legacy executor skill that consumes this output (`ralph` is legacy for `agent-loop`'s executor)
+- @$AIWG_ROOT/agentic/code/addons/agent-loop/skills/agent-loop-ext/SKILL.md — The crash-resilient external loop, same delegation pattern
+- @$AIWG_ROOT/agentic/code/addons/agent-loop/agents/ralph-verifier.md — Runs the verification command this skill proposes

package/agentic/code/addons/agent-loop/skills/ralph/SKILL.md

@@ -6,7 +6,7 @@ deprecated_names: [ralph]
 platforms: [all]
 description: Execute iterative task loop until completion criteria are met - iteration beats perfection
 commandHint:
-  argumentHint: '"<task>" --completion "<criteria>" [--max-iterations N] [--timeout M] [--interactive --guidance "text"]'
+  argumentHint: '"<task>" [--completion "<criteria>"] [--max-iterations N] [--timeout M] [--interactive --guidance "text"] [--auto-criteria | --no-infer-completion]'
   allowedTools: "Task, Read, Write, Bash, Glob, Grep, TodoWrite, Edit"
   model: opus
   category: automation
@@ -50,7 +50,7 @@ The task to execute. Should be:
 - Measurable completion state
 - Self-contained (all context provided)
 
-### --completion (required)
+### --completion (optional — inferred when omitted)
 Success criteria. Must be:
 - Verifiable (tests, lint, compilation)
 - Specific (not subjective)
@@ -66,6 +66,10 @@ Success criteria. Must be:
 - `--completion "code looks good"`
 - `--completion "feature is done"`
 
+**When omitted**: the loop delegates to the `infer-completion-criteria` skill, which derives a measurable criterion from project docs (CLAUDE.md / AGENTS.md / AIWG.md), package manifests, CI configuration, and `.aiwg/` artifacts. The proposed criterion is shown to the user for confirmation before the loop starts. Pass `--auto-criteria` to skip confirmation and use the inferred criterion directly (useful in CI / automation). Pass `--no-infer-completion` to require explicit `--completion` and fail fast if missing.
+
+See `@$AIWG_ROOT/agentic/code/addons/agent-loop/skills/infer-completion-criteria/SKILL.md` for the inference pipeline.
+
 ### --max-iterations (default: 10)
 Safety limit on iterations. Prevents infinite loops.
 
@@ -94,12 +98,21 @@ Create feature branch for loop work.
 
 ### Phase 1: Initialization
 
-1. Parse task and completion criteria
-2. Validate criteria are verifiable (can be checked via command)
-3. Create `.aiwg/ralph/` workspace if not exists
-4. Initialize iteration counter (i=0)
-5. Create feature branch if --branch specified
-6. Log initialization
+1. Parse task
+2. **Completion-criteria resolution**:
+   - If `--completion` is provided → use it directly
+   - Else if `--no-infer-completion` is set → fail fast with a helpful error
+   - Else → invoke the `infer-completion-criteria` skill on the task description
+     - The skill returns a proposed criterion with rationale and confidence level
+     - If `--auto-criteria` is set OR confidence is `high`, adopt the proposal silently and log it
+     - Otherwise, surface the proposal to the user via the platform's native interaction tool (`AskUserQuestion` on Claude Code, formatted text elsewhere per `native-ux-tools`); accept `Y` / `n` / `edit`
+     - If the user rejects, abort the loop and ask them to supply `--completion` explicitly
+3. Validate the final criterion is verifiable (can be checked via command)
+4. Create `.aiwg/ralph/` workspace if not exists
+5. Initialize iteration counter (i=0)
+6. Create feature branch if --branch specified
+7. **Write the criterion and its rationale into the loop's progress file** (`.aiwg/ralph/<loop-id>/progress.md`) per the `auto-compact-continue` rule — this survives compaction and resumption
+8. Log initialization
 
 **Communicate**:
 ```

package/agentic/code/addons/aiwg-utils/manifest.json

@@ -36,7 +36,8 @@
   "consolidation": {
     "strategy": "index-with-links",
     "rulesIndex": "rules/RULES-INDEX.md",
-    "deployIndexOnly": true
+    "deployIndexOnly": false,
+    "_note": "deployIndexOnly was true (#1343); changed to false 2026-05-14 so individual rule files (including skill-discovery.md) deploy to every provider's rules directory alongside the index. RULES-INDEX.md remains the canonical entry point; its links now resolve to local files on every provider, not just Claude/Cursor."
   },
   "commands": [],
   "agents": [
@@ -121,7 +122,8 @@
     "post-commit-index-refresh",
     "soul-enforcement",
     "skill-discovery",
-    "cli-secondary"
+    "cli-secondary",
+    "auto-compact-continue"
   ],
   "templates": [
     "devkit/addon-manifest",

package/agentic/code/addons/aiwg-utils/rules/RULES-INDEX.md

@@ -4,10 +4,15 @@ Core meta-utility rules for agent coordination, context management, and platform
 
 ---
 
-## AIWG Utilities Rules (20 rules — active with aiwg-utils addon)
+## AIWG Utilities Rules (21 rules — active with aiwg-utils addon)
 
 ### HIGH
 
+#### auto-compact-continue
+**Summary**: The answer to "should I keep working?" is always YES — until the task's measurable completion criteria are met or the user redirects. Context pressure, long tool outputs, and high iteration counts are not scope questions. When context fills, the right response is to compact, checkpoint to durable storage (activity log, progress file at `.aiwg/working/<task>-progress.md`, git history, AIWG memory), and continue. Trust platform auto-compact (REF-910); load-bearing state must live in `CLAUDE.md` / `AGENTS.md` / `AIWG.md` / activity log / progress file / git / `.aiwg/working/` — never only in conversation turns. Maintain a `## Compact Instructions` section so the summarizer preserves completion criteria, last successful step, failed approaches (do not let them be re-attempted), and authorization questions. Apply aggressive in-session compression (REF-122: passive=6% savings, aggressive=22.7%); update the progress file every 10–15 tool calls on long tasks. Exceptions: authorization gates (per `human-authorization`), 3-attempts-failed escalation (per `anti-laziness` Rule 6), explicit user redirect, genuinely ambiguous new directive classification (per `skill-discovery` Rule 0). "Should I continue?" is never the right question.
+**When to apply**: Any long-running session; before context fills; after long tool outputs; when crossing iteration thresholds; when resuming after compaction; when tempted to ask the user permission to keep going
+**Full rule**: @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/auto-compact-continue.md
+
 #### cli-secondary
 **Summary**: AIWG is agentic-first. The agent's strict priority order for any action: (1) **local skill** already loaded in context (kernel skills, framework quickrefs, deployed agents), (2) **discovered skill** via `aiwg discover` + `aiwg show`, (3) raw CLI command, (4) manual file edits as last resort. The skill carries the priming (pre-flight checks, dry-run preview, preservation logic, gates) that the CLI alone lacks. Sole exception: discovery/finder commands (`aiwg discover`, `aiwg show`, `aiwg list`, `aiwg status`, `aiwg version`, `aiwg runtime-info`, status/info subcommands) stay primary — they ARE the priming entry points and the bridge from priority 2 to priority 1. For mixed commands (`aiwg index`, `aiwg packages`, `aiwg ops`, `aiwg storage`), classify per subcommand. Includes a pairing table covering use/refresh/regenerate/doctor/init/promote/scaffold-*/add-*/doc-sync/lint/cleanup-audit/sdlc-accelerate/ralph/mc/steward/index build/ops actions/storage migrate.
 **When to apply**: Before invoking any AIWG CLI command, before writing skill/agent docs that reference CLI commands, when updating quickrefs or routing tables, when filing pairings audits