Skip to content

zrwangems/dsh-zrwang-plugin / ars/skills/academic-pipeline

academic-pipeline

Unverified

学术研究总编排:研究→写作→诚信检查→评审→返修→复审→终检→定稿的十阶段流水线,每阶段停在用户确认点,含材料护照与 7 类 AI 研究失败模式检查。Triggers: academic pipeline, research to paper, full paper workflow, end-to-end paper | 完整论文流程, 从研究到论文, 端到端写论文, 论文流水线。

FileKindSize
SKILL.mdskill md58.4 KB
_shared/ARCHITECTURE.mdmarkdown51.7 KB
_shared/MODE_REGISTRY.mdmarkdown6.7 KB
_shared/agents/compliance_agent.mdmarkdown9.4 KB
_shared/artifact_reproducibility_pattern.mdmarkdown9.8 KB
_shared/benchmark_report.schema.jsonconfig2.7 KB
_shared/benchmark_report_pattern.mdmarkdown8.8 KB
_shared/bibliographic_integrity_signals.mdmarkdown8.1 KB
_shared/collaboration_depth_rubric.mdmarkdown11.5 KB
_shared/compliance_checkpoint_protocol.mdmarkdown8.9 KB
_shared/compliance_report.schema.jsonconfig8.1 KB
_shared/contracts/README.mdmarkdown54.7 KB
_shared/contracts/activity/adjudication_activity_input.schema.jsonconfig18.5 KB
_shared/contracts/activity/adjudication_activity_store.schema.jsonconfig18.7 KB
_shared/contracts/audit/audit_jsonl.schema.jsonconfig5.4 KB
_shared/contracts/audit/audit_sidecar.schema.jsonconfig8.4 KB
_shared/contracts/audit/audit_verdict.schema.jsonconfig5.4 KB
_shared/contracts/audit/cross_document_consistency_advisory.schema.jsonconfig20.4 KB
_shared/contracts/audit/cross_document_consistency_advisory_draft.schema.jsonconfig23.4 KB
_shared/contracts/audit/cross_document_source_manifest.schema.jsonconfig6.3 KB
_shared/contracts/audit/tortured_phrase_advisory.schema.jsonconfig30.9 KB
_shared/contracts/audit/tortured_phrase_snapshot.schema.jsonconfig4.9 KB
_shared/contracts/audit/tortured_phrase_snapshot_manifest.schema.jsonconfig7.3 KB
_shared/contracts/capability/stage_capability_matrix.jsonconfig23.5 KB
_shared/contracts/claim_standing/candidate_ledger.schema.jsonconfig23.1 KB
_shared/contracts/claim_standing/query_plan.schema.jsonconfig12.7 KB
_shared/contracts/claim_standing/query_plan_v1_1.schema.jsonconfig20.3 KB
_shared/contracts/claim_standing/retrieval_input.schema.jsonconfig14.4 KB
_shared/contracts/claim_standing/stance_record.schema.jsonconfig11.7 KB
_shared/contracts/claim_standing/transmission_ledger.schema.jsonconfig7.6 KB
_shared/contracts/cross_model/codex_citation_receipt.schema.jsonconfig4.7 KB
_shared/contracts/cross_model/codex_citation_request.schema.jsonconfig986 B
_shared/contracts/cross_model/promotion_bakeoff_sealed_commitment.schema.jsonconfig1.5 KB
_shared/contracts/cross_model/promotion_bakeoff_sealed_reveal.schema.jsonconfig1.5 KB
_shared/contracts/degradation_registry.jsonconfig42.5 KB
_shared/contracts/evaluator/full.jsonconfig6.3 KB
_shared/contracts/evidence/claim_registry.schema.jsonconfig2.3 KB
_shared/contracts/evidence/claim_registry_coverage_report.schema.jsonconfig4.8 KB
_shared/contracts/evidence/evidence_row.schema.jsonconfig14.3 KB
_shared/contracts/evidence/evidence_row_v1_1.schema.jsonconfig11.4 KB
_shared/contracts/evidence/evidence_row_v1_2.schema.jsonconfig21.8 KB
_shared/contracts/evidence/evidence_row_v1_3.schema.jsonconfig10.7 KB
_shared/contracts/human_subjects/authority_profile_registry.schema.jsonconfig16.7 KB
_shared/contracts/human_subjects/committee_correspondence.schema.jsonconfig9.9 KB
_shared/contracts/human_subjects/content_coverage_advisory.schema.jsonconfig19.9 KB
_shared/contracts/human_subjects/irb_context_record.schema.jsonconfig12.1 KB
_shared/contracts/human_subjects/resolved_authority_context.schema.jsonconfig11.8 KB
_shared/contracts/human_subjects/review_pathway_rule_trace.schema.jsonconfig9.5 KB
_shared/contracts/human_subjects/review_pathway_trace_request.schema.jsonconfig4.8 KB
_shared/contracts/human_subjects/submission_packet_inventory.schema.jsonconfig8.5 KB
_shared/contracts/human_subjects/submission_packet_manifest.schema.jsonconfig32.2 KB
_shared/contracts/passport/audit_artifact_entry.schema.jsonconfig10.8 KB
_shared/contracts/passport/bibliographic_integrity_signal.schema.jsonconfig48.9 KB
_shared/contracts/passport/citation_provenance.schema.jsonconfig4.8 KB
_shared/contracts/passport/citation_verification_summary.schema.jsonconfig8.2 KB
_shared/contracts/passport/claim_audit_result.schema.jsonconfig7.8 KB
_shared/contracts/passport/claim_drift.schema.jsonconfig3.8 KB
_shared/contracts/passport/claim_intent_manifest.schema.jsonconfig6.6 KB
_shared/contracts/passport/constraint_violation.schema.jsonconfig3.6 KB
_shared/contracts/passport/excluded_source_entry.schema.jsonconfig1.7 KB
_shared/contracts/passport/experiment_alignment_result.schema.jsonconfig4.8 KB
_shared/contracts/passport/experiment_provenance_entry.schema.jsonconfig10.0 KB
_shared/contracts/passport/human_read_log.schema.jsonconfig3.8 KB
_shared/contracts/passport/inquiry_ledger_ref.schema.jsonconfig881 B
_shared/contracts/passport/literature_corpus_entry.schema.jsonconfig30.3 KB
_shared/contracts/passport/preregistration_artifact.schema.jsonconfig4.3 KB
_shared/contracts/passport/rejection_log.schema.jsonconfig3.3 KB
_shared/contracts/passport/reset_ledger_entry.schema.jsonconfig7.1 KB
_shared/contracts/passport/run_ledger.schema.jsonconfig8.0 KB
_shared/contracts/passport/standing_constraint_entry.schema.jsonconfig2.6 KB
_shared/contracts/passport/temporal_audit_results.schema.jsonconfig8.8 KB
_shared/contracts/passport/terminal_policies.schema.jsonconfig8.1 KB
_shared/contracts/passport/timeline.schema.jsonconfig4.7 KB
_shared/contracts/passport/uncited_assertion.schema.jsonconfig3.3 KB
_shared/contracts/passport/uncited_audit_failure.schema.jsonconfig4.4 KB
_shared/contracts/passport/user_attested_read_resolution.schema.jsonconfig3.2 KB
_shared/contracts/passport/version_records.schema.jsonconfig4.9 KB
_shared/contracts/patch/block_manifest.schema.jsonconfig2.1 KB
_shared/contracts/patch/legacy/v1_0/revision_patch.schema.jsonconfig5.3 KB
_shared/contracts/patch/revision_patch.schema.jsonconfig8.9 KB
_shared/contracts/pdf/pdf_content_classifier_diagnostic.schema.jsonconfig1.2 KB
_shared/contracts/pdf/pdf_content_classifier_worker.schema.jsonconfig2.2 KB
_shared/contracts/pdf/pdf_read_preflight.schema.jsonconfig6.8 KB
_shared/contracts/re_review/input_manifest.schema.jsonconfig7.6 KB
_shared/contracts/re_review/legacy/v1_0/input_manifest.schema.jsonconfig6.2 KB
_shared/contracts/re_review/legacy/v1_0/precommitment.schema.jsonconfig8.9 KB
_shared/contracts/re_review/legacy/v1_0/traceability.schema.jsonconfig34.2 KB
_shared/contracts/re_review/legacy/v1_0/verdict_record.schema.jsonconfig10.5 KB
_shared/contracts/re_review/precommitment.schema.jsonconfig8.6 KB
_shared/contracts/re_review/traceability.schema.jsonconfig37.7 KB
_shared/contracts/re_review/verdict_record.schema.jsonconfig10.5 KB
_shared/contracts/research_workflow/inquiry_branch_ledger.schema.jsonconfig17.0 KB
_shared/contracts/research_workflow/research_workflow_profile.schema.jsonconfig7.2 KB
_shared/contracts/research_workflow/research_workflow_profile_selection_receipt.schema.jsonconfig3.9 KB
_shared/contracts/review_target/constructive_review_findings.schema.jsonconfig7.0 KB
_shared/contracts/review_target/criteria_registry.schema.jsonconfig4.0 KB
_shared/contracts/review_target/review_criteria_binding_manifest.schema.jsonconfig7.9 KB
_shared/contracts/review_target/review_criteria_source_receipt.schema.jsonconfig5.6 KB
_shared/contracts/review_target/review_target_context.schema.jsonconfig4.5 KB
_shared/contracts/review_target/review_target_declaration.schema.jsonconfig4.6 KB
_shared/contracts/reviewer/full.jsonconfig3.7 KB
_shared/contracts/reviewer/methodology_focus.jsonconfig2.2 KB
_shared/contracts/reviewer/review_panel_provenance.schema.jsonconfig7.8 KB
_shared/contracts/reviewer/review_panel_provenance_carrier.schema.jsonconfig4.1 KB
_shared/contracts/reviewer/review_panel_provenance_input.schema.jsonconfig3.5 KB
_shared/contracts/revision/author_adjudication.schema.jsonconfig7.8 KB
_shared/contracts/revision/author_adjudication_input.schema.jsonconfig1.2 KB
_shared/contracts/revision/claim_strength_drift_disposition.schema.jsonconfig3.6 KB
_shared/contracts/revision/claim_strength_drift_disposition_input.schema.jsonconfig3.1 KB
_shared/contracts/revision/claim_strength_drift_findings.schema.jsonconfig4.2 KB
_shared/contracts/revision/claim_surface_manifest.schema.jsonconfig3.3 KB
_shared/contracts/revision/integrity_correction_authorization.schema.jsonconfig4.3 KB
_shared/contracts/revision/integrity_correction_authorization_input.schema.jsonconfig1.5 KB
_shared/contracts/revision/integrity_correction_list.schema.jsonconfig1.8 KB
_shared/contracts/revision/integrity_pass_receipt.schema.jsonconfig809 B
_shared/contracts/revision/revision_evidence_bundle.schema.jsonconfig4.9 KB
_shared/contracts/revision/revision_roadmap.schema.jsonconfig11.2 KB
_shared/contracts/submission/format_profile.example.yamlconfig971 B
_shared/contracts/submission/format_profile.schema.jsonconfig4.6 KB
_shared/contracts/submission/submission_verification_report.schema.jsonconfig10.3 KB
_shared/contracts/submission/venue_profile.schema.jsonconfig4.1 KB
_shared/contracts/writer/full.jsonconfig3.6 KB
_shared/cross_model_verification.mdmarkdown83.3 KB
_shared/description-original.mdmarkdown904 B
_shared/evals_lift_report.schema.jsonconfig5.0 KB
_shared/ground_truth_isolation_pattern.mdmarkdown16.0 KB
_shared/handoff_schemas.mdmarkdown96.9 KB
_shared/human_subjects_authority_registry.jsonconfig49.5 KB
_shared/mode_spectrum.mdmarkdown5.2 KB
_shared/model_tiering.mdmarkdown12.6 KB
_shared/output_language_pair.mdmarkdown7.7 KB
_shared/policy_data/nature_policy.mdmarkdown3.9 KB
_shared/prisma_trAIce_protocol.mdmarkdown10.2 KB
_shared/raise_framework.mdmarkdown7.5 KB
_shared/references/authority_content_coverage_advisory_protocol.mdmarkdown14.0 KB
_shared/references/claim_standing_candidate_ledger_protocol.mdmarkdown19.2 KB
_shared/references/claim_strength_ladder.mdmarkdown5.5 KB
_shared/references/cross_document_consistency_advisory_protocol.mdmarkdown13.5 KB
_shared/references/evidence_row_protocol.mdmarkdown14.4 KB
_shared/references/firm_rules.mdmarkdown11.0 KB
_shared/references/human_subjects_authority_protocol.mdmarkdown13.1 KB
_shared/references/intent_clarification_protocol.mdmarkdown11.9 KB
_shared/references/irb_terminology_glossary.mdmarkdown12.4 KB
_shared/references/per_source_method_weaknesses.mdmarkdown4.2 KB
_shared/references/protected_hedging_phrases.mdmarkdown8.9 KB
_shared/references/psychometric_terminology_glossary.mdmarkdown8.7 KB
_shared/references/review_criteria_consumer_protocol.mdmarkdown10.3 KB
_shared/references/review_form_note.mdmarkdown11.3 KB
_shared/references/review_pathway_rule_trace_protocol.mdmarkdown8.3 KB
_shared/references/routing_core.mdmarkdown5.7 KB
_shared/references/submission_packet_manifest_protocol.mdmarkdown13.6 KB
_shared/references/word_count_conventions.mdmarkdown9.0 KB
_shared/research_workflow_profiles/field_general.jsonconfig1.2 KB
_shared/review_criteria_registry.jsonconfig11.5 KB
_shared/review_criteria_sources/msr-2027-technical-papers.2026-08-24.jsonconfig2.0 KB
_shared/review_criteria_sources/sigsoft-empirical-standards.2026-08-24.jsonconfig1.4 KB
_shared/sprint_contract.schema.jsonconfig19.0 KB
_shared/style_calibration_protocol.mdmarkdown6.9 KB
_shared/templates/codex_audit_multifile_template.mdmarkdown16.7 KB
agents/claim_ref_alignment_audit_agent.mdmarkdown45.0 KB
agents/collaboration_depth_agent.mdmarkdown10.4 KB
agents/integrity_verification_agent.mdmarkdown75.2 KB
agents/pipeline_orchestrator_agent.mdmarkdown175.5 KB
agents/state_tracker_agent.mdmarkdown27.4 KB
examples/full_pipeline_example.mdmarkdown17.7 KB
examples/integrity_failure_recovery.mdmarkdown26.8 KB
examples/mid_entry_example.mdmarkdown13.4 KB
references/adapters/.gitkeepother0 B
references/adapters/overview.mdmarkdown10.0 KB
references/ai_research_failure_modes.mdmarkdown16.3 KB
references/changelog.mdmarkdown6.4 KB
references/claim_audit_calibration_protocol.mdmarkdown14.9 KB
references/claim_verification_protocol.mdmarkdown31.1 KB
references/external_review_protocol.mdmarkdown6.8 KB
references/integrity_review_protocol.mdmarkdown7.8 KB
references/literature_corpus_consumers.mdmarkdown12.3 KB
references/mode_advisor.mdmarkdown8.7 KB
references/passport_as_reset_boundary.mdmarkdown19.3 KB
references/pipeline_state_machine.mdmarkdown29.0 KB
references/plagiarism_detection_protocol.mdmarkdown14.1 KB
references/process_summary_protocol.mdmarkdown16.4 KB
references/progress_dashboard_template.mdmarkdown2.1 KB
references/reinforcement_content.mdmarkdown2.0 KB
references/reproducibility_audit.mdmarkdown3.2 KB
references/score_trajectory_protocol.mdmarkdown4.5 KB
references/team_collaboration_protocol.mdmarkdown10.7 KB
references/two_stage_review_protocol.mdmarkdown3.6 KB
scripts/_claim_audit_constants.pyscript13.7 KB
scripts/_markdown_lint_util.pyscript9.0 KB
scripts/_next_verified_at_ms.pyscript6.5 KB
scripts/_skill_lint.pyscript13.6 KB
scripts/ars_anchorize_draft.pyscript5.8 KB
scripts/ars_apply_revision_patch.pyscript36.2 KB
scripts/ars_cache_invalidate.pyscript1.3 KB
scripts/ars_mark_read.pyscript18.2 KB
scripts/ars_write_scope_guard.pyscript30.9 KB
scripts/audit_snapshot.pyscript23.5 KB
scripts/bibliographic_integrity_signals.pyscript32.2 KB
scripts/build_claim_standing_candidate_ledger.pyscript54.3 KB
scripts/build_claim_standing_query_plan.pyscript25.0 KB

scripts/build_claim_standing_query_plan.py

View on GitHub
#!/usr/bin/env python3
"""Consent-surface builder for the #655 claim-standing probe (design §3.1/§3.2).

Turns one Phase E Claim Registry row plus explicit researcher decisions into
a schema-valid `claim-standing-query-plan/1.0` (retrieval_only) or `/1.1`
(retrieval_plus_stance) plan, or into an explicit local `not_checked`
declination record. The §3.1 trigger is exact: at Stage 2.5 the recorded
`HIGH-IMPACT` tier is the registry witness (`RANDOM`, `TOP-UP`, and
`NOT-SELECTED` are never eligible); at Stage 4.5 the `ALL` registry is not
permission — a row is eligible only with the recorded five-part high-impact
basis, and a basis-less row stays ineligible until the researcher confirms
the classification. A Stage 2.5 row whose registry recorded no basis stays
eligible by tier, but binding a plan still needs the basis, supplied through
the same recorded researcher confirmation; the basis provenance (registry
vs researcher confirmation) is displayed on the consent surface and never
written back to the registry.

Consent is bound before any dispatchable plan exists. `propose` renders the
closed §3.2 consent surface, which embeds the complete consentable-plan
projection (claim, queries, roster, filters, content classes, caps, stance
plan, creation time) — what is shown IS what the receipt later binds.
`bind` compares the decisions' surface hash against the exact current
surface: absence produces a `consent_absent` declination, any drift a
`consent_invalidated` declination, and an explicit cancel a
`consent_cancelled` declination — each an explicit local `not_checked`
record with no plan and no network or model call anywhere in the builder.
Eligibility, hashing, and final validation replay through the Track A
substrate (`build_claim_standing_candidate_ledger`). The builder never
mutates its inputs.
"""
from __future__ import annotations

import argparse
import copy
import json
import sys
from pathlib import Path
from typing import Any

try:
    from scripts import build_claim_standing_candidate_ledger as substrate
    from scripts import claim_standing_discovery as discovery
except ImportError:  # direct script execution
    sys.path.insert(0, str(Path(__file__).resolve().parent))
    import build_claim_standing_candidate_ledger as substrate  # noqa: E402
    import claim_standing_discovery as discovery  # noqa: E402

SURFACE_KIND = "claim-standing-consent-surface/1.0"
DECLINATION_KIND = "claim-standing-probe-declination/1.0"
QUERY_PLAN_SUFFIX = ".query-plan.json"
DECISION_VALUES = ("retrieval_only", "retrieval_plus_stance", "cancel")
SESSION_ONLY_EXPORT_BOUNDARY = (
    "No local export is authorized under session_only persistence."
)
ADVISORY_STATEMENT = (
    "The probe result is advisory, search-bounded, and fallible; it is not a "
    "gate, it never changes a Phase E verdict, checkpoint result, manuscript "
    "byte, citation, or read ledger, and absent results never prove absence. "
    "Every probe surface remains STANCE CLASSIFICATION UNMEASURED until the "
    "#655 baseline measurement row exists."
)
CONSENT_CHOICES = [
    "edit_or_redact_claim",
    "approve_retrieval_only",
    "approve_retrieval_plus_stance",
    "cancel",
]


class PlanBuilderError(Exception):
    """Fail-closed refusal: no plan may be constructed from these inputs."""


def _fail(message: str) -> None:
    raise PlanBuilderError(message)


def _require(condition: bool, message: str) -> None:
    if not condition:
        _fail(message)


def _valid_basis(values: Any, source: str) -> list[str]:
    _require(
        isinstance(values, list)
        and bool(values)
        and all(isinstance(item, str) for item in values),
        f"{source}: high_impact_basis must be a non-empty string list",
    )
    unknown = [
        item
        for item in values
        if item not in substrate.HIGH_IMPACT_BASIS_VALUES
    ]
    if unknown:
        _fail(f"{source}: unknown high_impact_basis token {unknown[0]!r}")
    _require(
        len(set(values)) == len(values),
        f"{source}: high_impact_basis tokens must be unique",
    )
    return list(values)


def _confirmed_basis(confirmation: dict[str, Any]) -> list[str]:
    _require(
        confirmation.get("confirmed_high_impact") is True,
        "eligibility confirmation must set confirmed_high_impact true",
    )
    _require(
        isinstance(confirmation.get("recorded_at"), str)
        and bool(confirmation["recorded_at"]),
        "eligibility confirmation must record recorded_at",
    )
    return _valid_basis(
        confirmation.get("high_impact_basis"), "eligibility confirmation"
    )


def assess_eligibility(
    registry_row: dict[str, Any], confirmation: dict[str, Any] | None = None
) -> dict[str, Any]:
    """Apply the §3.1 trigger to one Claim Registry row.

    The verdict never mutates the row. At Stage 2.5 the recorded HIGH-IMPACT
    tier alone is the eligibility witness; the plan's five-part basis then
    comes from the registry when recorded, otherwise from a recorded
    researcher confirmation. At Stage 4.5 a basis-less ALL row is ambiguous
    and stays ineligible until the researcher confirms the classification.
    A confirmation can supply a missing basis; it cannot override a wrong
    selection tier.
    """
    checkpoint = registry_row.get("checkpoint")
    _require(
        checkpoint in substrate.CHECKPOINT_REQUIRED_TIER,
        f"checkpoint must be stage_2_5 or stage_4_5, got {checkpoint!r}",
    )
    tier = registry_row.get("registry_selection_tier")
    reasons: list[str] = []
    required_tier = substrate.CHECKPOINT_REQUIRED_TIER[checkpoint]
    if tier != required_tier:
        reasons.append(
            f"registry_selection_tier {tier!r} is not probe-eligible at "
            f"{checkpoint} (requires {required_tier!r}; RANDOM, TOP-UP, and "
            "NOT-SELECTED rows are never eligible, and ALL is not permission "
            "to probe every claim)"
        )
    recorded = registry_row.get("high_impact_basis")
    _require(
        recorded is None or isinstance(recorded, (list, tuple)),
        "registry row: high_impact_basis must be a list when present",
    )
    basis: list[str] = []
    basis_source: str | None = None
    requires_confirmation = False
    if not reasons:
        if recorded:
            basis = _valid_basis(list(recorded), "registry row")
            basis_source = "registry"
        elif confirmation is not None:
            basis = _confirmed_basis(confirmation)
            basis_source = "researcher_confirmation"
        else:
            requires_confirmation = True
            if checkpoint == "stage_4_5":
                reasons.append(
                    "the registry row records no five-part high-impact basis; "
                    "at Stage 4.5 the row is ambiguous and stays ineligible "
                    "until the researcher confirms the classification"
                )
    return {
        "eligible": not reasons,
        "high_impact_basis": basis,
        "basis_source": basis_source,
        "reasons": reasons,
        "requires_confirmation": requires_confirmation,
        # A row is dispatchable only when nothing further is owed by the
        # researcher — consumers must never branch on `eligible` alone.
        "dispatchable": not reasons and not requires_confirmation,
    }


def _resolved_basis(
    registry_row: dict[str, Any], decisions: dict[str, Any]
) -> tuple[list[str], str, dict[str, Any] | None]:
    confirmation = decisions.get("eligibility_confirmation")
    verdict = assess_eligibility(registry_row, confirmation=confirmation)
    if not verdict["eligible"]:
        _fail("; ".join(verdict["reasons"]))
    if not verdict["high_impact_basis"]:
        _fail(
            "the registry row records no five-part high-impact basis; the "
            "researcher must confirm the classification "
            "(decisions.eligibility_confirmation) before a consent surface "
            "can bind one"
        )
    return (
        verdict["high_impact_basis"],
        verdict["basis_source"],
        confirmation if verdict["basis_source"] == "researcher_confirmation" else None,
    )


def _roster(decisions: dict[str, Any]) -> list[dict[str, Any]]:
    indexes = decisions.get("indexes")
    _require(
        isinstance(indexes, list) and 1 <= len(indexes) <= 4,
        "decisions.indexes must be a list naming 1..4 discovery indexes",
    )
    _require(
        len(set(indexes)) == len(indexes),
        "decisions.indexes must be unique",
    )
    defaults = discovery.provider_roster_defaults()
    unknown = [index_id for index_id in indexes if index_id not in defaults]
    if unknown:
        _fail(f"index {unknown[0]!r} is not a declared discovery adapter")
    return [defaults[index_id] for index_id in sorted(indexes)]


def _claim_text(registry_row: dict[str, Any]) -> str:
    claim_text = registry_row.get("claim_text")
    _require(
        isinstance(claim_text, str) and bool(claim_text.strip()),
        "registry row must carry non-empty claim_text",
    )
    return claim_text


def _queries(
    registry_row: dict[str, Any], decisions: dict[str, Any]
) -> list[dict[str, Any]]:
    claim_text = _claim_text(registry_row)
    derived = substrate.exact_claim_query(claim_text)
    claim_sha = substrate.text_digest(claim_text)
    supplied = decisions.get("queries")
    if supplied is None:
        default = decisions.get("default_query")
        _require(
            isinstance(default, dict),
            "decisions.default_query is required when no queries are supplied",
        )
        supplied = [
            {
                "query_id": default.get("query_id", "q1"),
                "accepted_query_text": derived,
                "construction": "exact_claim",
                "language": default.get("language"),
                "date_filter": default.get("date_filter"),
                "index_targets": default.get(
                    "index_targets", sorted(decisions.get("indexes") or [])
                ),
            }
        ]
    _require(
        isinstance(supplied, list) and 1 <= len(supplied) <= 3,
        "decisions.queries must be a list of 1..3 queries when present "
        "(an explicit empty or non-list value is refused, never defaulted)",
    )
    queries: list[dict[str, Any]] = []
    for entry in supplied:
        _require(isinstance(entry, dict), "each query must be an object")
        construction = entry.get("construction")
        if construction == "assisted_then_researcher_approved":
            _fail(
                "assisted_then_researcher_approved is a future optional "
                "planner mode; this builder does not authorize it (design "
                "§4.1)"
            )
        _require(
            construction in ("exact_claim", "researcher_authored"),
            f"unknown query construction {construction!r}",
        )
        accepted = entry.get("accepted_query_text")
        _require(
            isinstance(accepted, str) and bool(accepted.strip()),
            "accepted_query_text must be non-empty",
        )
        if construction == "exact_claim":
            _require(
                accepted == derived,
                "an exact_claim query may only strip ARS citation markers and "
                "collapse ASCII whitespace; edited text must be declared "
                "researcher_authored",
            )
            original = derived
        else:
            original = entry.get("original_query_text", accepted)
        queries.append(
            {
                "query_id": entry.get("query_id"),
                "original_query_text": original,
                "accepted_query_text": accepted,
                "construction": construction,
                "source_claim_sha256": claim_sha,
                "language": entry.get("language"),
                "date_filter": entry.get("date_filter"),
                "index_targets": list(entry.get("index_targets") or []),
                "query_sha256": substrate.text_digest(accepted),
            }
        )
    return queries


def _stance_plan(decisions: dict[str, Any]) -> dict[str, Any] | None:
    decision = decisions.get("decision")
    _require(
        decision in DECISION_VALUES,
        f"decision must be one of {DECISION_VALUES}, got {decision!r}",
    )
    if decision != "retrieval_plus_stance":
        return None
    stance_plan = decisions.get("stance_plan")
    _require(
        isinstance(stance_plan, dict),
        "retrieval_plus_stance requires an explicit stance_plan naming the "
        "exact provider and model",
    )
    return copy.deepcopy(stance_plan)


def _explicit_string_list(decisions: dict[str, Any], field: str) -> list[str]:
    values = decisions.get(field)
    _require(
        isinstance(values, list)
        and bool(values)
        and all(isinstance(item, str) for item in values),
        f"decisions.{field} must be a non-empty string list (an explicit "
        "falsey or wrong-type value is refused, never defaulted)",
    )
    return list(values)


def _draft_plan(
    registry_row: dict[str, Any], decisions: dict[str, Any]
) -> tuple[dict[str, Any], dict[str, Any] | None, str, dict[str, Any] | None]:
    """Everything of the future plan except the consent block and plan hash."""
    basis, basis_source, confirmation = _resolved_basis(registry_row, decisions)
    stance_plan = _stance_plan(decisions)
    version = (
        substrate.PLAN_VERSION_1_1 if stance_plan else substrate.PLAN_VERSION
    )
    draft: dict[str, Any] = {
        "schema_version": version,
        "probe_id": decisions.get("probe_id"),
        "claim": {
            "checkpoint": registry_row.get("checkpoint"),
            "claim_id": registry_row.get("claim_id"),
            "claim_text": _claim_text(registry_row),
            "claim_sha256": substrate.text_digest(_claim_text(registry_row)),
            "registry_selection_tier": registry_row.get(
                "registry_selection_tier"
            ),
            "high_impact_basis": basis,
            "eligibility_confirmed_by_researcher": True,
        },
        "queries": _queries(registry_row, decisions),
        "provider_roster": _roster(decisions),
        "allowed_languages": _explicit_string_list(
            decisions, "allowed_languages"
        ),
        "allowed_document_types": _explicit_string_list(
            decisions, "allowed_document_types"
        ),
        "authorized_content_classes": list(
            substrate.STANCE_CONTENT_CLASSES
            if stance_plan
            else substrate.RETRIEVAL_ONLY_CONTENT_CLASSES
        ),
        "caps": dict(substrate.CAPS),
        "created_at": decisions.get("created_at"),
    }
    if version == substrate.PLAN_VERSION_1_1:
        draft["stance_plan"] = stance_plan
    return draft, stance_plan, basis_source, confirmation


def build_consent_surface(
    registry_row: dict[str, Any], decisions: dict[str, Any]
) -> dict[str, Any]:
    """The closed §3.2 consent receipt content, shown before any acceptance.

    Embeds the complete consentable-plan projection of the plan `bind` would
    construct from the same inputs, so the surface digest covers every field
    the consent receipt later binds.
    """
    return _surface_from_draft(
        *_draft_plan(registry_row, decisions), decisions
    )


def _surface_from_draft(
    draft: dict[str, Any],
    stance_plan: dict[str, Any] | None,
    basis_source: str,
    confirmation: dict[str, Any] | None,
    decisions: dict[str, Any],
) -> dict[str, Any]:
    local_persistence = decisions.get("local_persistence")
    _require(
        local_persistence in ("session_only", "explicit_local_export"),
        "local_persistence must be session_only or explicit_local_export",
    )
    authorized_output_path = decisions.get("authorized_output_path")
    if local_persistence == "explicit_local_export":
        _require(
            isinstance(authorized_output_path, str)
            and not authorized_output_path.endswith(("/", "\\")),
            "authorized_output_path must not end with a path separator: "
            "derived artifact names would become hidden dotfiles",
        )
    constructions = {
        query["construction"] for query in draft["queries"]
    }
    claim_display = dict(draft["claim"])
    claim_display["high_impact_basis_source"] = basis_source
    if confirmation is not None:
        claim_display["basis_confirmation_recorded_at"] = confirmation[
            "recorded_at"
        ]
    return {
        "surface_kind": SURFACE_KIND,
        "probe_id": draft["probe_id"],
        "checkpoint": draft["claim"]["checkpoint"],
        "claim": claim_display,
        "queries": draft["queries"],
        "providers": draft["provider_roster"],
        "consentable_plan": substrate.consentable_plan_projection(draft),
        "query_transmission": {
            "exact_claim_text": "exact_claim" in constructions,
            "researcher_edited_query": "researcher_authored" in constructions,
        },
        "caps": draft["caps"],
        "llm_transmission": {
            "abstracts_to_llm": bool(
                stance_plan and stance_plan.get("abstracts_to_llm_authorized")
            ),
            "session_held_full_text_to_llm": bool(
                stance_plan
                and stance_plan.get("session_held_full_text_to_llm_authorized")
            ),
        },
        "stance_provider": (
            {
                "provider_identity": stance_plan["provider_identity"],
                "model_identity": stance_plan["model_identity"],
            }
            if stance_plan
            else None
        ),
        "stance_retention": (
            {
                "retention_state": stance_plan["retention_state"],
                "retention_reference": stance_plan["retention_reference"],
            }
            if stance_plan
            else None
        ),
        "local_persistence": local_persistence,
        "authorized_output_path": authorized_output_path,
        "derived_artifact_suffixes": dict(substrate.ARTIFACT_SUFFIXES),
        "deletion_boundary": decisions.get("deletion_boundary"),
        "export_boundary": (
            substrate.EXPLICIT_LOCAL_EXPORT_BOUNDARY
            if local_persistence == "explicit_local_export"
            else SESSION_ONLY_EXPORT_BOUNDARY
        ),
        "advisory_statement": ADVISORY_STATEMENT,
        "choices": list(CONSENT_CHOICES),
    }


def consent_surface_sha256(surface: dict[str, Any]) -> str:
    return substrate.digest(surface)


def _declination(
    registry_row: dict[str, Any], decisions: dict[str, Any], reason: str
) -> dict[str, Any]:
    recorded_at = decisions.get("recorded_at") or decisions.get("accepted_at")
    _require(
        isinstance(recorded_at, str) and bool(recorded_at),
        "a declination must record recorded_at (or carry accepted_at)",
    )
    claim_text = _claim_text(registry_row)
    return {
        "record_kind": DECLINATION_KIND,
        "probe_id": decisions.get("probe_id"),
        "checkpoint": registry_row.get("checkpoint"),
        "claim_id": registry_row.get("claim_id"),
        "claim_sha256": substrate.text_digest(claim_text),
        "status": "not_checked",
        "reason": reason,
        "recorded_at": recorded_at,
        "network_calls": "none",
        "model_calls": "none",
    }


def bind_plan(
    registry_row: dict[str, Any], decisions: dict[str, Any]
) -> dict[str, Any]:
    """Bind researcher acceptance to the exact proposed consent surface.

    Returns the schema-valid plan, or an explicit `not_checked` declination
    record: `consent_absent` when no surface hash was supplied,
    `consent_invalidated` when the supplied hash does not match the exact
    current surface (claim edit, filter change, provider change, cap change,
    persistence change), and `consent_cancelled` on an explicit cancel.
    Never mutates its inputs; performs no network or model call.
    """
    # An explicit cancel is a refusal of consent, not an acceptance to
    # verify: it needs no surface hash and is recorded before any binding
    # comparison (a proposed retrieval_plus_stance surface followed by a
    # cancel must record consent_cancelled, never consent_invalidated).
    if decisions.get("decision") == "cancel":
        return _declination(registry_row, decisions, "consent_cancelled")
    draft, stance_plan, basis_source, confirmation = _draft_plan(
        registry_row, decisions
    )
    surface = _surface_from_draft(
        draft, stance_plan, basis_source, confirmation, decisions
    )
    supplied_hash = decisions.get("consent_surface_sha256")
    if supplied_hash is None:
        return _declination(registry_row, decisions, "consent_absent")
    if supplied_hash != consent_surface_sha256(surface):
        return _declination(registry_row, decisions, "consent_invalidated")

    version = draft["schema_version"]
    consent: dict[str, Any] = {
        "consent_receipt_id": decisions.get("consent_receipt_id"),
        "decision": decisions["decision"],
        "accepted_at": decisions.get("accepted_at"),
        "claim_sha256": draft["claim"]["claim_sha256"],
        "provider_roster_sha256": substrate.digest(draft["provider_roster"]),
        "caps_sha256": substrate.digest(draft["caps"]),
        "queries_sha256": substrate.digest(draft["queries"]),
        "stance_classification_authorized": bool(stance_plan),
        "advisory_acknowledged": True,
        "search_bounded_acknowledged": True,
        "local_persistence": surface["local_persistence"],
        "provider_retention_disclosed": True,
        "deletion_boundary": surface["deletion_boundary"],
        "export_boundary": surface["export_boundary"],
        "authorized_output_path": surface["authorized_output_path"],
    }
    if version == substrate.PLAN_VERSION_1_1:
        consent["stance_plan_sha256"] = (
            substrate.digest(stance_plan) if stance_plan else None
        )
    plan = dict(draft)
    plan["consent"] = consent
    consent["consentable_plan_sha256"] = substrate.digest(
        substrate.consentable_plan_projection(plan)
    )
    _require(
        consent["consentable_plan_sha256"]
        == substrate.digest(surface["consentable_plan"]),
        "internal consistency failure: the bound consentable-plan projection "
        "does not equal the projection the accepted surface displayed",
    )
    consent["receipt_sha256"] = substrate.bound_digest(consent, "receipt_sha256")
    plan["plan_sha256"] = substrate.bound_digest(plan, "plan_sha256")
    try:
        substrate.validate_schema(
            plan, substrate.plan_schema_filename(plan), "query plan"
        )
        substrate.validate_plan(plan)
    except substrate.LedgerError as exc:
        raise PlanBuilderError(f"bound plan failed validation: {exc}") from exc
    return plan


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    commands = parser.add_subparsers(dest="command", required=True)
    for name, help_text in (
        ("propose", "print the consent surface and its binding digest"),
        ("bind", "bind an accepted consent surface into a query plan"),
    ):
        sub = commands.add_parser(name, help=help_text)
        sub.add_argument("--registry-claim", type=Path, required=True)
        sub.add_argument("--decisions", type=Path, required=True)
        if name == "bind":
            sub.add_argument(
                "--output",
                type=Path,
                default=None,
                help=(
                    "write the bound plan to the consent-derived path; "
                    "requires the receipt to say explicit_local_export. "
                    "Omit to print the plan for session-only use."
                ),
            )
    args = parser.parse_args(argv)
    try:
        registry_row = substrate.load_json(args.registry_claim)
        decisions = substrate.load_json(args.decisions)
        if args.command == "propose":
            surface = build_consent_surface(registry_row, decisions)
            print(
                json.dumps(
                    {
                        "consent_surface": surface,
                        "consent_surface_sha256": consent_surface_sha256(
                            surface
                        ),
                    },
                    ensure_ascii=False,
                    indent=2,
                )
            )
        else:
            result = bind_plan(registry_row, decisions)
            if result.get("record_kind") == DECLINATION_KIND:
                # Distinct status: a declination is neither a bound plan
                # (0) nor an assessment error (1).
                print(json.dumps(result, ensure_ascii=False, indent=2))
                return 3
            elif args.output is None:
                print(json.dumps(result, ensure_ascii=False, indent=2))
            else:
                authorized = substrate.require_export_consent(
                    result, args.output, QUERY_PLAN_SUFFIX
                )
                substrate.write_new_ledger(authorized, result)
                print(f"query plan written: {authorized}")
    except (
        PlanBuilderError,
        substrate.LedgerError,
        OSError,
        ValueError,
        KeyError,
        TypeError,
        AttributeError,
    ) as exc:
        print(f"QUERY-PLAN ERROR: {exc}", file=sys.stderr)
        return 1
    return 0


if __name__ == "__main__":
    sys.exit(main())
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 323kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall