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/task_context.py

View on GitHub
"""Current work references, separate from historical completion receipts."""
from __future__ import annotations

import json

from check_delivery import (inspect_jsonl_text, inspect_csv_text, sha256_file,
                            reading_evidence_target, resolve_inside)
from task_storage import safe_path, nonempty, digest


def task_inputs(root):
    """One input reader for work preparation and version-bound review packets."""
    spec = safe_path(root, 'state/task_spec.md').read_text(encoding='utf-8')
    path = safe_path(root, 'state/requirements.jsonl')
    text = path.read_text(encoding='utf-8') if path.exists() else ''
    rows, errors = inspect_jsonl_text(text, 'Requirement')
    if errors:
        raise ValueError('; '.join(errors))
    return {'task': spec, 'requirements': text if text.strip() else '', 'rows': rows}


def source_inputs(root, sources):
    """Read selected source originals, using the same locators as content review."""
    texts, originals = {}, {}
    text_suffixes = {'.md', '.txt', '.html', '.htm', '.csv', '.tsv', '.json', '.jsonl', '.rst', '.log', '.yaml', '.yml'}
    for source in sources:
        names = set()
        if nonempty(source.get('evidence_path')):
            names.add(source['evidence_path'].strip())
        for field in ('url', 'read_evidence'):
            target = reading_evidence_target(source.get(field))
            if target:
                path = resolve_inside(root, target)
                if path is None:
                    raise ValueError(f"Source {source['source_id']}: evidence must stay inside the task.")
                names.add(path.relative_to(root.resolve()).as_posix())
        readable = False
        for name in sorted(names):
            path = safe_path(root, name)
            if not path.is_file() or not path.read_bytes().strip():
                raise ValueError(f"Source {source['source_id']}: missing or empty evidence {name}.")
            if path.suffix.lower() in text_suffixes:
                try:
                    texts[name] = path.read_text(encoding='utf-8')
                except UnicodeError as exc:
                    raise ValueError(f"Source {source['source_id']}: provide a UTF-8 evidence_path for {name}.") from exc
                readable = readable or bool(texts[name].strip())
            else:
                originals[name] = sha256_file(path)
        if not readable:
            raise ValueError(f"data/source_registry.csv row {source['source_id']}, evidence_path: set a task-relative UTF-8 source text or extract, such as sources/{source['source_id']}.md. URLs and page locators alone cannot be reviewed.")
    return texts, originals


def changed_inputs(root, inputs, current_hashes):
    from record_changes import input_digest
    changed = []
    for name, expected in inputs.items():
        if name not in current_hashes:
            try:
                current_hashes[name] = input_digest(root, name)
            except (OSError, ValueError):
                current_hashes[name] = None
        actual = current_hashes[name]
        if actual is None or actual != expected:
            changed.append(name)
    return changed


def research_outputs(root, warnings, progress=None):
    """Recover saved branch artifacts from the existing activity log, not another ledger."""
    outputs = {}
    # Older observations often name the same current file or registry row.
    # Compare each input once in this read of the task; later calls read it afresh.
    current_hashes = {}
    try:
        path = safe_path(root, 'logs/activity.jsonl')
        text = path.read_text(encoding='utf-8') if path.exists() else ''
    except (OSError, ValueError):
        warnings.append('Analysis observations unreadable; original activity log retained.')
        return []
    if text:
        for line in text.splitlines():
            try:
                row = json.loads(line)
                if (not isinstance(row, dict) or row.get('outcome') != 'saved'
                        or not row.get('artifact') or (row.get('artifact_kind') != 'analysis'
                            and not row.get('unit_id') and not row.get('host_task'))):
                    continue
                previous = outputs.get(row['artifact'], {})
                item = {'path': row['artifact'], 'sha256': row['artifact_sha256'],
                        'kind': row.get('artifact_kind'), 'complete': row.get('unit_complete', row.get('complete_draft', False)),
                        'contributors': sorted(set(previous.get('contributors', [])) | ({row['host_task']} if row.get('host_task') else set())),
                        'history': {'path': 'logs/activity.jsonl', 'artifact': row['artifact']}}
                for key in ('host_task', 'based_on', 'unit_id', 'depends_on', 'dependency_versions', 'handoff', 'question',
                            'artifact_snapshot', 'previous_version'):
                    if key in row:
                        item[key] = row[key]
                    elif key in previous:
                        item[key] = previous[key]
                item['owner'] = item.get('handoff', {}).get('to') or item.get('host_task')
                item['changed_inputs'] = [name for name in changed_inputs(root, item.get('based_on', {}), current_hashes)
                                          if name.startswith('record:') or safe_path(root, name) != safe_path(root, item['path'])]
                item['changed_since_save'] = bool(changed_inputs(root, {item['path']: item['sha256']}, current_hashes))
                outputs[item['path']] = item
            except (ValueError, KeyError, TypeError, AttributeError):
                warnings.append('Unreadable analysis observation; original activity row retained.')
    units = {item['unit_id']: item for item in outputs.values() if item.get('unit_id')}
    reviews = (progress or {}).get('unit_reviews', {})
    if not isinstance(reviews, dict):
        warnings.append('Unit review references are malformed; retained work requires an intact review record.')
        reviews = {}
    # Cached approval is useful only while the actual review inputs and retained
    # replies still match. Supplemental review evidence need not be in based_on.
    # Reuse the file checks, not inspect(), which itself reads research_outputs.
    current_reviews = set()
    plans = (progress or {}).get('unit_review_plans', {})
    for unit_id, item in units.items():
        review = reviews.get(unit_id, {})
        plan = plans.get(unit_id, {}) if isinstance(plans, dict) else {}
        if (not isinstance(review, dict) or not isinstance(plan, dict)
                or review.get('ok') is not True or review.get('artifact_sha256') != item['sha256']
                or plan.get('input_version') != review.get('input_version')
                or plan.get('artifact') != item['path'] or plan.get('artifact_sha256') != item['sha256']):
            continue
        try:
            from host_review import checked_files
            checked_files(root, plan)
            current_reviews.add(unit_id)
        except (OSError, ValueError, KeyError, TypeError, AttributeError) as exc:
            warnings.append(f'Unit {unit_id}: independent review is no longer current: {exc}')
    def inspect_unit(unit_id, visiting):
        if unit_id in visiting:
            return ['cyclic_dependency']
        item = units.get(unit_id)
        if item is None:
            return ['not_registered']
        issues = []
        if not item['complete']:
            issues.append('not_complete')
        if item['changed_inputs']:
            issues.append('inputs_changed')
        if item['changed_since_save']:
            issues.append('artifact_changed')
        if any(units.get(dependency, {}).get('sha256') != checksum
               for dependency, checksum in item.get('dependency_versions', {}).items()):
            issues.append('dependency_version_changed')
        if unit_id not in current_reviews:
            issues.append('independent_review_pending')
        if any(inspect_unit(dependency, visiting | {unit_id}) for dependency in item.get('depends_on', [])):
            issues.append('dependency_pending')
        return issues
    for item in outputs.values():
        item['dependencies'] = [{'unit_id': unit_id, 'path': units.get(unit_id, {}).get('path'),
                                 'issues': inspect_unit(unit_id, set())}
                                for unit_id in item.get('depends_on', [])]
        if item.get('unit_id'):
            item['readiness_issues'] = inspect_unit(item['unit_id'], set())
            item['review'] = reviews.get(item['unit_id'])
    return list(outputs.values())


def prepared_work(root, unit_id):
    """Find this unit's unconsumed preparation in the existing activity history."""
    if not unit_id:
        return None
    from record_changes import history
    for row in reversed(history(root, outcome=None)):
        if row.get('unit_id') != unit_id:
            continue
        if row.get('operation') == 'save' and row.get('outcome') == 'saved':
            return None
        if row.get('operation') == 'prepare_work' and row.get('outcome') == 'prepared':
            return row
    return None


def retain_prepared_work(root, packet):
    """Remember an explicit unit preparation; plain status remains read-only."""
    if not packet.get('unit_id'):
        return
    from run_observation import record_event, now
    prepared = {'unit_id': packet['unit_id'], 'question': packet['question'],
                'depends_on': [item['unit_id'] for item in packet['dependencies']],
                'based_on': packet['inputs'], 'input_version': packet['input_version']}
    previous = prepared_work(root, packet['unit_id'])
    if previous and all(previous.get(key) == value for key, value in prepared.items()):
        return
    stamp = now()
    record_event(root, {'operation': 'prepare_work', 'outcome': 'prepared',
                       'started_at': stamp, 'finished_at': stamp, **prepared})


def prepare_work(root, progress, work, *, resume_prepared=False):
    """Assemble the Agent's explicit selection; do not infer scope or choose a plan."""
    from record_changes import claim_source_ids, history, input_digest, requirements_for_units, rows_from
    allowed = {'question', 'unit_id', 'depends_on', 'requirement_ids', 'claim_ids', 'source_ids', 'paths'}
    if not isinstance(work, dict) or set(work) - allowed:
        raise ValueError('work: use optional question, unit_id, depends_on, requirement_ids, claim_ids, source_ids and paths.')
    if 'question' in work and not nonempty(work['question']):
        raise ValueError('work.question: provide the specific research question as text.')
    if 'unit_id' in work:
        import re
        if not isinstance(work['unit_id'], str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.-]*', work['unit_id']):
            raise ValueError('work.unit_id: use a saved or new research-unit ID with letters, numbers, dots, underscores or hyphens.')
    for key in allowed - {'question', 'unit_id'}:
        if key in work and (not isinstance(work[key], list) or any(not nonempty(v) for v in work[key])):
            raise ValueError(f'work.{key}: use a list of IDs or task-relative paths.')
    supplied = task_inputs(root)
    context = current_work(root, progress)
    unit = next((item for item in context['research_outputs'] if item.get('unit_id') == work.get('unit_id')),
                None) if work.get('unit_id') else None
    pending = prepared_work(root, work.get('unit_id')) if resume_prepared else None
    paths = list(work.get('paths', []))
    record_ids = {key: list(work.get(key, [])) for key in ('requirement_ids', 'claim_ids', 'source_ids')}
    upstream = []
    source_paths = {}
    if 'source_ids' in work and (unit or pending):
        # The existing save history preserves original paths even after a
        # source is withdrawn from the current registry.
        for event in history(root):
            for identity, files in event.get('record_changes', {}).get('source_observations', {}).items():
                source_paths.setdefault(identity, set()).update(files)
    def take_inputs(item, *, own=False):
        replacing_sources = own and 'source_ids' in work
        retired_paths = set()
        if replacing_sources:
            for name in item.get('based_on', {}):
                if name.startswith('record:sources:') and name.split(':', 2)[2] not in work['source_ids']:
                    retired_paths.update(source_paths.get(name.split(':', 2)[2], ()))
        if item.get('path'):
            paths.append(item['path'])
        for name in item.get('based_on', {}):
            if name.startswith('record:'):
                _, kind, identity = name.split(':', 2)
                field = {'sources': 'source_ids', 'claims': 'claim_ids', 'requirements': 'requirement_ids'}[kind]
                if replacing_sources and kind == 'sources':
                    continue
                aggregate = kind == 'requirements' and (identity == 'effective' or identity.startswith('effective@'))
                if not aggregate and identity not in record_ids[field]:
                    record_ids[field].append(identity)
            elif (name not in {'state/task_spec.md', 'state/requirements.jsonl', 'data/source_registry.csv', 'data/claims_registry.csv'}
                    and name not in retired_paths):
                paths.append(name)
    if pending:
        take_inputs(pending, own=True)
        if unit:
            paths.append(unit['path'])
    elif unit:
        take_inputs(unit, own=True)
    dependencies = list(work.get('depends_on', (pending or unit or {}).get('depends_on', [])))
    seen = set()
    def take_upstream(dependency):
        if dependency in seen:
            return
        seen.add(dependency)
        selected = next((item for item in context['research_outputs'] if item.get('unit_id') == dependency), None)
        if selected:
            upstream.append(selected)
            take_inputs(selected)
            for ancestor in selected.get('depends_on', []):
                take_upstream(ancestor)
    for dependency in dependencies:
        take_upstream(dependency)
    def select(rows, field, ids, label):
        missing = set(ids) - {r.get(field, r.get('id')) for r in rows}
        if missing:
            raise ValueError(f"work.{label}: unknown IDs {', '.join(sorted(missing))}.")
        return [r for r in rows if r.get(field, r.get('id')) in ids]
    def registry(name, kind):
        # Match the record binding: an unrelated row can add CSV columns whose
        # empty cells do not change this unit's selected evidence.
        return list(rows_from(safe_path(root, name).read_bytes(), kind).values())
    requirements = select(supplied['rows'], 'requirement_id', record_ids['requirement_ids'], 'requirement_ids')
    claims = select(registry('data/claims_registry.csv', 'claims'), 'claim_id', record_ids['claim_ids'], 'claim_ids')
    sources = registry('data/source_registry.csv', 'sources')
    source_ids = set(record_ids['source_ids'])
    registered = {s['source_id'] for s in sources}
    for claim in claims:
        source_ids.update(claim_source_ids(claim, registered))
    for requirement in requirements:
        source_ids.update(requirement.get('required_source_ids', []))
    selected_sources = select(sources, 'source_id', source_ids, 'source_ids')
    files, originals = source_inputs(root, selected_sources)
    for name in dict.fromkeys(paths):
        if name in originals:
            continue
        try:
            files[name] = safe_path(root, name).read_text(encoding='utf-8')
        except (OSError, ValueError) as exc:
            raise ValueError(f'work.paths: cannot read {name}; use an existing task-relative UTF-8 file.') from exc
    input_names = ['state/task_spec.md', *files, *originals]
    requirement_unit_ids = sorted({work['unit_id'], *seen}) if work.get('unit_id') else None
    requirement_binding = ('record:requirements:effective@' + ','.join(requirement_unit_ids)
                           if requirement_unit_ids else 'record:requirements:effective')
    input_names.append(requirement_binding)
    input_names.extend('record:sources:' + source['source_id'] for source in selected_sources)
    input_names.extend('record:claims:' + claim['claim_id'] for claim in claims)
    inputs = {name: input_digest(root, name) for name in dict.fromkeys(input_names)}
    result = {'question': work.get('question', (pending or unit or {}).get('question')), 'unit_id': work.get('unit_id'),
              'unit': unit, 'upstream_outputs': upstream, 'task': supplied['task'],
              'dependencies': [{'unit_id': dependency,
                                'issues': next((item.get('readiness_issues', []) for item in upstream
                                                if item.get('unit_id') == dependency), ['not_registered'])}
                               for dependency in dependencies],
              'task_directory': str(root), 'effective_requirements': context['effective_requirements'],
              'applicable_requirements': requirements_for_units(context['effective_requirements'], requirement_unit_ids),
              'requirement_unit_ids': requirement_unit_ids,
              'scope_decisions': context['scope_decisions'], 'selected_requirements': requirements,
              'claims': claims, 'sources': selected_sources, 'files': files, 'source_files': originals,
              'main_artifact': context['artifact'], 'research_outputs': context['research_outputs'], 'inputs': inputs,
              'production_contexts': context['production_contexts']}
    result['input_version'] = digest({'question': result['question'], 'inputs': inputs})
    return result


def runtime_identity(toolkit):
    """Identify this implementation; do not claim the agent tool loaded its Skill."""
    result = {"version": (toolkit / "VERSION").read_text(encoding="utf-8").strip(),
              "implementation_path": str(toolkit / "scripts/research_workflow.py"),
              "implementation_sha256": sha256_file(toolkit / "scripts/research_workflow.py"),
              "entry_path": str(toolkit / "SKILL.md"),
              "entry_sha256": sha256_file(toolkit / "SKILL.md"),
              "host_loaded_entry": "not_observed"}
    return result


def current_work(root, progress):
    result = {"task_spec": "state/task_spec.md", "requirements": "state/requirements.jsonl",
              "artifact": None, "open_requirements": [], "effective_requirements": [],
              "scope_decisions": [], "warnings": [], "brief": progress.get('brief', {})}
    current = progress.get("current_artifact")
    if current is not None:
        try:
            path = safe_path(root, current["path"])
            checksum = sha256_file(path)
            result["artifact"] = {**current, "current_sha256": checksum,
                                  "changed_since_save": checksum != current.get("sha256")}
        except (OSError, ValueError, KeyError, TypeError):
            result["warnings"].append("Current artifact is missing or invalid; inspect the registered path.")
    try:
        path = safe_path(root, result["requirements"])
        if path.exists():
            rows, errors = inspect_jsonl_text(path.read_text(encoding="utf-8"), result["requirements"])
            result["warnings"].extend(errors)
            for row in rows:
                status = row.get("status")
                if isinstance(status, str) and status in {'waived', 'out_of_scope', 'accepted_limitation'}:
                    result['scope_decisions'].append(row)
                else:
                    result['effective_requirements'].append(row)
                if not isinstance(status, str):
                    result["warnings"].append("Requirement status is not text; retain the row and repair it through existing records.")
                    result["open_requirements"].append(row)
                elif status not in {"satisfied", "waived", "out_of_scope", "accepted_limitation"}:
                    result["open_requirements"].append(row)
    except (OSError, ValueError):
        result["warnings"].append("Requirements unreadable; inspect existing records before recovery.")
    result['research_outputs'] = research_outputs(root, result['warnings'], progress)
    result['work_units'] = [item for item in result['research_outputs'] if item.get('unit_id')]
    result['production_contexts'] = sorted({host for item in result['research_outputs']
                                          for host in item.get('contributors', [])}
                                         | ({progress['author_id']} if nonempty(progress.get('author_id')) else set()))
    result["scope"] = ("Current registered manuscript, effective requirements and recorded contributions."
                       if result["artifact"] else "No main manuscript is registered; select it with draft.main=true when saving.")
    if result["artifact"] and not nonempty(result["artifact"].get("owner")):
        result["warnings"].append("Main manuscript producer is missing. Save draft.path, draft.main=true and draft.host_task with the actual producing agent's task/session ID before independent review.")
    return result


def require_current_artifact(progress, artifact):
    current = progress.get("current_artifact")
    if current is not None and current.get("path") != artifact:
        raise ValueError("artifact differs from the registered main draft. Use its path or explicitly register the intended main draft with draft.main=true.")
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