git:20261005.b0d5373 to git:20261105.982c6c5

- description: Closed-loop field-agent that drives plugin quality improvements by running phase1/phase2/phase3 on benchmark IC projects, DRILLING each systematic gap to a fully-converged all-layers-resolved state in its OWN sandbox worktree, then handing the gatekeeper ONE complete verified bundle (candidate.patch + per-layer regression tests + 2-round clean-room proof) to REVIEW + land — not re-discover. Still files ORGANIC backlog issues and AUDITS the fixes the core-agent self-verifies and CLOSES. Invoke as a cron prompt with a target benchmark folder and an LLM-review prompt; every tick the loop first audits CLOSED `core-closed` issues against the real benchmark (VERIFIED → add `field-verified`, NOT adequate → `gh issue reopen` + remove `core-closed`), then self-advances through review → deep-resolve → file-bundle → monitor → audit until STOP CONDITION (no new gaps + no open primary/secondary issue + no un-audited closed issue).

-

- <!-- WAVE_76_CHIP_AGNOSTIC_BANNER -->

-

- > **Case-study notation.** This skill cites the IC-A / USB-HID tester /

- > MDV-A1101 BENCH-A reference project as concrete evidence for the

- > rules below. The rules themselves are chip-AGNOSTIC and apply to

- > any IC of the matching `ic_class` (see

- > `vibe-ic-marketplace/plugins/vibe-ic/programs/ic_class_profile.py`).

- > When you adopt this skill on a different IC, swap `IC-A` →

- > `<your IC name>` and `USB-HID tester` → `<your host-tester name>`; the

- > structural gates and rule bodies do not depend on those SKUs.

- > See `docs/design/CASE_STUDIES/IC-A_*.md` for the full BENCH-A

- > regression history.

-

- # Field-Agent Loop — Closed-Loop Plugin Quality Improvement

-

- ## Purpose

-

- The field-agent is the **organic improvement engine** for the

- vibe-ic plugin. It treats real IC benchmark projects as a test

- harness: re-run the plugin at HEAD, ask a fresh LLM to compare

- source docs against generated output, and convert every

- systematic gap it finds into a structured backlog issue.

-

- > **Contribution-layer note.** The field-agent is a **Layer-1** intake role: it

- > **files a backlog** (a report — or hands the gatekeeper a candidate-patch

- > bundle) and audits landed fixes. It never edits the plugin/MCP and never pushes

- > to `main`. Direct-push is the maintainer-internal (**Layer-2**) landing method

- > for the gatekeeper's own fixes — not the field-agent's path. The maintainer

- > resolves every backlog into the next plugin version.

-

- The core-agent now **self-verifies and CLOSES** each issue it

- fixes (adding the `core-closed` label). The default terminal

- state is therefore **CLOSED**. The field-agent is the

- **audit/reopen safety net**: at every cron tick it re-checks the

- core-agent's closed issues on the actual benchmark — not on the

- unit test fixtures. If the fix holds on real silicon it stamps

- `field-verified` (terminal); if it does not, the field-agent

- **reopens** the issue (`gh issue reopen`), posts counter-evidence,

- and removes `core-closed` so the core-agent re-engages. This

- audit/reopen model is what kills the old wait-for-verification

- limbo where a fixed issue sat un-confirmed forever.

-

- The loop is **chip-AGNOSTIC**: filed issues describe general

- plugin gaps (e.g. "extractor X doesn't match canonical pattern Y"),

- never project-specific bugs. Every YAML passes

- `backlog_sanitize_check` before filing.

-

- ### Why discovery alone is not enough — the deeper-layer disease

-

- For most of its history the field-agent reported only the **surface

- layer it could see**: it ran the benchmark, observed the topmost

- failing layer, filed one backlog, and handed it off. The core-agent

- fixed exactly that surface — and then, on the next round, a **deeper

- layer surfaced** that had been hidden behind the one just fixed. The

- record is full of this multi-round drilling done the slow way, one

- layer per round-trip:

-

- - **#770 r2..r6** — five reopen rounds, each peeling one provenance

- layer the prior fix had unmasked.

- - **#518 r1..r4** — the instantiation-graph / reset-skip family,

- four rounds because each guard exposed the next wrapper shape.

- - **#780 r1..r2** — two rounds for what was, in hindsight, one

- convergent defect.

-

- Each round costs a full file → core-fix → push → re-audit cycle just

- to **re-discover** the next layer that was always going to be there.

- The cure is structural: the field-agent must **DRILL to a

- fully-converged, all-layers-resolved state in its OWN sandbox

- worktree FIRST**, then hand the gatekeeper **ONE complete verified

- bundle** to **REVIEW + land** — not a surface symptom for the

- gatekeeper to re-discover layer by layer. This is the

- **deep-resolution contract** in the section of the same name below.

-

- ## State

-

- Every field-agent cron has a state file at the target folder root:

-

- ```

- <target>/_field_agent_state.json

- ```

-

- Schema:

-

- ```json

- {

- "step": 1 | 2 | 3 | 4 | "STOPPED",

- "iter": <int>,

- "started_at": "<YYYY-MM-DD>",

- "target_folder": "<absolute path>",

- "last_plugin_version": "<semver>",

- "agent_task_id": "<id or null>",

- "agent_status": "<short status string>",

- "issue_number": <int or null>, // primary tracked issue

- "tracking_secondary": [<int>, ...], // secondary issues

- "sandbox_worktree": "<path or null>", // deep-resolution prototype sandbox

- "bundle_path": "<path or null>", // handoff bundle dir for the primary

- "residual_rounds_clean": <int>, // consecutive clean-room rounds at 0 residual

- "last_summary": "<one paragraph>"

- }

- ```

-

- ## The loop

-

- The loop is **review → deep-resolve → file-bundle → monitor →

- audit**. Step 2 is no longer "file a one-line symptom"; it is "drill

- the gap to convergence in a sandbox, then file a complete verified

- **bundle**". Steps 1, 3, 4 are unchanged in shape.

-

- ### Step 1 — review

-

- Run when `agent_task_id` is null OR the prior agent task is

- completed/failed.

-

- ```bash

- cd /home/<your-user>/AI_IC_design/vibe-ic-marketplace && git pull --ff-only

- cd /home/<your-user>/AI_IC_design/mcp-eda && git pull --ff-only

- ```

-

- Check `plugins/vibe-ic/.claude-plugin/plugin.json` version.

-

- Dispatch a fresh **general-purpose Agent** with a prompt that:

- - names the target benchmark folder

- - runs phase1 (or phase2+3 / phase2+3+analog depending on cron

- intent)

- - asks the agent to read input docs + generated_docs and report

- systematic (chip-AGNOSTIC) gaps

- - caps response length (≤800 words is a good default)

- - explicitly lists already-closed gap IDs the agent must NOT

- re-report

-

- Save the dispatched agent's task id, set `agent_status=running`.

-

- ### Step 2 — deep-resolve, then file the bundle

-

- When the dispatched agent reports concrete quality gaps, do **not**

- file a surface symptom and hand off. First **drill the gap to a

- fully-converged, all-layers-resolved state in a throwaway sandbox

- worktree** (the full procedure is in **Deep-resolution before

- handoff** below), THEN file a complete verified bundle:

-

- 1. **Drill to convergence in a sandbox** — run the inner close-loop

- (run benchmark IC → observe the TOP failing layer → prototype a

- chip-AGNOSTIC fix → re-run → the next deeper layer surfaces →

- prototype it too → repeat until **0 residual**). See the

- deep-resolution section for the exact aggregate/audit probes and

- the convergence criterion.

- 2. **Admit the bundle** through the new admission gate before filing

- anything:

- ```bash

- python3 <plugin_root>/programs/handoff_bundle_check.py <bundle_dir>

- # the bundle dir is POSITIONAL — there is no --bundle flag

- # exit 0 → ADMIT: bundle is admissible (0 residual × 2 rounds,

- # chip-AGNOSTIC candidate, per-LAYER tests, Step-2.7 run)

- # exit 1 → INCOMPLETE; the printed reason names the missing

- # criterion — fix it in the sandbox and re-run

- # exit 2 → the bundle / manifest could not be read at all (this is

- # a usage or I/O error, NOT a verdict about the bundle)

- ```

- A bundle that does not pass this gate is NOT filed — it is still

- a surface symptom, not a converged resolution.

- 3. For the gap, write the backlog YAML

- `<repo_root>/vibe-ic-marketplace/community/backlogs/ORGANIC-<YYYYMMDD>-<slug>.yaml`

- (ORGANIC #794 — this used to read `<plugin_root>/community/backlogs/`,

- which resolves to `plugins/vibe-ic/community/backlogs/` and does not

- exist. That is the ONE directory `agent_checkin_scope_guard.ZONE_BACKLOG`

- and the `--audit tracked` hygiene gate watch; a file written anywhere else

- is watched by nothing.)

- using the schema in the `community-backlog-submit` skill, and

- describe **all** layers the bundle resolves (not just the surface

- one), so the gatekeeper reviews the converged whole.

- 4. Sanitize:

- ```bash

- python3 <plugin_root>/programs/backlog_sanitize_check.py \

- --file <yaml>

- ```

- If `pass: false` → fix the flagged literal, re-sanitize. The

- `candidate.patch` inside the bundle is sanitized the same way —

- no `ic-a`, `bench-a`, vendor names, or project paths as logic.

- 5. File the GitHub issue (NO confirmation prompt), attaching the

- bundle as the candidate **PROPOSAL** (never as a self-merged

- change):

- ```bash

- gh issue create --repo vibeic/vibe-ic \

- --title "ORGANIC: <title>" \

- --body "$(cat <yaml>)"

- ```

- The issue body links the bundle (`candidate.patch`, the per-layer

- regression tests, the 2-round clean-room residual proof, the

- Step-2.7 record). The patch rides as an **untrusted proposal** the

- gatekeeper reviews and independently reproduces — see the

- guardrails in the deep-resolution section.

- 6. Save `state.issue_number = <primary>`,

- `tracking_secondary = [<others>]`, `state.bundle_path = <dir>`,

- `state.step = 3`.

-

- **One bundle per independent root cause.** If the drill reveals that

- the "deep" problem is actually **several independent root causes**

- (not one convergent chain of layers), SPLIT into multiple

- bundles / issues — first filed becomes primary, the rest go into

- `tracking_secondary`. Do NOT ship one un-bisectable mega-bundle. (A

- single convergent chain of layers — like #770's provenance peel —

- IS one bundle; independent defects are NOT.)

-

- ### Step 3 — monitor (until core/gatekeeper lands the bundle)

-

- `gh issue view <issue_number>` and watch for any of:

- - the issue transitions to **CLOSED** with label `core-closed`

- (the gatekeeper independently reproduced + Step-2.7'd the bundle,

- landed it, self-verified + closed it)

- - plugin version advances past `state.last_plugin_version`

- - maintainer comment

-

- The issue going CLOSED+`core-closed` is the primary trigger →

- `state.step = 4` (the audit step). The closed-audit rule below

- will pick the issue up regardless, but advancing the tracked

- issue's step keeps the state file honest.

-

- If plugin version bumps for an unrelated track (e.g. PnR fixes

- on a phase1 issue), just update `state.last_plugin_version` to

- the new version and stay in step 3.

-

- > **The bundle is a PROPOSAL, not a merge.** Even a 0-residual

- > bundle is landed by the **gatekeeper only**. The field-agent

- > never pushes the prototype and never self-merges it. "Only

- > Core/gatekeeper edits the plugin" means only the gatekeeper

- > **LANDS** — it does not forbid the field-agent from prototyping

- > the fix. See the deep-resolution guardrails.

-

- ### Step 4 — audit (verify the landed fix, reopen if inadequate)

-

- #### Verify discipline — ARTIFACT-FIRST (mandatory, chip-AGNOSTIC default)

-

- **Before launching ANY phase re-run, classify the closed fix's diff.**

- A full phase3 re-run is ~40 minutes (route ~21 min + DRC + LVS); most

- closed fixes do NOT need it. The asymmetry: the core-agent fixes

- autonomously via a persistent loop, so the field agent must NOT

- reintroduce 40-minute synchronous babysitting where a seconds-long

- artifact check is the faithful real-surface verification.

-

- 1. **Classify the fix by what its diff TOUCHES — the deterministic

- answer is the program `fix_surface_classify.py` (#602), do NOT

- eyeball it:**

- ```bash

- python3 plugins/vibe-ic/programs/fix_surface_classify.py <issue|sha>

- # exit 0 CONSUMER_ONLY → artifact-first verify (step 2) [deterministic]

- # exit 10 PRODUCER → justified re-run (step 3) [deterministic]

- # exit 11 MIXED → AI-adjudicate the residual (step 2.5) [uncertain]

- ```

- It maps each diff hunk → its enclosing function/file → a maintained

- PRODUCER set (route/floorplan/streamout/geometry emitters: `step_pnr`,

- `make_tracks`, `_gds_grid_snap`, `_magic_def_to_gds`,

- `_klayout_merge_layers`, the `_GDS_*_PY` emitters, …) vs a CONSUMER

- set (checkers / classifiers / verdict-message strings). **Three-tier

- dispatch — the deterministic ends are decided by the program; only the

- uncertain middle goes to an AI agent:**

- - **CONSUMER_ONLY** (deterministic) — a checker / classifier /

- verdict-message / cache-decision / disclosure-line change (e.g. a DRC

- off-grid classifier, an LVS cross-reference string, a pin-count

- disclosure, a cache-validity line). The route, geometry, netlist,

- DEF, GDS and report files are UNCHANGED by such a fix.

- - **PRODUCER** (deterministic) — a change to the route/geometry

- producers: PnR Tcl, floorplan, CTS, streamout, or a verdict that

- depends on the actual run (e.g. a measure-only SPEF repair that

- prevents a segfault, a route-convergence verdict keyed on the real

- DRT count).

- - **MIXED** (uncertain) — touches both sets, OR an unknown/ambiguous

- surface the rules could not PROVE consumer-only. **This is the

- genuine judgment residual** (why_not_bucket_a) — and instead of

- defaulting straight to a ~40-min re-run, it goes to an AI agent

- (step 2.5). The program does NOT guess; it hands the agent the

- minimal material.

- 2. **CONSUMER_ONLY → drive the NEW program version against the

- project's ALREADY-PERSISTED artifacts** (`reports/phase3/*.rpt`,

- `lvs_verdict.json`, the netlist / DEF / GDS) and read the verdict.

- This is the faithful real-surface check and it takes SECONDS — feed

- the prior run's artifacts to the new program, do not regenerate them.

- 2.5. **MIXED → AI-adjudicate the ambiguous hunks BEFORE deciding to

- re-run.** Get the minimal agent material — the ambiguous hunks only,

- not the whole diff — from the program:

- ```bash

- python3 plugins/vibe-ic/programs/fix_surface_classify.py <issue|sha> \

- --adjudication-bundle

- ```

- The bundle carries each ambiguous hunk's file + enclosing symbol +

- changed lines + why it was ambiguous, plus what the engine already

- decided (producers/consumers) as context, plus the decision question.

- READ those hunks and decide per the bundle's rule: **ALL ambiguous

- hunks are consumer → treat the commit as CONSUMER_ONLY and do step 2

- (artifact-first, NO re-run); ANY is producer, or you cannot tell →

- step 3 (re-run).** This is the program-first / agent-on-uncertain

- split: the rules settle the certain hunks; the agent reads only the

- residual the rules could not. Do NOT auto-re-run a MIXED without

- reading the bundle — that throws away the whole point of the

- classifier.

- 3. **PRODUCER (or a MIXED the agent ruled producer/unsure) → a full

- phase3 re-run is justified** (clean-wipe + re-run the affected

- phase(s) below). Only here.

- 4. **A "check status" request is READ-ONLY**: report the persisted

- artifact state; do NOT launch a run. The canonical answer is the

- universal watchdog `run_status.py <project> [--phase auto]` (#599):

- a bounded one-shot probe that returns DONE / DIED / STUCK /

- RUNNING_ON_TIME in seconds from existing artifacts (the phase's

- `reports/orchestrator/<phase>_one_shot.json` verdict, the live log

- mtime as heartbeat, and the `.runner.lock` holder PID). Use it as

- the field-agent heartbeat too: launch a producer re-run async, then

- each status check is this one probe — never block on a wait-for-exit

- watcher, which cannot tell a hung step from progress.

-

- This is **non-negotiable**: re-running phase3 to confirm a

- checker/message-only fix wastes ~40 min per issue for a verification an

- artifact check does faithfully in seconds.

-

- #### Audit execution

-

- **Re-dispatch a fresh general-purpose Agent** (not the original

- task — must be a clean context) with an audit prompt that:

- - names the specific issue + the v1.6.x test file that ships the

- fix

- - **consumer-only fix**: drives the new program/gate against the

- affected IC's already-persisted artifacts and reads the verdict

- (seconds) — NO phase re-run

- - **producer fix only**: clean-wipes the affected benchmark IC(s) and

- re-runs phase1/phase2/phase3 as needed against the **real benchmark**

- - inspects the load-bearing fields the fix touches

- - reports PASS criteria objectively

- - spot-checks the unaffected ICs for regression

-

- Two outcomes:

-

- - **VERIFIED ok** → post a verify comment, add label

- `field-verified` (the issue STAYS CLOSED — this is the terminal

- do-not-re-audit marker), `state.step = 1`,

- `state.agent_task_id = null`.

- ```bash

- gh issue edit <num> --repo "$REPO" --add-label field-verified

- ```

- - **NOT adequate** → `gh issue reopen` + post a counter-evidence

- comment (see the FIELD reopen-comment shape below) with the

- exact failing field/value on the real benchmark AND a concrete

- suggested-fix line, then remove `core-closed` so the core-agent

- treats it as actionable again. The issue is now OPEN; track it

- as the primary and go to `state.step = 3`.

- ```bash

- gh issue reopen <num> --repo "$REPO"

- gh issue comment <num> --repo "$REPO" --body-file reopen_comment.md

- gh issue edit <num> --repo "$REPO" --remove-label core-closed

- ```

-

- **FIELD reopen-comment shape** (post on NOT-adequate):

-

- ```

- Field agent 複查未通過，已 reopen：

- **複查對象**：#<num> <title>

- **實機證據**：<failing field/value on the real benchmark>

- **建議修法**：<concrete suggested-fix line>

- （已移除 core-closed 標籤；等待 core agent 重新處理。）

- ```

-

- ### STOP CONDITION

-

- The real convergence test (per the fix-all-into-the-plugin principle in

- `benchmark-enhancement-capture` / `community-backlog-submit`) is that a **fresh

- clean-room re-run on the newest plugin produces 0 residual that needs a plugin

- fix**, confirmed across two consecutive rounds — every recoverable residual is

- captured and fixed into the plugin (program > skill, never discarded as

- "variance" / "design-side" / "not a plugin gap"). In loop terms:

-

- At Step 1: if the fresh review agent reports **STOP_RECOMMENDATION: YES**

- (no new gaps AND no open primary/secondary issue AND the closed-audit

- rule below returns an empty list — i.e. no un-audited `core-closed`

- issue remains), then:

-

- ```bash

- CronList # find this cron's id

- CronDelete <id>

- echo "STOP cron."

- ```

-

- Exit.

-

- ## Deep-resolution before handoff

-

- This is the core of the field-agent's job: **converge the whole stack

- of layers in your own sandbox, then hand the gatekeeper one complete

- verified bundle to review + land** — never a surface symptom for the

- gatekeeper to re-discover one layer per round-trip (#770 r2..r6,

- #518 r1..r4, #780 r1..r2). The field-agent is the layer-driller; the

- gatekeeper is the independent reviewer + lander.

-

- ### Prototyping is allowed — in a throwaway sandbox only

-

- The field-agent **MAY prototype plugin fixes in a throwaway sandbox

- worktree.** Inside that sandbox it may run `rtl_hygiene_lint --fix`,

- re-synth, re-PnR, re-DRC, and edit programs or skills — whatever it

- takes to reach a converged fix. This is **not** a violation of "only

- Core/gatekeeper edits the plugin": that rule governs who **LANDS** a

- change, not whether the field may **prototype** one. Concretely:

-

- - The prototype lives in a **sandbox worktree** off the project, e.g.

- `git worktree add <target>/_deep_resolve_sandbox <base-sha>`; record

- it in `state.sandbox_worktree`.

- - The prototype is **NEVER pushed** and **NEVER self-merged**. It is

- not committed to any shared branch the gatekeeper would treat as

- authoritative.

- - The prototype rides into the handoff bundle as

- **`candidate.patch`** — an **untrusted PROPOSAL**. The gatekeeper

- independently reproduces it and decides whether to land it (often

- re-deriving the fix rather than applying the patch verbatim).

- - Tear the sandbox down after the bundle is filed

- (`git worktree remove`), but keep `candidate.patch` and the test

- files inside the filed bundle.

-

- ### The inner close-loop (drill to 0 residual)

-

- Run the failing benchmark IC through the runner and **peel layers

- until none remain**:

-

- 1. **Run** the failing benchmark IC through the one-shot runner

- (phase1 / phase2 / phase3 as the gap demands), in the sandbox.

- 2. **Observe the TOP failing layer.** To answer "is there a *deeper*

- layer hiding behind the one I'm looking at?", use the aggregate /

- audit probes — they roll up every per-layer verdict so a fixed

- surface layer cannot hide the next one:

- - `python3 plugins/vibe-ic/programs/phase1_verify_aggregate.py <proj>`

- - `python3 plugins/vibe-ic/programs/phase2_verify_aggregate.py <proj>`

- - `python3 plugins/vibe-ic/programs/phase3_verify_aggregate.py <proj>`

- - `python3 plugins/vibe-ic/programs/signoff_audit.py <proj>`

- (sign-off layer roll-up: DRC / LVS / STA / IR-drop / antenna …)

- 3. **Prototype a chip-AGNOSTIC fix** for the top layer in the sandbox

- (program > skill; the fix must generalize — no chip/vendor/SKU

- literal as logic, no keyword overfit, root cause not bypass).

- 4. **Re-run.** The next deeper layer surfaces (this is exactly the

- per-round peeling that #770 / #518 did across reopen rounds — now

- collapsed into one sandbox session).

- 5. **Prototype it too**, and **repeat from step 1** until the

- aggregate/audit probes report **0 residual**.

-

- Capture a **per-LAYER regression test** for every layer you peel —

- both the surface layer and each deeper one — so a future run cannot

- silently re-open the chain. (A bundle that fixes 4 layers ships

- ≥4 layer-pinned tests, each built from a clean independent reference

- fixture, never a fixture seeded from the very output under test.)

-

- ### Convergence criterion (the bundle's admission gate)

-

- A bundle is **admissible for handoff** — and `handoff_bundle_check.py`

- (the NEW program the core-agent is adding) is the gate that enforces

- it — only when ALL of:

-

- - **0 residual across 2 INDEPENDENT clean-room rounds.** A fresh

- clean-room re-run on the candidate plugin produces 0 residual that

- needs a plugin fix, reproduced across **two** consecutive

- independent rounds (not the same run inspected twice). Track the

- count in `state.residual_rounds_clean`; it must reach 2.

- - **Candidate is chip-AGNOSTIC.** `candidate.patch` carries no

- chip/vendor/SKU literal as logic; it passes `backlog_sanitize_check`

- and the chip-AGNOSTIC source guard.

- - **Per-LAYER regression tests** — one for the surface layer and one

- for each deeper layer the bundle resolves; each built from a clean

- independent reference fixture.

- - **Field ran Step-2.7 on its OWN prototype** before handoff (the

- adversarial multi-lens self-review on the candidate diff, recorded

- in the bundle). The field does not hand off a prototype it has not

- itself adversarially reviewed.

- - **NO version bump in the bundle** (owner directive 2026-06-17:

- *"field dont need to have version to issue pr. all versions are given

- by gatekeeper"*). `candidate.patch` must NOT touch `plugin.json` /

- `marketplace.json` — the gatekeeper assigns the next strictly-monotonic

- version at merge (`gatekeeper_assign_version.py`), because two in-flight

- bundles that each self-bumped would collide. The field's job is the

- converged fix + tests + clean-room proof, not the version.

-

- Run the gate before filing (see Step 2):

-

- ```bash

- python3 <plugin_root>/programs/handoff_bundle_check.py <bundle_dir>

- # the bundle dir is POSITIONAL — there is no --bundle flag

- # exit 0 → ADMIT; file the bundle

- # exit 1 → INCOMPLETE; the printed reason names the missing

- # criterion (residual not 0×2 / not chip-agnostic /

- # missing layer test / no Step-2.7 record) — fix in the

- # sandbox and re-run

- # exit 2 → the bundle / manifest could not be read (usage / I/O

- # error, NOT a verdict about the bundle)

- ```

-

- > **Known limitation, measured — read this before treating an INCOMPLETE on

- > `root_cause_not_surface` as your bug.** That item admits only a

- > `fix_surface_classify` verdict of `PRODUCER`. Over the 200 most recent

- > `origin/main` commits fed in as candidate bodies the classifier returned

- > `PRODUCER` **0** times (`CONSUMER_ONLY` 85, `MIXED` 115). If that item is

- > the ONLY red one, the bundle is very likely fine and the PRODUCER registry

- > is what needs widening — say so in the handoff instead of reshaping the fix

- > to satisfy the classifier.

-

- ### CRITICAL guardrails — do NOT over-rotate

-

- Deep-resolution makes the field-agent stronger, not autonomous. The

- following are **non-negotiable** and bound the new power:

-

- 1. **The gatekeeper still independently reproduces + Step-2.7s the

- bundle.** The field's own 0-residual proof is a *proposal*, not a

- verdict. **Never trust a force-overwrite-to-0 or a subagent-built

- fixture blindly** — a `candidate.patch` that drives some residual

- counter to 0 may have done so by *masking* a real defect rather

- than fixing it (the documented force-overwrite-to-0 masking risk:

- a detector that over-fires to 0 looks converged but is hiding a

- mis-fire). The gatekeeper re-derives the fix and re-runs Step-2.7

- on the bundle from a clean context; a 0 it cannot independently

- reproduce is rejected.

- 2. **KEEP the post-merge real-benchmark re-audit.** Even after the

- gatekeeper lands the bundle, the field-agent's closed-audit safety

- net (below) still re-checks the landed fix on the **real

- benchmark**. A bundle/PR gives **role-independence, not

- judgment-independence**: the deepest spec-interpretation layers

- (does the generated design actually *mean* what the spec says?) are

- blind to any local self-check — only a fresh agent re-reading the

- spec against the real generated output catches them. The

- deep-resolution drill does NOT retire the audit/reopen loop.

- 3. **SPLIT independent root causes.** When the "deep" problem is

- actually several **independent** root causes — not one convergent

- chain of layers — file **multiple bundles / PRs**, never one

- un-bisectable mega-PR. A mega-PR that bundles unrelated fixes

- cannot be bisected when one of them regresses, and forces an

- all-or-nothing review. (One convergent chain of layers, like #770's

- provenance peel where each layer was hidden behind the previous, IS

- a single bundle; genuinely independent defects are NOT.)

-

- ## The deterministic closed-audit rule

-

- The core-agent now self-verifies, CLOSES, and stamps `core-closed`

- on every issue it fixes. The cron MAY have filed issues across

- multiple field-agent sessions (e.g. one cron's audit shipped the

- slice for a neighbouring cron's umbrella issue). Without an

- explicit cross-check, the loop drifts: it tracks only its own

- primary issue and never re-checks the core-agent's other closed

- fixes on real silicon.

-

- **Therefore: at every cron tick, BEFORE Step 1, run:**

-

- ```bash

- plugins/vibe-ic/skills/field-agent-loop/programs/check_closed_for_field_audit.sh

- ```

-

- (The script is bundled with this skill.)

-

- It returns the list of all **CLOSED** ORGANIC issues authored by

- you that carry `core-closed` and **LACK** `field-verified`. For

- each, dispatch a fresh verify agent against the **real benchmark**:

-

- 1. Dispatch a verify agent scoped to that issue (clean context).

- 2. On **VERIFIED ok** → add label `field-verified`; the issue

- **stays CLOSED** (terminal do-not-re-audit marker).

- ```bash

- gh issue edit <num> --repo "$REPO" --add-label field-verified

- ```

- 3. On **NOT adequate** → `gh issue reopen` + post the FIELD

- reopen-comment (counter-evidence) + remove `core-closed` so the

- issue returns to OPEN and the core-agent treats it as

- actionable again.

- ```bash

- gh issue reopen <num> --repo "$REPO"

- gh issue comment <num> --repo "$REPO" --body-file reopen_comment.md

- gh issue edit <num> --repo "$REPO" --remove-label core-closed

- ```

-

- This is **non-negotiable**: an un-audited `core-closed` issue

- means a core-agent fix has never been confirmed on real silicon.

- A field-driven deep-resolution bundle does **not** exempt the issue

- from this audit — even a 0-residual bundle is re-checked on the real

- benchmark after it lands, because the bundle proves role-independence,

- not judgment-independence (see guardrail 2). The field-agent no

- longer waits for any `wait-for-verification` label — that label is

- **RETIRED**; the field audits CLOSED issues instead.

-

- ## Constraints (non-negotiable)

-

- - **NO RTL ORACLE**: never inspect `input/rtl/` or any generated

- RTL when assessing input-doc-only extractors. The plugin must

- derive structure from input docs. (This holds inside the

- deep-resolution sandbox too — prototyping a fix never licenses

- reading the RTL oracle to "converge".)

- - **Chip-AGNOSTIC backlog AND candidate.patch**: every YAML and every

- bundled `candidate.patch` must pass `backlog_sanitize_check`. No

- `ic-a`, `bench-a`, `vendor`, `usb_hid_tester`, `aid`, vendor IC

- names, or project paths in the title/pattern/suggested_fix or in the

- patch logic. The authoritative deny-list lives in

- `tests/chip_deny_list.txt`.

- - **Field-agent files GENERAL plugin gaps**, never chip-specific

- bugs. The user owns chip-specific fixes; the field-agent owns

- plugin generality.

- - **Prototype, never land.** The field-agent may prototype a fix in a

- throwaway sandbox and ship it as `candidate.patch`, but it NEVER

- pushes the prototype and NEVER self-merges. Only the gatekeeper

- LANDS plugin changes.

- - **No y/n confirmation**: file issues directly. Do not ask.

- - **Sanitize before file**: every YAML and every `candidate.patch`,

- every time, even when you're sure it's clean.

-

- ## Campaign orchestration — single-driver principle

-

- A multi-tick field campaign drives the one-shot runners against a

- project directory over and over, often handing the project from a

- background agent to a successor agent across cron ticks. These are the

- host lessons for keeping that hand-off clean:

-

- - **One runner per project dir at a time.** A project directory is a

- single-writer resource: the run logs, manifests, and provenance under

- its `reports/` tree are written by exactly one driving runner. Two

- runners pointed at the same project will co-write that tree and

- corrupt the run record. The runner now enforces this with a

- `<proj>/.runner.lock` (pid + ISO timestamp + runner name): a second

- concurrent invocation against a live-held project is refused by name

- (`CONCURRENT_RUN_REFUSED`, naming the holder pid) and exits non-zero;

- a lock left behind by a dead runner is cleaned as stale and the new

- runner proceeds. Treat a `CONCURRENT_RUN_REFUSED` as a signal to find

- and resolve the other driver — never to delete the lock by hand and

- retry. **The deep-resolution sandbox is a SEPARATE project dir**

- (its own worktree): never run the inner close-loop against the live

- audited project — clone/worktree it so the sandbox runner holds its

- own lock and never collides with the audit driver.

-

- - **Never abandon a background runner that still holds a project.**

- Before handing a project to a successor agent (or before STOP), the

- driving agent MUST either `wait` for its background runner to finish

- or `kill` it. An abandoned, still-alive background runner keeps its

- lock and will (correctly) refuse the successor — and worse, if the

- lock is force-removed, both runners co-write and the run record is

- silently corrupted. This applies to sandbox runners too — account

- for every sandbox runner you spawn and tear the sandbox worktree

- down after the bundle is filed.

-

- - **The double-driver incident (generic).** In a real campaign an

- orphaned background runner was left driving a project while the cron

- advanced and a successor agent launched a fresh runner on the SAME

- project; both wrote logs / manifests / provenance concurrently. There

- was no refusal mechanism, so the corruption went unnoticed until the

- artifacts were audited. The single-driver lock above is the

- deterministic fix; the operational rule is: account for every

- background runner you spawn — wait or kill — before relinquishing a

- project.

-

- - **Keep your turn ALIVE to completion — never detach-and-idle (v1.3.51,

- the launch-and-idle abandon bug).** The failure that motivated this

- rule: an agent that delegates a multi-hour run launches the runner as a

- DETACHED background process, then its turn ENDS (idle); when the

- detached process later finishes, NOTHING re-invokes the agent, so its

- "then write RESULT.md" step never runs. The runner's OWN outputs

- (`reports/final_summary.md` / orchestrator `*_one_shot.json` verdict /

- GDS/SPEF artifacts) exist, but the synthesis deliverable is never

- written. All three beliefs that make yielding feel safe are impossible

- (vibe-ic#558): the harness does not **re-invoke** a finished turn; a

- background waiter can only wake a turn that is **still alive**; and a monitor

- **notifies the DISPATCHER**, not the agent, so it cannot resume you.

- written — observed 3× in one session (two idled pre-write; one flow

- finished but RESULT.md had to be hand-authored from artifacts). Rules:

- 1. **Run the long tool through the BLOCKING `_watchdog.run_supervised`**

- (returns ONLY on process exit or stall, killing only a

- non-progressing job — never a live one), NOT a raw detached host

- `timeout &`. That keeps your turn alive until the run genuinely

- completes, so your write step actually runs.

- 2. **Your FINAL act before reporting done is to WRITE + SELF-VERIFY the

- deliverable**: author `RESULT.md`, then run

- `python3 programs/run_output_completeness_check.py <run_dir>` on your

- OWN run_dir. Exit 0 (COMPLETE) is the only "done"; exit 3

- (RUN_STILL_IN_PROGRESS) means the run isn't finished yet; any FAIL

- (`COMPUTE_DONE_DELIVERABLE_MISSING` / `DELIVERABLE_STUB` /

- `RUN_DIED_EARLY`) means you have not delivered.

- 3. **NO RESULT / empty output = the run FAILED.** A run that produced no

- RESULT is not "mostly done" — it is a failed run; do not report it as

- complete. The gate emits a capture candidate on FAIL — feed it to

- `enhancement_emit.py` so the gap is absorbed, never silent.

-

- ## Cron-invocation template

-

- ```

- <short-name>-field-agent

-

- You are the field-agent loop for <target>. State at

- <target>/_field_agent_state.json.

-

- At EVERY tick, BEFORE Step 1, run the deterministic closed-audit

- rule (programs/check_closed_for_field_audit.sh): for each CLOSED

- `core-closed` issue lacking `field-verified`, dispatch a verify

- agent against the real benchmark — VERIFIED → add `field-verified`

- (stays closed); NOT adequate → `gh issue reopen` + counter-evidence

- comment + remove `core-closed`.

-

- In Step 2, do NOT file a surface symptom. DRILL the gap to 0 residual

- in a throwaway sandbox worktree first (inner close-loop: run → observe

- top layer via phase{1,2,3}_verify_aggregate / signoff_audit →

- prototype a chip-AGNOSTIC fix → re-run → peel the next deeper layer →

- repeat), gate the bundle with handoff_bundle_check.py (0 residual ×2

- rounds + chip-AGNOSTIC candidate.patch + per-LAYER tests + your own

- Step-2.7), then file ONE complete verified bundle as a PROPOSAL. Split

- independent root causes into separate bundles. NEVER push or self-merge

- the prototype — the gatekeeper independently reproduces + Step-2.7s +

- lands it, and the post-merge real-benchmark re-audit still runs.

-

- [paste the four-step loop above, adapted to the target intent]

-

- LLM-review prompt body (Step 1):

- "<paste the prompt that names the target ICs, the runner, the

- known-closed gap IDs, and the report cap>"

- ```

-

- Save this prompt as the CronCreate `prompt` field; pick a 4–6

- minute interval; field-agent self-paces from there.

-

- ## Verification traps (MANDATORY audit hygiene)

-

- Traps that corrupted audit verdicts in real sessions (rules 1-2:

- 2026-06-06, ORGANIC #456; rule 3: 2026-06-07, ORGANIC #460/#466

- verification round) — all are now standing rules for EVERY fix audit:

-

- 1. **Pipeline exit-code masking.** `prog … | tail; echo $?` reports

- `tail`'s exit code, not the gate's — a FAILing gate reads as exit 0.

- RULE: run the gate program BARE first and capture its exit code

- (`prog …; rc=$?`), THEN pretty-print output separately (or use

- `set -o pipefail`). Never derive a verdict from a piped invocation.

-

- 2. **Which-tree-runs resolution.** Verifying a fix against the repo

- tree proves nothing if the INSTALLED PLUGIN CACHE is what actually

- executes — the cache can lag the marketplace origin by several

- versions. RULE: before auditing a fix, resolve which tree will run

- (installed cache vs repo checkout vs marketplace origin); when the

- cache lags, check out / worktree the origin commit under audit,

- run against THAT, and STATE the tree+version in the verify comment.

-

- 3. **Acceptance-criterion audit, not unit-test trust.** A core-closed

- issue's fix comment will report the new tests green + full suite

- green — but those are the *intermediate products of the new code*,

- not proof the defect is gone. RULE: audit a core-closed issue by

- FIRST running the issue's own `## 驗收` (acceptance) command(s)

- end-to-end on the **real benchmark** — the actual program / gate

- invocation, observing its end-state output. The unit-test / suite

- evidence quoted in the fix comment is **secondary**; treat a fix

- whose acceptance command still fails as NOT adequate and reopen it,

- regardless of how green the suite is. This pattern recurred twice in

- one verification round (2026-06-07): one fix's tests asserted only

- that a generated bridge artifact existed and never exercised the

- `all_of` coverage sub-gate that actually decided the step verdict;

- another's rule landed in skill prose instead of the runner that

- executes it — both passed their own suites yet failed the moment the

- acceptance command was run end-to-end. Reproduce a defect-artifact

- fixture shaped like the issue's `現象`, run the acceptance command,

- and assert the END state — never the intermediate. (When an issue

- genuinely has no `## 驗收` section, fall back to reproducing the

- `現象` to an end-state; do not substitute unit-test trust.)

-

- **The same trap applies to your OWN deep-resolution bundle.** The

- bundle's 0-residual proof is *intermediate product of your

- candidate.patch*, not proof the defect class is gone. Build each

- per-layer regression test from a clean independent reference fixture

- (a known-good N-stage shift-reg → N, a comb block → 0), NEVER from a

- fixture seeded from the patch's own output — a subagent-built

- fixture seeded from the output under test is circular and its green

- test lies. This is also why the gatekeeper re-derives the fix rather

- than trusting your patch's green tests (guardrail 1).

-

- **Filing convention (flow #485):** every `## 驗收` section you FILE

- must contain **at least one concrete executable command in fenced

- code** — narrative-only bullets leave the deterministic

- `acceptance_evidence_in_fix_comment_check` gate unable to bite (it

- then emits a named `ACCEPTANCE_NARRATIVE_ONLY` warning instead of

- biting, and the trace has to be audited manually). The intake check

- (`regression_issue_intake_check`) warns at filing time on

- zero-command acceptance sections.

-

- **Filing-time lint (flow #489):** ORGANIC-form issues never pass

- through the (network-only, template-gated) intake check — so the

- filing step is draft → lint → create:

- `python3 programs/organic_issue_body_lint.py <draft.md>` (or stdin

- `-`). Fix any `MISSING_ACCEPTANCE` / `ACCEPTANCE_NARRATIVE_ONLY` /

- `NO_DEFECT_ARTIFACT` warning (the last one points at the flow #487

- snapshot helper) BEFORE `gh issue create`.

-

- 4. **A published L document is the output of a PAST run — ask it which

- one.** (2026-07-28, #522.) On one day three issues were filed against

- `benchmark-data/**/generated_docs/L*.json` produced ~70 releases

- earlier and read as the current state of the flow; one was written by

- someone holding this exact rule in the brief they had just handed out.

- Discipline was not enough because the documents said nothing about

- their own vintage. They do now. RULE: before quoting a count from a

- published L document, calling a gate on it a blocker, or filing an

- issue whose premise is what it contains, run

- ```bash

- python3 programs/l_doc_generator_stamp.py <design-dir>

- # Published corpus scans must opt into recursive scope explicitly.

- python3 programs/l_doc_generator_stamp.py <corpus-dir> --corpus

- ```

- `CURRENT` — same release and same L-doc taxonomy as your checkout;

- read it as current. `STALE` / `NEWER` — the report gives the version

- distance. `UNSTAMPED` — produced before the stamp existed, vintage

- unknown: **re-derive through the canonical entry before concluding

- anything**, and if you file anyway, say which version you measured.

- The same applies to your own audit of a `core-closed` fix: a

- `## 驗收` command run against a stale artefact reproduces the past,

- not the fix.

- ## Reference

- - Handoff bundle admission gate: `programs/handoff_bundle_check.py`

- - Layer roll-up probes (inner close-loop):

- `programs/phase1_verify_aggregate.py`,

- `programs/phase2_verify_aggregate.py`,

- `programs/phase3_verify_aggregate.py`, `programs/signoff_audit.py`

- - Helper script: `programs/check_closed_for_field_audit.sh`

- - Backlog YAML schema + sanitize: `vibe-ic:community-backlog-submit`

- - Phase 1 deep review: `vibe-ic:phase1-completeness-deep-review`

- - Compliance gate: `compliance.yaml` (run after producing

- state-file updates / verify comments)

- ## Compliance gate (mandatory)

- After producing your verify comment or backlog YAML, save to a

- file and run:

- ```bash

- python3 <plugin_root>/_shared/skill_compliance_check.py \

- --requirements ./compliance.yaml <output_file>

- ```

- Exit 0 = PASS, exit 1 = FAIL with missing elements listed. Patch

- and re-run until PASS.