# What "Patch, Never Regenerate" Means in Hyperresearch: Immutable Research Outputs

> Understand the 'patch, never regenerate' concept in Hyperresearch. Learn how this constraint ensures immutable research outputs, preserving provenance and preventing hallucinations for reliable scientific integrity.

- Repository: [Jordan Gibbs/hyperresearch](https://github.com/jordan-gibbs/hyperresearch)
- Tags: deep-dive
- Published: 2026-09-13

---

**In Hyperresearch, "patch, never regenerate" is a strict architectural constraint that forbids rewriting entire research drafts after the synthesis phase, permitting only surgical edit-hunks by the patcher (step 14) and polish auditor (step 15) to preserve provenance and prevent hallucinations.**

Hyperresearch is an open-source autonomous research pipeline that treats the synthesized report as an immutable artifact once generated. This principle ensures that every subsequent modification remains traceable, reproducible, and grounded in the original research query rather than risking the introduction of new errors through wholesale regeneration.

## Why Regeneration Is Forbidden After Synthesis

Once the pipeline completes **step 11** (or **step 10** for the light tier), the synthesized draft is considered the canonical output. Re‑generating the entire document at this stage would discard the provenance chain established by all preceding steps, potentially re‑introducing hallucinations or factual drift. According to the [`README.md`](https://github.com/jordan-gibbs/hyperresearch/blob/main/README.md) overview, the system explicitly forbids this behavior to guarantee research integrity.

By limiting post‑synthesis modifications to *surgical* edit‑hunks, Hyperresearch ensures that every change is auditable against the original query. The patcher validates each finding against the source material before application, creating a traceable log of exactly what was modified and why.

## Tool‑Lock Enforcement and Permission Constraints

The "patch, never regenerate" rule is mechanically enforced through **tool‑locking**. Both the patcher and polish auditor are restricted to the `[Read, Edit]` permission set, as implemented in [`src/hyperresearch/core/hooks.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/core/hooks.py) during agent registration.

This constraint means:
- **No file creation**: Agents cannot create new files or overwrite entire reports.
- **Edit‑only access**: Modifications are confined to existing files, specifically the `patch‑log.json` stub.
- **Escalation protocol**: If a critic proposes changes requiring structural rewrites (such as reorganizing entire sections), the finding is marked as `orchestrator_escalated` in the patch log rather than allowing the sub‑agent to violate the tool lock.

The skill definitions in [`src/hyperresearch/skills/hyperresearch-14-patcher.md`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/skills/hyperresearch-14-patcher.md) codify these restrictions, ensuring that any attempt to exceed `[Read, Edit]` permissions triggers an immediate escalation to the user.

## The Operational Flow of Patch‑Only Editing

The patch‑only workflow follows a strict three‑phase process after synthesis completes:

1. **Stub Creation**: The orchestrator writes a `patch‑log.json` stub to `research/runs/<vault_tag>/patch-log.json`. This is the only file the patcher is permitted to modify.
2. **Patch Application**: The patcher reads critic findings, validates each against the original research query, and updates the stub with structured fields including `total_findings`, `applied`, `skipped`, `conflicts`, and `orchestrator_escalated` entries.
3. **Final Polish**: The polish auditor runs a hygiene pass (step 15), also locked to `[Read, Edit]`, ensuring grammatical and formatting consistency without regenerating content.

```bash

# Run full research through synthesis (steps 1‑13)

hyperresearch run my_query.md --profile full

# Orchestrator creates the patch‑log stub (required pre‑step‑14)

echo '{"total_findings":0,"applied":[],"skipped":[],"conflicts":[],"orchestrator_escalated":[]}' \
  > research/runs/<vault_tag>/patch-log.json

# Invoke patcher (step 14) — edits only the existing stub

hyperresearch skill hyperresearch-14-patcher --vault-tag <vault_tag>

# Final polish (step 15) — confined to read/edit permissions

hyperresearch skill hyperresearch-15-polish --vault-tag <vault_tag>

```

## Source Code Implementation

The enforcement mechanism is distributed across three critical files:

- **[`README.md`](https://github.com/jordan-gibbs/hyperresearch/blob/main/README.md)** (lines 115‑117): Introduces the "Patch, never regenerate" principle as a pipeline invariant.
- **[`src/hyperresearch/skills/hyperresearch-14-patcher.md`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/skills/hyperresearch-14-patcher.md)** (lines 52‑60): Defines the stub‑creation process and tool‑lock constraints for the patcher skill.
- **[`src/hyperresearch/core/hooks.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/core/hooks.py)**: Registers the patcher and polish auditor agents with the `[Read, Edit]` permission lock, physically preventing file creation or full overwrites.

## Summary

- **Immutable synthesis**: Once step 11 (or step 10) produces a draft, the document is never rewritten from scratch.
- **Surgical edits only**: The patcher applies only validated edit‑hunks to `patch‑log.json`, ensuring traceability.
- **Tool‑lock guarantees**: `[Read, Edit]` permissions hard‑coded in [`hooks.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/hooks.py) prevent accidental regeneration.
- **Escalation path**: Structural issues requiring full rewrites escalate to the orchestrator rather than violating the patch‑only constraint.

## Frequently Asked Questions

### What happens if a critic identifies a structural flaw requiring full section rewrites?

The patcher cannot regenerate entire sections due to its `[Read, Edit]` tool lock. Instead, it flags the finding as `orchestrator_escalated` in `patch‑log.json`, alerting the user to resolve the structural issue manually while preserving the original synthesized content.

### At which specific pipeline steps does "patch, never regenerate" take effect?

The rule activates immediately after **step 11** (full tier) or **step 10** (light tier) completes the synthesis phase. **Step 14** (patcher) and **step 15** (polish auditor) are the only subsequent steps permitted to modify the output, and both are constrained to editing the existing `patch‑log.json` stub.

### How does Hyperresearch physically prevent agents from regenerating drafts?

Agent registration in [`src/hyperresearch/core/hooks.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/core/hooks.py) binds both the patcher and polish auditor to the `[Read, Edit]` permission set. This tool‑lock prevents file creation operations and full‑file overwrites, ensuring agents can only modify existing files within strictly defined boundaries.

### Can the patcher create new auxiliary files during the editing process?

No. The patcher is explicitly prohibited from creating new files. It operates exclusively on the `patch‑log.json` stub initialized by the orchestrator. Any requirement for new file generation would trigger an escalation rather than permitting the agent to bypass the `[Read, Edit]` constraint.