opencode-skills-collection 4.1.18 → 4.1.20

package/bundled-skills/goal-instruction-writer/references/drift-control.md

@@ -0,0 +1,160 @@
+# Drift Control Reference
+
+Use this reference for Goals that run for more than a few iterations, cross
+phases, touch several artifacts, or invite exploratory side quests. Drift is a
+change in direction that is not justified by the Goal Anchor, even when the
+new work is technically useful.
+
+## Freeze a Goal Anchor
+
+Write this short block before the first work unit and carry it through every
+checkpoint:
+
+```text
+Goal Anchor: <one sentence describing the user/system outcome>
+Success criteria: C1 <...>; C2 <...>; C3 <...>
+Frozen scope: <invariants, protected behavior, and forbidden side effects>
+Allowed authority: <tools, files, systems, and approvals available>
+Current phase: <phase or milestone>
+```
+
+The Anchor is an invariant, not a plan. Plans may change when evidence changes.
+The outcome, acceptance criteria, frozen scope, or authority may change only
+through an explicit owner decision, a durable scope-change record, or a new Goal
+version. Never rewrite them to justify work that already happened.
+
+## Use an iteration alignment record
+
+Before acting, write:
+
+```text
+Iteration: <number>
+Target criterion: <C1/C2/...>
+Expected delta: <observable evidence that should change>
+Scope reason: <why this is inside the frozen boundary now>
+```
+
+After verifying, append:
+
+```text
+Actual evidence: <test, diff, artifact, source, or decision>
+Alignment: ON_TARGET | SIDE_QUEST | DRIFTED
+Decision: continue | defer | replan | pause
+Next cursor: <single next work unit or unblock>
+```
+
+The three alignment labels have different behavior:
+
+- **ON_TARGET:** the named criterion moved or new relevant evidence supports
+  a justified next step. Continue.
+- **SIDE_QUEST:** the work may be useful but is not required by this Goal.
+  Record it in a deferred list and return to the next unmet criterion.
+- **DRIFTED:** the work changed the Goal or scope without authorization, the
+  next action cannot be justified from the Anchor, or the no-progress threshold
+  is reached. Stop and realign.
+
+## Detect drift early
+
+Treat any of these as a drift signal:
+
+- The agent cannot name which criterion the current action advances.
+- The expected evidence is replaced by activity, volume, or elapsed time.
+- A new issue becomes the main work without a recorded link to the outcome.
+- Allowed files, systems, sources, or side effects expand silently.
+- The baseline or acceptance criteria are rewritten to fit completed work.
+- Two materially equivalent actionable attempts produce neither acceptance
+  progress nor new relevant evidence.
+- The plan keeps generating “one more” improvement after all criteria are
+  already verified.
+
+The default no-progress threshold is two materially equivalent actionable
+attempts; use a smaller threshold for high-risk or expensive work and a larger
+one only when the task's evidence is naturally sparse.
+
+## Scheduled external waits
+
+When an external response is pending, record the unmet criterion, dependency,
+last observation, next check time (with timezone) or relevant notification, and
+deadline or unblock condition in the current cursor.
+
+Evaluate host limits and deadlines before the next-check trigger; an expired
+limit takes precedence even when the next lookup is not yet due.
+
+- Before the check trigger, do not issue another lookup or ping. Continue an
+  independently actionable criterion; if none remains, yield with the wait
+  checkpoint preserved. Waiting itself does not consume an actionable work
+  unit or increment the no-progress counter. It is not acceptance progress.
+- On the agreed time or relevant notification, check the dependency once.
+  Reuse unchanged evidence and record a new justified check time if the
+  dependency remains pending within its window. A due observation of "still
+  pending" is neither a failed actionable attempt nor acceptance progress.
+  A notification warrants a check, not automatic acceptance of the response.
+- Stop premature repeated polling and realign its schedule. Every actual tool
+  call, failed attempt, and elapsed interval remains subject to host budgets;
+  the waiting exception does not reset or extend those limits.
+- If the feedback deadline arrives before the required response, report
+  `GOAL TIMEBOXED: awaiting first external feedback` with the open criterion
+  and resume condition. If another budget expires first, honor that limit.
+  Without a supported resume trigger, preserve the named dependency and apply
+  the host's blocked/yield rules instead of inventing more work.
+
+A wait checkpoint does not schedule an automatic wake-up or authorize a new
+message. Host status rules still apply; an owner pause remains distinct.
+
+## Run phase gates
+
+Run a phase gate every 3–5 iterations by default, at each milestone, and before
+an irreversible or high-cost action. A phase gate should:
+
+1. Re-read the Goal Anchor and compare it with the current state.
+2. Mark each criterion `open`, `verified`, or `blocked` with evidence.
+3. Review the diff or artifact list against Allowed and Frozen scope.
+4. Move side quests to the deferred list with a reason and revisit condition.
+5. Record one justified next action, its target criterion, and expected delta.
+
+If all criteria are verified, finish as complete. If only a scheduled external
+wait remains, preserve its checkpoint and yield; otherwise report the named
+blocker under host rules. Do not invent work to keep the loop alive.
+
+## Recover from drift
+
+When a drift trigger fires:
+
+1. Stop the current loop before taking another action.
+2. Write the alignment record and preserve the last durable cursor.
+3. Compare current changes with the baseline and classify them as aligned,
+   deferred side quest, or unauthorized scope change.
+4. Keep aligned evidence. Isolate or revert side-quest changes only when the
+   authority and repository safety rules allow it; never discard external work
+   silently.
+5. Re-plan one next action from the Anchor, or ask the owner for a scope or
+   objective decision.
+6. Resume only after the checkpoint records `ON_TARGET` and an expected delta.
+
+Use `GOAL REALIGNMENT REQUIRED` as the default control stop. Report the
+last aligned criterion, the drift trigger, preserved evidence, deferred work,
+and the exact decision needed to resume.
+
+## Minimal prompt block
+
+```markdown
+## Goal anchor
+- Outcome: <one immutable sentence>
+- Criteria: <C1, C2, C3>
+- Frozen scope: <invariants and forbidden side effects>
+- Current phase: <phase or milestone>
+
+## Drift control
+Before each iteration, name one target criterion, expected evidence delta, and
+scope reason. After verification, label the result `ON_TARGET`, `SIDE_QUEST`, or
+`DRIFTED`. Park side quests. Re-read the Anchor every 3–5 iterations, at phase
+gates, and before irreversible work. If two equivalent actionable attempts add
+neither acceptance progress nor new relevant evidence, or the Anchor/scope
+changes without approval, stop and emit
+`GOAL REALIGNMENT REQUIRED`; record the cursor and exact re-alignment
+decision needed before resuming. For an agreed external wait, record the open
+criterion, next check time/event, and deadline. Before that trigger, continue
+independent work or yield. Waiting and a due observation of "still pending"
+do not increment the failed-attempt counter or verify an acceptance criterion.
+Actual calls and elapsed time remain subject to host budgets.
+```

package/bundled-skills/goal-instruction-writer/references/examples.md

@@ -0,0 +1,220 @@
+# Goal Instruction Examples
+
+These examples show the shape of the output. They are deliberately small so
+they can be adapted to a real task.
+
+## Coding: fix a reproducible import failure
+
+Weak request:
+
+> Fix the importer and keep trying until it works.
+
+Better Goal:
+
+```markdown
+# Goal: Make the CSV importer accept quoted multiline fields
+
+## Objective
+Update the importer so the fixture `fixtures/quoted_multiline.csv` loads into
+the existing record model without truncation or row-count drift.
+
+## Baseline and scope
+- Baseline: current `main` revision and the existing importer test suite.
+- Allowed scope: importer code, its focused tests, and fixture data needed to
+  reproduce the failure.
+- Frozen scope: public record fields, unrelated parsers, and dependencies.
+
+## Acceptance criteria
+- [ ] The focused fixture test passes and preserves the expected row count.
+- [ ] Existing importer tests pass.
+- [ ] The diff explains the parsing boundary and contains no unrelated edits.
+
+## Verification strategy
+During parser edits, run the focused fixture test. Once the parser is stable,
+run the existing importer suite and review the diff. Record the checked parser,
+fixtures, dependencies, and test environment; reuse passing results while those
+inputs remain valid. A report-only edit needs a report check. A later parser
+change requires the focused test and affected importer regressions again;
+broaden if its impact is unclear. Apply the repository's command timeout to
+expensive checks and leave any timed-out criterion open.
+
+## Execution loop
+Inspect the failing fixture and parser state; make one smallest hypothesis-driven
+change; run the focused test; record the result and diff; then choose the next
+unmet criterion from the evidence.
+
+## Limits and no-op rule
+Use at most four hypothesis iterations. Do not repeat a failed parser change
+without new evidence; after two equivalent failures, report the blocker.
+
+## Termination
+Emit `GOAL COMPLETE` only when all three criteria are verified. Emit
+`GOAL BLOCKED: <reason>` if the fixture or required dependency is unavailable,
+including the exact unblock needed. Emit `GOAL TIMEBOXED: <state>` after the
+fourth iteration if the criteria remain open.
+
+## Reporting
+Return the revision, commands and results, changed files, remaining gap, and
+the terminal label. Distinguish newly run checks from reused evidence.
+```
+
+### SDK delivery: choose checks after a successful validation
+
+Keep all required release checks, but let the actual change determine which
+evidence must be refreshed:
+
+| Later change | Next verification |
+| --- | --- |
+| Only the handoff report or receipt changes | Check that document; reuse runtime and artifact results whose inputs remain valid |
+| A cancellation fix changes SDK behavior and the AAR | Run the affected regression checks, rebuild affected artifacts, and refresh consumer checks against the new AAR |
+| A new API snapshot is added while the AAR is unchanged | Check the new snapshot; reuse existing compatibility and runtime results tied to the same AAR and inputs |
+
+## Research: compare two options
+
+Weak request:
+
+> Research these tools and tell me which one is best.
+
+Better Goal:
+
+```markdown
+# Goal: Recommend one analytics tool for the stated workload
+
+## Objective
+Produce a cited comparison of Tool A and Tool B and recommend one option for a
+team with <constraints>, with the trade-offs explicit enough for a decision.
+
+## Baseline and scope
+- Baseline: official documentation and current pricing pages checked on the
+  research date.
+- Allowed scope: public, first-party sources plus the user's stated workload.
+- Frozen scope: do not infer private capabilities or promise an unverified
+  integration.
+
+## Acceptance criteria
+- [ ] Each decision criterion has a source and a short evidence quote or
+  paraphrase.
+- [ ] Material differences, costs, and constraints are compared in one table.
+- [ ] The recommendation states when the other option would be better.
+
+## Execution loop
+Inspect one criterion at a time; collect the strongest primary source for each
+tool; record evidence and uncertainty; update the comparison; then select the
+next criterion that could change the recommendation.
+
+## Limits and no-op rule
+Cover the five agreed criteria and stop after one primary source per material
+claim unless a conflict needs resolution. Do not keep searching after the
+recommendation is stable and all criteria are sourced.
+
+## Termination
+Emit `GOAL COMPLETE` when the table, citations, and conditional recommendation
+are complete. Emit `GOAL BLOCKED: <missing constraint or source>` when a decision
+depends on an owner answer or inaccessible evidence.
+
+## Reporting
+Return the comparison, recommendation, uncertainty, sources, and terminal
+label.
+```
+
+## Open source: publish a skill with an external maintainer gate
+
+Weak request:
+
+> Promote the skill everywhere and get it merged into a curated list.
+
+Better Goal:
+
+```markdown
+# Goal: Make the skill discoverable and leave the curated-list submission reviewable
+
+## Objective
+Publish a validated skill package, create one reviewable distribution
+submission, and record the exact external dependency if a maintainer must merge
+it.
+
+## Goal anchor
+- Outcome: the skill is installable from its source repository and its curated-list submission has a durable status.
+- Criteria: C1 package validation; C2 one distribution submission; C3 feedback
+  and blocker record; C4 one non-author response.
+- Frozen scope: no new social accounts, mass posting, repeated maintainer pings, or silent scope expansion.
+- Current phase: launch and first feedback.
+
+## Baseline and scope
+- Baseline: the current repository revision, release metadata, and existing
+  installation command.
+- Allowed scope: the skill repository, one curated-list submission, and one
+  feedback thread.
+- Authority: the agent may edit the repository and submit or update its own
+  contribution; only the upstream maintainer may merge the external PR.
+
+## Acceptance criteria
+- [ ] The skill validator and installation smoke test pass.
+- [ ] One public submission links to the repository and explains how to install it.
+- [ ] The feedback thread records the use case, current status, and exact
+  unblock needed for any external gate.
+- [ ] At least one non-author reply records a concrete use case, result, defect,
+  or improvement; an author-only comment does not satisfy this criterion.
+
+## Execution loop
+Repeat one bounded work unit at a time:
+1. Inspect the durable cursor, then the repository, release, submission, and
+   feedback-thread status only when the relevant check is due.
+2. Select one open criterion, expected evidence, and scope reason.
+3. Make one focused documentation, packaging, or submission update.
+4. Verify the result with a validator, link, commit, or platform status.
+5. Classify it as `ON_TARGET`, `SIDE_QUEST`, or `DRIFTED`, then record the next
+   cursor.
+
+## Drift control
+- Re-read the Anchor before each public post, version change, or new submission.
+- Defer unrelated channels, feature ideas, and promotional experiments.
+- If a maintainer gate is the only remaining work, preserve the named dependency
+  and its agreed resume trigger; otherwise report the exact blocker under host
+  rules. Do not repeatedly contact the maintainer.
+- If the scope expands without approval, or two equivalent actionable attempts
+  add neither acceptance progress nor new relevant evidence, emit
+  `GOAL REALIGNMENT REQUIRED`.
+
+## Limits and no-op rule
+- Use at most three actionable work units and one maintainer follow-up until
+  new review evidence arrives.
+- Do not repeat a post or submission without a material change in evidence.
+- While C4 is pending within its feedback window, record the last observation,
+  next agreed check time or reply notification, and deadline. Before that
+  trigger, skip further queries and pings; continue other open criteria or
+  yield with the checkpoint preserved. Verify any response before counting it.
+- An agreed wait consumes neither an actionable work unit nor the no-progress
+  allowance; a due observation of "still pending" is not a failed attempt or
+  acceptance progress. Actual queries and elapsed time still count toward host
+  limits; stop premature repeated polling and realign its schedule.
+- Define a feedback window before execution; if it closes without the required
+  non-author response, stop as `GOAL TIMEBOXED: awaiting first external feedback`.
+
+## Termination
+- `GOAL COMPLETE` when the package, submission, status record, and feedback
+  threshold are verified.
+- `GOAL BLOCKED: upstream maintainer review required` when only the external
+  merge remains, the submission is clean, and no supported resume trigger is
+  available; honor the host's blocked-status rules.
+- `GOAL TIMEBOXED: awaiting first external feedback` when the feedback window
+  closes before the required non-author response arrives.
+- `GOAL TIMEBOXED: <state>` when the launch window ends with the verified
+  progress and next safe action recorded.
+
+## Reporting
+Return the release or revision, validation evidence, submission URL, current
+external status, deferred side quests, remaining gap, and terminal label.
+```
+
+## Chinese output shape
+
+When the user asks in Chinese, keep the same contract and translate the labels
+or preserve exact terminal strings when a system already depends on them. For
+example:
+
+```markdown
+目标：交付一个可验收的 <结果>
+循环：检查 → 选择一个最小工作单元 → 执行 → 验证 → 记录游标
+结束：`GOAL COMPLETE` / `GOAL BLOCKED: <原因>` / `GOAL TIMEBOXED: <状态>`
+```

package/bundled-skills/goal-instruction-writer/references/goal-contract.md

@@ -0,0 +1,169 @@
+# Goal Contract Reference
+
+This reference defines the fields used by `goal-instruction-writer`. It is a
+compact design contract rather than a generic project-management checklist.
+
+## Why the three layers matter
+
+An agent can fail in three different ways:
+
+1. The **Goal** is vague, so activity is mistaken for progress.
+2. The **Loop** is unbounded, so the agent repeats work or drifts out of scope.
+3. The **Termination** rule is missing, so the agent cannot distinguish success
+   from a blocker, a pause, or an exhausted budget.
+
+The three layers are evaluated together. A precise objective with no evidence
+is not complete; a good loop with no limit can still run forever; a stop rule
+with no progress signal can stop at the wrong time.
+
+## Field guide
+
+| Field | Required question | Good evidence |
+| --- | --- | --- |
+| Objective | What observable end state should exist? | A file, behavior, decision, or verified fact |
+| Goal anchor | What must remain true across iterations? | One-sentence outcome, criterion IDs, frozen scope, current phase |
+| Loop preview | What will one iteration and each branch look like? | State transitions, first work unit, evidence, gates, terminal states |
+| Baseline | What is authoritative now? | Revision, URL, dataset snapshot, or current finding |
+| Allowed scope | What may change? | Named files, systems, sources, or decision boundary |
+| Frozen scope | What must remain unchanged? | Explicitly protected behavior, data, or external state |
+| Acceptance criteria | How will a reviewer know it is done? | Test result, diff, artifact, cited source, or checklist |
+| Verification strategy | Which checks run during edits, at delivery, or after a change? | Focused checks, required broader gates, evidence validity, rerun reasons, cost bounds |
+| Feedback evidence threshold | What counts as real feedback, and how much is required? | Entry point only, N non-author replies, named cohort, and a timebox |
+| External wait (when applicable) | When may a pending dependency be checked again? | Open criterion, dependency, last observation, next check time/event, deadline or unblock |
+| Work unit | What is one iteration small enough to verify? | One hypothesis, patch, experiment, or review slice |
+| Progress signal | What changes after a useful iteration? | New evidence, reduced gap, changed artifact, or decision |
+| Alignment check | How is each iteration tied back to the Goal? | Target criterion, expected delta, scope reason, alignment label |
+| Drift trigger | When must the loop stop and realign? | No criterion moved, silent scope change, repeated no-progress iterations |
+| Phase gate | When is the Anchor re-read? | Every 3–5 iterations, milestone, or before irreversible work |
+| Decision log | What prevents rationale from being lost? | Decision, evidence, criterion, rejected side quest, scope impact |
+| Limit | When must the loop yield? | Time, attempts, token/tool budget, or finite queue |
+| No-op rule | What prevents repetition? | Change approach after failure; stop after repeated blocker |
+| Terminal states | What are the legal endings? | Complete, blocked, paused, timeboxed/budgeted, stopped |
+| Report | What survives the final response? | Status, evidence, remaining gap, cursor, next action |
+
+## Ready-to-paste skeleton
+
+```markdown
+# Goal: <verb + observable outcome>
+
+## Objective
+Produce <artifact/behavior/decision> so that <user or system value>.
+
+## Goal anchor
+- Outcome: <one immutable sentence>
+- Criteria: <C1, C2, C3>
+- Frozen scope: <invariants and forbidden side effects>
+- Current phase: <phase or milestone>
+
+## Baseline and scope
+- Baseline: <authoritative revision, source, or current state>.
+- Allowed scope: <files, systems, sources, or decisions that may change>.
+- Frozen scope: <invariants and forbidden side effects>.
+- Authority: <tools and approvals available; owner-only gates>.
+
+## Acceptance criteria
+- [ ] <observable criterion with its evidence>
+- [ ] <observable criterion with its evidence>
+- [ ] <observable criterion with its evidence>
+
+## Feedback evidence (when applicable)
+- Threshold: <entry point only | N non-author responses | named cohort>
+- What counts: <concrete use case, result, defect, or decision>
+- Window: <date, number of attempts, or timebox>
+
+## External wait (when applicable)
+- Checkpoint: <open criterion, dependency, last observation>.
+- Resume trigger: <next check time with timezone or relevant notification>;
+  deadline/unblock: <feedback deadline or named dependency resolution>.
+- Check overall limits and deadlines first. Before the trigger, skip further
+  lookups or pings; continue independent work or yield with the checkpoint
+  preserved. On the trigger, verify the response.
+- Waiting and a due observation of "still pending" are neither failed
+  actionable attempts nor acceptance progress. Actual tool calls and elapsed
+  time still count against the overall host limits.
+
+## Verification strategy
+- Iteration checks: <smallest checks sufficient for the affected behavior>.
+- Phase/delivery checks: <required broader checks and artifacts, with triggers>;
+  complete them once the relevant implementation is stable.
+- Evidence reuse: record the checked source/artifact and relevant inputs,
+  dependencies, and environment; carry forward results while they remain valid.
+  Label reused and newly run checks separately. Documentation or receipt edits
+  do not invalidate unrelated runtime checks.
+- Reruns: name the change or new evidence that invalidates a result; rerun
+  affected checks, including consumers of changed artifacts. Broaden when the
+  impact, a failure, uncertainty, or an explicit requirement warrants it.
+- Cost bounds: <command timeouts or attempt caps for expensive checks>;
+  a timeout leaves the corresponding criterion open.
+
+## Execution loop
+Repeat one bounded work unit at a time:
+1. Inspect <state and last cursor>; honor pending wait triggers before lookups.
+2. Select one unmet criterion, expected delta, and scope reason.
+3. Act within Allowed scope and Authority.
+4. Apply the verification strategy to the relevant criterion and capture evidence.
+5. Classify the iteration as `ON_TARGET`, `SIDE_QUEST`, or `DRIFTED`.
+6. Record the delta, remaining gap, decision, and next cursor.
+
+## Drift control
+- Re-read the Goal anchor every 3–5 iterations, at phase gates, and before
+  irreversible or high-cost actions.
+- Park side quests in a deferred list; do not expand the Goal silently.
+- If two equivalent actionable attempts add neither acceptance progress nor
+  new relevant evidence, or the Anchor/scope changes without owner approval,
+  stop and emit `GOAL REALIGNMENT REQUIRED`. An agreed wait does not increment
+  this counter; stop repeated premature polling and realign its schedule.
+- Resume only after recording the re-aligned next action and its expected delta.
+
+## Limits and no-op rule
+- Limit: <timebox, budget, attempt cap, or finite work-unit list>.
+- Do not repeat an action without new information. After <N> materially
+  equivalent failures, change the hypothesis or terminate as blocked.
+
+## Termination
+- `GOAL COMPLETE` when all acceptance criteria are verified and the deliverable
+  is available. Stop; further checking requires invalidated evidence or a
+  concrete unresolved concern about a criterion.
+- `GOAL BLOCKED: <reason>` when the next meaningful action needs a named
+  dependency, owner decision, or unresolved failure; include the unblock needed.
+- `GOAL PAUSED: <reason>` only after an explicit owner pause; preserve the
+  cursor.
+- `GOAL REALIGNMENT REQUIRED` when a drift check fails; preserve the checkpoint
+  and resume only after recording a justified next action within the Goal anchor.
+- `GOAL TIMEBOXED: <state>` when the limit is reached; report progress and the
+  safest next action.
+- `GOAL STOPPED: <reason>` when the owner cancels or authority would be
+  exceeded.
+
+## Reporting
+After each iteration and at termination, report the terminal label (if any),
+verified evidence, remaining gap, and next cursor or unblock.
+```
+
+## Quality checks
+
+Before returning a Goal, check:
+
+- For preview-first work, the loop was shown and confirmed before the final Goal
+  was generated.
+- The objective describes an end state rather than a list of activities.
+- The Goal anchor is short enough to re-read and is not silently mutable.
+- Every acceptance criterion can be checked from named evidence.
+- The verification strategy separates iteration checks from required phase or
+  delivery checks, defines evidence validity and rerun triggers, and bounds
+  expensive commands without weakening acceptance requirements.
+- For feedback, adoption, pilot, launch, or validation work, the evidence
+  threshold and window are explicit; author-only activity is not counted unless
+  the Goal chooses it.
+- Pending external waits have a next check trigger and deadline/unblock. The
+  loop skips early polling, can continue independent work or yield, and retains
+  overall budget limits without counting waiting as a failed attempt.
+- Every iteration names one criterion, an expected delta, and a scope reason.
+- The next iteration is selected from current state, not from a fixed script
+  that ignores results.
+- The loop has a progress signal, a limit, a no-op rule, and a drift trigger.
+- Phase gates and a decision log make long runs resumable and auditable.
+- Complete, blocked, pause, and budget endings are distinguishable.
+- The instruction does not grant new access or external side effects that the
+  user did not authorize.
+- The final report leaves a durable cursor another agent could resume.

package/bundled-skills/goal-instruction-writer/references/loop-preview.md

@@ -0,0 +1,113 @@
+# Loop Preview Reference
+
+Use this format when the user wants to inspect the execution loop before the
+final Goal is written. The preview should be concrete enough to review, but it
+is not permission to execute the work.
+
+## Preview contract
+
+Show these elements in order:
+
+1. **Provisional outcome:** the current best one-sentence result, with
+   assumptions called out.
+2. **Starting state:** the baseline, known constraints, and first cursor.
+3. **Iteration flow:** what is inspected, selected, executed, verified, and
+   recorded in one cycle.
+4. **Branches:** what happens after success, a new failure, no progress, a side
+   quest, missing authority, a scheduled external wait, or a drift signal.
+5. **Progress evidence:** what must change for an iteration to count; which
+   checks run during edits or at delivery, when evidence can be reused, and
+   which changes trigger a rerun. Include bounds for expensive checks.
+6. **Drift gates:** when the Anchor is re-read and what triggers realignment.
+7. **Terminal states:** exact complete, blocked, paused, timeboxed, and stopped
+   conditions.
+8. **Decisions to confirm:** only the choices that could materially change the
+   loop, scope, evidence, or terminal rules. For feedback, adoption, pilot,
+   launch, or validation work, confirm the evidence threshold, what counts, and
+   the feedback window; for pending dependencies, include the next check
+   time/event, deadline/unblock, and independent work or yield branch.
+
+End with a handoff such as: “确认这个循环后，我再生成最终 Goal 指令。” Do not
+include a final executable Goal in a preview-only response and do not perform
+external mutations.
+
+## Visual shape
+
+```mermaid
+flowchart TD
+    A[Inspect baseline and cursor] --> W{Waiting before next check trigger?}
+    W -->|No| B[Choose one criterion and expected delta]
+    W -->|Yes| X{Independent work available?}
+    X -->|Yes| B
+    X -->|No| Y[Yield with wait checkpoint]
+    B --> C[Act within allowed scope]
+    C --> D[Verify evidence]
+    D --> E{Alignment check}
+    E -->|ON_TARGET| F[Record delta and next cursor]
+    F --> G{All criteria verified?}
+    G -->|No| H{Phase gate due?}
+    H -->|No| A
+    H -->|Yes| I[Re-read Anchor and review scope]
+    I --> A
+    G -->|Yes| J[GOAL COMPLETE]
+    E -->|SIDE_QUEST| K[Defer with revisit condition]
+    K --> A
+    E -->|DRIFTED| L[Pause and realign]
+    L --> M[GOAL REALIGNMENT REQUIRED]
+    D --> N{Blocked, budgeted, or owner-stopped?}
+    N -->|Blocked| O[GOAL BLOCKED]
+    N -->|Budget/time limit| P[GOAL TIMEBOXED]
+    N -->|Owner cancels| Q[GOAL STOPPED]
+```
+
+Overall time, token, and tool limits apply on every branch. The wait checkpoint
+records when the host or user may resume; it does not create a scheduler.
+
+## Preview table
+
+| Point in the loop | Preview question | Required decision |
+| --- | --- | --- |
+| Start | What state and cursor are authoritative? | Baseline and first work unit |
+| Select | Which criterion moves next? | Target criterion and expected delta |
+| Act | What is inside the boundary? | Allowed scope and authority |
+| Verify | What proves progress, and when must it be checked again? | Focused and phase/delivery checks, pass/fail rule, evidence reuse, rerun triggers, cost bounds |
+| Branch | What happens if the result is unexpected? | Retry with a new hypothesis, defer, block, or realign |
+| Gate | When is the Anchor re-read? | Cadence, milestone, and high-risk trigger |
+| Feedback | How much evidence counts as real feedback? | Threshold, what counts, and feedback window |
+| Wait | When can an external dependency be checked again? | Next check time/event, deadline/unblock, independent work or yield |
+| End | What makes the work legally stop? | Complete, blocked, paused, timeboxed, stopped |
+
+## Example preview
+
+```markdown
+## Loop preview
+
+### Provisional outcome
+Produce a tested importer patch that accepts the quoted multiline fixture.
+Assumption: the current fixture and test command are authoritative.
+
+### One iteration
+Inspect the failing parser path → choose one parsing hypothesis → make one
+focused change → run the fixture test → record the diff and result.
+
+### Branches
+- Test passes: mark C1 verified and select the next open criterion.
+- Test fails with new evidence: revise the hypothesis and try one different
+  focused change.
+- Same failure twice: stop as `GOAL BLOCKED` with the exact missing evidence.
+- Useful unrelated cleanup: mark `SIDE_QUEST` and defer it.
+- No criterion moves or scope expands: pause as
+  `GOAL REALIGNMENT REQUIRED`.
+
+### Gate and limits
+Re-read the Anchor after three iterations and before changing dependencies.
+Use at most four hypothesis iterations. Run the existing importer suite once
+the parser is stable; after a further parser change, refresh affected regression
+evidence. Report-only edits do not invalidate unrelated passing parser checks.
+Use the repository's command timeout for expensive checks; report any unverified
+criterion if it expires.
+
+### Confirm before drafting
+Please confirm the retry threshold and whether dependency changes are allowed;
+then the final Goal can be generated.
+```