Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions .agents/skills/physics-erdos-loop/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ Read [governance.md](references/governance.md) before changing a claim, conventi

- A campaign is an immutable research event, not canonical truth.
- A proposal can challenge a claim; only an accepted claim can supersede one.
- Accepted canon governs release and promotion decisions, but remains falsifiable and reviewable; a conflict is a diagnosis to investigate, not a reason to erase evidence or halt conditional artifact work.
- A verifier passing is necessary, but proves only its asserted predicate.
- A campaign completion decision, scientific claim decision, and PR merge decision are independent. Use `research-pr-harvest` for the merge decision.
- Numeric agreement is a comparator, never a concept-selection mechanism or hidden derivation input.
Expand Down Expand Up @@ -107,7 +108,7 @@ After failure, choose the next action from the diagnosis:
- implementation defect → repair and rerun;
- unstable numerics → change discretization, solver, precision, or oracle;
- bad representation → change variables, gauge, basis, coordinates, or formalism;
- concept conflicts with the framework → reject or reformulate it and try another candidate;
- concept conflicts with the framework → determine whether the defect belongs to the candidate or is independent evidence against accepted structure; reject or reformulate a defective candidate, otherwise open a `challenges` or foundational-revision proposal and keep the frontier active;
- target was misstated → correct the claim while preserving the user's objective;
- accepted foundation appears inconsistent → open a separate foundational-revision proposal.

Expand Down Expand Up @@ -142,9 +143,9 @@ A large pass tally with insensitive predicates does not promote a claim.

## Phase 6 — assess framework fit before data fit

Compare candidates using the preregistered criteria. Structural fit precedes empirical closeness. If the favored candidate requires reinterpretation of unrelated claims, convention mixing, compensating imports, or narrative edits, reject it and continue the search.
Compare candidates using the preregistered criteria. Structural fit precedes empirical closeness. If the favored candidate requires reinterpretation of unrelated claims, convention mixing, compensating imports, or narrative edits merely to preserve it, reject it and continue the search. If the mismatch is reproduced independently of that candidate, treat it as evidence about canon and route it through a separate challenge rather than assuming acceptance status resolves the science.

Do not revise foundations merely to save a candidate. A foundational revision must demonstrate an independent pre-existing inconsistency, compare at least two repairs, select the minimum coherent change, enumerate the migration, and pass global replay.
Do not revise foundations merely to save a candidate. A foundational revision is nevertheless a legitimate advancement route when it demonstrates an independent pre-existing inconsistency, compares at least two repairs, selects the minimum coherent change, enumerates the migration, and passes global replay. Until adjudication, the conflict blocks promotion and accepted downstream use, not truthful conditional APIs or continued investigation.

Only after the structural choice is frozen should you open the comparator gate and report predictive agreement or disagreement.

Expand Down Expand Up @@ -176,11 +177,11 @@ For accepted claims:
3. Move the adjudicated campaign record into the immutable `campaigns/` log.
4. Run `scripts/render_docs.py`; never hand-edit `docs/generated/`.
5. Generate or synchronize accepted claim/release memory. Keep proposal and attempt memory separate.
6. Run targeted scientific checks, `scripts/validate.sh` (which includes the full test suite), and `git diff --check`; do not repeat the unchanged full suite separately. Run validation and commit in separate process invocations so an unguarded shell cannot continue past a failed gate and mask it with a later successful command.
6. Run targeted scientific checks, `scripts/validate.sh --full`, and `git diff --check`; promotion is a full-validation boundary, so do not repeat that unchanged suite separately. Run validation and commit in separate process invocations so an unguarded shell cannot continue past a failed gate and mask it with a later successful command.

## Phase 10 — done gate

Declare the campaign objective complete only when every item in the success contract passes and the debt ledger is empty. An honest failure leaves the objective active with a new candidate or repair queued. It does not prevent an individual PR or agent run from ending at a clean harvest checkpoint: use `research-pr-harvest` to merge independently correct, novel, reusable units, name and keep open the canonical goal issue, update that issue with the merged/refactor/history disposition and unit-level rationale, and hand the exact frontier to a fresh run. Missing work toward the larger goal is frontier rather than debt unless a merged or promoted unit promises it. A pause caused by user authority or an external dependency preserves the active contract and exact next executable action; it is not scientific completion. When a repeated workflow defect or tooling gotcha is discovered, correct and consolidate the relevant instruction in `AGENTS.md`, this skill, and the applicable memory template; do not merely append another overlapping rule.
Declare the campaign objective complete only when every item in the success contract passes and the debt ledger is empty. An honest failure leaves the objective active with a new candidate or repair queued. It does not prevent an individual PR or agent run from ending at a clean harvest checkpoint: use `research-pr-harvest` to merge independently correct, novel, reusable units, name and keep open the canonical goal issue, update that issue with the merged/refactor/history disposition and unit-level rationale, and hand the exact frontier to a fresh run. Keep a source PR open while a finite repair or harvest is live; close it unmerged only after the harvest skill's terminal-close test. Missing work toward the larger goal is frontier rather than debt unless a merged or promoted unit promises it. A pause caused by user authority or an external dependency preserves the active contract and exact next executable action; it is not scientific completion. When a repeated workflow defect or tooling gotcha is discovered, correct and consolidate the relevant instruction in `AGENTS.md`, this skill, and the applicable memory template; do not merely append another overlapping rule.

## Working with delegated agents

Expand Down
34 changes: 29 additions & 5 deletions .agents/skills/research-pr-harvest/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Read the PR, linked goal, base release, accepted claim boundary, diff, tests, an

Identify one canonical goal issue and confirm that it existed before the PR was submitted, including before a draft PR. The PR must mention that issue explicitly: use `Advances #N` while the goal remains incomplete and reserve `Fixes #N` for full completion. If the source PR has no pre-existing issue, do not merge it. Create the canonical issue, preserve the source PR as provenance, and place any selected units in a new compliant harvest PR opened after the issue.

In this repository, treat the user's act of supplying a PR URL or number to an agent that did not open, commit to, or materially implement that PR as standing authorization to complete the normal PR lifecycle without further operator prompts: review and comment, edit PR metadata, create a focused harvest branch or follow-up PR, merge or close according to the evidence, and update the linked issue. An agent must not merge any PR it opened, committed to, or materially implemented. If the reviewing agent performs substantive repairs or creates a follow-up harvest PR, a distinct agent or repository owner must execute that merge. Leave a validated handoff when no distinct merger is available. Do not force-push a contributor's branch, delete unrelated branches, broaden the issue objective, or promote unsupported claims. If an external permission or branch rule blocks an action, preserve the exact next action and report the actual blocker.
In this repository, treat the user's act of supplying a PR URL or number to an agent that did not open, commit to, or materially implement that PR as standing authorization to complete the normal PR lifecycle without further operator prompts: review and comment, edit PR metadata, request changes, create a focused harvest branch or follow-up PR, merge when eligible, close only after the terminal-close test below, and update the linked issue. An agent must not merge any PR it opened, committed to, or materially implemented. If the reviewing agent performs substantive repairs or creates a follow-up harvest PR, a distinct agent or repository owner must execute that merge. Leave a validated handoff when no distinct merger is available. Do not force-push a contributor's branch, delete unrelated branches, broaden the issue objective, or promote unsupported claims. If an external permission or branch rule blocks an action, preserve the exact next action and report the actual blocker.

## Slice the PR into harvest atoms

Expand Down Expand Up @@ -50,11 +50,23 @@ Classify every unit as one of:
- **refactor then merge** — valuable core exists but must be decoupled, renamed, narrowed, or convention-corrected;
- **leave in PR history** — speculative capstone, duplicated machinery, unsupported interpretation, failed route, or maintenance cost with no durable reusable unit.

`Refactor then merge` is an active lifecycle state, not a polite rejection. Name
the repair owner or handoff, live source or harvest PR, exact change, and landing
test. Keep the source PR open in `request changes`, `active refactor`, or
`active harvest` state until that unit lands or becomes terminal.

Close an unmerged PR only when every reusable atom has landed elsewhere, every
remaining atom has unit-level evidence that it is incorrect, non-novel, or
unmaintainable, the author or owner explicitly withdraws it, or a superseding
landed implementation makes it redundant. Missing accepted dependency closure,
a conflict with current canon, lack of a distinct merger, or a pending finite
repair does not pass this terminal-close test.

## Build a harvest merge

Prefer a focused harvest commit or follow-up PR over merging an inseparable campaign dump. Include only the selected implementation, tests, and minimal API documentation.

- Keep accepted-claim authority in the registry; do not promote a headline because related code merges.
- Keep accepted-claim authority in the registry; do not promote a headline because related code merges. Treat accepted canon as release authority, not an irrevisable premise: a correct conditional API may merge with explicit assumptions while contrary evidence proceeds through `challenges` or a separately governed foundational revision.
- Create or confirm the canonical goal issue before opening the focused PR. Name it using `Advances #N` for partial progress and use `Fixes #N` only after the full goal passes its completion gate.
- Record the authoring or implementing agent and a distinct intended merger. The authoring agent may prepare, validate, and hand off the PR but may not merge it.
- Keep the goal issue open when the campaign remains incomplete.
Expand All @@ -73,16 +85,18 @@ After the final merge boundary is known, update the goal issue—not only the PR
- <unit and landed location> — Rationale: <why it is correct, reusable, and independent enough to own>. Evidence: <tests/oracle>.

### Requires refactor
- <unit> — Rationale: <valuable core>. Required change: <specific decoupling, correction, or narrowing>. Source: <PR path/commit>.
- <unit> — Rationale: <valuable core>. Required change: <specific decoupling, correction, or narrowing>. Owner/handoff: <identity>. Live PR: <source or harvest PR>. Landing test: <exact evidence>. Source: <PR path/commit>.

### Left in PR history
- <unit> — Rationale: <why it should not enter main>. Source: <PR path/commit>.

### Continuation
- Claims promoted: <none or ids>
- Goal state: <open or complete>
- PR lifecycle: <request changes, active refactor, active harvest, merged, or terminal closed>
- Landed interfaces: <paths/symbols>
- Next decisive action: <one executable step or test>
- Terminal-close evidence: <not applicable, or qualifying reason plus landed replacement links>

### What closes the goal
- Objective-level closure: <the positive scientific result and governance gates, independent of the reviewed route>
Expand Down Expand Up @@ -111,6 +125,14 @@ For the current route, list necessary proof obligations and the evidence that wo

Treat review conclusions as reasoned and rebuttable, not as accepted scientific authority. For every blocking conclusion, state what counterexample, derivation, constraint count, controlled limit, or other evidence would change the assessment. Invite focused disagreement without weakening the completion gate.

When a route conflicts with accepted canon, separate its artifact claim from its
authority claim. A canon conflict blocks promotion and accepted downstream use;
it does not by itself block a correct conditional artifact, erase contrary
evidence, or close the PR. Test whether the mismatch is a candidate defect or a
pre-existing canonical inconsistency. If it survives independently of the
favored route, open a `challenges` or foundational-revision proposal with
competing repairs and keep the scientific frontier active.

## Preserve novelty without creating debt

Missing pieces of the parent goal are the **campaign frontier**, not debt. Debt means an unresolved defect, unsupported promise, broken consumer, or hidden assumption inside the scope being merged or promoted.
Expand All @@ -134,12 +156,13 @@ Treat the goal as long-lived and each agent run or PR as bounded.
- Harvest a unit as soon as it becomes locally complete; do not hold all value hostage to the capstone.
- Maintain a short PR frontier with `landed`, `current hypothesis`, and `next decisive test` rather than expanding narrative state.
- If later work becomes repetitive, weakens claims, substitutes ceremony for new evidence, or only restates earlier results, stop that run at the last strong milestone. Merge the harvest, leave the goal open, and hand the frontier to a fresh agent.
- Keep the source PR open while a declared refactor or harvest remains live; reassess closure only after the unit lands or the terminal-close test passes.

An individual run may end at a clean handoff without lowering or closing the campaign objective.

## Validate proportionately

Run targeted tests and claim-appropriate oracles for each harvested unit, impact analysis for changed public symbols, affected consumers, and one repository validation at the final unchanged merge boundary. Do not rerun unrelated full validation for each discarded campaign artifact.
Run targeted tests and claim-appropriate oracles for each harvested unit, impact analysis for changed public symbols, affected consumers, and one repository validation at the final unchanged merge boundary. An additive public export may use scoped validation when impact is bounded, no existing contract changes, consumers are known, and targeted API coverage passes. Reserve full validation for promotion or release, shared numerics or verification machinery, claim/release governance semantics, changed existing public contracts with consumers, dependency or cross-cutting convention changes, multi-sector changes, or uncertain impact. Pull-request CI uses `scripts/validate_changed.py` for this conservative decision and uses fixed checks only when no pytest scope is affected; scheduled/manual CI supplies the periodic full backstop. Do not rerun unrelated full validation for each discarded campaign artifact or again after merge.

## Report the disposition

Expand All @@ -164,7 +187,8 @@ Use this compact structure:
- Authoring or implementing agent: <identity>
- Distinct merger: <identity or handoff pending>
- Issue handoff: <posted link or ready-to-post pending>
- PR disposition: <progress merge, harvest split, request changes, or close>
- PR lifecycle: <request changes, active refactor, active harvest, merged, or terminal closed>
- Terminal-close evidence: <not applicable, or qualifying reason plus landed replacement links>
- Campaign frontier: <next decisive question>
```

Expand Down
15 changes: 11 additions & 4 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,12 +89,15 @@ Campaign frontier outside this merge unit:
## Validation boundary

Mark a nonapplicable scientific row `N/A` and explain why in the verification
section; do not claim it passed.
section; do not claim it passed. An additive public export may stay scoped when
impact analysis shows a bounded sector, no changed existing contract, known
consumers, and targeted API coverage. Record that rationale rather than treating
the export alone as a full-suite trigger.

- [ ] Targeted tests and named scientific verifiers pass.
- [ ] Load-bearing mutations, counterexamples, or wrong-convention probes fail as expected.
- [ ] Affected downstream consumers replay.
- [ ] `scripts/validate.sh --pytest-scope ...` passes with the exact selectors recorded, or the full-suite trigger is explained and `scripts/validate.sh --full` passes.
- [ ] `scripts/validate.sh --pytest-scope ...` passes with the exact selectors recorded, `--fixed-only` is justified by no affected pytest scope, or the full-suite trigger is explained and `scripts/validate.sh --full` passes; PR CI's `scripts/validate_changed.py` decision agrees.
- [ ] The pytest scope remains valid against the merge base; an equivalent unchanged validation is not duplicated.
- [ ] `git diff --check` passes in a separate invocation.
- [ ] No unrelated, generated-by-hand, or host-specific artifacts are included.
Expand All @@ -119,10 +122,12 @@ fields in a formal review.
- Claim promotion: <!-- none or exact claim IDs and review evidence -->
- Goal completion: <!-- yes/no and still-open gate -->
- Merge as written: <!-- yes/no -->
- Refactor or harvest: <!-- exact units and required changes -->
- Refactor or harvest: <!-- exact units, owner/handoff, live PR, required changes, and landing test -->
- Leave in PR history: <!-- exact units and rationale -->
- Source PR lifecycle: <!-- request changes, active refactor, active harvest, merged, or terminal closed -->
- Terminal-close evidence: <!-- N/A, or qualifying reason and landed replacement links -->
- Next decisive action: <!-- one concrete step -->
- Head branch disposition: <!-- auto-delete after merge; preserve if closed-unmerged/failed; name any explicit owner exception -->
- Head branch disposition: <!-- auto-delete after merge; otherwise preserve unless owner retirement follows a recorded terminal-close decision -->

### Reviewer checks

Expand All @@ -134,5 +139,7 @@ fields in a formal review.
- [ ] Every new public symbol has an explicit authority status and owning issue.
- [ ] Verification sensitivity and applicable numerical/formal limits audited.
- [ ] Merge, claim-promotion, and goal-completion decisions kept independent.
- [ ] A finite refactor or harvest has an owner/handoff, live PR, and landing test; its source PR remains open.
- [ ] Any proposed unmerged closure passes the terminal-close test and records landed replacements.
- [ ] Canonical issue handoff is posted or preserved ready to post.
- [ ] The exact same-repository head will be deleted after merge; open or closed-unmerged/failed heads are preserved unless an owner explicitly retires them.
Loading