Skip to content

rrrrrredy/research-toolkit / plugins/research-toolkit

research-toolkit

Flagged

Use for source-backed long-form research and writing in English or Chinese across fields, including revisions and continuation. Understand requirements, develop analysis through substantive research collaboration, and deliver a complete report after independent review, audit and acceptance.

FileKindSize
.codex-plugin/plugin.jsonconfig1.0 KB
.generated-files.jsonconfig6.3 KB
.mcp.jsonconfig158 B
LICENSEother1.0 KB
README.mdmarkdown3.4 KB
README.zh-CN.mdmarkdown3.0 KB
SKILL.mdskill md7.8 KB
SKILL.zh-CN.mdmarkdown6.5 KB
VERSIONother6 B
docs/compatibility.mdmarkdown3.8 KB
docs/compatibility.zh-CN.mdmarkdown3.2 KB
docs/delivery-verification.mdmarkdown19.2 KB
docs/delivery-verification.zh-CN.mdmarkdown16.3 KB
docs/review-completion.mdmarkdown18.0 KB
docs/review-completion.zh-CN.mdmarkdown14.7 KB
docs/usage-data.mdmarkdown15.4 KB
docs/usage-data.zh-CN.mdmarkdown13.9 KB
docs/usage-modes.mdmarkdown55.6 KB
docs/usage-modes.zh-CN.mdmarkdown48.6 KB
hooks/hooks.jsonconfig3.2 KB
mcp.jsonconfig253 B
plugin.jsonconfig1.1 KB
references/gotchas.mdmarkdown6.2 KB
references/gotchas.zh-CN.mdmarkdown3.6 KB
references/horizontal-vertical-analysis.mdmarkdown4.3 KB
references/horizontal-vertical-analysis.zh-CN.mdmarkdown3.2 KB
references/optional-analysis-lenses.mdmarkdown8.1 KB
references/optional-analysis-lenses.zh-CN.mdmarkdown6.1 KB
references/postmortem-lessons.mdmarkdown4.3 KB
references/postmortem-lessons.zh-CN.mdmarkdown3.5 KB
references/quality-gates.mdmarkdown5.7 KB
references/quality-gates.zh-CN.mdmarkdown4.5 KB
references/research-standard.mdmarkdown18.2 KB
references/research-standard.zh-CN.mdmarkdown13.7 KB
references/research-workflow.mdmarkdown25.5 KB
references/research-workflow.zh-CN.mdmarkdown19.9 KB
references/subagents-and-review-loop.mdmarkdown17.0 KB
references/subagents-and-review-loop.zh-CN.mdmarkdown13.4 KB
references/task-continuity.mdmarkdown6.9 KB
references/task-continuity.zh-CN.mdmarkdown5.3 KB
references/writing-style.mdmarkdown18.1 KB
references/writing-style.zh-CN.mdmarkdown14.9 KB
requirements-mcp.txtmarkdown11 B
scripts/agent_session.pyscript6.2 KB
scripts/check_delivery.pyscript44.6 KB
scripts/check_review_completion.pyscript28.5 KB
scripts/cli_agent_session.pyscript9.6 KB
scripts/codex_session.pyscript7.5 KB
scripts/extract_source_text.pyscript10.7 KB
scripts/host_review.pyscript78.4 KB
scripts/install_usage.pyscript9.7 KB
scripts/record_changes.pyscript13.7 KB
scripts/release_updates.pyscript9.8 KB
scripts/research_guidance.pyscript5.8 KB
scripts/research_host.pyscript52.4 KB
scripts/research_mcp.pyscript18.9 KB
scripts/research_records.pyscript28.5 KB
scripts/research_workflow.pyscript40.9 KB
scripts/review_process.pyscript5.2 KB
scripts/review_runner.pyscript20.2 KB
scripts/run_observation.pyscript7.7 KB
scripts/task_context.pyscript21.1 KB
scripts/task_lock.pyscript1.7 KB
scripts/task_reading.pyscript4.0 KB
scripts/task_storage.pyscript3.1 KB
scripts/usage_events.pyscript38.9 KB
scripts/usage_host.pyscript7.8 KB
scripts/usage_opencode.mjsscript3.1 KB

scripts/research_records.py

View on GitHub
"""Save agent-provided research records without making users edit CSV/JSONL."""
from __future__ import annotations
import csv
import io
import json
import os
import uuid
import hashlib
import re
import shutil
from check_delivery import (inspect_csv_text, inspect_jsonl_text, length_constraint_errors, sha256_file,
                            has_evidence, REQUIREMENT_DECISION_STATUSES, READING_REQUIREMENTS)
from run_observation import now, record_event

SCHEMAS = {
    "sources": ("data/source_registry.csv", "source_id", "S", "url",
                ["source_id", "title", "url", "source_type", "read_scope", "read_evidence", "evidence_path"]),
    "claims": ("data/claims_registry.csv", "claim_id", "C", "claim",
               ["claim_id", "claim", "claim_type", "supporting_sources", "counter_evidence", "uncertainty"]),
    "requirements": ("state/requirements.jsonl", "requirement_id", "R", "summary", []),
}


def revised_spec(original, previous, updates):
    """Replace known brief values while retaining manually added sections."""
    text = original.decode("utf-8-sig").replace("\r\n", "\n").replace("\r", "\n")
    for key, value in updates.items():
        if previous.get(key) == value:
            continue
        header = f"## {key}\n\n"
        if key not in previous and not re.search(r"(?m)^## " + re.escape(key) + r"\s*$", text):
            text = text.rstrip() + "\n\n" + header + value + "\n"
            continue
        pattern = re.compile(r"(?m)^" + re.escape(header + previous.get(key, "")) + r"(?=\n|$)")
        if len(list(pattern.finditer(text))) != 1:
            raise ValueError(f"brief.{key}: task_spec no longer matches the saved field. Agent: reconcile that field with the actual specification before retrying; retain other sections.")
        text = pattern.sub(lambda _: header + value, text, count=1)
    return text.encode("utf-8")


def merge_records(root, kind, incoming, replace):
    from task_storage import safe_path
    name, identity, prefix, natural_key, defaults = SCHEMAS[kind]
    path = safe_path(root, name)
    original = path.read_bytes() if path.exists() else None
    if not isinstance(incoming, list) or any(not isinstance(row, dict) for row in incoming):
        raise ValueError(f"{kind}: provide a list of objects, not CSV text.")
    columns, rows = list(defaults), []
    if original and not replace:
        text = original.decode("utf-8-sig")
        if defaults:
            rows, errors = inspect_csv_text(text, name, (identity,), identity)
            columns = list(csv.DictReader(io.StringIO(text)).fieldnames or defaults)
        else:
            rows, errors = inspect_jsonl_text(text, name)
            ids = [r.get(identity, r.get("id")) for r in rows]
            if any(not isinstance(i, str) or not i.strip() for i in ids) or len(set(ids)) != len(ids):
                errors.append("Missing or duplicate requirement IDs.")
            for row in rows:
                if identity not in row and "id" in row:
                    row[identity] = row["id"]
        if errors:
            raise ValueError(f"{kind}: {'; '.join(errors)} Agent: recover complete rows and resubmit with replace=['{kind}']; the tool retains the original backup.")
    used = {row[identity] for row in rows}
    touched, ids = set(), []
    for index, patch in enumerate(incoming):
        patch = dict(patch)
        if any(not isinstance(key, str) or not key.strip() for key in patch):
            raise ValueError(f"{kind}[{index}]: field names must be nonempty text.")
        key = patch.get(identity)
        if key is None:
            matches = [r for r in rows if patch.get(natural_key) and r.get(natural_key) == patch[natural_key]]
            if len(matches) > 1:
                raise ValueError(f"{kind}[{index}]: multiple {natural_key} matches; supply {identity} from the saved records.")
            if matches:
                key = matches[0][identity]
            else:
                n = 1
                while f"{prefix}{n}" in used:
                    n += 1
                key = f"{prefix}{n}"
        if not isinstance(key, str) or not key.strip() or key in touched:
            raise ValueError(f"{kind}[{index}].{identity}: provide distinct nonempty IDs in this request.")
        patch[identity] = key
        touched.add(key)
        used.add(key)
        ids.append(key)
        old = next((row for row in rows if row[identity] == key), None)
        row = {**(old or {}), **patch}
        if defaults:
            if kind == "sources":
                row.setdefault("read_scope", "not_read")
                if not isinstance(row["read_scope"], str) or row["read_scope"] not in {"", "not_read", "partial", "abstract", "relevant_sections", "full_text"}:
                    raise ValueError(f"sources[{index}].read_scope: use not_read/partial/abstract/relevant_sections/full_text.")
            for field, value in row.items():
                if field == "supporting_sources" and isinstance(value, list) and all(isinstance(v, str) for v in value):
                    row[field] = ";".join(value)
                elif not isinstance(value, str):
                    raise ValueError(f"{kind}[{index}].{field}: use text" + (" or a source-ID list." if field == "supporting_sources" else "."))
                if field not in columns:
                    columns.append(field)
            required = ("title", "url", "source_type") if kind == "sources" else ("claim", "claim_type")
            for field in required:
                if not row.get(field, "").strip():
                    raise ValueError(f"{kind}[{index}].{field}: provide the actual {field}; existing values are retained on updates.")
        else:
            if not isinstance(row.get("summary", row.get("description")), str):
                raise ValueError(f"requirements[{index}].summary: provide the requirement in plain language.")
            if "unit_ids" in row:
                unit_ids = row["unit_ids"]
                if (not isinstance(unit_ids, list)
                        or any(not isinstance(value, str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.-]*', value) for value in unit_ids)
                        or len(set(unit_ids)) != len(unit_ids)):
                    raise ValueError(f"requirements[{index}].unit_ids: use distinct research-unit IDs, such as [\"domestic\"]; omit or use [] for a global requirement.")
            row.setdefault("status", "pending")
            if row["status"] not in {"pending", "open", "in_progress", "blocked", "satisfied", "waived", "out_of_scope", "accepted_limitation"}:
                raise ValueError(f"requirements[{index}].status: use pending/open/in_progress/blocked/satisfied/waived/out_of_scope/accepted_limitation.")
            if row["status"] == "satisfied" and not has_evidence(row.get("evidence")):
                raise ValueError(f"requirements[{index}].evidence: satisfied needs a nonempty evidence string or list; keep pending until checked.")
            if row["status"] in REQUIREMENT_DECISION_STATUSES:
                decision = row.get("user_decision")
                if not isinstance(decision, dict) or not all(isinstance(decision.get(k), str) and decision[k].strip() for k in ("source_turn", "quote")):
                    raise ValueError(f"requirements[{index}].user_decision: retain the user's actual source_turn and quote for this scope decision.")
            if "required_source_ids" in row and (not isinstance(row["required_source_ids"], list)
                    or not row["required_source_ids"] or not all(isinstance(s, str) and s.strip() for s in row["required_source_ids"])):
                raise ValueError(f"requirements[{index}].required_source_ids: use a nonempty list of source IDs.")
            # An explicit user scope decision can retire a legacy obligation
            # without inventing a corrected reading promise for that old row.
            if row["status"] not in REQUIREMENT_DECISION_STATUSES and ("reading_requirement" in row or "required_source_ids" in row):
                if not isinstance(row.get("reading_requirement"), str) or row["reading_requirement"] not in READING_REQUIREMENTS:
                    raise ValueError(f"requirements[{index}].reading_requirement: use full_text or relevant_sections.")
                source_ids = row.get("required_source_ids")
                if (not isinstance(source_ids, list) or not source_ids
                        or not all(isinstance(s, str) and s.strip() for s in source_ids)
                        or len(source_ids) != len(set(source_ids))):
                    raise ValueError(f"requirements[{index}].required_source_ids: use a nonempty list of distinct source IDs.")
            if "length_constraint" in row:
                errors = length_constraint_errors(row["length_constraint"])
                if errors:
                    raise ValueError(f"requirements[{index}].length_constraint: {'; '.join(errors)}")
        if old is None:
            rows.append(row)
        else:
            rows[rows.index(old)] = row
    if defaults:
        stream = io.StringIO(newline="")
        writer = csv.DictWriter(stream, fieldnames=columns, lineterminator="\n")
        writer.writeheader()
        writer.writerows(rows)
        content = stream.getvalue()
    else:
        content = "".join(json.dumps(row, ensure_ascii=False) + "\n" for row in rows)
    return name, content.encode("utf-8"), original, ids


def save_records(root, sources=None, claims=None, requirements=None, draft=None, replace=None, brief=None):
    from task_storage import safe_path, load
    from research_guidance import BRIEF_FIELDS
    stamp, operation_id = now(), uuid.uuid4().hex
    event = {"operation": "save", "operation_id": operation_id, "started_at": stamp}
    plans, backups, ids, temporary, committed = [], [], {}, [], []
    try:
        progress = load(root, "state/progress.json")
        old_progress = dict(progress)
        if brief is not None:
            if (not isinstance(brief, dict) or not brief or any(k not in BRIEF_FIELDS for k in brief)
                    or any(not isinstance(v, str) or not v.strip() for v in brief.values())):
                raise ValueError("brief: provide nonempty text updates to question/audience/scope/output/depth/evidence_standard.")
            previous_brief = progress.get("brief", {})
            progress["brief"] = {**previous_brief, **brief}
            if progress["brief"] != previous_brief:
                path = safe_path(root, "state/task_spec.md")
                original_spec = path.read_bytes()
                plans.append(("state/task_spec.md", revised_spec(original_spec, previous_brief, brief), original_spec))
        values = {"sources": sources, "claims": claims, "requirements": requirements}
        replace = [] if replace is None else replace
        if not isinstance(replace, list) or any(k not in SCHEMAS or values[k] is None for k in replace):
            raise ValueError("replace: list only supplied record collections (sources, claims, requirements).")
        for kind, incoming in values.items():
            if incoming is not None:
                name, content, original, ids[kind] = merge_records(root, kind, incoming, kind in replace)
                plans.append((name, content, original))
                if kind in replace and original is not None:
                    backups.append((f"logs/record-backups/{operation_id}/{name}", original, None))
        if draft is not None:
            allowed = {"path", "content", "complete", "main", "kind", "based_on", "host_task",
                       "unit_id", "depends_on", "handoff", "question"}
            if not isinstance(draft, dict) or set(draft) - allowed:
                raise ValueError("draft: use path and optional content/complete/main/kind/based_on/host_task/unit_id/depends_on/handoff/question; complete records draft or unit completeness, not delivery approval.")
            name = draft.get("path")
            path = safe_path(root, name)
            target_name = path.relative_to(root.resolve()).as_posix()
            protected = {"state", "data", "logs", "reviews"}
            if (name.split("/")[0] in protected or target_name.split("/")[0] in protected
                    or path.suffix not in {".md", ".txt"}):
                raise ValueError("draft.path: use a report .md/.txt path outside state/data/logs/reviews, including resolved link targets; for example, reports/draft.md.")
            if type(draft.get("complete", False)) is not bool:
                raise ValueError("draft.complete: use true or false.")
            if type(draft.get("main", False)) is not bool:
                raise ValueError("draft.main: use true or false.")
            if draft.get("kind", "report") not in {"report", "comparison", "review", "analysis"}:
                raise ValueError("draft.kind: use report, comparison, review or analysis (a research contribution).")
            from task_context import research_outputs, prepared_work
            outputs = research_outputs(root, [], progress)
            previous = next((item for item in outputs if safe_path(root, item['path']) == path), {})
            current = progress.get("current_artifact", {})
            writes_current = bool(current.get('path') and safe_path(root, current['path']) == path)
            unit_id = draft.get('unit_id', previous.get('unit_id'))
            prepared = prepared_work(root, unit_id) or {}
            # Bind the versions actually returned at preparation, not current
            # file hashes at save time. Explicit callers retain their override.
            supplied_inputs = draft.get('based_on', prepared.get('based_on', previous.get('based_on', {})))
            if not isinstance(supplied_inputs, dict):
                raise ValueError('draft.based_on: use the work_context.inputs reference-to-SHA256 object.')
            if unit_id is not None:
                if not isinstance(unit_id, str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.-]*', unit_id):
                    raise ValueError('draft.unit_id: use a stable research-unit ID with letters, numbers, dots, underscores or hyphens.')
                if previous.get('unit_id') not in {None, unit_id} or any(
                        item.get('unit_id') == unit_id and safe_path(root, item['path']) != path for item in outputs):
                    raise ValueError('draft.unit_id: retain the registered unit and its original artifact path; use a new ID for different work.')
                if not isinstance(draft.get('host_task'), str) or not draft['host_task'].strip():
                    raise ValueError('draft.host_task: identify the actual producing agent task/session when saving a research unit.')
                event['unit_id'] = unit_id
                event['unit_complete'] = draft.get('complete', False)
            if 'question' in draft:
                if not isinstance(draft['question'], str) or not draft['question'].strip():
                    raise ValueError('draft.question: state the research question this contribution answers.')
                event['question'] = draft['question']
            elif prepared.get('question') or previous.get('question'):
                event['question'] = prepared.get('question') or previous['question']
            dependencies = draft.get('depends_on', prepared.get('depends_on', previous.get('depends_on', [])))
            if (not isinstance(dependencies, list) or any(not isinstance(value, str) or not value.strip() for value in dependencies)
                    or len(set(dependencies)) != len(dependencies) or unit_id in dependencies):
                raise ValueError('draft.depends_on: use distinct upstream research-unit IDs; a unit cannot depend on itself.')
            if dependencies and unit_id is None:
                raise ValueError('draft.unit_id: identify the research unit whose dependencies are being saved.')
            if unit_id:
                graph = {item['unit_id']: item.get('depends_on', []) for item in outputs if item.get('unit_id')}
                graph[unit_id] = dependencies
                def cyclic(identity, visiting):
                    return identity in visiting or any(cyclic(parent, visiting | {identity}) for parent in graph.get(identity, []))
                if cyclic(unit_id, set()):
                    raise ValueError('draft.depends_on: remove the cyclic dependency; retain only actual upstream work.')
                event['depends_on'] = dependencies
                upstream_versions = {}
                for dependency in dependencies:
                    upstream = next((item for item in outputs if item.get('unit_id') == dependency), None)
                    if upstream:
                        upstream_versions[dependency] = supplied_inputs.get(upstream['path'],
                            previous.get('dependency_versions', {}).get(dependency, upstream['sha256']))
                event['dependency_versions'] = upstream_versions
                if draft.get('complete'):
                    pending = []
                    for dependency in dependencies:
                        upstream = next((item for item in outputs if item.get('unit_id') == dependency), None)
                        issues = upstream.get('readiness_issues', []) if upstream else ['not_registered']
                        if upstream and upstream_versions[dependency] != upstream['sha256']:
                            issues = issues + ['dependency_version_changed']
                        if issues:
                            pending.append(f"{dependency}: {', '.join(issues)}")
                    if pending:
                        raise ValueError('draft.complete: upstream work is not ready (' + '; '.join(pending)
                                         + '). Save the current draft with complete=false; finish or revise and independently review the affected upstream work.')
            if 'host_task' in draft:
                if not isinstance(draft['host_task'], str) or not draft['host_task'].strip():
                    raise ValueError('draft.host_task: retain the actual agent task/session reference as text.')
                event['host_task'] = draft['host_task']
            handoff = draft.get('handoff')
            if handoff is not None:
                if (not isinstance(handoff, dict) or set(handoff) - {'summary', 'pending', 'decisions', 'to'}
                        or not isinstance(handoff.get('summary'), str) or not handoff['summary'].strip()):
                    raise ValueError('draft.handoff: use summary, optional pending/decisions lists and to (the receiving agent task/session).')
                for field in ('pending', 'decisions'):
                    if field in handoff and (not isinstance(handoff[field], list) or any(
                            not isinstance(value, str) or not value.strip() for value in handoff[field])):
                        raise ValueError(f'draft.handoff.{field}: use a list of substantive points; retain full analysis in the artifact.')
                if 'to' in handoff and (not isinstance(handoff['to'], str) or not handoff['to'].strip()):
                    raise ValueError('draft.handoff.to: use the receiving agent task/session reference.')
                if not event.get('host_task'):
                    raise ValueError('draft.host_task: identify the sender of the handoff.')
                event['handoff'] = handoff
            # The main manuscript has one declared writer. Transfer is a saved
            # handoff from that writer, not another writer silently claiming main.
            main_owner = current.get('owner')
            owner = main_owner if (writes_current or draft.get('main')) and main_owner else previous.get('owner') if unit_id else None
            if owner and event.get('host_task') != owner:
                raise ValueError(f'draft.host_task: {owner} owns this manuscript or research unit. Save an explicit handoff.to from that owner before another agent writes it.')
            if 'based_on' in draft or prepared or previous.get('based_on'):
                for input_name, checksum in supplied_inputs.items():
                    if isinstance(input_name, str) and input_name.startswith('record:'):
                        parts = input_name.split(':', 2)
                        if len(parts) != 3 or parts[1] not in SCHEMAS or not parts[2]:
                            raise ValueError(f'draft.based_on[{input_name}]: use a record reference returned in work_context.inputs.')
                    else:
                        safe_path(root, input_name)
                    if not isinstance(checksum, str) or not re.fullmatch('[a-f0-9]{64}', checksum):
                        raise ValueError(f'draft.based_on[{input_name}]: use the SHA256 returned in work_context.inputs.')
                event['based_on'] = supplied_inputs
            if unit_id:
                def other_inputs(item):
                    return {key: value for key, value in item.get('based_on', {}).items()
                            if key.startswith('record:') or safe_path(root, key) != path}
                if (other_inputs(event) != other_inputs(previous)
                        or dependencies != previous.get('depends_on', [])
                        or event.get('question') != previous.get('question')):
                    # This cached approval describes the previous input selection.
                    # Keep its plan and original results for the next revision.
                    progress['unit_reviews'] = {key: value for key, value in progress.get('unit_reviews', {}).items()
                                                if key != unit_id}
            # Preserve earlier contributions through the existing backup mechanism.
            # A child contribution never implicitly replaces the registered main draft.
            original = path.read_bytes() if path.exists() else None
            content = draft.get("content")
            if "content" not in draft:
                content = path.read_text(encoding="utf-8")
            if not isinstance(content, str) or not content.strip():
                raise ValueError("draft.content: provide nonempty report text or an existing nonempty UTF-8 file.")
            if "content" in draft:
                plans.append((name, content.encode("utf-8"), original))
                if original is not None and original != content.encode('utf-8'):
                    backup = f'logs/record-backups/{operation_id}/{name}'
                    backups.append((backup, original, None))
                    event['previous_version'] = {'path': backup, 'sha256': sha256_file(path)}
            if unit_id:
                # Retain the saved version even if an agent tool subsequently edits its
                # working file directly. Handoff summaries never replace it.
                snapshot = f'logs/record-backups/{operation_id}/saved/{name}'
                backups.append((snapshot, content.encode('utf-8') if 'content' in draft else original, None))
                event['artifact_snapshot'] = {'path': snapshot,
                    'sha256': hashlib.sha256(content.replace('\r\n', '\n').replace('\r', '\n').encode('utf-8')).hexdigest()}
            event.update(artifact=name, artifact_kind=draft.get('kind', 'report'),
                         complete_draft=draft.get("complete", False) and draft.get('kind') != 'analysis')
            if draft.get("main") or writes_current:
                normalized = content.replace("\r\n", "\n").replace("\r", "\n")
                progress["current_artifact"] = {"path": name,
                    "sha256": hashlib.sha256(normalized.encode("utf-8")).hexdigest(),
                    "kind": draft.get("kind", current.get("kind", "report") if current.get("path") == name else "report")}
                active_owner = (handoff or {}).get('to') or event.get('host_task') or main_owner
                if active_owner:
                    progress['current_artifact']['owner'] = active_owner
                if unit_id:
                    progress['current_artifact']['unit_id'] = unit_id
        if not plans and draft is None and brief is None:
            raise ValueError("Supply sources, claims, requirements or a draft to save.")
        research_changed = any(content != original for _, content, original in plans)
        if draft is not None:
            research_changed = research_changed or progress != old_progress or any(
                key in event and event[key] != previous.get(key)
                for key in ('unit_id', 'depends_on', 'handoff', 'based_on', 'host_task', 'question'))
            content_hash = hashlib.sha256(content.replace('\r\n', '\n').replace('\r', '\n').encode('utf-8')).hexdigest()
            research_changed = (research_changed or previous.get('sha256') != content_hash
                or ('complete' in draft and draft['complete'] != previous.get('complete', False)))
        if research_changed:
            progress['review_contract'] = max(2, progress.get('review_contract', 1))
            if progress.get('stage') in {'final', 'review'} or progress.get('status') == 'complete':
                progress.update(stage='revise', status='in_progress',
                    next_action='Continue the affected research and independent review; historical receipts remain retained.')
        if progress != old_progress:
            # Keep historical receipts and reviews intact. An explicit new main
            # draft or brief revision cannot retain a terminal current state.
            if progress.get("stage") in {"final", "review"} or progress.get("status") == "complete":
                progress.update(stage="revise", status="in_progress",
                                next_action="Continue the current work; reconcile affected requirements and review this version before delivery.")
            path = safe_path(root, "state/progress.json")
            plans.append(("state/progress.json", (json.dumps(progress, ensure_ascii=False, indent=2) + "\n").encode("utf-8"), path.read_bytes()))
        # Validate and stage every payload before replacing any current record.
        for name, content, original in backups + plans:
            if content == original:
                continue
            path = safe_path(root, name)
            path.parent.mkdir(parents=True, exist_ok=True)
            temp = path.with_name(path.name + "." + operation_id + ".tmp")
            temporary.append(temp)
            with temp.open("xb") as stream:
                stream.write(content)
            if path.exists():
                shutil.copymode(path, temp)
            committed.append((path, original, False))
        for i, temp in enumerate(temporary):
            path, original, _ = committed[i]
            os.replace(temp, path)
            committed[i] = (path, original, True)
        if draft is not None:
            event["artifact_sha256"] = sha256_file(safe_path(root, draft["path"]))
        event["outcome"] = "saved"
        result = {"ok": True, "saved_ids": ids, "updated_files": [p[0] for p in plans if p[1] != p[2]],
                  "backups": [p[0] for p in backups], "next_action": "Continue the research; existing draft, review and delivery checks still apply."}
        if ids:
            from record_changes import history, summarize_save
            try:
                event["record_changes"] = summarize_save(root, plans, ids, history(root))
            except (OSError, ValueError, TypeError, KeyError, AttributeError):
                result["observation_warning"] = "Records saved; change summary unavailable. Existing checks still apply."
    except (ValueError, TypeError, OSError, KeyError) as exc:
        for path, original, changed in reversed(committed):
            if changed:
                if original is None:
                    path.unlink(missing_ok=True)
                else:
                    path.write_bytes(original)
        event.update(outcome="error", error=str(exc))
        if isinstance(exc, OSError):
            next_action = ("The save failed; prior records were retained. Resolve access or file-use restrictions at the reported path, "
                           "then retry the same save. Do not change research fields to work around a file error.")
        else:
            next_action = "Agent: correct the indicated fields and retry. Keep research decisions with the user; do not ask them to edit CSV/JSONL."
        result = {"ok": False, "errors": [str(exc)], "next_action": next_action}
    finally:
        for temp in temporary:
            temp.unlink(missing_ok=True)
    event.update(finished_at=now())
    try:
        record_event(root, event)
    except (ValueError, OSError) as exc:
        result["observation_warning"] = f"Activity could not be recorded: {exc}"
    if result["ok"]:
        from record_changes import latest_changes
        from task_context import current_work
        result["changes"] = latest_changes(root)
        result["current_work"] = current_work(root, load(root, "state/progress.json"))
    return {**result, "observation": event}
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall