fanhuadesenlinnn/tdesktop
1
0
Fork 0
mirror of https://hubproxy.babadafafafafa.cn/https://github.com/telegramdesktop/tdesktop synced 2026-09-20 08:03:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

[ai] Keep task review and testing focused and convergent

Browse Source
This commit is contained in:
John Preston
2026-08-23 08:21:14 +04:00
parent 316be6f553
commit a49c572f77
6 changed files with 486 additions and 198 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
.agents/shared/test-loop.md
View File

@@ -26,7 +26,9 @@ assessment, recovery, and reporting.
already-satisfied outcome;
- available commands, toolchains, targets, executables and UI-driver
capabilities;
- MAX_ATTEMPTS and MAX_TEST_RUNS.
- MAX_ATTEMPTS, MAX_TEST_RUNS, and MAX_TEST_CAMPAIGNS. The default campaign
bound is two total: one normal campaign and at most one focused recovery
campaign.
No instrument is globally mandatory. Its prerequisites become mandatory only
after assessment selects a check that needs it.
@@ -46,8 +48,10 @@ TEST_FLAW:
IMPL_BUG:
a sound check exposed a defect; fix the implementation, run targeted general
and affected-specialist review, retain the next implementation attempt, then
rerun only invalidated checks.
and invalidated-specialist review while carrying prior approvals forward,
retain the next implementation attempt, then rerun only invalidated checks.
Use the perform-task convergence gate after two non-converging bug fixes or
any architectural/scope expansion.
UNRECOVERABLE:
a required subject or capability cannot be reached safely after independent
@@ -103,16 +107,20 @@ surface. Record before each recovery:
- next direct instrument;
- why it executes the changed surface and preserves an independent oracle.
When the flaw's cause is the instrument idiom rather than this task's fixture,
repair the harness in the same run, not only the overlay: add the missing
helper to `Telegram/SourceFiles/test/`, tighten an existing contract so the
failed technique becomes unreachable, or add the symptom to that directory's
README failure-diagnosis table. Prefer making the technique impossible over
documenting that it is forbidden — the repair that retired the unbounded probe
accessor also exposed a check that had been passing vacuously in two earlier
runs, which a written rule would not have caught. A diagnosis left in one
task's notes is rediscovered by the next task at full campaign cost, and this
is the mechanism that stops it.
When the flaw's cause is a reusable instrument idiom rather than this task's
fixture, do not silently expand a product task's retained implementation into
shared harness work. Recover the current proof with a safe inventoried
disposable overlay/helper when possible, and record a concrete discovered
workflow follow-up to add or tighten the shared helper and its self-test. That
follow-up gets its own implementation, review, evidence, and `[ai]` commit
intent. If no safe disposable recovery can decide the current task without the
permanent harness repair, stop at the bounded recovery boundary and name that
dependency instead of mixing purposes in one task.
For a task whose requested outcome is itself the shared harness repair, retain
the change directly: prefer making a bad technique impossible over merely
documenting that it is forbidden, and verify the helper with focused harness
self-tests rather than an unrelated Telegram feature campaign.
Before writing any local overlay helper, search that directory first. An
overlay that reimplements a shared facility is itself a TEST_FLAW risk: the
@@ -133,11 +141,20 @@ The directness ladder is task-dependent:
subject.
After a repeated signature, use a fresh recovery assessment and forbid the
failed technique. MAX_TEST_RUNS closes one campaign, not the task: preserve
passes, isolate unmet checks, and either start focused recovery with a different
instrument or prove every applicable strategy unsafe, unavailable, or
non-causal in a Recovery exhaustion table. Time spent, the cap, repeated
failure, probe complexity, and a blank screenshot are not exhaustion.
failed technique. MAX_TEST_RUNS closes the normal campaign, not the task:
preserve passes, isolate unmet checks, and either start one focused recovery
campaign with a different instrument or prove every applicable strategy unsafe,
unavailable, or non-causal in a Recovery exhaustion table. The focused campaign
runs only unmet checks and their controls.
Do not start a third campaign. At the focused campaign cap, or after the same
focused failure signature repeats without a new directness step, run one final
independent assessment. It either records genuine recovery exhaustion or
returns a hard stop naming the still-plausible direct strategy and the human or
environment decision needed to continue. A cap, elapsed time, repeated failure,
probe complexity, and a blank screenshot are not exhaustion and never become
approval or a task `Block` by themselves; the hard stop leaves the task
`in-progress` and recoverable.
## Assessment

11
.agents/skills/continue/SKILL.md
View File

@@ -342,9 +342,20 @@ After it returns, require one of:
canonical AI master;
- source checkout clean and task exceptionally `blocked` on canonical master,
with exact unverified behavior;
- a pre-source `Scope: split-required` or review-convergence
`RESCOPE_REQUIRED` boundary with `work/split-proposal.md`, leaving the task
`in-progress` and all source/task recovery intact; or
- a clearly reported global hard stop, leaving the task `in-progress` and all
task-scoped local state recoverable for the next invocation.
A rescope boundary stops this invocation and is reported to the human; it is
not retried, approved, blocked, or routed as an ordinary discovered follow-up.
On a later invocation, a performer that finds the same unresolved boundary
returns it immediately without rerunning planning, review, builds, or tests.
Inbox planning prevents most new oversized tasks; replacing an already-active
task and deciding how to salvage its source is a deliberate queue mutation,
not authority the scheduler should infer.
Before accepting a canonical test block, read `work/result.md` and
`work/test.md`. It is genuine only when the verdict is not `TEST_FLAW`, does
not cite `MAX_TEST_RUNS` or a missing/blank capture as the blocker, and

47
.agents/skills/perform-task/SKILL.md
View File

@@ -119,9 +119,18 @@ produces:
3. one canonical `Approve <full-task-id>` commit containing all final AI
artifacts and state.
New and unfinished tasks use the single adaptive `implement` path. During
assessment, select one mandatory general review, every specialist review whose
failure surface is present, and a falsifiable evidence plan. The evidence loop
New and unfinished tasks use the single adaptive `implement` path. Assessment
must first confirm that the request is one cohesive implementation/review/test
unit. If it contains independently useful and independently testable product
boundaries, record `Scope: split-required` and a concrete split proposal before
source edits, then stop for queue rescoping; do not force the broad request
through smaller implementation phases and call it one task.
For a cohesive task, select one mandatory general review and a falsifiable
evidence plan. The first general review uses the complete implementation as the
safety net and chooses specialist reviews only for concrete material questions
that benefit from focused tracing or repository search. Surface presence is a
recall prompt, not an automatic specialist. The evidence loop
may use static readings, commands and artifacts, unit tests, a standalone probe
or component binary, a Telegram Debug build with logged assertions, an in-app
overlay, Computer Use, screenshots, or any necessary combination. Do not
@@ -129,13 +138,22 @@ require a portable account, Telegram executable, or desktop unless a selected
check uses it. Do not weaken a runtime or visual check merely because another
instrument is cheaper.
The assessment's selection is provisional until implementation exists. The
general reviewer examines the complete diff and evidence plan, may require a
missing specialist or stronger instrument, and cannot defer a concern to an
optional reviewer. Review fixes receive targeted re-review instead of an
unconditional replay of every lens. A task whose desired outcome was already
present may finish without a source commit only after the same general review
and evidence loop prove `Outcome: already-satisfied`.
The general reviewer examines the complete diff and evidence plan, may require
a specialist or stronger instrument, and cannot defer a concern to an optional
reviewer. Its approval and every clean specialist result carry forward. A fix
invalidates only the findings, changed invariants, specialists, validations,
and evidence checks it actually affects. Review fixes receive a focused general
delta review plus only those invalidated specialists; they do not restart the
full review or evidence design.
Automatic replay is bounded. If two review verdicts need changes, findings are
not converging, or a fix expands the architecture or owned paths, run the
pipeline's independent convergence assessment instead of another broad round.
It chooses a bounded focused repair, a coherent replan, or `RESCOPE_REQUIRED`;
unresolved findings are never approved merely to meet the bound. A task whose
desired outcome was already present may finish without a source commit only
after the same general review and evidence loop prove
`Outcome: already-satisfied`.
Only a genuine exhausted task blocker produces a
canonical `Block <full-task-id>` commit. Agent interruption, tool loss, and
@@ -146,10 +164,11 @@ A repeated evidence setup failure is not exhausted recovery by itself. Follow
the shared directness ladder: forbid the failed command, fixture, probe, or
capture technique and make the next run closer to the changed surface. The configured
test-run cap closes one campaign: preserve prior passes, isolate the unmet
checks, and start a focused recovery campaign unless a fresh assessment proves
every direct strategy exhausted. The cap and a `TEST_FLAW` can never by
themselves publish `BLOCKED`; the former two-identical-signature shortcut must
not be used.
checks, and start at most one focused recovery campaign unless a fresh
assessment proves every direct strategy exhausted. A second campaign cap or a
repeated non-converging focused signature stops automatic work for an explicit
human/convergence decision; it does not start another campaign. A cap and a
`TEST_FLAW` can never by themselves publish `BLOCKED` or approval.
A locked macOS session is not an environment stop or evidence blocker for a
selected Telegram runtime check. Skip interactive Computer Use and complete

308
.agents/skills/perform-task/references/phase-prompts.md
View File

@@ -22,8 +22,9 @@ every applicable placeholder: `<TASK>`, `<TASK_ID>`, `<WORK_DIR>`,
## Orchestration Rules
- When delegation is available, use a fresh subagent for Phase 1 (context and plan), Phase 3, each Phase 4 implementation unit, each Phase 6 general review pass, each surviving Phase 6 specialist, and each Phase 6 fix. Do not switch those phases to same-session midstream because of a timeout or missing artifact.
- The mandatory general reviewer runs first and alone on the complete diff, and emits the retirement list. Surviving specialist reviews are independent and write disjoint reports, so spawn them together when capacity allows, giving them the diff and the retirement decision but never the general reviewer's findings. The general reviewer then returns, confirms or drops their findings, reconciles the evidence design, and owns the overall verdict.
- When delegation is available, use a fresh subagent for Phase 1 (context and plan), Phase 3, each Phase 4 implementation unit, the initial Phase 6 general review, each selected specialist, each Phase 6 fix, each focused re-review, and any convergence assessment. Do not switch those phases to same-session midstream because of a timeout or missing artifact.
- The initial mandatory general reviewer runs first and alone on the complete diff, and emits a specialist decision table with one concrete material question for every selected lens. Selected specialists are independent and write disjoint reports, so spawn them together when capacity allows, giving them the diff and their question but never the general reviewer's findings. When the host supports continuing the saved general-review agent, send synthesis back to that agent; otherwise use one fresh synthesis agent with the saved general report and specialist reports instead of making it rediscover the whole review.
- After a fix, use the focused re-review prompt: one mandatory general reviewer over the fix and affected invariants, plus only specialists whose recorded question or blocker the fix invalidated. Carry every other approval forward. Do not schedule a lens from surface presence alone.
- Treat delegation as selected only after the first real phase spawn succeeds; tool presence is insufficient. An immediate depth/capacity/policy rejection before phase work selects same-session checklists and is not a delegated retry.
- Phase 7 runs in the current session on native, non-WSL Windows because it depends on the final local diff and touched-file set. Skip it on WSL and keep files LF/no-BOM there.
- Write each phase prompt to `<WORK_DIR>/logs/phase-<phase-name>.prompt.md` before execution.
@@ -43,7 +44,7 @@ every applicable placeholder: `<TASK>`, `<TASK_ID>`, `<WORK_DIR>`,
is the completion signal; there is no polling, no heartbeat-mtime ladder,
and no stall windows. On return, validate the artifact-based completion
checks below before treating the phase as done.
- Spawn the independent leaves of one step — the surviving Phase 6 specialists,
- Spawn the independent leaves of one step — the selected Phase 6 specialists,
or assessed-disjoint Phase 4 units —
as parallel Agent calls in a single message so they run concurrently.
- If a returned leaf fails its completion check, retry that disposable phase
@@ -57,7 +58,7 @@ every applicable placeholder: `<TASK>`, `<TASK_ID>`, `<WORK_DIR>`,
- When this session is a top-level `/perform-task`, run each leaf as one
blocking `spawn_subagent` (`background: false`). The call returning is
the completion signal; validate the artifact checks below on return.
- Spawn the independent leaves of one step — the surviving Phase 6 specialists,
- Spawn the independent leaves of one step — the selected Phase 6 specialists,
or assessed-disjoint Phase 4
units — as parallel `spawn_subagent` calls in a single message.
- When this session is a `/continue` child, do not call `spawn_subagent`.
@@ -70,6 +71,9 @@ every applicable placeholder: `<TASK>`, `<TASK_ID>`, `<WORK_DIR>`,
### Codex: asynchronous spawn and wait
- Store the canonical target returned by `spawn_agent`.
- After the initial general reviewer finishes pass 1, keep its canonical target.
When specialists finish, use `followup_task` on that target with the pass-2
synthesis prompt instead of spawning a second complete-diff reviewer.
- Poll with `wait_agent` for at most 60 seconds per call; use elapsed wall-clock windows for stall decisions. Use 30-60 second polls when a phase appears close to landing.
- `wait_agent` is mailbox-wide and may wake for another agent or user input. A timeout is not failure. After every wake, handle new user input if any, inspect the saved target with `list_agents`, and check the expected artifact and matching progress file.
- If the expected artifact exists and shows progress, wait again.
@@ -121,11 +125,12 @@ Do not restate the full context, plan, diff, or long reasoning in the chat reply
were made. For a project task, `project.proposed.md` must also exist and be
non-empty. For a `Visual: layout` task, `visual.md` must also satisfy the
visual design completion check below.
- Phase 3 is complete only when `plan.md` contains both `Phases:` in the Status section and `Assessed: yes`, or records a rejection outcome (`Fast-Path: rejected` or `Approach: rejected`) that sends the performer back to a fresh Phase 1 leaf.
- Phase 3 is complete only when `plan.md` contains both `Phases:` in the Status section and `Assessed: yes`, records a rejection outcome (`Fast-Path: rejected` or `Approach: rejected`) that sends the performer back to a fresh Phase 1 leaf, or records `Scope: split-required` and has a complete `split-proposal.md` that stops source work for queue rescoping.
- Phase 4 is complete only when the target phase checkbox changed to checked and the touched-file list matches the owned write set, or the blocker explains any mismatch.
- Phase 5 is complete only when the build outcome is known and the build checkbox is updated on success.
- A Phase 6 specialist is complete only when every scheduled specialist wrote `review<R>-<lens>.md` with a `## Verdict:` line and a non-empty `## Checked` section. A report that records no checked surfaces is incomplete work.
- Phase 6 general review is complete only when `review<R>-general.md` and `review<R>.md` exist with a `## Verdict:` line, a non-empty `## Coverage` section, every retired lens carrying its absence assertion, every surviving lens accounted for, and every evidence check reconciled against the actual diff.
- A Phase 6 specialist is complete only when every scheduled specialist wrote `review<R>-<lens>.md` with a `## Verdict:` line and a non-empty `## Checked` section tied to its assigned material question. A report that records no checked surface is incomplete work.
- Initial Phase 6 general review is complete only when `review1-general.md` and `review1.md` exist with a `## Verdict:` line, a non-empty `## Coverage` section, every standard lens marked `SELECT` or `OMIT` with a valid reason, every selected lens accounted for, and every evidence check reconciled against the actual diff.
- A focused Phase 6 review is complete only when `review<R>-focused.md` and `review<R>.md` name the fix paths and invariants, account for every carried-forward and invalidated approval, account for every rerun specialist, and reconcile only invalidated evidence checks. A convergence assessment is complete only with one exact disposition from the pipeline and its required bounded next action or split proposal.
- Phase 6b is complete only when the requested fixes were applied and the post-fix build outcome is known.
- Phase 3 is additionally incomplete until `test-design.md` exists, covers
every acceptance surface, assigns each check a direct instrument, oracle,
@@ -332,12 +337,15 @@ Do not implement code in this phase.
## Phase 3: Plan Assessment
Assessment has two rejection outcomes besides refinement, and both withhold
`Assessed: yes` and send the performer back to a fresh Phase 1 leaf:
Assessment has two approach rejection outcomes besides refinement, and both
withhold `Assessed: yes` and send the performer back to a fresh Phase 1 leaf:
`Fast-Path: rejected` when the performer's same-session Phase 1 undersized the
task, and `Approach: rejected` when the plan is over-engineered or over-coupled
beyond step-level repair. On an approach rejection the performer appends the
assessor's named simpler direction to the Phase 1 rerun prompt.
assessor's named simpler direction to the Phase 1 rerun prompt. A third outcome,
`Scope: split-required`, means the request itself contains several independently
useful and testable product boundaries; it writes `split-proposal.md` and stops
before source edits instead of trying another plan for the same task.
```text
You are a plan assessment agent. Review and refine an implementation plan.
@@ -380,10 +388,10 @@ Assess the plan:
beats both growing a mega-module and scattering through one; judge
whether the boundary does work, not whether it is new.
5. Expected surfaces: record the surfaces this task is likely to touch and the
escalations they would imply, as a note for the reviewer. Do not select or
omit review lenses here — the general reviewer decides that with the diff in
hand, and every optional lens runs unless it retires the lens by asserting
the absence of its surface.
escalations they would imply, as a recall note for the reviewer. Do not
select or omit review lenses here — the first general reviewer decides that
with the diff in hand from concrete material questions, not surface presence
alone.
6. Evidence design: map every acceptance criterion and material shipped risk to
the most direct practical instrument that can detect the negative. Allow
static readings, commands/artifacts, unit tests, a standalone probe or
@@ -392,7 +400,10 @@ Assess the plan:
Preserve deep app testing when behavior lives in Telegram, and require tight
captures for visible claims. Do not require Telegram for an isolated probe or
build-stage claim it cannot strengthen.
7. Phase sizing: Each phase should be implementable by a single agent in one session. If a phase has more than about 8-10 substantive code changes, split it further.
7. Phase sizing: Each phase should be implementable by a single agent in one
session. If a phase has more than about 8-10 substantive code changes, split
the phase. Then assess the task as a whole: several well-sized phases do not
make an intrinsically broad task cohesive.
8. Visual contract (layout tasks): when visual.md exists, verify its anchors
are real (the cited style tokens, fonts, and reference widgets exist),
the ordered derivation is arithmetically consistent, and every quantity the
@@ -412,15 +423,38 @@ Assess the plan:
precedent or existing mechanism to ride on, which existing files absorb
the change, and where it stays contained. The performer reruns Phase 1 as
a fresh leaf with those lines as input.
11. Intrinsic scope: decide whether one fresh reviewer and one coherent
evidence campaign can judge the final retained result. Strong split signals
are multiple parts with their own useful outcome and oracle; a stable
dependency order where a later part can consume an earlier approved part;
separate network, persistence, concurrency/ownership, engine, lifecycle, or
UI boundaries; materially different fixtures or platforms; or a diff too
broad for one reviewer to reason about as one invariant set. Phase count,
changed-file count, and acceptance count are warning signals, not automatic
thresholds. Keep inseparable API-plus-only-caller changes together.
Update plan.md with your refinements. Keep the same structure but:
When this fails because of the request rather than the proposed approach,
add `Scope: split-required` to Status, do NOT add `Assessed: yes`, and write
`<WORK_DIR>/split-proposal.md` with:
- why one review/test campaign is not coherent;
- the smallest independently buildable and testable replacement tasks;
- each task's shipped boundary, acceptance oracle, and dependencies;
- which current source or validated artifacts, if any, can be salvaged;
- a final integration task only when integration itself has behavior not
already proved by the component tasks.
Do not edit source and do not create or mutate queue tasks. Return
`RESCOPE_REQUIRED` to the performer.
If you selected any rejection outcome, write only its required status, reason,
direction or split proposal and stop. Otherwise update plan.md with your
refinements. Keep the same structure but:
- fix any inaccuracies
- add missing steps
- remove files, abstractions, and steps the task does not need — deletion is
as much a refinement as addition
- improve the approach if you found better patterns
- ensure phases are properly sized for single-agent execution
- finalize `## Expected Surfaces` as a note for the reviewer, selecting no lens
- finalize `## Expected Surfaces` as a recall note for the reviewer, selecting no lens
- finalize `## Evidence Plan`, then write `<WORK_DIR>/test-design.md` with one
check per acceptance surface: Claim, Changed surface, Instrument, Oracle,
Window, Control, Falsifier, and Evidence. State which prerequisites are
@@ -530,32 +564,39 @@ review runs for every task. The optional library is lifetime, reuse, structure,
performance, and security; the general reviewer may add a specialist-<domain>
review for another material risk.
For iteration R:
For the initial implementation:
1. Run the general reviewer first and alone, on the complete diff. Besides its
own review it emits the retirement list: every optional lens runs unless it
is retired, and a lens is retired only by asserting the absence of its
surface in the terms `pipeline.md` gives. Record each retirement with its
assertion. It writes review<R>-general.md.
2. Run the surviving specialists independently and in parallel. Give them the
diff and the retirement decision, never the general reviewer's findings.
They write review<R>-<lens>.md.
3. The general reviewer returns, confirms or drops each specialist finding
against the code, and writes the actionable review<R>.md, accounting for
every retired and every surviving lens.
4. APPROVED closes review. NEEDS_CHANGES runs the fix phase for blocking
1. Run the general reviewer first and alone on the complete diff. It owns the
complete safety review and writes `review1-general.md` with a `SELECT` or
`OMIT` decision for every standard lens. Every `SELECT` includes one concrete
material failure question and affected paths/invariants. Surface presence is
a recall prompt, not a reason by itself.
2. Run selected specialists independently and in parallel. Give each the diff
and its exact question, never the general reviewer's findings or another
review report. They write `review1-<lens>.md`.
3. Continue the same general-review agent for synthesis when the host supports
it. Otherwise use a fresh synthesis agent that starts from
`review1-general.md`, reads the specialist reports, and opens only the code
needed to confirm their findings. It writes actionable `review1.md`.
4. `APPROVED` closes review. `NEEDS_CHANGES` runs the fix phase for blocking
findings only.
5. After a substantive fix, increment R, rerun general with emphasis on the
changed hunks so it re-decides retirement there, and rerun only the
specialists whose surfaces the fix touched or whose prior blocking finding
was repaired. A fix that changed no owned source closes the loop without
another round.
There is no automatic five-lens replay, and no lens is skipped by omission:
silence retires nothing. Every review cycle must either add material coverage,
validate changed code, or close. A wording or style suggestion is non-blocking
unless it causes incorrect behavior, unsafe use, misleading build instructions,
a repository-rule violation, or a material maintenance defect.
For a fix, increment R and do not repeat the initial shape. Run one focused
general reviewer over the fix result, changed paths/functions, affected callers,
prior blockers, and invalidated evidence checks. Rerun only a specialist that
originated a repaired blocker or whose exact recorded question the fix changed.
The focused general reviewer confirms those reports and writes `review<R>.md`,
explicitly carrying all other approvals forward.
After two `NEEDS_CHANGES` verdicts, non-shrinking findings, architectural/scope
expansion, or loss of a reliable carry-forward boundary, run the convergence
prompt instead of another ordinary fix round. It permits at most one final
focused repair before a stop, replan, or rescope. The bound never converts an
unresolved finding into approval.
A wording or style suggestion is non-blocking unless it causes incorrect
behavior, unsafe use, misleading build instructions, a repository-rule
violation, or a material maintenance defect.
### Shared specialist preamble
@@ -568,8 +609,16 @@ Read:
- <WORK_DIR>/plan.md
- AGENTS.md and REVIEW.md
- the task specification
- the complete task diff and every changed file in full
- for R > 1, the preceding actionable review and fix result
- the complete task diff and changed files relevant to the assigned question
- the exact material review question and affected paths/invariant
- for R > 1, only the preceding actionable finding and fix result assigned to
this specialist
Do not read another reviewer's findings. Do not search or read
`<WORK_DIR>/review*` or phase-review logs beyond the exact files listed above;
root repository searches at the source checkout instead. If another review
report is exposed accidentally, disclose it and stop so only this specialist
can be rerun cleanly.
Review only this task's diff under your assigned angle. Search outside the diff
when your angle requires repository or call-site context, but do not report
@@ -586,7 +635,8 @@ Write <WORK_DIR>/review<R>-<LENS>.md:
## Lens: <LENS> — iteration <R>
## Checked
<Every changed surface examined under this angle and what was established.>
<Every relevant changed surface examined for the assigned question and what
was established.>
## Findings
<For each: title, file/line, Severity: BLOCKING | NON_BLOCKING, concrete
@@ -679,37 +729,46 @@ security invariant for a blocking finding.
### Mandatory general review
The general reviewer owns the result and cannot assume a specialist covered an
angle. It runs twice per iteration: pass 1 alone on the diff, emitting the
retirement list, and pass 2 after the surviving specialists report.
angle. Its initial pass is the one complete-diff safety review. Synthesis should
continue that reviewer when possible; a replacement synthesis reviewer starts
from its saved work rather than duplicating it.
~~~text
You are the mandatory general reviewer for one Telegram Desktop task,
iteration <R>, pass <PASS> of 2. You are a leaf and must not delegate.
initial review, pass <PASS> of 2. You are a leaf and must not delegate.
Read:
- the task specification and every referenced input
- <WORK_DIR>/context.md, plan.md, visual.md when present, and test-design.md
- AGENTS.md and REVIEW.md
- on pass 2 only, every review<R>-<lens>.md the surviving specialists wrote
- the complete task diff and every changed file in full
- adjacent callers, consumers, generated/build declarations, and repository
- on pass 1, the complete task diff and every changed file in full, plus
adjacent callers, consumers, generated/build declarations, and repository
precedents needed to judge integration
- on pass 2, review1-general.md, every selected review1-<lens>.md, and only the
code needed to confirm/drop a specialist finding or resolve a contradiction
Independently review correctness, completeness, edge/error paths, unintended
regressions, integration, proportionality, repository conventions, and the
evidence design. Do not defer anything to a specialist.
On pass 1 no specialist has run yet. Besides your own review, emit the
retirement list. Every optional lens — lifetime, reuse, structure, performance,
security — runs unless you retire it, so a lens you do not mention still runs.
Retire one only by asserting the absence of its surface in the exact terms
pipeline.md gives, and write that assertion beside it; a failing clause keeps
the lens, and "documentation only" is not an assertion of absence. Name any
extra domain specialist a material risk needs. Then return: the performer runs
the surviving specialists and calls you back for pass 2.
On pass 1 no specialist has run yet. Besides your own review, emit a specialist
decision table. Mark every optional lens — lifetime, reuse, structure,
performance, security — exactly `SELECT` or `OMIT`; silence is invalid.
`SELECT` only when the actual diff presents a concrete material failure question
for which focused tracing, call-site search, or domain expertise adds useful
independent confidence. State the question, affected paths/invariant, and the
failure it could expose. `OMIT` when the surface is absent or narrow enough that
your complete review already established its relevant invariant with no open
specialist question; state that proof. Surface presence alone, `low risk`, time
pressure, or `documentation only` is not a decision. Name any extra domain
specialist a material risk needs. Then return: the performer runs selected
specialists and calls you back for pass 2.
On pass 2, confirm every specialist finding against the code; drop it when the
concrete failure does not hold.
concrete failure does not hold. Do not redo the complete general review; carry
pass 1 findings and coverage forward and open only the code needed for
synthesis or a newly contradicted invariant.
Reconcile test-design.md against the actual diff:
- every acceptance criterion and material new risk has a check;
@@ -725,11 +784,10 @@ Reconcile test-design.md against the actual diff:
- selected instrument prerequisites are explicit, and unavailable unselected
instruments are not treated as blockers.
If pass 2 exposes a material risk no surviving lens covered — including one you
retired on pass 1 — write "Missing specialist: <name> — <reason>" and return
without an implementation verdict. The performer runs that specialist, then
calls you back again in iteration R. Retiring a lens you then have to recall is
a worse outcome than keeping it, so retire only on the absence clauses.
If pass 2 exposes a concrete material question no selected lens covered, write
"Missing specialist: <name> — <question>" and return without an implementation
verdict. The performer runs only that specialist, then calls you back. Do not
turn a generic surface into a late specialist request.
Classify findings:
- BLOCKING: concrete wrong behavior, crash, race, security/data-safety failure,
@@ -738,13 +796,14 @@ Classify findings:
- NON_BLOCKING: optional wording, preference, speculative cleanup, or polish.
Preserve it in Dropped/Notes, but do not ask the fix agent to implement it.
Write <WORK_DIR>/review<R>-general.md with Checked, specialist confirmation,
Write <WORK_DIR>/review1-general.md with Checked, the specialist decision table,
specialist confirmation,
evidence reconciliation, findings and verdict. Then write
<WORK_DIR>/review<R>.md:
<WORK_DIR>/review1.md:
## Code Review — Iteration <R>
## Code Review — Initial
## Coverage
<general coverage plus selected/omitted specialist reasons>
<general coverage plus every SELECT/OMIT reason and material question>
## Evidence reconciliation
<each planned check confirmed or changed>
## Verdict: APPROVED | NEEDS_CHANGES | MISSING_SPECIALIST
@@ -757,6 +816,88 @@ An APPROVED verdict requires no blocking finding and complete evidence
reconciliation. NEEDS_CHANGES requires at least one blocking finding.
~~~
### Focused general re-review
~~~text
You are the mandatory focused general reviewer for one Telegram Desktop task,
review round <R> after a blocking fix. You are a leaf and must not delegate.
Read:
- the task specification, AGENTS.md, and REVIEW.md;
- <WORK_DIR>/review<R-1>.md and the fix result;
- the fixed paths, containing functions/types, and affected callers;
- test-design.md entries the fix reports invalidated;
- only the specialist reports explicitly rerun for this fix.
Do not restart the complete-diff review. Verify each repaired blocker, inspect
the fix for regressions in its actual data/control/lifetime boundary, and check
that no undeclared path changed. For every prior general and specialist approval,
record `CARRIED` with why the fix did not touch its exact code or invariant, or
`INVALIDATED` with the concrete changed question. Presence of a broad surface is
not invalidation.
Rerun a specialist only when it originated a repaired blocker, its exact prior
question changed, or this fix introduced a new concrete material question that
focused expertise must answer. If one is needed and has not run, write
`Missing specialist: <name> — <question>` and return; the performer runs only
that specialist and calls you back.
Reconcile only evidence checks whose changed surface, oracle, fixture, or
expected result the fix invalidated. Carry all other checks forward.
Write <WORK_DIR>/review<R>-focused.md and <WORK_DIR>/review<R>.md with:
## Code Review — Focused round <R>
## Fix boundary
<touched paths, repaired blockers, affected functions/invariants>
## Carried approvals
<general, specialist, validation, and evidence approvals with reason>
## Invalidated approvals
<only those actually changed, plus rerun result>
## Verdict: APPROVED | NEEDS_CHANGES | MISSING_SPECIALIST | CONVERGENCE_REQUIRED
## Changes Required
<blocking findings only>
Return `CONVERGENCE_REQUIRED` rather than another ordinary fix when this is the
second NEEDS_CHANGES verdict, findings did not shrink, the fix expanded owned
paths/architecture, or the carry-forward boundary is unreliable.
~~~
### Review convergence assessment
~~~text
You are an independent review-convergence assessor for one Telegram Desktop
task. You are a leaf and must not delegate or edit source.
Read the task, context.md, assessed plan.md, every canonical review<R>.md, every
fix result, current owned paths, the current complete task diff, and the exact
validation/evidence status. Read source only as needed to decide disposition.
Diagnose why review is not converging: repeated discovery in stable code,
regressions introduced by fixes, architectural coupling, oversized intrinsic
scope, or an external unsafe boundary. Preserve findings already resolved and
do not run another broad review.
Write <WORK_DIR>/review-convergence<C>.md with exactly one verdict:
## Verdict: CONTINUE_FOCUSED | REPLAN_CURRENT | RESCOPE_REQUIRED | HARD_STOP
- CONTINUE_FOCUSED: one bounded list of remaining blockers, one owned write
set, the approvals carried forward, and at most one final focused review.
- REPLAN_CURRENT: why the task remains cohesive, the exact validated source
boundary to preserve or restore, and the replacement approach. Do not use
this to disguise multiple independent product outcomes as phases.
- RESCOPE_REQUIRED: why one review/evidence campaign is incoherent and a
split-proposal.md containing independently buildable/testable replacement
tasks, acceptance oracles, dependencies, and salvageable work.
- HARD_STOP: the exact unsafe or unavailable condition and required human
action.
The verdict cannot approve code. If a permitted final focused round still has
blocking findings, stop with its unapproved artifacts; do not begin another
campaign automatically.
~~~
### Review fix
~~~text
@@ -768,12 +909,18 @@ file named by a blocking finding. Implement only "Changes Required".
Do not implement Dropped or non-blocking notes. Stay inside owned-paths.txt and
do not edit AI artifacts.
After editing, run the cheapest pre-review validation affected by the fix. For
an app-source fix this is normally the configured Debug build; for an isolated
script, generated artifact, or probe it may be its focused syntax/configure or
component check. Use build-lock recovery when applicable.
After editing, run the cheapest validation that can catch breakage in the fixed
surface: a focused compile/target, syntax/configure check, unit, probe, or
component command when sufficient. Rerun the complete Telegram Debug build
immediately only when the fix changes the build graph/ABI or no focused command
can validate compilation; otherwise the performer runs the complete selected
pre-review validation once after review approval. Use build-lock recovery when
applicable.
Report exact touched paths and which review specialists the fix invalidated.
Report exact touched paths, repaired findings, changed functions/invariants,
which prior specialist question (if any) the fix invalidated and why, and which
validation/evidence checks it invalidated. Surface presence alone is not
invalidation.
If no blocking finding can be acted on inside the owned write set, change
nothing and report that boundary.
~~~
@@ -831,8 +978,10 @@ for independent confirmation.
## Evidence-Campaign-Cap Assessment
At MAX_TEST_RUNS with an evidence flaw still open, use a fresh assessor. The cap
is a convergence checkpoint, never a terminal verdict.
At MAX_TEST_RUNS with an evidence flaw still open, use a fresh assessor. The
first campaign cap may start one focused recovery campaign. A focused campaign
cap or repeated non-converging focused signature is the final automatic
checkpoint; it cannot start a third campaign.
~~~text
Read the task, final diff, plan.md, test-design.md, test.md, every run artifact,
@@ -850,9 +999,10 @@ Write <WORK_DIR>/test-cap-assessment-<C>.md:
<each instrument or setup already attempted and forbidden, followed by the next
safe strategy that executes the changed surface>
## Verdict: FOCUSED_RECOVERY | RECOVERY_EXHAUSTED
## Verdict: FOCUSED_RECOVERY | RECOVERY_EXHAUSTED | HARD_STOP
Choose FOCUSED_RECOVERY whenever a safer or more direct reading, command,
Choose FOCUSED_RECOVERY only after the normal campaign and whenever a safer or
more direct reading, command,
artifact inspection, unit, probe, component, Telegram log/overlay, physical
interaction or visual capture can still decide an unmet check. The next
campaign runs only unmet checks and their controls.
@@ -861,6 +1011,12 @@ Choose RECOVERY_EXHAUSTED only when every applicable instrument is unsafe,
unavailable, or would bypass the task's changed surface. Time spent, a run cap,
overlay complexity, a blank screenshot, or repeated identical failure is not
exhaustion.
At the focused campaign boundary, choose HARD_STOP when a plausible safe direct
strategy remains but automatic recovery did not converge. Name that strategy,
the exact prior proof retained, and the human/environment decision needed to
continue. Leave the task in-progress; do not publish approval or Block and do
not begin another campaign automatically.
~~~

243
.agents/skills/perform-task/references/pipeline.md
View File

@@ -63,6 +63,7 @@ out/Debug/Telegram.app/Contents/MacOS/Telegram
MAX_ATTEMPTS = 4
MAX_TEST_RUNS = 12 per test campaign
MAX_TEST_CAMPAIGNS = 2 total: one normal and at most one focused recovery
COMPUTER_USE_POLICY = auto | overlay-only | required
```
@@ -138,9 +139,13 @@ work/context.md
work/project.proposed.md # project tasks only
work/visual.md # layout tasks only
work/plan.md
work/review1-general.md # mandatory independent review and verdict
work/review1-<specialist>.md # only specialists selected by assessment
work/review1.md # actionable overall verdict for the iteration
work/split-proposal.md # only when assessment rejects intrinsic scope
work/review1-general.md # mandatory complete-diff review and selection
work/review1-<specialist>.md # specialists selected for material questions
work/review1.md # canonical first-review verdict
work/review<R>-focused.md # mandatory focused general re-review, R > 1
work/review<R>-<specialist>.md # only specialists invalidated by the fix
work/review-convergence<C>.md # bounded loop disposition when needed
work/test-design.md # assessed evidence contract, reconciled after diff
work/test.md
work/test-cap-assessment-*.md # independent focused-recovery decision at a campaign cap
@@ -206,9 +211,11 @@ prompts, plus the host-specific orchestration rules.
touch and the change is mechanical — roughly two source files or fewer, no
new APIs, strings, or style tokens, no layout derivation. When in doubt,
delegate. Assessment always runs as a fresh leaf and has the authority to
reject the fast-path sizing or the plan's whole approach as over-engineered;
either rejection forces a Phase 1 leaf rerun, an approach rejection with the
assessor's simpler direction added to the prompt.
reject the fast-path sizing, reject the plan's whole approach as
over-engineered, or reject the task itself as several independently testable
product boundaries. Fast-path and approach rejection force a Phase 1 leaf
rerun; intrinsic scope rejection writes the split proposal and stops before
source edits so queue planning can replace the task.
- Use `fork_turns: "none"` with explicit paths. Fork the smallest turn window
only for genuinely unavailable chat-only visual context.
- Inherit the parent's model and reasoning level. Do not invent tool fields.
@@ -256,11 +263,19 @@ Run sequentially:
duplication, edge cases, repository conventions, and phase sizing; weigh
the approach against the closest repository precedent and its containment
against the shared modules it touches, and reject over-engineering rather
than refining it; on layout tasks verify the visual contract's anchors and
derivation; on a fast-path plan verify the sizing itself. Require
than refining it. Before approving the plan, apply the intrinsic-scope gate:
if it contains several useful boundaries with separate acceptance or
evidence, stable dependency order, or materially different subsystems and
failure analysis, write `work/split-proposal.md`, record
`Scope: split-required`, and stop before source edits. Phase count and line
count are warning signals, not automatic decisions; the decisive question
is whether one fresh reviewer and one coherent evidence campaign can judge
the retained result. On layout tasks verify the visual contract's anchors
and derivation; on a fast-path plan verify the sizing itself. Require
`Phases: <N>` and `Assessed: yes`, or a recorded `Fast-Path: rejected` /
`Approach: rejected` outcome that reruns Phase 1 as a fresh leaf — an
approach rejection with the assessor's simpler direction as added input.
approach rejection with the assessor's simpler direction as added input —
or the terminal pre-edit `Scope: split-required` planning boundary.
3. **Implement.** Run one leaf per assessed plan phase. Before each edit,
update `work/owned-paths.txt`. A leaf edits only its owned paths and its
phase status; it does not commit.
@@ -273,22 +288,27 @@ Run sequentially:
cleanup and build-lock recovery only to a command that writes the configured
build tree.
5. **Review.** Run the adaptive review/fix loop from the phase prompts. The
independent general reviewer always runs over the complete diff, adjacent
integration, task contract, and `work/test-design.md`. Before it, run every
specialist selected by assessment: lifetime (including concurrency and
races), reuse, structure, performance, security, or a named domain review.
The general reviewer confirms or drops their findings, adds any missing
specialist or evidence check, and writes the single `review<R>.md` the fix
phase implements. Only material blocking findings cause a fix. After a fix,
rerun the general review plus specialists whose surfaces changed; never
replay unrelated lenses. Rebuild or rerun a cheaper pre-review check only
when the fix touched that instrument's surface.
first independent general reviewer always examines the complete diff,
adjacent integration, task contract, and `work/test-design.md`, and selects
specialists for concrete material questions. It confirms or drops their
findings and writes the single `review1.md` the fix phase implements. Only
material blocking findings cause a fix. After a fix, preserve every prior
approval that the fix did not invalidate: run one focused general review of
the fix and affected invariants, plus only the specialists that originated a
repaired blocker or whose exact review question the fix changed. Presence of
a broad surface is not enough to replay it. Reconcile only invalidated
evidence checks and rerun only affected validation. At the convergence
triggers below, stop the ordinary loop and obtain an explicit repair,
replan, or rescope disposition.
6. **Normalize.** On native non-WSL Windows, normalize only task-owned source,
header, style, localization, and build/config text to CRLF without BOM,
preserving content and trailing-newline state, then rerun the selected
pre-review validation when normalization could affect it. On macOS,
Linux, and WSL preserve LF/no-BOM.
7. **Commit and test.** When the task changed source, create the implementation
7. **Commit and test.** If any review fix followed the last complete selected
pre-review validation, run that complete validation once after review
approval; focused per-fix checks do not replace this final gate. When the
task changed source, create the implementation
commit with the scripted helper, then run the evidence loop below:
```bash
@@ -332,77 +352,111 @@ Evidence plan:
- Evidence: <planned durable output>
```
Assessment does not choose reviewers. The general reviewer does that with the
diff in hand, and `Expected surfaces` is a note for it, not a decision.
Assessment rejects ceremony as well as under-testing: it removes checks that
cannot be affected by the task.
Assessment does not choose reviewers. The first general reviewer does that with
the diff in hand, and `Expected surfaces` is a recall checklist rather than an
automatic decision. Assessment rejects ceremony as well as under-testing: it
removes checks that cannot be affected by the task.
### Review selection
Selection happens with the diff in hand, never before it. Assessment records
the surfaces it expects and the escalation triggers it can name, but it does
not choose reviewers: a lens picked from the task text is a prediction, and
the hazards that matter are routinely invisible until the implementation
exists. A task reading `open a different page` produced a use-after-free that
only the diff showed.
Selection happens with the implementation in hand. Assessment records expected
surfaces and escalation triggers, but a task-text prediction neither schedules
nor omits a reviewer.
The independent **general** review therefore runs first, alone. It reads every
changed file in full and owns correctness, completeness, adjacent integration,
unintended regressions, proportionality, repository conventions, and the
adequacy of the evidence plan. It cannot defer a concern to a specialist.
The independent **general** review runs first, alone, exactly once for the
initial implementation. It reads every changed file in full and owns
correctness, completeness, adjacent integration, unintended regressions,
proportionality, repository conventions, and evidence adequacy. It cannot defer
a concern to a specialist. This complete-diff pass is the mandatory safety net.
Its first output is the **retirement list**. Every specialist below runs unless
the general reviewer retires it, so a lens nobody considered still runs. Retire
one only by asserting the absence of its surface in the terms given, and record
each retirement with that assertion in `review<R>.md`:
Its first output is a **specialist decision table**. Account for every lens
below with `SELECT` or `OMIT`; silence is invalid. Select a specialist only when
the diff creates a concrete material failure question that focused tracing,
call-site search, or domain expertise is likely to answer better than the
general pass alone. Record that question, the affected paths or invariant, and
what a failure would do. Omit it when the surface is absent, or when the surface
is narrow and the general reviewer has already established the relevant
invariant with no unresolved specialist question. `Low risk`, time pressure,
and `documentation only` are not sufficient reasons by themselves.
- **lifetime** — owns object and resource ownership, callbacks, re-entrancy,
The lens surfaces are recall prompts, not automatic retention clauses:
- **lifetime** — object and resource ownership, callbacks, re-entrancy,
destruction order, threads, concurrency, races, synchronization,
cancellation, and shutdown. Retire only when the diff adds or changes no
owner, stores nothing past its call, registers no callback or subscription,
touches no destruction or teardown path, and crosses no thread or async
boundary.
- **reuse** — owns duplication of an established helper, API, style, string,
switch, algorithm, or mechanism. Retire only when the diff introduces none
of those and edits existing call sites alone.
- **structure** — owns cross-module placement, broad moves or deletion,
generated files, build graphs, platform containment, and new abstractions.
Retire only when the diff adds, moves and deletes no file, changes no build
graph or generated output, and crosses no module or platform boundary.
- **performance** — owns hot or repeated paths, main-thread blocking, startup,
memory, I/O, scale, and material build-time cost. Retire only when the diff
adds nothing to a repeated, hot or startup path, adds no allocation, I/O or
blocking work there, and adds no material build-time cost.
- **security** — owns secrets, authentication, permissions, privacy,
cryptography, untrusted input, command or subprocess construction,
filesystem boundaries, downloads, network trust, and destructive behavior.
Retire only when the diff touches none of them.
cancellation, and shutdown;
- **reuse** — duplication of an established helper, API, style, string, switch,
algorithm, or mechanism;
- **structure** — cross-module placement, broad moves or deletion, generated
files, build graphs, platform containment, and new abstractions;
- **performance** — hot or repeated paths, main-thread blocking, startup,
memory, I/O, scale, and material build-time cost;
- **security** — secrets, authentication, permissions, privacy, cryptography,
untrusted input, command or subprocess construction, filesystem boundaries,
downloads, network trust, and destructive behavior.
One failing clause keeps the lens. The test is presence of the surface, not an
estimate of how risky it looks: presence is checkable by the next reader and
severity is not, and severity judged under time pressure drifts optimistic.
`documentation only` is not an assertion of absence; the clauses above are.
The general reviewer may add a named domain specialist when a material risk
such as ABI portability or persistence migration fits none of the lenses.
The general reviewer may also add a named domain specialist when a material
risk such as ABI portability or persistence migration fits none of the lenses.
Run selected specialists independently and in parallel. Give each the task
diff, its exact material review question, and source paths, but never the
general reviewer's findings or another review report. Specialist source search
is rooted at `SOURCE_ROOT`; it must not search or read `WORK_DIR/review*` or
phase-review logs beyond the explicit input list. Accidental exposure is
reported and invalidates only that specialist, not already independent work.
Then run the surviving specialists independently and in parallel. Give them the
diff and the retirement decision, never the general reviewer's findings: a
specialist that reads them anchors on them, and the independence of the lenses
is what lets the synthesis drop a finding another lens refutes.
A specialist reports only material findings with a concrete failure. Reuse the
same general reviewer for synthesis when the host supports continuing that
agent; otherwise a fresh synthesis reviewer starts from the saved general
report and specialist reports, then reads only code needed to confirm or drop
their findings. It writes the sole `review1.md` verdict and accounts for every
lens decision. Wording, style, or optional cleanup that does not cause wrong
behavior, unsafe use, material maintenance cost, or a repository-rule violation
is non-blocking and never starts a fix cycle.
A specialist reports only material findings with a concrete failure. The general
reviewer then returns, confirms each one against the code, and writes the sole
`review<R>.md` verdict, which accounts for every retired and every surviving
lens. Wording, style, or optional cleanup that does not cause wrong behavior,
unsafe use, material maintenance cost, or violated repository rules is
non-blocking and never starts a fix cycle.
### Focused re-review and convergence
After a blocking fix, repeat the same shape against what the fix changed:
general reruns with emphasis on the changed hunks and re-decides retirement
there; only specialists whose surfaces the fix touched rerun. A fix that changed
no owned source closes the loop. A new surface triggers reassessment instead of
an automatic replay of every lens.
An approval remains valid until a later edit changes the exact code or
invariant it established. Before each blocking fix, save the canonical review
and require the fix result to list its touched paths, repaired findings, changed
invariants, and invalidated validations/evidence. After the fix:
1. run one mandatory focused general review over those edits, the containing
functions and affected callers, and the prior blocking findings;
2. rerun only a specialist that originated a repaired blocker or whose recorded
material question the fix actually changed;
3. reconcile only evidence checks invalidated by the fix; and
4. carry every other general, specialist, validation, and evidence approval
forward explicitly.
The focused general reviewer owns synthesis. It may add a specialist only for a
new concrete material question introduced by the fix. Merely touching an async,
storage, build, security, or other broad surface does not invalidate every lens
that could describe it. It reads the complete task diff only when the fix has
made the previous review boundary unreliable, in which case it triggers the
convergence assessment rather than silently restarting the initial review.
Stop the ordinary fix loop and run a fresh independent convergence assessment
when any of these holds:
- two canonical review verdicts have required changes;
- blocker count or affected scope did not materially shrink after a fix;
- a fix adds owned paths, a subsystem, a build/platform boundary, or a new
ownership, concurrency, persistence, or trust mechanism; or
- the reviewer can no longer state which prior approvals remain valid.
The assessor writes `review-convergence<C>.md` with exactly one disposition:
- `CONTINUE_FOCUSED` — one bounded fix list and at most one final focused
review round;
- `REPLAN_CURRENT` — the task remains cohesive, but implementation returns to
an explicitly named validated boundary and a replacement plan before review;
- `RESCOPE_REQUIRED` — the task contains independently testable product
boundaries; write or update `split-proposal.md` and stop automatic work; or
- `HARD_STOP` — an exact unsafe or unavailable condition needs human action.
If the allowed final focused round still has blocking findings, stop with the
unapproved convergence artifact. Never approve unresolved findings and never
start another broad review campaign merely because time remains.
### Evidence selection
@@ -626,11 +680,15 @@ For every instrument, assessment returns exactly one of:
after the bounded directness assessment.
A `TEST_FLAW` recovery must remove an assumption or move closer to the changed
surface. Do not repeat the same command, fixture, or overlay wording. A campaign
cap is an assessment checkpoint, not permission to block: carry prior passes,
isolate unmet checks, and choose a more direct instrument or document recovery
exhaustion. An `IMPL_BUG` fix creates a new retained attempt, triggers targeted
general/specialist re-review, and reruns only invalidated checks.
surface. Do not repeat the same command, fixture, or overlay wording. The normal
campaign cap is an assessment checkpoint: carry prior passes, isolate unmet
checks, and choose at most one focused recovery campaign or document recovery
exhaustion. A focused campaign that does not converge stops automatic work with
an exact recoverable hard stop; it never starts a third campaign or converts the
cap into approval/Block. An `IMPL_BUG` fix creates a new retained attempt, uses the same
focused general/invalidated-specialist review and convergence triggers as the
pre-commit loop, and reruns only invalidated checks. It never restarts the
initial complete-diff review simply because the attempt number changed.
The evidence author reads the full task, assessed plan, final task diff, and
existing `test-design.md`. It covers every acceptance surface and nothing
@@ -758,6 +816,14 @@ delays finishing the work actually in hand.
## Failure handling
- `Scope: split-required` before source edits and `RESCOPE_REQUIRED` from a
convergence assessment are planning boundaries, not task `Block` verdicts
and not permission to keep retrying. Preserve `split-proposal.md`, all
validated source recovery, and the task's `in-progress` state; return the
proposal to the scheduler or human and stop automatic performance until the
queue is deliberately replaced. A resumed performer that sees the same
unresolved boundary reports it immediately without rerunning context,
implementation, review, or builds.
- Source lineage has a strict timing boundary. Before Phase 1, a missing
approved prerequisite is a clean pre-phase routing stop: do not publish
`blocked`, edit source, or create a backport/cherry-pick/rebase/merge task.
@@ -776,10 +842,11 @@ delays finishing the work actually in hand.
starting new shared work. A dirty/non-buildable checkout or global
environment problem stops the current invocation.
- A test campaign cap is not a clean blocked attempt. Preserve the overlay and
evidence, run the cap assessment, and continue with a focused campaign while
any safe direct strategy remains. The publication helper rejects a test block
whose report still says `TEST_FLAW`, cites the run cap, or lacks the required
recovery-exhaustion record.
evidence and run the cap assessment. The normal campaign may authorize one
focused campaign; the focused campaign boundary either proves recovery
exhaustion or returns a recoverable hard stop instead of looping. The
publication helper rejects a test block whose report still says `TEST_FLAW`,
cites the run cap, or lacks the required recovery-exhaustion record.
- A Windows file-lock build error follows the shared bounded exact-checkout
recovery. Only exhaustion or an unsafe/non-owned holder stops the run and
asks the human; the task remains `in-progress`.

22
.agents/skills/process-inbox/SKILL.md
View File

@@ -108,8 +108,26 @@ essential context, and use a standalone task only when no project does.
Do not create generic holding projects such as `fixes`. A release batch of
unrelated regressions normally becomes standalone tasks or tasks in existing
domain projects. Group requests into one task only when they form one cohesive,
independently testable behavior. Split work until every task is implementable
in one pass and has an exact observable acceptance result.
independently testable behavior that can be implemented, reviewed, and tested
as one normal pass.
Split at product boundaries, not arbitrary file or line-count boundaries. A
request needs multiple tasks when two or more parts have their own useful
outcome and acceptance oracle, when a later part can consume an earlier part as
a stable dependency, or when the parts require materially different context,
failure analysis, or evidence setup. New network, persistence, concurrency or
ownership machinery plus application lifecycle/UI integration are especially
strong split signals when each can be exercised independently. Shared project
context, overlapping files, or one eventual feature does not by itself justify
paying one review and test loop over their combined implementation.
Do not over-split inseparable changes: keep a small API and its only caller
together when neither has a meaningful standalone result, and keep one atomic
behavior together when separating it would leave an unbuildable or untestable
intermediate state. For every proposed task, state the one shipped boundary it
owns and the direct evidence that can approve it without first implementing a
sibling. If that sentence needs several independent outcomes or several
unrelated instruments, split again.
Project slugs are unique across `projects/` and `projects/archive/`. When a
request belongs to an archived project, restore it before routing to it: