105 lines
6.2 KiB
Markdown
105 lines
6.2 KiB
Markdown
# Differentiated remediation handoff v2
|
|
|
|
This user-approved extension separates a successful causal diagnosis from the
|
|
kind of follow-up work needed. The architecture document remains unchanged.
|
|
BugAnalysis diagnoses, describes missing implementation information and produces
|
|
handoff documents. It does not execute remediation, coordinate recipients,
|
|
monitor their work or enforce downstream dependencies or execution readiness.
|
|
|
|
## Documents and statuses
|
|
|
|
For every confirmed diagnosis handled by the new handoff protocol, the package
|
|
contains both:
|
|
|
|
* `handoffs/coding/CR-NNNN/change_request.json` (plus a readable summary).
|
|
`format_version=2`, `assignment=assigned|none`, and a required
|
|
`human_dev_assigned` boolean make the intent explicit. The request status is
|
|
`ready`, `template` or `none`. None means no coding assignment was necessary
|
|
or possible; the reason is retained. The JSON does not contain the human task
|
|
body. It contains coding-relevant instructions, including missing input and
|
|
named placeholder tokens when the task is to create a template.
|
|
* `handoffs/human-dev/HD-NNNN/human_dev_request.md`. This is prose with a task
|
|
title, reason, instructions and expected result. It can request implementation
|
|
data collection, completing templates, or an operational/admin correction.
|
|
With no human task it explicitly says `Kein Human-Dev-Auftrag vorhanden`.
|
|
The manifest points to this document through `human_dev_request`.
|
|
|
|
The generation decision is saved for provenance under
|
|
`analysis/change-requests/NNNN/decision.json`; it contains the model's two
|
|
assignments so both delivered documents can be reproduced and verified. The
|
|
coding JSON only conveys whether a human also received an assignment.
|
|
|
|
A template order must name unique tokens such as `{{POSITION_X}}` and describe
|
|
which data is absent. This describes the coding task; BugAnalysis neither checks
|
|
the eventual implementation nor waits for anyone to fill those tokens. Assigned
|
|
coding tasks retain known-reference, root-scope and validation-instruction checks.
|
|
Verified project-research captures are usable as local implementation context.
|
|
The service does not require canonical reference archives where human-selected,
|
|
reviewed remediation data would suffice. Semantic correctness of task prose
|
|
remains an LLM responsibility; the structural validator cannot infer every error.
|
|
|
|
## Completion and responsibility
|
|
|
|
Ready coding, template coding, human-only and explicit no-assignment documents
|
|
all follow `BUILDING_DIAGNOSIS -> OUTPUT_READY -> HANDED_OFF` (after recipient
|
|
acknowledgement). A human remediation task is not a pending investigation request.
|
|
No new waiting status, work queue, feedback requirement or dependency gate exists.
|
|
Output validation checks the handoff package itself, including document hashes,
|
|
manifest pointers and identity. It does not validate future recipient actions.
|
|
|
|
Missing repair data does not produce FAILED_TO_ANALYZE or BLOCKED. If handoff
|
|
model responses repeatedly fail validation, a deterministic no-coding/human-dev
|
|
assignment asks for external preparation of remediation instructions; the
|
|
confirmed diagnosis remains successful. Model-provider failures can still block
|
|
this internal document-production step. Diagnosis data collection and its
|
|
existing asynchronous investigation workflow are unchanged. An inconclusive
|
|
diagnosis still goes to review without a remediation coding task.
|
|
|
|
## Versioning and replay
|
|
|
|
New handoff contexts freeze `handoff_protocol=2`. New calls now use
|
|
`change_request_v4` (compact v3 view with broader remediation-data guidance);
|
|
already persisted v1/v2/v3 requests keep their original prompt,
|
|
including crash recovery and provider retries.
|
|
Persisted historical contexts and calls keep their original prompt/hash. Pending
|
|
legacy responses are deterministically adapted into both new handoff documents;
|
|
closed historical packages retain v1 output semantics, including old
|
|
insufficient-context review packages.
|
|
Closed historical case packages are not silently rewritten. A new trial can
|
|
start from a pre-handoff generation in a separate workspace to exercise v2
|
|
without repeating the diagnosis or overwriting the original case.
|
|
|
|
Both documents and all original package files survive portable export and replay.
|
|
No additional LLM phase is added, and research budgets are neither reset nor
|
|
spent by handoff document generation.
|
|
|
|
## Compact handoff requests and correction feedback
|
|
|
|
The complete frozen context stays in the package. The v3 model view retains the
|
|
accepted diagnosis (including uncertainty), full interpretation, original human
|
|
observations, bug description, expected behavior and data-quality qualifiers.
|
|
Every investigation evidence payload remains complete, including query filters,
|
|
row coverage, truncation indicators and snapshot origin. Evidence record history
|
|
is replaced in the request by its content reference and hash; it remains in the
|
|
full context. Raw input inventories, runtime fact catalogs and duplicate source
|
|
catalogs are omitted at this post-diagnosis stage. No LLM summary is generated.
|
|
The output schema remains in the model message as well as the gateway contract,
|
|
so JSON-object and text-only endpoints still receive the complete output contract.
|
|
|
|
`local_context` offers only exact source/evidence pairs accepted by the existing
|
|
validator, with explicit `allowed_evidence_refs`. A database capture is a valid
|
|
scope reference. A schema file about the same table is not automatically evidence
|
|
for that capture. Validation and provenance requirements are not relaxed.
|
|
|
|
Each new v3 attempt includes prior validation codes and rejected affected scopes
|
|
from this revision, plus correction guidance. Feedback is reconstructed only from
|
|
attempts before the bound operation so later failures cannot change earlier
|
|
request hashes. A rejected v2 operation can proceed with a new v3 attempt without
|
|
rewriting its context or its previous calls; attempt limits remain unchanged.
|
|
|
|
Offline measurement on the local g87 test case: user message 317,069 -> 33,568
|
|
characters (89.4% reduction); serialized gateway request 338,972 -> 44,173 UTF-8
|
|
bytes (87.0%). All five evidence payloads remain; the offered source catalog
|
|
shrinks from 209 entries to five proven references. These are deterministic
|
|
size measurements, not a measured provider token count or quality guarantee.
|