Skip to content

Adonis0123/adonis-skills / skills/architecture-hardening-loop

architecture-hardening-loop

Verified

Run a bounded scan-triage-fix-independent-review-rescan loop on an explicit or uniquely resolvable user-supplied code scope until no evidence-backed architecture fixes remain. Use for implementation-inclusive architecture cleanup, DDD or high-cohesion hardening, and autonomous architecture improvement.

FileKindSize
SKILL.mdskill md25.1 KB
agents/openai.yamlconfig713 B
evals/evals.jsonconfig40.3 KB
evals/trigger-eval.jsonconfig4.4 KB
references/ownership-and-evidence.mdmarkdown6.7 KB
references/scope-resolution.mdmarkdown1.6 KB

references/ownership-and-evidence.md

View on GitHub
# Goal ownership and evidence freshness

Load this file only when the user explicitly requested Goal creation/management, an active Goal or caller parent contract must be reconciled, a Goal must be closed, or a review verdict may be reused. Classification, contract writing, and report-only scanning do not need its Goal sections.

## Ownership evidence

Read from native Goal tools, product Goal status, or a caller-supplied parent contract that can be checked (objective, frozen scope, Done condition, completion owner). A native getter is not the only evidence source. Record one of `none` / `exact-same-goal` / `broader-compatible` / `conflicting/unclear`. If evidence is insufficient, classify `conflicting/unclear`.

This preflight read is ownership-only: do not create, replace, or terminally update a Goal. `conflicting/unclear` obeys `goal-gate` `Decision: defer` and returns `HUMAN_GATE` before the first scan.

Compatibility must be proven by objective, frozen scope, and Done condition. “A Goal already exists” is neither proof of compatibility nor a reason to pause a compatible parent.

## Goal 关系

`goal-gate` is conditional here: reconcile an existing/parent Goal before scan, or honor an explicit user request to create one only after at least one `Fix` is confirmed. `exact-same-goal` / `broader-compatible` continue the existing Goal. Merely invoking the architecture Loop does not authorize Goal creation. Never create a nested Goal.

| Goal 关系             | 行为                                                                                                                                             | 完成所有权                              |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
| `none`                | 用户明确要求 Goal 且安全闸门通过时,创建覆盖本次范围、验证与 `NO_ACTIONABLE_FINDINGS` 的 Goal;否则继续 Hardening Contract 并报告 `not-created`  | 显式创建时 `created-by-loop`,否则 none |
| `exact-same-goal`     | 用户明确继续同一 architecture-hardening 目标;`Next: continue active goal`,不创建或替换                                                         | 本 Loop 可在全部条件满足后完成          |
| `broader-compatible`  | 本 Loop 是 active parent Goal 冻结范围与 Done condition 中的一个 checkpoint;`Next: continue active goal`,不创建、不替换、不收窄 Done condition | 父编排器;本 Loop 只上报 checkpoint     |
| `conflicting/unclear` | 服从 `goal-gate` 的 `Decision: defer`,返回 `HUMAN_GATE`,只问如何处理冲突或归属                                                                 | none                                    |

## Codex / Grok 完成合同

Do not borrow one runtime's field names for the other.

**Codex (`get_goal` / `create_goal` / status-only `update_goal`):**

- Continue an exact-same Goal without calling terminal `update_goal` until Done condition is proven.
- Do not invent Grok `message` / `completed` / `blocked_reason`.
- When this Loop owns the full objective and `NO_ACTIONABLE_FINDINGS` + required verification + final review (if any Fix) are proven: `update_goal` with `status: complete`.
- Do not complete a `broader-compatible` parent.

**Grok (user-run `/goal`, then Grok-style `update_goal`):**

- Do not invent `create_goal` / `get_goal`, and do not ask the user to paste a second `/goal`.
- While a Fix remains: only a `message` checkpoint. Never `completed: true`.
- Do not use Codex `status: complete` / `status: blocked`.
- When this Loop owns the full objective and Done condition is proven: `update_goal` with `completed: true` (optional `message`).

Zero-Fix after a matching evidence identity does **not** create a new Goal. Close using the relation recorded at preflight:

- `none` → `Goal: not-created`
- `exact-same-goal` → after terminal consult, required verification, and the full Done condition, use that runtime's terminal schema
- `broader-compatible` → `Goal: active-checkpoint`; keep the parent Goal active
- `conflicting/unclear` already stopped at `HUMAN_GATE` and must not reach this branch

Only this Loop may mark a Goal completed, and only when it owns completion, `Result: NO_ACTIONABLE_FINDINGS`, required verification passed, and no open `Fix` remains. After a Fix, default `completion=pass` requires the final review to cover the same Evidence id and be `PASS` / `NO_FINDINGS`; a Decision Closure is valid only when the user explicitly selected review-only mode. No `awaiting_user_decision` packet may remain. A `broader-compatible` parent is always `active-checkpoint`; the parent orchestrator closes remaining Done conditions. The zero-Fix branch does not invent a review.

## `scanEvidence` identity

Every scanner pass owns its own `scanEvidence`. Evidence id is required on both the zero-Fix and Fix branches.

1. **E1 (first scan):** before the first scanner pass, run `review-loop evidence` on current `HEAD` + the frozen path filter. Record `{ baseSha, pathFilter, digest, coveredPaths, sourceRound }`.
2. **E2 (post-Fix rescan):** after a Fix, take `evidence` returned by `review-loop run` / `close`. Recompute current identity on the same `baseSha` + `pathFilter`. Only if it matches, select that identity as this pass's `scanEvidence` (E2).
3. **Terminal consult freshness:** after the terminal Reviewer consult, re-run `review-loop evidence` on this pass's `baseSha` / `pathFilter`. Enter `NO_ACTIONABLE_FINDINGS` only when digest equals the identity chosen **before this scanner pass**.
4. **E3 (drift):** if that recomputation differs (E3), scanner/consult evidence is stale. Rescan the same scope; if a rescan is impossible, report `UNVERIFIED`. Do not complete a Goal.

A post-Fix rescan compares only against the E2 selected before that rescan. Never fall back to first-scan E1.

Protocol artifacts (`.review-handoff/**`, `$GIT_COMMON_DIR/info/exclude`) are recorded separately and are not part of scanner scope.

## Digest equality and review reuse

Equality compares only `baseSha + pathFilter + digest`. `coveredPaths` is audit-only and never substitutes for digest. `Decision Closure` reuses `sourceRound`; it does not re-prove the current worktree.

Same `HEAD` and same path set are not enough: a content change that keeps SHA and paths but alters digest invalidates the old verdict.

If any required field is missing, current identity cannot be recomputed, or digest mismatches, the old review is not reusable. Re-run review, or report `UNVERIFIED`. Do not claim `NO_ACTIONABLE_FINDINGS` or complete a Goal on stale evidence.

After evidence matches, stop immediately. Do not run “one more scan for confidence.”
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall