ra1-fix

Files (66)

• SKILL.md
• manifest.json
• __init__.py · scripts/readiness/
• answers.py · scripts/readiness/
• __init__.py · scripts/readiness/checks/
• _agent_policy.py · scripts/readiness/checks/
• _helpers.py · scripts/readiness/checks/
• _workflow_policy.py · scripts/readiness/checks/
• build.py · scripts/readiness/checks/
• devenv.py · scripts/readiness/checks/
• docs.py · scripts/readiness/checks/
• judgment.py · scripts/readiness/checks/
• loop.py · scripts/readiness/checks/
• observability.py · scripts/readiness/checks/
• product.py · scripts/readiness/checks/
• security.py · scripts/readiness/checks/
• style.py · scripts/readiness/checks/
• taskdisc.py · scripts/readiness/checks/
• testing.py · scripts/readiness/checks/
• cli.py · scripts/readiness/
• __init__.py · scripts/readiness/collectors/
• _observation.py · scripts/readiness/collectors/
• exec.py · scripts/readiness/collectors/
• git.py · scripts/readiness/collectors/
• github.py · scripts/readiness/collectors/
• static.py · scripts/readiness/collectors/
• context.py · scripts/readiness/
• coverage_gate.py · scripts/readiness/
• registry.json · scripts/readiness/criteria/
• detect.py · scripts/readiness/
• __init__.py · scripts/readiness/fix/
• recipes.py · scripts/readiness/fix/
• gaps.py · scripts/readiness/
• history.py · scripts/readiness/
• judgments.py · scripts/readiness/
• model.py · scripts/readiness/
• parsers.py · scripts/readiness/
• process.py · scripts/readiness/
• report.py · scripts/readiness/
• run.py · scripts/readiness/
• safe_io.py · scripts/readiness/
• score.py · scripts/readiness/
• theme.py · scripts/readiness/
• version.py · scripts/readiness/
• AGENTS.md · templates/
• CODEOWNERS · templates/
• bug_report.md · templates/ISSUE_TEMPLATE/
• SECURITY.md · templates/
• guide-skill.md · templates/acdc/
• solve-skill.md · templates/acdc/
• verify-skill.md · templates/acdc/
• workflow.md · templates/acdc/
• readiness.yml · templates/ci/
• dependabot.yml · templates/
• devcontainer.json · templates/
• env.example · templates/
• eslintrc.json · templates/
• gitignore.ra1 · templates/
• denylist.md · templates/loop/
• loop-runs-README.md · templates/loop/
• …and 6 more

SKILL.md (first lines)

# Agent Readiness Fix

Raise a repo's readiness by applying only **safe** changes. The engine plans, writes, and
**verifies** every scaffold; you present the canonical `fix_contract`. No direct file writes, no
git branch/commit/push/PR commands, and no prose authoring: the engine owns the remediation
contract and you report it exactly.

## Steps

`<skill-dir>` below is this skill's own directory: the absolute path your runtime reports when it
loads the skill. Substitute it. Do not write `$(dirname "$0")`.

1. **Plan from a fresh scan** (source-less; no stored report is required, and `latest.json` is
   never a dependency — a first-run report-persistence refusal cannot deadlock this skill):

   ```bash
   python3 -I "<skill-dir>/scripts/readiness/cli.py" fix --project . --format json
   ```

   The canonical JSON `fix_contract` carries `operation: "plan"`, the normalized plan buckets
   (`auto` with shared-target `criterion_ids`, `propose`, `github`, `manual`), and
   `verification.status: "not_run"`. Focus the plan deterministically with `--include <id>...` /
   `--exclude <id>...` (authoritative criterion-id filters only — never free-form instructions),
   or the `--instructions` keyword→pillar grammar, which annotates unsupported phrases as a note
   rather than silently filtering. Present the plan and the engine-owned explanation for every
   proposed action; never reconstruct a trace from prose.

2. **Apply only on explicit current-turn mutation request**, using the fixed grammar:

   ```bash
   python3 -I "<skill-dir>/scripts/readiness/cli.py" fix --project . --apply --format json
   ```

   `--apply` always requires a clean/known Git worktree (no bypass), runs a fresh baseline scan,
   refuses on repository-indeterminate or incomplete static/Git evidence (and requested-T2
   incompleteness), performs create-only scaffold writes (existing targets are skipped proposals;
   `.gitignore` is create-if-missing only, never appended), re-scans with identical options, and
   computes the authoritative comparable delta. Append `--github` only when the current-turn
   request explicitly requires online T2 verification, and paired `--host-proxy` only on a
   separate current-turn host-proxy request. `fix` never writes report/history/latest.

3. **Report only the canonical `fix_contract`** — present it verbatim: `operation: "apply"`, the
   fresh plan, the exact `apply_result` (`written`/`skipped` targets with their complete
   `criterion_ids`), and `verification` with `status` (`passed`/`failed`/`not_run`), `errors`,
   `confirmed_ids`, `unresolved`, `regressions`, before/after `level`, and `decision_successful`.

   - `confirmed_ids` are the only IDs you may call fixed/verified — never an unresolved or
     regressed one.
   - On post-write failure the behavior is intentional and explicit: created files are retained
     (never rolled back, never auto-deleted) and every retained creation plus its unresolved or
     regression state is reported so the maintainer can inspect or revert with normal version
     control. Generating or storing a subsequent full report is a separate explicit `ra1 report`
     invocation, never an automatic post-fix step.

## Contract (do not violate)

- **Never push and never open a PR without explicit user confirmation.** You do not run git
  branch/commit/push/merge commands at all — branching and committing are the user's controlled
  action after reviewing the contract.
- **No direct file tools.** You never read/write/edit repository files; every mutation goes
  through the fixed `fix --apply` command.
- **Auto-apply config scaffolds only.** README/AGENTS.md/tests/runbooks are *proposed drafts* the
  user reviews; the engine never auto-writes prose, and neither do you.
- **Never bundle GitHub setting changes** with code commits. `github` bucket items are a manual
  checklist of commands the user runs and confirms — you never execute them.
- **Never claim success without verification.** Only `verification.status: "passed"` plus the
  matching `confirmed_ids` authorizes the words "fixed" or "verified"; everything else stays
  unresolved/regressed as recorded.
- Respect a dirty worktree: `fix --apply` refuses (never bypasses) a dirty or indeterminate Git
  state — there is no force flag.

From tjboudreaux/ready-agent-1, MIT.

More from tjboudreaux/ready-agent-1