diff --git a/README.md b/README.md index 085ef3f0b..4a42c68fc 100644 --- a/README.md +++ b/README.md @@ -155,14 +155,18 @@ dispatches ready DAG nodes with `program` dispatch mode. `decodex research compile` is the native Decodex research/design entrypoint. It accepts minimal natural-language intake or a structured research/design JSON packet, -then persists a `decodex.decision_contract/1` payload in local runtime SQLite. The -Decodex research method frames the question first, records evidence, compares -realistic options, forms a challenge-ready judgment, resolves skeptic objections, and -then ends as `decision_ready`, `not_decision_ready`, `blocked`, or -`needs_human_decision`. A compiled contract is latent and cannot queue work, mutate -tracker state, set goals, or authorize implementation. `decodex research promote` -records explicit acceptance for a stored contract; only promoted contracts may later -feed issue shaping or internal Execution Program readiness. +then persists a contract-first `decodex.decision_contract/1` payload in local runtime +SQLite. The Decodex research method frames the question first, records an evidence +ledger, compares realistic options, forms a challenge-ready judgment, resolves skeptic +objections, and then ends as `decision_ready`, `not_decision_ready`, `blocked`, or +`needs_human_decision`. New Decodex research may use `docs/research/` only for +JSON research artifacts, never the old `research-run/2` event-log shape; removed +legacy JSON runs are consolidated in +`docs/research/legacy-research-goal-audit.json`. A compiled contract is latent and +cannot queue work, mutate tracker state, set goals, or authorize implementation. +`decodex research promote` records explicit acceptance for a stored contract; only +promoted contracts may later feed issue shaping or internal Execution Program +readiness. `decodex intake goal` materializes a promoted Decision Contract. `--dry-run` prints the proposed normal Linear issues, dependencies, conflict domains, and dispatch plan @@ -390,8 +394,7 @@ The tracked workspace currently keeps: and content workflow lane - `docs/reference/` as the current repository and artifact surface map lane - `docs/decisions/` as the durable design-rationale lane -- `docs/research/` as legacy or supporting machine-authored research artifacts; current - Decodex research authority flows through runtime-local Decision Contracts +- `docs/research/` as supporting JSON research reports and evidence, not runtime authority - `dev/` as local development helpers outside `dev/skills/`, such as the operator dashboard mock server - `assets/` as generated Decodex App icon source notes, Icon Composer foreground, diff --git a/apps/decodex/src/loop_contract.rs b/apps/decodex/src/loop_contract.rs index 735dd1810..b44c92755 100644 --- a/apps/decodex/src/loop_contract.rs +++ b/apps/decodex/src/loop_contract.rs @@ -314,6 +314,8 @@ impl DecisionResearchProvenance { /// Non-authoritative research evidence retained before promotion. #[derive(Clone, Debug, Eq, PartialEq, Deserialize, Serialize)] pub(crate) struct DecisionResearchEvidence { + #[serde(default = "default_research_evidence_kind")] + kind: String, claim: String, support: String, #[serde(skip_serializing_if = "Option::is_none")] @@ -321,6 +323,7 @@ pub(crate) struct DecisionResearchEvidence { } impl DecisionResearchEvidence { fn validate(&self) -> Result<()> { + validate_required("decision contract research_evidence.kind", &self.kind)?; validate_required("decision contract research_evidence.claim", &self.claim)?; validate_required("decision contract research_evidence.support", &self.support)?; @@ -432,6 +435,8 @@ pub(crate) struct DecisionExecutionReadiness { #[serde(default)] proposed_issue_summaries: Vec, #[serde(default)] + promotion_targets: Vec, + #[serde(default)] conflict_domains: Vec, #[serde(default)] queue_intent: Vec, @@ -454,6 +459,10 @@ impl DecisionExecutionReadiness { &self.proposed_issue_summaries } + pub(crate) fn promotion_targets(&self) -> &[String] { + &self.promotion_targets + } + pub(crate) fn conflict_domains(&self) -> &[String] { &self.conflict_domains } @@ -482,6 +491,7 @@ impl DecisionExecutionReadiness { "decision contract proposed_issue_summaries", &self.proposed_issue_summaries, )?; + validate_string_list("decision contract promotion_targets", &self.promotion_targets)?; validate_string_list("decision contract conflict_domains", &self.conflict_domains)?; validate_string_list("decision contract queue_intent", &self.queue_intent)?; @@ -709,6 +719,10 @@ fn decision_contract_record_version() -> u16 { DECISION_CONTRACT_RECORD_VERSION } +fn default_research_evidence_kind() -> String { + String::from("unspecified") +} + fn validate_required(name: &str, value: &str) -> Result<()> { if value.trim().is_empty() { eyre::bail!("{name} must not be empty."); diff --git a/apps/decodex/src/research_design.rs b/apps/decodex/src/research_design.rs index 24ee97b39..0223ae337 100644 --- a/apps/decodex/src/research_design.rs +++ b/apps/decodex/src/research_design.rs @@ -84,6 +84,8 @@ pub(crate) struct ResearchDesignRunInput { #[serde(default)] proposed_issue_summaries: Vec, #[serde(default)] + promotion_targets: Vec, + #[serde(default)] conflict_domains: Vec, #[serde(default)] queue_intent: Vec, @@ -122,6 +124,7 @@ impl ResearchDesignRunInput { validation_expectations: Vec::new(), risk_notes: Vec::new(), proposed_issue_summaries: Vec::new(), + promotion_targets: Vec::new(), conflict_domains: Vec::new(), queue_intent: Vec::new(), private_evidence_refs: Vec::new(), @@ -157,6 +160,8 @@ impl ResearchProvenanceInput { #[derive(Clone, Debug, Eq, PartialEq, Deserialize, Serialize)] #[serde(deny_unknown_fields)] pub(crate) struct ResearchEvidenceInput { + #[serde(default = "default_input_evidence_kind")] + kind: String, claim: String, support: String, #[serde(skip_serializing_if = "Option::is_none")] @@ -165,6 +170,7 @@ pub(crate) struct ResearchEvidenceInput { impl ResearchEvidenceInput { fn normalized(self) -> Result { Ok(Self { + kind: normalize_required_text("evidence.kind", self.kind)?, claim: normalize_required_text("evidence.claim", self.claim)?, support: normalize_required_text("evidence.support", self.support)?, source_ref: normalize_optional_text("evidence.source_ref", self.source_ref)?, @@ -308,6 +314,7 @@ pub(crate) struct ResearchDesignRunReport { pub(crate) missing_decisions: Vec, pub(crate) blockers: Vec, pub(crate) proposed_issue_summaries: Vec, + pub(crate) promotion_targets: Vec, pub(crate) conflict_domains: Vec, pub(crate) private_evidence_ref_count: usize, pub(crate) public_projection_ref_count: usize, @@ -332,6 +339,7 @@ impl ResearchDesignRunReport { .execution_readiness() .proposed_issue_summaries() .to_vec(), + promotion_targets: contract.execution_readiness().promotion_targets().to_vec(), conflict_domains: contract.execution_readiness().conflict_domains().to_vec(), private_evidence_ref_count: input.private_evidence_refs.len(), public_projection_ref_count: input.public_projection_refs.len(), @@ -385,6 +393,7 @@ struct NormalizedResearchDesignInput { validation_expectations: Vec, risk_notes: Vec, proposed_issue_summaries: Vec, + promotion_targets: Vec, conflict_domains: Vec, queue_intent: Vec, private_evidence_refs: Vec, @@ -452,6 +461,7 @@ impl NormalizedResearchDesignInput { "proposed_issue_summaries", input.proposed_issue_summaries, )?, + promotion_targets: normalize_text_list("promotion_targets", input.promotion_targets)?, conflict_domains: normalize_text_list("conflict_domains", input.conflict_domains)?, queue_intent: normalize_text_list("queue_intent", input.queue_intent)?, private_evidence_refs: input @@ -484,6 +494,9 @@ impl NormalizedResearchDesignInput { if self.evidence.is_empty() { eyre::bail!("decision-ready research requires at least one evidence claim."); } + if self.evidence.iter().any(|evidence| evidence.kind == "unspecified") { + eyre::bail!("decision-ready research requires an evidence kind for each claim."); + } if self.options.is_empty() { eyre::bail!("decision-ready research requires at least one option comparison."); } @@ -500,6 +513,9 @@ impl NormalizedResearchDesignInput { "decision-ready research requires at least one proposed issue summary for downstream shaping." ); } + if self.promotion_targets.is_empty() { + eyre::bail!("decision-ready research requires at least one promotion target."); + } if !self.unresolved_decisions.is_empty() || !self.evidence_gaps.is_empty() { eyre::bail!( "decision-ready research cannot carry unresolved decisions or evidence gaps." @@ -696,6 +712,7 @@ fn build_decision_contract( "validation_expectations": input.validation_expectations, "risk_notes": risk_notes(input), "proposed_issue_summaries": input.proposed_issue_summaries, + "promotion_targets": input.promotion_targets, "conflict_domains": input.conflict_domains, "queue_intent": queue_intent(input), }, @@ -764,6 +781,7 @@ fn research_evidence_json(input: &NormalizedResearchDesignInput) -> Vec { .iter() .map(|item| { serde_json::json!({ + "kind": item.kind, "claim": item.claim, "support": item.support, "source_ref": item.source_ref, @@ -871,6 +889,10 @@ fn default_feedback(outcome: ResearchDesignOutcome) -> &'static str { } } +fn default_input_evidence_kind() -> String { + String::from("unspecified") +} + fn generated_contract_id(input: &ResearchDesignRunInput) -> Result { let slug = intent_slug(&input.intent); let encoded = serde_json::to_vec(input)?; @@ -954,6 +976,7 @@ mod tests { summary: String::from("Research output is latent until accepted or promoted."), }], evidence: vec![ResearchEvidenceInput { + kind: String::from("repo_source"), claim: String::from("Decision-ready research can shape downstream issues."), support: String::from( "The compiler carries objectives, validation expectations, and issue summaries.", @@ -993,6 +1016,7 @@ mod tests { proposed_issue_summaries: vec![String::from( "Wire natural-language research trigger into Decodex plugin surface.", )], + promotion_targets: vec![String::from("plugins/decodex/skills")], conflict_domains: vec![String::from("runtime")], queue_intent: Vec::new(), private_evidence_refs: vec![ResearchPrivateEvidenceRefInput { @@ -1060,6 +1084,35 @@ mod tests { }; assert!(missing_validation_error.to_string().contains("requires validation expectations")); + + let mut missing_evidence_kind = decision_ready_input(); + + missing_evidence_kind.evidence[0].kind = String::from("unspecified"); + + let missing_evidence_kind_error = + match research_design::compile_research_design_run(missing_evidence_kind, "decodex") { + Ok(_) => panic!("decision-ready research should require evidence kinds"), + Err(error) => error, + }; + + assert!(missing_evidence_kind_error.to_string().contains("requires an evidence kind")); + + let mut missing_promotion_target = decision_ready_input(); + + missing_promotion_target.promotion_targets.clear(); + + let missing_promotion_target_error = + match research_design::compile_research_design_run(missing_promotion_target, "decodex") + { + Ok(_) => panic!("decision-ready research should require a promotion target"), + Err(error) => error, + }; + + assert!( + missing_promotion_target_error + .to_string() + .contains("requires at least one promotion target") + ); } #[test] @@ -1089,6 +1142,10 @@ mod tests { record.contract().execution_readiness().proposed_issue_summaries(), &[String::from("Wire natural-language research trigger into Decodex plugin surface.")] ); + assert_eq!( + record.contract().execution_readiness().promotion_targets(), + &[String::from("plugins/decodex/skills")] + ); assert!( store .list_linear_execution_events("decodex", "XY-860") diff --git a/docs/decisions/index.md b/docs/decisions/index.md index 77ed34b12..b5b6ea85b 100644 --- a/docs/decisions/index.md +++ b/docs/decisions/index.md @@ -26,6 +26,9 @@ Question this index answers: "why was it designed this way?" - [`decodex-plugin-source.md`](./decodex-plugin-source.md) records why this repository owns the canonical Decodex plugin and why generic Playbook guidance should only keep portable routing. +- [`mcp-capability-gateway-and-skill-slimming.md`](./mcp-capability-gateway-and-skill-slimming.md) + records why Decodex should introduce an MCP capability gateway while slimming + skills into static routing, authority, and safety entrypoints. - [`radar-control-plane-publisher.md`](./radar-control-plane-publisher.md) records the stable capability names for upstream Codex intelligence, retained-lane orchestration, and public publishing after the repository integration. diff --git a/docs/decisions/mcp-capability-gateway-and-skill-slimming.md b/docs/decisions/mcp-capability-gateway-and-skill-slimming.md new file mode 100644 index 000000000..d6ae67366 --- /dev/null +++ b/docs/decisions/mcp-capability-gateway-and-skill-slimming.md @@ -0,0 +1,179 @@ +# MCP Capability Gateway And Skill Slimming + +Status: decision_ready +Date: 2026-06-16 +Question: Should Decodex introduce MCP, and if so how should MCP, skills, docs, and +runtime authority divide responsibilities? +Decision: Build a Decodex MCP capability gateway and slim skills into static routing, +policy, and safety entrypoints. Keep runtime state authoritative in Decodex, expose +docs and runtime state through MCP resources, expose state-changing operations through +schema-bound MCP tools, expose reusable workflows through MCP prompts, and keep skills +small enough to route the agent to the right capability without embedding full docs or +runtime state. +Consequences: Skills lose bulk instructional content and become stable policy +wrappers. Docs stay authoritative and can be fetched as resources. Runtime actions stay +typed, auditable, and authority-checked. Decodex can evolve capability surfaces without +reinstalling large skill text. + +## Decision Contract Snapshot + +Source intent: Evaluate whether Decodex should introduce MCP, whether MCP enables +skill slimming, and what the strongest architecture should be. + +Terminal status: `decision_ready` + +Promotion targets: + +- `docs/decisions`: this rationale record. +- `docs/spec/loop-runtime.md`: research method and Decision Contract authority rules. +- `plugins/decodex/skills/research*/`: slim, contract-first research routing. +- Future runtime issue: MCP server implementation, only after explicit promotion. + +Selected option: Hybrid Decodex MCP capability gateway plus thin skills. + +Non-goals: + +- Do not make MCP the source of Decodex truth. +- Do not replace checked-in docs with generated MCP-only content. +- Do not let MCP tools bypass Decision Contract, Authority Envelope, validation, or + identity routing. +- Do not keep large method bodies inside every skill when docs/resources can supply + them on demand. + +## Evidence Ledger + +| Kind | Evidence | Source | +| --- | --- | --- | +| `external_source` | The latest official MCP spec is `2025-11-25`; it defines MCP as a JSON-RPC protocol where hosts connect through clients to servers that provide context and capabilities. | [MCP specification 2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25) | +| `external_source` | MCP separates server features into resources for context/data, prompts for templated workflows, and tools for executable functions. That maps cleanly to Decodex docs, reusable workflows, and state-changing runtime operations. | [MCP specification 2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25) | +| `external_source` | Resources are application-driven and addressed by URI; servers can list, read, template, subscribe, and notify resource changes. Decodex docs, Decision Contracts, status snapshots, and skill references fit this model better than skill-embedded text. | [MCP resources](https://modelcontextprotocol.io/specification/2025-11-25/server/resources) | +| `external_source` | Tools are model-invoked executable functions and can return structured content with output schemas; MCP guidance expects user consent and visible authorization for tool invocations. Decodex mutating operations belong here, with authority checks. | [MCP tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools) | +| `external_source` | Prompts are user-controlled templates discoverable from the server. Decodex research, promotion, validation, and handoff workflows can become prompts instead of large skill bodies. | [MCP prompts](https://modelcontextprotocol.io/specification/2025-11-25/server/prompts) | +| `external_source` | MCP standard transports are stdio and Streamable HTTP. Local Decodex should start with stdio for desktop/CLI use and add Streamable HTTP only when the local daemon or app needs multi-client access. | [MCP transports](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) | +| `external_source` | MCP authorization is optional, but HTTP transports that support authorization should follow the spec; stdio should retrieve credentials from environment rather than the HTTP auth flow. | [MCP authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) | +| `repo_source` | Decodex already treats runtime-local `decodex.decision_contract/1` payloads as research authority and keeps research latent until promotion. | [`docs/spec/loop-runtime.md`](../spec/loop-runtime.md) | +| `repo_source` | The repository documentation policy requires durable guidance to live in `docs/spec`, `docs/runbook`, `docs/reference`, or `docs/decisions`; `docs/research/` is JSON supporting evidence, not governing authority. | [`docs/policy.md`](../policy.md) | +| `inference` | Because MCP resources can expose docs/current state on demand, skills should not duplicate long reference bodies. Because MCP tools can mutate external state, skills must still carry authority routing and safety triggers. | Derived from MCP resource/tool controls plus Decodex authority model. | + +## Options + +| Option | Decision | Reason | +| --- | --- | --- | +| Keep skills-only architecture | Rejected | Skills are good at static routing but poor at fresh state, structured readback, typed mutation, and external source freshness. Large skills also increase token load and drift. | +| Replace skills with MCP-only architecture | Rejected | MCP can expose capabilities, but it does not by itself teach the agent when a Decodex authority boundary applies. A small skill layer is still the right installable policy surface. | +| Build a hybrid MCP gateway and slim skills | Selected | MCP owns dynamic resources, prompts, and tools; skills own trigger routing, safety boundaries, and progressive disclosure. This uses each surface for the behavior it is best at. | +| Remote HTTP MCP first | Deferred | Streamable HTTP is useful for app/server integration, but local stdio is simpler for first implementation and avoids premature auth and multi-client complexity. | + +## Architecture + +```mermaid +flowchart TD + U["User / Codex thread"] --> S["Thin Decodex skills"] + S --> P["MCP prompts: research, promote, validate, handoff"] + S --> R["MCP resources: docs, contracts, status, skill refs"] + S --> T["MCP tools: compile, promote, status, intake, lane controls"] + R --> D["Checked-in docs"] + R --> DB["Runtime SQLite"] + T --> C["Decodex Rust runtime"] + C --> DB + C --> L["Linear/GitHub/local worktrees"] + P --> S +``` + +Layer responsibilities: + +- Decodex Rust runtime is the source of truth for state, contracts, queue readiness, + lane lifecycle, and authority checks. +- MCP gateway is the typed capability facade over runtime and docs. +- Skills are the small policy pack that decides when to read resources, call tools, or + stop for human authority. +- Docs remain the durable source for contracts, runbooks, reference maps, and design + rationale. +- Eval/harness gates verify that skill slimming did not remove required routing, + safety, or evidence behavior. + +## MCP Surface + +Resources: + +- `decodex://docs/index` +- `decodex://docs/spec/{topic}` +- `decodex://docs/runbook/{topic}` +- `decodex://docs/reference/{topic}` +- `decodex://docs/decisions/{topic}` +- `decodex://skills/{skill_name}` +- `decodex://decision-contracts/{contract_id}` +- `decodex://projects/{service_id}/status` +- `decodex://projects/{service_id}/agent-evidence/{issue_id}` + +Prompts: + +- `decodex_research`: starts contract-first bounded research. +- `decodex_arrange_accepted_research`: promotes accepted research into planning. +- `decodex_validation_ready`: runs a validation-ready lane to its native gate and + stops. +- `decodex_handoff`: produces a human-readable handoff after verification. + +Tools: + +- `research_compile(input)`: validates evidence kinds, options, objections, + promotion targets, validation expectations, and writes a latent Decision Contract. +- `research_promote(contract_id, acceptance_source)`: records explicit acceptance and + refuses unresolved gaps. +- `status_live(service_id, limit)`: performs fresh runtime/tracker readback. +- `intake_goal_dry_run(contract_id)`: previews generated issues and Program nodes. +- `intake_goal_apply(contract_id)`: mutates only after accepted authority exists. +- `lane_control(action, issue_id, reason)`: pause, resume, scan, interrupt, or steer + inside existing lane-control policy. +- `docs_validate(paths)`: runs repo-native docs or surface checks when available. + +Tool rules: + +- Read-only tools may run without promotion when they only expose public-safe state. +- Mutating tools must require explicit authority and return structured results. +- Tools must not expose raw private evidence, credentials, transcript text, hidden + graph ids, or local paths unless the governing Decodex surface allows it. +- Every mutating result should include `status`, `authority_source`, `changed_surfaces`, + `validation_next_step`, and `public_projection`. + +## Skill Slimming Rules + +Keep in skills: + +- Trigger descriptions and routing order. +- Authority boundaries and refusal conditions. +- Which MCP resources or prompts to load. +- Which MCP tools are allowed for the phase. +- What evidence is required before claiming done, fixed, ready, or decision-ready. + +Move out of skills: + +- Long method bodies. +- Static docs that already live in `docs/`. +- Current runtime state. +- Large examples that can be exposed as resources. +- Repeated copies of specs, runbooks, and reference maps. + +Target shape: + +- One router skill for Decodex. +- Thin phase skills for research, planning, automation, commit, land, and labels. +- Shared method references either checked into docs or exposed as MCP resources. +- Eval gate for every slimming pass to catch broken trigger coverage, missing safety + boundaries, stale links, and token bloat. + +## Validation Expectations + +- `plugin-eval analyze` on changed research skills should find no critical routing, + safety, or progressive-disclosure issue. +- `cargo test -p decodex plugin_surface_tests research_design` should pass after + schema and packaged-skill changes. +- `git diff --check` should pass. +- Future MCP implementation should start read-only: resources plus status readback, + then add `research_compile`, then add mutating promotion/intake controls. + +## Open Follow-Up + +Implementation is intentionally not included here. The next promoted work should be +split into one read-only MCP gateway issue, one research compile/promote tool issue, +one skill-slimming eval issue, and one docs/resource validation issue. diff --git a/docs/index.md b/docs/index.md index 09356d6fe..1716f90a8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -50,6 +50,8 @@ The split below is by question type, not by human-versus-agent audience. - Need rationale for keeping execution-graph semantics internal behind a natural-language user surface -> `docs/decisions/natural-language-loop-runtime.md` +- Need rationale for Decodex MCP integration, MCP/skills/docs/runtime boundaries, or + skill slimming -> `docs/decisions/mcp-capability-gateway-and-skill-slimming.md` - Need the current Radar, Control Plane, and Publisher capability boundary -> `docs/decisions/radar-control-plane-publisher.md` - Need Radar raw-artifact retention, archive manifests, or GitHub Release archive @@ -57,10 +59,10 @@ The split below is by question type, not by human-versus-agent audience. `docs/runbook/radar-artifact-archive.md` - Need historical upstream commit trace, skipped-candidate state, or local Radar ledger behavior -> `docs/spec/radar-ledger.md` -- Need older machine-authored research run artifacts or supporting evidence trails -> - `docs/research/` -- Need new Decodex bounded research, design investigation, or research-to-execution - promotion -> `plugins/decodex/skills/research*/` and +- Need research reports, supporting research evidence, or the implemented/superseded + status of older machine-authored research targets -> `docs/reference/research-runs.md` +- Need new Decodex bounded research, design investigation, evidence ledger, or + research-to-execution promotion -> `plugins/decodex/skills/research*/` and `docs/spec/loop-runtime.md` - Need reusable agent-facing Decodex usage instructions -> `plugins/decodex/` - Need repo-local Radar skills for upstream Codex triage, code analysis, release @@ -92,6 +94,7 @@ The split below is by question type, not by human-versus-agent audience. - Start each document with a short routing header that says what the document is for, when to read it, and what it does not cover. - Keep links explicit and stable. -- Treat `docs/research/` as supporting evidence, not as a primary authority lane. +- Treat `docs/research/` as a JSON-only supporting research-report and evidence lane, + not as a primary authority lane or old event-log write target. - Treat Decodex research output as latent until accepted or promoted through the loop-runtime contract in `docs/spec/loop-runtime.md`. diff --git a/docs/policy.md b/docs/policy.md index 03d80fdd4..50cd55e39 100644 --- a/docs/policy.md +++ b/docs/policy.md @@ -26,20 +26,29 @@ This repository standardizes on four primary documentation lanes: - `runbook` defines procedure, not truth, current state, or rationale. - `reference` defines current state, not truth, procedure, or rationale. - `decisions` defines rationale, not truth, procedure, or current state. -- `docs/research/` is supporting evidence only. It does not own repository truth, - procedure, current state, or rationale. +- `docs/research/` is a JSON-only supporting research-report and evidence artifact + lane. It does not own repository truth, procedure, current state, rationale, or + runtime authority. - If a document starts answering a second question type, split it and link to the authoritative lane instead of stretching one document across lanes. ## Artifact lanes -- `docs/research/` is allowed for legacy or supporting machine-authored research run - artifacts. +- `docs/research/` may hold supporting JSON research reports and extracted evidence. +- Keep `docs/research/` internally uniform: tracked files under that directory must + be JSON research artifacts, not Markdown prose documents. +- Do not add new old-shape `research-run/2` event-log JSON files under + `docs/research/`. +- Removed legacy machine-authored JSON event logs are consolidated in + `docs/research/legacy-research-goal-audit.json`; use Git history only for raw event + log provenance. - `docs/research/` is not a primary documentation lane and is not authoritative for runtime behavior, repository policy, or operator procedures. +- New Decodex bounded research belongs in runtime-local + `decodex.decision_contract/1` records until accepted and promoted. - If a research result becomes durable repository guidance, promote it into `spec`, - `runbook`, `reference`, or `decisions` and link back to the originating artifact only - as supporting evidence. + `runbook`, `reference`, or `decisions` and cite source provenance only as supporting + evidence. ## Placement rules diff --git a/docs/reference/index.md b/docs/reference/index.md index d8cf25ff6..9a1170f4c 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -9,7 +9,7 @@ Question this index answers: "how is it currently organized or implemented?" - You need the current repository layout, ownership boundaries, or where a topic lives. - You need to know which directory or file surface is authoritative for a class of work. -- You need to understand the role of machine-authored artifacts such as `docs/research/`. +- You need to understand where research reports and supporting evidence fit. ## Do not use this index when @@ -29,5 +29,5 @@ Question this index answers: "how is it currently organized or implemented?" and keep/merge/delete standards. - [`workspace-layout.md`](./workspace-layout.md) for the repository surface map and directory ownership boundaries, including the canonical Decodex plugin source. -- [`research-runs.md`](./research-runs.md) for the role and limits of `docs/research/` - artifacts. +- [`research-runs.md`](./research-runs.md) for the role and limits of the + `docs/research/` JSON research-report and evidence artifact lane. diff --git a/docs/reference/research-runs.md b/docs/reference/research-runs.md index 7509ca489..c8ec0df32 100644 --- a/docs/reference/research-runs.md +++ b/docs/reference/research-runs.md @@ -1,10 +1,12 @@ # Research Runs -Purpose: Explain the role of `docs/research/` artifacts in this repository and how they -relate to the primary documentation taxonomy. +Purpose: Explain the role of the `docs/research/` JSON research-report and evidence +artifact lane in this repository and how removed legacy JSON event logs relate to the +primary documentation taxonomy. -Read this when: You encounter `docs/research/.json` files and need to know -whether they are authoritative documentation, generated artifacts, or supporting +Read this when: You encounter a `docs/research/*.json` report, a reference to an old +`docs/research/.json` file in Git history, or need to know whether research +artifacts are authoritative documentation, generated artifacts, or supporting evidence. Not this document: The research method itself, the runtime contract, or a design @@ -15,16 +17,28 @@ results. ## Status of `docs/research/` -- `docs/research/` is the legacy persistence root for the earlier external research - tooling and remains a supporting evidence lane. -- Files in `docs/research/` are machine-authored run artifacts, not primary - documentation lanes. +- `docs/research/` is a supporting JSON research-report and evidence artifact lane. +- Tracked files under `docs/research/` must be JSON research artifacts, not Markdown + prose documents. +- The former `research-run/2` JSON files in `docs/research/` were machine-authored + run artifacts, not primary documentation lanes and not the new research shape. +- The tracked legacy JSON files were consolidated into + [`../research/legacy-research-goal-audit.json`](../research/legacy-research-goal-audit.json) + and removed from the tree. +- New Decodex bounded research must not use the old `research-run/2` event-log JSON + shape. +- A promoted or explicitly requested research report may live under `docs/research/` + when it is a JSON research artifact and supporting evidence rather than governing + policy. - A research run may contain useful evidence, alternatives, and objections, but it does not by itself define repository truth. - For Decodex-specific loop-runtime work, the Decodex `research*` skills plus - `decodex research compile` supersede this artifact lane as the runtime-owned path. - They store a `decodex.decision_contract/1` payload in local runtime SQLite and leave - the result latent until explicit promotion. + `decodex research compile` replace the old event-log JSON shape as the runtime-owned + path. They store a top-level `decodex.decision_contract/1` payload in local runtime + SQLite and leave the result latent until explicit promotion. +- A useful legacy run may be cited from Git history as `research_provenance` or + supporting `research_evidence` inside a Decision Contract, but the contract is the + current research output. ## Promotion rules @@ -38,12 +52,20 @@ results. conclusion into `docs/decisions/`. - If a Decodex-native research/design result should feed issue shaping or unattended execution, promote the stored Decision Contract first. Do not infer acceptance from - a research summary or from a `docs/research/` JSON artifact. + a research summary or from a legacy `docs/research/` JSON artifact. ## Practical reading rule -- Read `docs/research/` when you need an older evidence trail. +- Read [`../research/legacy-research-goal-audit.json`](../research/legacy-research-goal-audit.json) + when you need the current status of removed legacy research targets. +- Keep index and routing prose in this reference document, not inside `docs/research/`; + `docs/research/` itself stays limited to JSON research artifacts. +- Use Git history only when you need the raw old `research-run/2` event trail. - Read one of the four primary documentation lanes when you need current repository guidance. -- Use Decodex `research*` skills and Decision Contracts for new bounded Decodex +- Use Decodex `research*` skills and Decision Contracts for all new bounded Decodex research. +- Expect old `research-run/2` files to put the useful conclusion near the end of an + event log. Do not copy that shape into new research; new research must expose + terminal status, selected option, evidence ledger, gaps, validation, and promotion + target from the top-level contract. diff --git a/docs/reference/workspace-layout.md b/docs/reference/workspace-layout.md index 5613b977b..f515fa9de 100644 --- a/docs/reference/workspace-layout.md +++ b/docs/reference/workspace-layout.md @@ -30,7 +30,7 @@ should not be treated as repository source. | `docs/runbook/` | Operator procedures, validation sequences, deployment steps, and content workflows. | | `docs/reference/` | Current repository and artifact surface maps. | | `docs/decisions/` | Durable rationale for repository-level design choices. | -| `docs/research/` | Legacy or supporting machine-authored research run artifacts; current Decodex research authority is runtime-local Decision Contracts. | +| `docs/research/` | Supporting JSON research reports and evidence. It does not own runtime authority, policy, current-state reference, or durable rationale until promoted into the matching primary docs lane. | | `dev/` | Local development helpers outside `dev/skills/`, such as the operator dashboard mock server. | | `assets/` | Shared static assets that are not owned by the Astro app's generated output. Decodex App icons live under `assets/app-icon/{source,composer,generated}/`; menu bar template assets live under `assets/tray-icon/{source,generated}/`; `scripts/assets/render_decodex_app_icons.swift` regenerates the icon set. | | `.github/` | CI, release, Pages deployment, and content-refresh workflows. | @@ -160,8 +160,11 @@ tracker routing, and policy. - Reusable agent-facing Decodex usage instructions live under `plugins/decodex/`. - `docs/runbook/`, `docs/reference/`, and `docs/decisions/` must not override runtime or workflow authority. -- `docs/research/` is supporting evidence only. It does not become policy until its - conclusions are promoted into governing docs. +- `docs/research/` remains a supporting JSON report and evidence lane. Removed legacy JSON + event logs are consolidated in + [`../research/legacy-research-goal-audit.json`](../research/legacy-research-goal-audit.json). + Current Decodex runtime research authority still flows through runtime-local + Decision Contracts until accepted and promoted. ## Local-only and generated directories diff --git a/docs/research/2026-03-31_decodex-plan-boundary-v2.json b/docs/research/2026-03-31_decodex-plan-boundary-v2.json deleted file mode 100644 index f312ce1e4..000000000 --- a/docs/research/2026-03-31_decodex-plan-boundary-v2.json +++ /dev/null @@ -1,99 +0,0 @@ -{ - "schema": "research-run/2", - "run_id": "2026-03-31_decodex-plan-boundary-v2", - "question": "How should decodex handle plan-backed Linear issues while staying decoupled from plugin-specific contracts?", - "success_criteria": [ - "Clarify whether decodex should directly understand the plan plugin surface.", - "Identify the minimal stable surfaces decodex should depend on.", - "Identify the concrete conflict between the new single-issue plan authority pointer and decodex's current execution prompt input." - ], - "constraints": [ - "Keep decodex dependent only on Linear, GitHub, and Codex runtime surfaces.", - "Do not turn decodex into a consumer of plugin-private schemas by default.", - "Use repository-local evidence only for this bounded pass." - ], - "stop_rule": "Stop once the bounded pass either identifies one stable boundary shape or proves that a specific surface contract is still missing.", - "primary_hypothesis": "Decodex should remain plan-agnostic, and the current conflict comes from overloading the routed Linear issue body as both human task description and machine authority pointer.", - "rival_hypotheses": [ - "Decodex should parse and consume plan-authority or tracked-plan directly.", - "The current plan issue-body contract can coexist with decodex unchanged." - ], - "falsifiers": [ - "If decodex already consumes a generic execution surface that safely replaces issue.description, then the current conflict is overstated.", - "If the plan plugin can make the issue body machine-only without degrading decodex dispatch or operator comprehension, then the issue-body overload claim is false." - ], - "coverage": { - "mode": "standard", - "min_source_families": 0 - }, - "continuation": { - "mode": "stop", - "attempt": 1, - "max_attempts": 1 - }, - "events": [ - { - "seq": 1, - "type": "probe_completed", - "remaining_option_count": 1, - "independent_option_questions": [], - "external_slices": [] - }, - { - "type": "evidence_recorded", - "evidence": [ - { - "id": "E1", - "kind": "observation", - "source_family": "repo_code", - "summary": "Decodex currently builds its execution prompt by copying issue.description into the Description section for normal, review-repair, and delivery-closeout dispatch." - }, - { - "id": "E2", - "kind": "observation", - "source_family": "repo_docs", - "summary": "The updated plan plugin writing contract requires the routed Linear issue body to be exactly one fenced plan-authority/1 JSON block and explicitly forbids prose in that snapshot." - }, - { - "id": "E3", - "kind": "observation", - "source_family": "repo_docs", - "summary": "Decodex's documented plan-related boundary is currently negative only: saved plan phase=done never substitutes for explicit terminal finalization, but decodex does not otherwise consume plan-authority, tracked-plan, or plan-event contracts." - } - ], - "seq": 2 - }, - { - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T1", - "summary": "Making decodex parse plugin-private plan contracts would couple runtime orchestration to plugin method contracts and turn decodex into a second control plane.", - "supporting_evidence_ids": [ - "E3" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T2", - "summary": "Keeping decodex plan-agnostic while also replacing the issue body with a machine-only authority pointer leaves decodex without a stable human-readable task briefing surface.", - "supporting_evidence_ids": [ - "E1", - "E2" - ], - "disconfirming_evidence_ids": [] - } - ], - "seq": 3 - }, - { - "type": "finalized_not_decision_ready", - "reason": "The bounded pass confirms that decodex should stay plan-agnostic and identifies a real surface conflict, but it still lacks an explicit replacement contract for the stable human-readable execution briefing surface when a routed issue body becomes a machine-only plan pointer.", - "missing_evidence": [ - "An explicit repository contract for where decodex should read the human-readable execution briefing when the routed issue body is reserved for plan-authority/1.", - "A repository decision on whether plan-backed issues are eligible for direct decodex dispatch before Codex-side plan execution has materialized the current task." - ], - "seq": 4 - } - ] -} diff --git a/docs/research/2026-03-31_decodex-plan-boundary-v3.json b/docs/research/2026-03-31_decodex-plan-boundary-v3.json deleted file mode 100644 index f45e30f49..000000000 --- a/docs/research/2026-03-31_decodex-plan-boundary-v3.json +++ /dev/null @@ -1,320 +0,0 @@ -{ - "schema": "research-run/2", - "run_id": "2026-03-31_decodex-plan-boundary-v3", - "question": "How should decodex handle plan-backed Linear issues while staying decoupled from plugin-specific contracts?", - "success_criteria": [ - "Choose a stable execution-briefing surface that lets decodex stay plan-agnostic.", - "Compare at least two realistic design options for where the human-readable task briefing should live.", - "Produce a bounded recommendation that preserves the Linear + GitHub + Codex dependency boundary." - ], - "constraints": [ - "Keep decodex dependent only on Linear, GitHub, and Codex runtime surfaces.", - "Do not require decodex to parse plugin-private plan contracts by default.", - "Use repository-local evidence for the bounded pass." - ], - "stop_rule": "Stop once one option is recommendation-worthy under the current evidence or the bounded pass proves that no safe choice is ready.", - "primary_hypothesis": "The right design is to keep decodex plan-agnostic and move the machine plan pointer away from the only surface that decodex currently uses as a human-readable execution briefing.", - "rival_hypotheses": [ - "Decodex should read the linked tracked-plan surface directly when a routed issue is plan-backed.", - "Plan-backed issues should remain ineligible for direct decodex dispatch until a Codex-side step materializes a generic current-task surface." - ], - "falsifiers": [ - "If a decodex-safe human-readable briefing can be derived from the existing plan-linked document without making decodex understand plan-private schemas, the current conflict may be solvable without moving the pointer.", - "If moving the pointer off the issue body creates worse coordination failure than teaching decodex a generic linked-document briefing read, the plan-agnostic recommendation is too strict." - ], - "coverage": { - "mode": "standard", - "min_source_families": 0 - }, - "continuation": { - "mode": "stop", - "attempt": 1, - "max_attempts": 1 - }, - "events": [ - { - "seq": 1, - "type": "probe_completed", - "remaining_option_count": 3, - "independent_option_questions": [ - "Which surface should carry the stable human-readable execution briefing when a routed issue also carries machine plan authority?", - "Which option preserves decodex's runtime boundary best while minimizing workflow churn for Linear-backed planning?" - ], - "external_slices": [] - }, - { - "type": "evidence_recorded", - "evidence": [ - { - "id": "E1", - "kind": "observation", - "source_family": "repo_code", - "summary": "Decodex currently builds its execution prompt by copying issue.description into the Description section for normal, review-repair, and delivery-closeout dispatch." - }, - { - "id": "E2", - "kind": "observation", - "source_family": "repo_docs", - "summary": "The updated plan plugin writing contract requires the routed Linear issue body to be exactly one fenced plan-authority/1 JSON block and explicitly forbids prose in that snapshot." - }, - { - "id": "E3", - "kind": "observation", - "source_family": "repo_docs", - "summary": "Decodex's current documented plan boundary only says that saved plan phase=done cannot replace explicit terminal finalization; it does not otherwise consume plan-authority, tracked-plan, or plan-event contracts." - } - ], - "seq": 2 - }, - { - "type": "worker_completed", - "worker": "analyst", - "summary": "Preferred option A. It keeps decodex plan-agnostic and preserves the existing human-readable issue briefing path, while B risks turning generic linked-document reads into de facto plan parsing and C adds dispatch gating and materialization friction.", - "seq": 3, - "target_inventory_seq": 1 - }, - { - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T1", - "summary": "Option A preserves the cleanest boundary because decodex can continue to rely on a human-readable issue brief and never consume plugin-private plan schemas.", - "supporting_evidence_ids": [ - "E1", - "E3" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T2", - "summary": "Option A has the highest migration cost because the current plan plugin contract hard-codes the issue body as the authority pointer surface.", - "supporting_evidence_ids": [ - "E2" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T3", - "summary": "Option B appears cheaper, but it weakens the boundary because a generic linked-document briefing read risks becoming de facto parsing of plan-owned structure.", - "supporting_evidence_ids": [ - "E1", - "E2", - "E3" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T4", - "summary": "Option C keeps decodex decoupled but adds dispatch gating and a second materialization surface before normal decodex execution can begin.", - "supporting_evidence_ids": [ - "E1", - "E2" - ], - "disconfirming_evidence_ids": [] - } - ], - "seq": 4 - }, - { - "type": "judgment_candidate_created", - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "A_move_machine_pointer_off_issue_body", - "rejected_options": [ - "B_generic_linked_document_briefing_read_in_decodex", - "C_make_plan_backed_issues_ineligible_until_materialized" - ], - "decision_claim": "Keep decodex plan-agnostic and move the machine plan pointer off the routed issue body, preserving a stable human-readable issue description or equivalent generic issue briefing surface for decodex dispatch.", - "key_evidence_ids": [ - "E1", - "E2", - "E3" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T4" - ] - }, - "seq": 5, - "judgment_hash": "sha256:e413dcbbac1ed9f12c4cf3d6449a1ec895c71de715092e8f6d723711e2e288e7" - }, - { - "type": "worker_completed", - "worker": "skeptic", - "summary": "The judgment survives only in narrowed form: decodex should stay plan-agnostic, but moving the machine pointer off the routed issue body does not survive challenge as an immediate recommendation because it breaks the current plan authority contract unless that contract is redesigned in lockstep.", - "objections": [ - { - "id": "O1", - "summary": "Moving the pointer off the routed issue body immediately breaks the current plan writing, execution, and validation contract." - }, - { - "id": "O2", - "summary": "Any replacement surface must remain singular and machine-addressable inside Linear or the plan authority model becomes ambiguous." - }, - { - "id": "O3", - "summary": "Decodex currently dispatches from issue.description, so any preserved human-readable briefing must either remain there or be accompanied by an explicit synchronized dispatch-surface change." - } - ], - "seq": 6, - "target_judgment_hash": "sha256:e413dcbbac1ed9f12c4cf3d6449a1ec895c71de715092e8f6d723711e2e288e7" - }, - { - "type": "evidence_recorded", - "evidence": [ - { - "id": "E4", - "kind": "observation", - "source_family": "repo_docs", - "summary": "The plan execution contract hard-stops unless the routed issue body contains a valid plan-authority/1 envelope, and it forbids execution from mutating those issue-body pointer fields." - } - ], - "seq": 7 - }, - { - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T5", - "summary": "The immediate safe recommendation is to keep decodex plan-agnostic and reject machine-only issue bodies for normal decodex dispatch, because moving the pointer off issue.description without a coordinated contract migration breaks the current plan authority model.", - "supporting_evidence_ids": [ - "E1", - "E2", - "E4" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T6", - "summary": "A future contract redesign may still move machine authority away from the issue body, but only if it preserves one singular machine-addressable Linear authority surface and simultaneously gives decodex an explicit stable dispatch briefing surface.", - "supporting_evidence_ids": [ - "E1", - "E2", - "E4" - ], - "disconfirming_evidence_ids": [] - } - ], - "seq": 8 - }, - { - "type": "judgment_candidate_created", - "addresses_objection_ids": [ - "O1", - "O2", - "O3" - ], - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "A_prime_keep_decodex_plan_agnostic_but_disallow_machine_only_issue_bodies_for_direct_dispatch", - "rejected_options": [ - "B_generic_linked_document_briefing_read_in_decodex", - "C_make_plan_backed_issues_ineligible_until_materialized" - ], - "decision_claim": "Keep decodex plan-agnostic. Under the current contracts, decodex should not accept routed issues whose issue body is only a machine plan pointer, because decodex dispatch still depends on a stable human-readable issue.description surface. Immediate recommendation: do not teach decodex to parse plan-private contracts; instead require any decodex-dispatched issue to preserve a stable generic briefing surface in issue.description, and treat a machine-only issue body as inaligned with normal decodex dispatch until a coordinated contract redesign lands.", - "key_evidence_ids": [ - "E1", - "E2", - "E3", - "E4" - ], - "key_tradeoff_ids": [ - "T1", - "T5", - "T6" - ] - }, - "seq": 9, - "judgment_hash": "sha256:ffe1ba1e527bcb61d5cb1455c461a421798f210cc958c7698160fb5d88e7fb57" - }, - { - "type": "worker_completed", - "worker": "skeptic", - "summary": "The narrowed judgment still overstates the current contract. The source set proves a prompt-surface mismatch, but not an existing decodex eligibility rule. It also needed one explicit field-mapping check to confirm that the plan plugin's issue-body pointer is the same Linear description surface that decodex dispatches.", - "objections": [ - { - "id": "O4", - "summary": "The recommendation should be framed as a design recommendation or contract rule, not as an existing decodex acceptance contract." - }, - { - "id": "O5", - "summary": "The issue-body conflict needed one explicit field-mapping check from Linear description to TrackerIssue.description before it could support a firm integration claim." - } - ], - "seq": 10, - "target_judgment_hash": "sha256:ffe1ba1e527bcb61d5cb1455c461a421798f210cc958c7698160fb5d88e7fb57" - }, - { - "type": "evidence_recorded", - "evidence": [ - { - "id": "E5", - "kind": "observation", - "source_family": "repo_code", - "summary": "Decodex's Linear tracker maps the GraphQL issue.description field directly into TrackerIssue.description, and orchestrator prompt construction injects that same TrackerIssue.description into the dispatch prompt's Description section." - } - ], - "seq": 11 - }, - { - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T7", - "summary": "The strongest supported output is a design recommendation and contract rule for future integration, not a claim that current decodex runtime already enforces dispatch eligibility based on issue-body shape.", - "supporting_evidence_ids": [ - "E1", - "E3", - "E5" - ], - "disconfirming_evidence_ids": [] - } - ], - "seq": 12 - }, - { - "type": "judgment_candidate_created", - "addresses_objection_ids": [ - "O4", - "O5" - ], - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "A_double_prime_keep_decodex_plan_agnostic_and_define_a_contract_rule_for_dispatch_surface", - "rejected_options": [ - "B_generic_linked_document_briefing_read_in_decodex", - "C_make_plan_backed_issues_ineligible_until_materialized" - ], - "decision_claim": "Design recommendation: keep decodex plan-agnostic and do not teach it to parse plan-private contracts. Because decodex dispatch currently reads Linear description verbatim and the current plan plugin requires that same issue body to be machine-only plan-authority/1 JSON, a machine-only routed issue body is inaligned with normal decodex dispatch under the present contracts. The immediate contract rule should therefore be: any issue that decodex dispatches must preserve a stable generic human-readable briefing in the Linear description surface, and plan-contract changes that remove that surface require a coordinated redesign of both plan authority and decodex dispatch inputs.", - "key_evidence_ids": [ - "E1", - "E2", - "E4", - "E5" - ], - "key_tradeoff_ids": [ - "T1", - "T6", - "T7" - ] - }, - "seq": 13, - "judgment_hash": "sha256:273e70dd4050cc4a7bb756f5a75397eb8883af9065bfb715619d483cace91eab" - }, - { - "type": "worker_completed", - "worker": "skeptic", - "summary": "The judgment survives. The strongest caveat is that the present evidence proves prompt-content mismatch rather than a guaranteed hard runtime failure, and a future coordinated redesign could still intentionally expose a public planning surface to decodex without violating plan-agnosticism.", - "seq": 14, - "target_judgment_hash": "sha256:273e70dd4050cc4a7bb756f5a75397eb8883af9065bfb715619d483cace91eab" - }, - { - "type": "finalized_decision_ready", - "judgment_hash": "sha256:273e70dd4050cc4a7bb756f5a75397eb8883af9065bfb715619d483cace91eab", - "confidence": "high", - "missing_evidence": [], - "seq": 15 - } - ] -} diff --git a/docs/research/2026-03-31_decodex-plan-boundary/run.json b/docs/research/2026-03-31_decodex-plan-boundary/run.json deleted file mode 100644 index 956a7ef54..000000000 --- a/docs/research/2026-03-31_decodex-plan-boundary/run.json +++ /dev/null @@ -1,87 +0,0 @@ -{ - "schema": "research-run/2", - "run_id": "2026-03-31_decodex-plan-boundary", - "question": "How should decodex handle plan-backed Linear issues while staying decoupled from plugin-specific contracts?", - "success_criteria": [ - "Clarify whether decodex needs any direct awareness of the plan plugin.", - "Identify the minimal stable surfaces decodex should depend on.", - "Identify the concrete conflict between the new plan issue-body contract and the current decodex dispatch path." - ], - "constraints": [ - "Keep decodex dependent only on Linear, GitHub, and Codex runtime surfaces.", - "Do not turn decodex into a consumer of plugin-private schemas by default.", - "Use repository-local evidence only for this bounded pass." - ], - "stop_rule": "Stop once the bounded pass either identifies one stable boundary shape or proves that more explicit surface design work is still required.", - "primary_hypothesis": "Decodex should remain plan-agnostic, and the current conflict comes from overloading the Linear issue body as both human task description and machine authority pointer.", - "rival_hypotheses": [ - "Decodex should parse and consume plan-authority or tracked-plan directly.", - "The current plan issue-body contract can coexist with decodex unchanged." - ], - "falsifiers": [ - "If decodex already consumes a generic execution surface that can replace issue.description safely, then the current conflict is overstated.", - "If the plan plugin can keep the issue body machine-only without degrading decodex task dispatch, then the issue-body overload claim is false." - ], - "events": [ - { - "seq": 1, - "type": "probe_completed", - "remaining_option_count": 1, - "independent_option_questions": [], - "external_slices": [] - }, - { - "seq": 2, - "type": "evidence_recorded", - "evidence": [ - { - "id": "E1", - "kind": "observation", - "summary": "The plan plugin writing contract requires the routed Linear issue body to be exactly one fenced plan-authority/1 JSON block and explicitly forbids prose in that snapshot." - }, - { - "id": "E2", - "kind": "observation", - "summary": "Decodex currently builds its dispatch prompt by copying issue.description into the Description section for normal, review-repair, and delivery-closeout runs." - }, - { - "id": "E3", - "kind": "observation", - "summary": "Decodex's current plan-related logic is limited to preventing a saved plan phase=done from replacing explicit terminal finalization; it does not otherwise consume plan-authority, tracked-plan, or plan-event contracts." - } - ] - }, - { - "seq": 3, - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T1", - "summary": "Making decodex parse plugin-private plan contracts would couple runtime orchestration to plugin method contracts and create a second control plane boundary.", - "supporting_evidence_ids": [ - "E3" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T2", - "summary": "Keeping decodex plan-agnostic while also replacing the issue body with a machine-only pointer leaves decodex without a stable human-readable task briefing surface.", - "supporting_evidence_ids": [ - "E1", - "E2" - ], - "disconfirming_evidence_ids": [] - } - ] - }, - { - "seq": 4, - "type": "finalized_not_decision_ready", - "reason": "The bounded pass confirms a real surface conflict but does not yet establish the replacement contract for where a decodex-safe human task briefing should live when the issue body becomes a machine-only authority pointer.", - "missing_evidence": [ - "An explicit repository-level contract for the human-readable execution briefing surface when a routed issue also carries plan-authority/1.", - "A decision on whether planned issues are ever eligible for direct decodex dispatch before Codex-side plan execution has materialized the current task." - ] - } - ] -} diff --git a/docs/research/2026-04-01_plan-linear-decoupled-design/run.json b/docs/research/2026-04-01_plan-linear-decoupled-design/run.json deleted file mode 100644 index 79e3d8838..000000000 --- a/docs/research/2026-04-01_plan-linear-decoupled-design/run.json +++ /dev/null @@ -1,493 +0,0 @@ -{ - "schema": "research-run/2", - "run_id": "2026-04-01_plan-linear-decoupled-design", - "question": "How should the plan plugin keep its old legacy saved-plan strengths after moving storage to Linear while staying decoupled from decodex and from overly specific Linear transport details?", - "success_criteria": [ - "Identify the clean boundary between decodex, the routed Linear issue, and the plan plugin's machine authority surfaces.", - "Compare at least two viable plan-plugin architecture options for the Linear-backed design.", - "Recommend a design that preserves machine-readability and append-only history without over-coupling execution to raw Linear export shape." - ], - "constraints": [ - "Keep decodex plan-agnostic and dependent only on generic issue briefing plus normal tracker and PR surfaces.", - "Assume the canonical plan storage remains in Linear rather than reverting to repository-local saved-plan authority.", - "Use bounded repository-local evidence from decodex and the repo-local plan plugin only." - ], - "stop_rule": "Stop once the bounded pass can recommend one design shape for the Linear-backed plan plugin and name the smallest contract corrections needed to make it reliable.", - "primary_hypothesis": "The cleanest design keeps the current Linear surfaces but splits the plugin into a thin Linear ingress adapter plus a transport-agnostic plan core that consumes only a normalized execution surface.", - "rival_hypotheses": [ - "The current design is already the right long-term shape and only needs small contract wording fixes.", - "The plugin should let the execution core depend directly on the full routed Linear issue export because that is simpler and the coupling cost is acceptable." - ], - "falsifiers": [ - "If the current design already limits execution to a minimal normalized surface rather than the full routed issue export, an ingress/core split would be unnecessary.", - "If adding a normalized ingress layer would force duplicated selection logic or materially reduce reliability, the extra decoupling would not be worth it." - ], - "events": [ - { - "seq": 1, - "type": "probe_completed", - "remaining_option_count": 2, - "independent_option_questions": [ - "Should the plan execution core depend directly on the routed Linear issue export or on a normalized execution surface derived from it?", - "Which contract elements must stay strict machine-only versus which should remain generic human-readable briefing surfaces?" - ], - "external_slices": [] - }, - { - "seq": 2, - "type": "evidence_recorded", - "evidence": [ - { - "id": "E1", - "kind": "observation", - "summary": "Decodex now treats the routed issue description only as a generic briefing surface and explicitly redacts machine-only fenced payloads from dispatch prompts." - }, - { - "id": "E2", - "kind": "observation", - "summary": "The repo-local plan writing contract now keeps the routed Linear issue as the parent work item and generic dispatch briefing surface instead of a plugin-private JSON envelope." - }, - { - "id": "E3", - "kind": "observation", - "summary": "The repo-local plan writing contract stores the canonical tracked-plan/1 contract in exactly one linked Linear document and stores append-only execution history in plan-event/1 comments." - }, - { - "id": "E4", - "kind": "observation", - "summary": "The current execution helpers still validate against the routed issue export and require issue.documents[].content for every linked document, which means the current consumer path still depends on a fairly raw Linear export shape." - }, - { - "id": "E5", - "kind": "observation", - "summary": "The plan-event validator only accepts a strict single fenced JSON block, while the execution skill text still contains one step that implies extra prose fields in the same progress comment." - } - ] - }, - { - "seq": 3, - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T1", - "summary": "Keeping the routed issue generic preserves decodex and human operator usability, but it means the plan plugin must not overload that issue surface with machine authority.", - "supporting_evidence_ids": [ - "E1", - "E2" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T2", - "summary": "The current direct use of routed issue exports is pragmatic and keeps the plugin thin, but it also couples execution more tightly to Linear export shape than the old saved-plan model needed.", - "supporting_evidence_ids": [ - "E3", - "E4" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T3", - "summary": "Strict single-block machine contracts keep events and linked docs easy to validate, but any mixed prose requirement in the same surface immediately creates self-contradictory contracts.", - "supporting_evidence_ids": [ - "E5" - ], - "disconfirming_evidence_ids": [] - } - ] - }, - { - "seq": 4, - "type": "worker_completed", - "worker": "analyst", - "target_inventory_seq": 1, - "summary": "Option B is the better long-term design if the adapter stays thin: keep the current Linear surfaces, but concentrate raw issue-export reading, canonical document selection, and cross-surface validation in an ingress layer so the execution core consumes only a validated normalized surface." - }, - { - "seq": 5, - "type": "evidence_recorded", - "evidence": [ - { - "id": "E6", - "kind": "observation", - "summary": "After cross-surface validation, the current execution contract already treats the linked document's tracked-plan state as the source of truth rather than the raw routed issue export." - }, - { - "id": "E7", - "kind": "inference", - "summary": "A normalized ingress layer is practical because the current helpers already derive a validated execution surface; the refactor can narrow and clean that boundary instead of redesigning the external Linear surfaces." - }, - { - "id": "E8", - "kind": "inference", - "summary": "Keeping execution bound directly to issue.documents content and linked-document enumeration preserves current behavior but does not recover the old saved-plan transport decoupling." - } - ] - }, - { - "seq": 6, - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T4", - "summary": "A thin Linear ingress adapter preserves the successful old saved-plan semantics after the move to Linear, but only if the adapter owns raw export validation and the core stops depending on full routed issue exports.", - "supporting_evidence_ids": [ - "E4", - "E6", - "E7" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T5", - "summary": "The normalized execution surface should avoid duplicating phase and task-pointer fields outside tracked-plan.state; otherwise the adapter and core would create a second competing runtime truth.", - "supporting_evidence_ids": [ - "E6", - "E7" - ], - "disconfirming_evidence_ids": [] - } - ] - }, - { - "seq": 7, - "type": "judgment_candidate_created", - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "Option B", - "rejected_options": [ - "Option A" - ], - "decision_claim": "Keep the current external Linear surfaces but split the plan plugin into a thin Linear ingress adapter plus a transport-agnostic execution core whose minimal contract is the validated tracked-plan plus stable ids, with latest-event retained only as validated provenance rather than a second runtime source of truth.", - "key_evidence_ids": [ - "E1", - "E3", - "E4", - "E6", - "E7", - "E8" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T4", - "T5" - ] - }, - "judgment_hash": "sha256:277e518b517bb78f2dc5d0c49c2b40502011e1bf3b4aabf510383ad31525aa35" - }, - { - "seq": 8, - "type": "worker_completed", - "worker": "skeptic", - "target_judgment_hash": "sha256:277e518b517bb78f2dc5d0c49c2b40502011e1bf3b4aabf510383ad31525aa35", - "summary": "The first judgment was too aggressive: latest-event still participates in canonical selection, runtime progression still leaks through spec.tasks status, and a truly minimal transport-agnostic core is not yet justified by the current contract." - }, - { - "seq": 9, - "type": "evidence_recorded", - "evidence": [ - { - "id": "E9", - "kind": "observation", - "summary": "The current contract forbids execution from mutating spec.* but still uses spec.tasks[*].status to validate legal runtime progression, which means runtime ownership is not yet fully isolated inside tracked-plan.state." - }, - { - "id": "E10", - "kind": "observation", - "summary": "The latest valid plan-event is not only audit history; it also participates in canonical tracked-plan document selection when multiple linked tracked-plan candidates exist." - }, - { - "id": "E11", - "kind": "inference", - "summary": "The clean next step is a staged design: first make plugin-local runtime ownership self-consistent, then narrow the adapter boundary, instead of promising a fully transport-agnostic core immediately." - }, - { - "id": "E12", - "kind": "observation", - "summary": "Current event ordering and canonical selection still rely on second-granularity timestamps, which means adapter extraction alone would not remove ambiguity without an accompanying contract cleanup." - } - ] - }, - { - "seq": 10, - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T6", - "summary": "A staged design preserves the successful move from legacy saved-plan storage to Linear while avoiding a premature promise of a transport-agnostic core before runtime ownership and canonical selection semantics are cleaned up.", - "supporting_evidence_ids": [ - "E9", - "E10", - "E11" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T7", - "summary": "Cleaning plugin-local state ownership first adds short-term contract work, but it prevents the adapter/core split from merely renaming today's internal contradictions.", - "supporting_evidence_ids": [ - "E9", - "E11", - "E12" - ], - "disconfirming_evidence_ids": [] - } - ] - }, - { - "seq": 11, - "type": "judgment_candidate_created", - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "Staged Option B", - "rejected_options": [ - "Option A", - "Immediate thin-core Option B" - ], - "decision_claim": "Keep the current external Linear surfaces, but treat the next design step as a staged clean-break inside the plugin: first make runtime ownership self-consistent by keeping generic issue briefing on the routed issue, one canonical tracked-plan in the linked document, strict machine-only plan-event comments, and runtime progression tracked only in runtime-owned fields; then narrow read_execution_surface into an adapter-owned validated ingress contract without promising a fully transport-agnostic execution core until canonical selection and state ownership are clean.", - "key_evidence_ids": [ - "E1", - "E3", - "E5", - "E9", - "E10", - "E11", - "E12" - ], - "key_tradeoff_ids": [ - "T1", - "T3", - "T6", - "T7" - ] - }, - "judgment_hash": "sha256:b1e137e4fe6865cb48df44d6477e2f75db7911a769460b6cd0c77499566241e3" - }, - { - "seq": 12, - "type": "worker_completed", - "worker": "skeptic", - "target_judgment_hash": "sha256:b1e137e4fe6865cb48df44d6477e2f75db7911a769460b6cd0c77499566241e3", - "summary": "The staged design was still incomplete: it did not assign a legal runtime owner for task status, and it deferred the ingress adapter even though execution already depends on linked documents and comments that current generic runtime surfaces do not provide." - }, - { - "seq": 13, - "type": "evidence_recorded", - "evidence": [ - { - "id": "E13", - "kind": "observation", - "summary": "Execution is currently allowed to mutate only runtime-owned state while task status still lives inside spec.tasks, so the current contract does not give execution a legal way to advance plan-local task progress." - }, - { - "id": "E14", - "kind": "observation", - "summary": "Current execution depends on linked documents and plan-event comment history, but the generic runtime surfaces discussed around decodex do not themselves supply a stable ingress contract for those documents and comments." - }, - { - "id": "E15", - "kind": "inference", - "summary": "The clean next design is boundary-first repair: introduce an explicit Linear ingress adapter now while simultaneously moving runtime task progress fully into runtime-owned state, instead of deferring either half." - }, - { - "id": "E16", - "kind": "observation", - "summary": "Canonical tracked-plan selection still relies on timestamp ordering across candidate event histories, so the ingress boundary needs an explicit ordering or revision responsibility rather than leaving that ambiguity implicit." - } - ] - }, - { - "seq": 14, - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T8", - "summary": "Moving task progress and task-status ownership out of spec and into runtime-owned state restores the old saved-plan separation between stable intent and execution state, but it requires a schema revision to tracked-plan rather than a wording-only fix.", - "supporting_evidence_ids": [ - "E9", - "E13", - "E15" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T9", - "summary": "An explicit Linear ingress adapter has to land together with the contract cleanup because execution already depends on linked docs and comments; delaying adapter extraction would keep transport coupling hidden in the core path.", - "supporting_evidence_ids": [ - "E10", - "E14", - "E15" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T10", - "summary": "Canonical selection and event ordering should become an adapter-owned responsibility with an explicit revision or ordering rule; otherwise timestamp ambiguity remains even after other decoupling work lands.", - "supporting_evidence_ids": [ - "E12", - "E16" - ], - "disconfirming_evidence_ids": [] - } - ] - }, - { - "seq": 15, - "type": "judgment_candidate_created", - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "Boundary-first repair", - "rejected_options": [ - "Option A", - "Immediate thin-core Option B", - "State-cleanup-before-adapter staged design" - ], - "decision_claim": "Keep the current external Linear surfaces, but make the next design step a boundary-first repair inside the plugin: routed issue remains generic briefing only; one linked document remains the canonical tracked-plan; plan-event comments stay strict single JSON blocks; runtime task progress and task status move fully into runtime-owned state rather than spec.tasks; and an explicit Linear ingress adapter becomes responsible for reading issue, documents, and comments, selecting the canonical tracked-plan with a defined ordering rule, and emitting one validated execution-surface contract for the execution path. A narrower transport-agnostic core may follow later, but this boundary-first repair is the decision-ready next step.", - "key_evidence_ids": [ - "E1", - "E3", - "E5", - "E10", - "E13", - "E14", - "E15", - "E16" - ], - "key_tradeoff_ids": [ - "T1", - "T3", - "T8", - "T9", - "T10" - ] - }, - "judgment_hash": "sha256:f5cff28ca34dcc7e6660b0e05c70d17dd0744824b78f25953d0d75ee7f465ee9" - }, - { - "seq": 16, - "type": "worker_completed", - "worker": "skeptic", - "target_judgment_hash": "sha256:f5cff28ca34dcc7e6660b0e05c70d17dd0744824b78f25953d0d75ee7f465ee9", - "summary": "Boundary-first repair is directionally right but still incomplete unless it also defines cross-document lineage, a write-side consistency rule, a concrete runtime task-state schema, and explicit semantics for plan-local done versus decodex lane completion." - }, - { - "seq": 17, - "type": "evidence_recorded", - "evidence": [ - { - "id": "E17", - "kind": "observation", - "summary": "Current plan-event contracts do not carry a cross-document revision or supersedes primitive, so canonical selection still falls back to timestamp ordering across histories." - }, - { - "id": "E18", - "kind": "observation", - "summary": "Current execution updates the linked document and append-only event separately while validation later requires exact agreement, which means transient write skew can block execution." - }, - { - "id": "E19", - "kind": "observation", - "summary": "The current contract relies on spec.tasks status for plan-local progress, but execution is not allowed to mutate spec.*, so a replacement runtime task-state shape is required rather than implied." - }, - { - "id": "E20", - "kind": "observation", - "summary": "The plan plugin treats done as plan-local while decodex's current operator guidance warns agents not to mark a saved plan done before terminal finalize succeeds, so outer-lifecycle semantics are not yet aligned." - }, - { - "id": "E21", - "kind": "inference", - "summary": "A decision-ready design needs one more level of specificity: event lineage and write protocol must be first-class, not residual implementation details." - } - ] - }, - { - "seq": 18, - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T11", - "summary": "Treating events as the authoritative runtime log and the linked document as a checkpointed snapshot reduces write-skew fragility, but it makes readers responsible for replay or lag-tolerant validation.", - "supporting_evidence_ids": [ - "E18", - "E21" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T12", - "summary": "Adding an explicit plan revision or lineage contract is more verbose than timestamp selection, but it restores deterministic authority after replans and preserves one of the old saved-plan strengths: clear canonical ownership.", - "supporting_evidence_ids": [ - "E17", - "E21" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T13", - "summary": "Separating plan-local done from lane terminal completion preserves plugin autonomy, but it requires a small decodex wording change so plan.done is no longer treated as forbidden before terminal finalize in every context.", - "supporting_evidence_ids": [ - "E20" - ], - "disconfirming_evidence_ids": [] - } - ] - }, - { - "seq": 19, - "type": "judgment_candidate_created", - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "Boundary-first repair with event-log authority", - "rejected_options": [ - "Option A", - "Immediate thin-core Option B", - "State-cleanup-before-adapter staged design", - "Boundary-first repair without lineage/write-protocol changes" - ], - "decision_claim": "Keep the current external Linear surfaces, but define the next architecture as a boundary-first repair with event-log authority: the routed issue remains generic briefing only; the linked document keeps stable plan intent and a checkpointed runtime snapshot; append-only plan-event comments become the authoritative runtime log and must stay strict single JSON blocks; a new explicit plan revision/lineage field replaces timestamp-only canonical selection across replans; runtime task progress moves into a runtime-owned task-state structure rather than spec.tasks status; and a Linear ingress adapter becomes responsible for reading issue, documents, and comments, selecting the canonical document and latest authoritative event by lineage plus seq, tolerating checkpoint lag under a defined write protocol, and emitting one validated execution surface for execution. Decodex stays plan-agnostic, but its wording should distinguish plan-local done from lane terminal completion instead of banning plan.done outright before terminal finalize.", - "key_evidence_ids": [ - "E1", - "E3", - "E5", - "E13", - "E14", - "E17", - "E18", - "E19", - "E20", - "E21" - ], - "key_tradeoff_ids": [ - "T1", - "T3", - "T8", - "T9", - "T11", - "T12", - "T13" - ] - }, - "judgment_hash": "sha256:6897bb1133bc40d498e1aaf0b1edea57d688814ee4d0e08866fa56dda4056f0c" - }, - { - "seq": 20, - "type": "worker_completed", - "worker": "skeptic", - "target_judgment_hash": "sha256:6897bb1133bc40d498e1aaf0b1edea57d688814ee4d0e08866fa56dda4056f0c", - "summary": "The boundary-first repair with event-log authority is directionally coherent, but it is still missing implementation-blocking contract details: the runtime task-state schema, lineage/revision semantics, and the exact lag-tolerant write protocol." - }, - { - "seq": 21, - "type": "finalized_not_decision_ready", - "reason": "The bounded pass identified a coherent architecture direction, but the design is still missing concrete contract definitions for runtime task-state replacement, cross-document lineage and canonical-selection semantics, and a lag-tolerant write protocol between checkpointed documents and authoritative plan-event history.", - "missing_evidence": [ - "A concrete runtime task-state schema that can replace spec.tasks[*].status while preserving deterministic next-task and dependency validation.", - "A precise lineage or revision contract for replans and cross-document canonical selection, including how a new revision becomes authoritative before it has execution history.", - "A defined write protocol and validator rule for document and event skew, including write order, crash recovery, and when a stale checkpoint is acceptable versus blocking.", - "An explicit alignment rule between plan-local done and decodex lane terminal completion semantics." - ] - } - ] -} diff --git a/docs/research/2026-04-02_delivery-skill-removal-with-agents.json b/docs/research/2026-04-02_delivery-skill-removal-with-agents.json deleted file mode 100644 index f2fc9bb6c..000000000 --- a/docs/research/2026-04-02_delivery-skill-removal-with-agents.json +++ /dev/null @@ -1,320 +0,0 @@ -{ - "schema": "research-run/2", - "run_id": "2026-04-02_delivery-skill-removal-with-agents", - "question": "How should decodex remove the delivery skill family while staying consistent with the current AGENTS.md workflow and minimizing breakage?", - "success_criteria": [ - "Recommend a concrete target design for removing delivery-prepare and delivery-closeout as skills.", - "Explain which responsibilities move into Decodex runtime/spec/prompting versus WORKFLOW.md or other repo policy surfaces.", - "Give a phased migration route that preserves the existing review -> land -> closeout lifecycle while reducing skill authority." - ], - "constraints": [ - "Use the Research plugin's run-file workflow and host-level subagents.", - "Prefer an incremental migration over a big-bang rewrite.", - "Do not rely on human-readable commit history as a requirement." - ], - "stop_rule": "Stop once there is a challenge-ready recommendation for delivery-skill removal, or once bounded evidence shows the recommendation is still unsafe.", - "primary_hypothesis": "The delivery skill family can be removed cleanly by moving lifecycle authority into Decodex runtime and post-review protocol surfaces while moving repo-specific validation and docs gates into WORKFLOW.md-backed policy.", - "rival_hypotheses": [ - "A thin delivery shim skill is still required because AGENTS, landing, and repair flows depend too directly on delivery-specific routing.", - "Delivery removal should wait until review-prepare, review-repair, pr-land, and review-loop are all redesigned together in one larger protocol rewrite." - ], - "falsifiers": [ - "If current runtime or prompting still depends on delivery skill-local semantics that cannot be expressed by existing retained-lane protocol surfaces, removing delivery skills first is not safe.", - "If repo-specific validation, docs automation, or merge policy cannot be externalized without reintroducing delivery-specific skills, the proposed split is incomplete." - ], - "coverage": { - "mode": "standard", - "min_source_families": 0 - }, - "continuation": { - "mode": "auto_if_not_decision_ready", - "attempt": 1, - "max_attempts": 2, - "session_id": "2026-04-02_delivery-skill-removal-with-agents" - }, - "events": [ - { - "seq": 1, - "type": "probe_completed", - "remaining_option_count": 3, - "independent_option_questions": [ - "What is the smallest migration slice that removes delivery skills without breaking the retained review -> land -> closeout lifecycle?", - "Which current delivery responsibilities belong in Decodex runtime/spec/prompting versus WORKFLOW.md or AGENTS policy?" - ], - "external_slices": [ - { - "id": "S1", - "question": "Which delivery responsibilities are already modeled as Decodex runtime, prompt, or tracker-tool authority rather than skill-local behavior?" - }, - { - "id": "S2", - "question": "Which current skill, AGENTS, and dev-smoke references still hard-depend on delivery-prepare or delivery-closeout?" - }, - { - "id": "S3", - "question": "Which repo-specific validation and docs gates can be represented by WORKFLOW.md or adjacent policy without keeping delivery skills?" - } - ] - }, - { - "type": "evidence_recorded", - "evidence": [ - { - "id": "E1", - "kind": "observation", - "summary": "Decodex runtime, prompting, and tracker-tool bridge already model retained delivery_closeout as a first-class post-review phase with dedicated dispatch, prompt contract, and terminal completion handling.", - "source_family": "repo_code" - }, - { - "id": "E2", - "kind": "observation", - "summary": "Repo policy already has machine-readable surfaces for completed tracker state and repo-native validation commands through WORKFLOW.md, so delivery-specific test gating is not required as a skill-local authority.", - "source_family": "repo_spec" - }, - { - "id": "E3", - "kind": "observation", - "summary": "The strongest remaining delivery dependencies are in .codex/AGENTS.md workflow prose, pr-land and review-repair skill instructions, and dev smoke coverage rather than in the retained-lane runtime model itself.", - "source_family": "repo_code" - }, - { - "id": "E4", - "kind": "contradiction", - "summary": "A retained delivery_closeout continuation boundary currently requires the issue to remain in success_state even though dispatch policy and retry tests allow delivery_closeout scheduling after the issue reaches completed state.", - "source_family": "repo_code" - }, - { - "id": "E5", - "kind": "observation", - "summary": "Current delivery history semantics such as delivery/1 merge preservation and merge-commit payload generation live in pr-land and AGENTS policy, and WORKFLOW.md does not yet expose an equivalent merge-history policy field.", - "source_family": "repo_code" - } - ], - "seq": 2 - }, - { - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T1", - "summary": "Removing delivery skills first has low runtime-model risk because retained delivery_closeout authority already exists, but it still requires coordinated policy and test cleanup across AGENTS, skill docs, and dev smoke.", - "supporting_evidence_ids": [ - "E1", - "E3" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T2", - "summary": "Moving repo-native validation and docs gates into WORKFLOW.md or adjacent repo policy simplifies the runtime/skill boundary, but merge-history semantics need a new home because they are not represented in the current workflow contract.", - "supporting_evidence_ids": [ - "E2", - "E5" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T3", - "summary": "An incremental delivery-only removal slice minimizes blast radius, but the continuation-boundary contradiction should be resolved or explicitly constrained before the final closeout protocol is declared complete.", - "supporting_evidence_ids": [ - "E4" - ], - "disconfirming_evidence_ids": [ - "E1" - ] - } - ], - "seq": 3 - }, - { - "type": "worker_completed", - "worker": "scout", - "summary": "Scout confirmed that delivery_closeout lifecycle authority already lives in Decodex runtime/spec, while remaining delivery dependencies are concentrated in AGENTS, skill prose, and dev smoke rather than in the retained-lane model.", - "seq": 4, - "target_inventory_seq": 1 - }, - { - "type": "inventory_updated", - "remaining_option_count": 2, - "independent_option_questions": [ - "Should delivery skill removal be executed now as its own first migration slice, or delayed until a larger review/landing protocol rewrite?", - "Which delivery responsibilities need new runtime or workflow surfaces before the skill pair can be deleted without leaving policy gaps?" - ], - "external_slices": [], - "supporting_evidence_ids": [ - "E1", - "E2", - "E3", - "E4", - "E5" - ], - "seq": 5 - }, - { - "type": "evidence_recorded", - "evidence": [ - { - "id": "E6", - "kind": "inference", - "summary": "The preferred migration order is to remove delivery-prepare and delivery-closeout first, because Decodex already owns closeout lifecycle authority while the remaining skill dependencies are concentrated in repo policy and smoke coverage.", - "source_family": "repo_analysis" - }, - { - "id": "E7", - "kind": "missing_evidence", - "summary": "The only unresolved design check that could change the migration shape is whether retained delivery_closeout continuation after transition to completed_state is intended to be allowed or whether closeout is intentionally single-turn before completion." - } - ], - "seq": 6 - }, - { - "type": "worker_completed", - "worker": "analyst", - "summary": "Analyst prefers a delivery-first removal slice now, with merge-history policy and closeout-boundary semantics externalized before direct skill deletion.", - "seq": 7, - "target_inventory_seq": 5 - }, - { - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T4", - "summary": "A delivery-first removal slice makes immediate progress with bounded blast radius, but it still requires adding a new runtime or workflow surface for merge-history policy before pr-land can stop depending on delivery/1 semantics.", - "supporting_evidence_ids": [ - "E3", - "E5", - "E6" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T5", - "summary": "Waiting for a larger protocol rewrite reduces duplicate policy edits, but it delays removal even though the retained delivery_closeout lifecycle is already internal to Decodex.", - "supporting_evidence_ids": [ - "E1", - "E6" - ], - "disconfirming_evidence_ids": [ - "E4" - ] - } - ], - "seq": 8 - }, - { - "type": "judgment_candidate_created", - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "delivery_first_runtime_externalization", - "rejected_options": [ - "wait_for_full_review_landing_protocol_rewrite" - ], - "decision_claim": "Remove delivery-prepare and delivery-closeout as the first migration slice now. Move retained delivery lifecycle authority fully into Decodex runtime/spec/prompting, move repo-native validation and docs gates into WORKFLOW.md-backed policy, add a replacement merge-history policy surface before removing pr-land's delivery/1 assumptions, and resolve or explicitly constrain completed-state continuation semantics during the slice.", - "key_evidence_ids": [ - "E1", - "E2", - "E3", - "E5", - "E6" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T4", - "T5" - ] - }, - "seq": 9, - "judgment_hash": "sha256:feaeeeb23ca74758ab00810c5aac2f41bcaaed5c40d6f89b796004f8ac1f1f31" - }, - { - "type": "worker_completed", - "worker": "skeptic", - "summary": "Skeptic agrees with a delivery-first slice only if the migration explicitly handles the current GitHub-mirroring responsibility and the completed-state continuation mismatch.", - "objections": [ - { - "id": "O1", - "summary": "The current recommendation leaves a behavior gap unless GitHub mirroring is explicitly de-scoped or replaced before deleting delivery-closeout." - } - ], - "seq": 10, - "target_judgment_hash": "sha256:feaeeeb23ca74758ab00810c5aac2f41bcaaed5c40d6f89b796004f8ac1f1f31" - }, - { - "type": "evidence_recorded", - "evidence": [ - { - "id": "E8", - "kind": "observation", - "summary": "The lifecycle spec still treats GitHub mirroring as part of delivery_closeout completion, while the retained-lane runtime evidence gathered for this run centered on merged PR lineage and tracker completed-state validation rather than an explicit mirroring implementation path.", - "source_family": "repo_spec" - } - ], - "seq": 11 - }, - { - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T6", - "summary": "A delivery-first slice remains sound only if GitHub mirroring is either moved into runtime-owned closeout behavior or explicitly removed from lifecycle expectations during the same slice.", - "supporting_evidence_ids": [ - "E8" - ], - "disconfirming_evidence_ids": [ - "E1" - ] - } - ], - "seq": 12 - }, - { - "type": "judgment_candidate_created", - "addresses_objection_ids": [ - "O1" - ], - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "delivery_first_runtime_externalization", - "rejected_options": [ - "wait_for_full_review_landing_protocol_rewrite" - ], - "decision_claim": "Remove delivery-prepare and delivery-closeout as the first migration slice now, but make the slice explicitly include three policy transfers before direct skill deletion: (1) move retained delivery lifecycle authority fully into Decodex runtime/spec/prompting, (2) move repo-native validation and docs gates into WORKFLOW.md-backed policy, and (3) either move GitHub mirroring into runtime-owned closeout behavior or explicitly remove it from lifecycle expectations. Also add a replacement merge-history policy surface before removing pr-land's delivery/1 assumptions, and resolve or explicitly constrain completed-state continuation semantics during the slice.", - "key_evidence_ids": [ - "E1", - "E2", - "E3", - "E5", - "E6", - "E8" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T4", - "T5", - "T6" - ] - }, - "seq": 13, - "judgment_hash": "sha256:28a47aa43f99a3b7eaee7532aad438fe97226fc42ffae69aafddd11954dcb243" - }, - { - "type": "worker_completed", - "worker": "skeptic", - "summary": "Replacement judgment survives challenge. No remaining material objections remain if the slice explicitly covers GitHub mirroring disposition, replacement merge-history policy, and the completed-state continuation acceptance gate.", - "objections": [], - "seq": 14, - "target_judgment_hash": "sha256:28a47aa43f99a3b7eaee7532aad438fe97226fc42ffae69aafddd11954dcb243" - }, - { - "type": "finalized_decision_ready", - "confidence": "medium", - "missing_evidence": [ - "Confirm whether retained delivery_closeout continuation after completed_state is intended runtime behavior or a bug to fix during the slice." - ], - "seq": 15, - "judgment_hash": "sha256:28a47aa43f99a3b7eaee7532aad438fe97226fc42ffae69aafddd11954dcb243" - } - ] -} diff --git a/docs/research/2026-04-02_drop-delivery-skills.json b/docs/research/2026-04-02_drop-delivery-skills.json deleted file mode 100644 index f4c2f0e5a..000000000 --- a/docs/research/2026-04-02_drop-delivery-skills.json +++ /dev/null @@ -1,152 +0,0 @@ -{ - "schema": "research-run/2", - "run_id": "2026-04-02_drop-delivery-skills", - "question": "What runtime-native design should replace the delivery skills if decodex discards them completely?", - "success_criteria": [ - "Eliminate delivery-prepare and delivery-closeout as workflow skills.", - "Keep post-review landing and closeout machine-checkable inside decodex.", - "Preserve explicit closeout semantics without relying on skill-local commit-message workflows.", - "Produce a migration shape that fits the current orchestrator, tracker bridge, and workflow policy surfaces." - ], - "constraints": [ - "Use the current checkout as the primary evidence source.", - "Do not require delivery-specific skills or skill shims in the target design.", - "Keep tracker writes issue-scoped and aligned with the existing decodex runtime ownership model.", - "Do not depend on branch-name or PR-title heuristics for delivery decisions." - ], - "stop_rule": "Stop once the replacement design is concrete enough to implement or once the bounded pass is blocked by a required worker gate.", - "primary_hypothesis": "The delivery skills should be replaced by a decodex-owned delivery protocol: workflow policy declares the closeout target and merge behavior, the runtime owns post-review state transitions and validation, and the agent uses only issue-scoped tracker tools plus repo-native git and GitHub actions.", - "rival_hypotheses": [ - "A thin delivery skill shim is still required as the user-facing entrypoint even after the protocol moves into decodex.", - "The existing delivery commit-message contract should remain the primary authority even if the runtime owns closeout." - ], - "falsifiers": [ - "If decodex lacks the runtime surfaces needed to validate merged PR lineage and completed tracker state, removing the skills would create an unowned gap.", - "If merge policy still requires a delivery-specific commit contract that cannot move into runtime or workflow policy, deleting the skills would remove essential authority." - ], - "coverage": { - "mode": "standard", - "min_source_families": 0 - }, - "continuation": { - "mode": "stop", - "attempt": 1, - "max_attempts": 1, - "session_id": "2026-04-02_drop-delivery-skills" - }, - "events": [ - { - "seq": 1, - "type": "probe_completed", - "remaining_option_count": 1, - "independent_option_questions": [], - "external_slices": [] - }, - { - "seq": 2, - "type": "evidence_recorded", - "evidence": [ - { - "id": "E1", - "kind": "observation", - "summary": "The normative post-review lifecycle already treats `delivery_closeout` as a retained-lane phase whose meaning must not depend on a helper name, so the domain boundary already belongs to decodex rather than to a skill wrapper.", - "source_family": "repo_spec" - }, - { - "id": "E2", - "kind": "observation", - "summary": "The orchestrator already has a dedicated `DeliveryCloseout` dispatch mode plus runtime validation for GitHub availability and retained PR lineage, which shows the runtime already models delivery closeout as first-class execution state.", - "source_family": "repo_code" - }, - { - "id": "E3", - "kind": "observation", - "summary": "The tracker tool bridge already exposes issue-scoped transition and comment tools and validates that delivery closeout only completes after the merged PR matches the retained lane and the issue has reached the resolved completed state.", - "source_family": "repo_code" - }, - { - "id": "E4", - "kind": "inference", - "summary": "The current delivery skills duplicate runtime concerns by carrying closeout semantics, merge-history semantics, and tracker-sync rules in skill prose even though the runtime and workflow specs already own the same lifecycle boundary.", - "source_family": "repo_code" - }, - { - "id": "E5", - "kind": "observation", - "summary": "The current delivery-prepare skill adds extra report-generation and commit-message-contract obligations that are not required by the tracker tool bridge or the retained-lane runtime model.", - "source_family": "repo_code" - } - ] - }, - { - "seq": 3, - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T1", - "summary": "Internalizing delivery into decodex removes duplicated skill/runtime authority, but decodex must then own a small explicit delivery protocol surface in workflow policy and prompt contracts instead of relying on skill prose.", - "supporting_evidence_ids": [ - "E1", - "E2", - "E4" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T2", - "summary": "Dropping the delivery commit-message contract simplifies commit and push flow, but any semantics currently carried by `delivery_mode` and typed refs must move to runtime-owned state or issue-scoped tool calls before merge and closeout.", - "supporting_evidence_ids": [ - "E3", - "E5" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T3", - "summary": "If delivery becomes runtime-native, merge policy should derive from PR state plus workflow policy rather than from whether commit subjects happen to match a delivery JSON schema.", - "supporting_evidence_ids": [ - "E1", - "E2", - "E5" - ], - "disconfirming_evidence_ids": [] - } - ] - }, - { - "seq": 4, - "type": "judgment_candidate_created", - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "runtime-native-delivery-protocol", - "rejected_options": [ - "keep-delivery-skills-as-thin-shims", - "keep-delivery-commit-contract-as-primary-authority" - ], - "decision_claim": "Discard the delivery skills entirely and replace them with a decodex-owned delivery protocol: workflow policy declares the resolved completed state and merge/closeout policy, the runtime owns landing and closeout validation, and the coding agent uses only issue-scoped tracker tools plus repo-native git and GitHub actions.", - "key_evidence_ids": [ - "E1", - "E2", - "E3", - "E4", - "E5" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T3" - ] - }, - "judgment_hash": "sha256:dec502b46d7fb2c49715ccd5ff9d8b3531c068c20bf312c0ce0496135e4b6b09" - }, - { - "seq": 5, - "type": "finalized_error", - "reason_code": "worker_unavailable", - "details": "The research plugin requires a skeptic worker for the current judgment candidate, but this turn did not include explicit child-agent authorization, so the bounded run could not complete the required adversarial challenge.", - "failed_workers": [ - "skeptic" - ] - } - ] -} diff --git a/docs/research/2026-04-02_plan-plugin-to-progress-skill-multiagent-decision.json b/docs/research/2026-04-02_plan-plugin-to-progress-skill-multiagent-decision.json deleted file mode 100644 index be9cc7f13..000000000 --- a/docs/research/2026-04-02_plan-plugin-to-progress-skill-multiagent-decision.json +++ /dev/null @@ -1,233 +0,0 @@ -{ - "schema": "research-run/2", - "run_id": "2026-04-02_plan-plugin-to-progress-skill-multiagent-decision", - "question": "Should decodex remove the plan plugin and replace it with one Linear-backed development progress state skill optimized for AI/agent/LLM execution state?", - "success_criteria": [ - "Determine whether removing the plan plugin is preferable to keeping or simplifying it.", - "Use explicit child-agent evaluation and challenge passes before finalizing.", - "Define the replacement as an issue-scoped Linear execution-state skill that preserves lifecycle boundaries." - ], - "constraints": [ - "Keep the routed Linear issue description as a generic briefing surface rather than plugin-private state.", - "Prefer one skill over a writing/execution split unless evidence shows the split is required.", - "Do not let the replacement skill substitute for review handoff, delivery closeout, or terminal finalize." - ], - "stop_rule": "Stop once the repository evidence plus explicit analyst and skeptic passes support a decision-ready recommendation or show that removing the plan plugin would leave unresolved lifecycle gaps.", - "primary_hypothesis": "The current repo needs one Linear-backed development progress state skill more than it needs a separate plan plugin, so the best fit is to remove the plan plugin and replace it with an issue-scoped progress-state skill.", - "rival_hypotheses": [ - "The plan plugin should stay and only be simplified because the runtime still needs durable strategy authority.", - "The best fit is to keep the plan plugin internals but collapse writing and execution into one skill instead of removing it." - ], - "falsifiers": [ - "If the runtime depends on linked-plan lineage or linked-plan documents for normal execution continuity, removing the plan plugin is insufficient.", - "If an issue-scoped Linear checkpoint cannot cover the state an agent needs for retries, verification, and review repair, the replacement skill is insufficient." - ], - "coverage": { - "mode": "standard", - "min_source_families": 0 - }, - "continuation": { - "mode": "auto_if_not_decision_ready", - "attempt": 1, - "max_attempts": 2, - "session_id": "2026-04-02_plan-plugin-to-progress-skill-multiagent-decision" - }, - "events": [ - { - "seq": 1, - "type": "probe_completed", - "remaining_option_count": 3, - "independent_option_questions": [ - "Does normal decodex execution actually require durable strategy authority beyond issue-scoped execution checkpoints?", - "Would one Linear-backed progress-state skill fit the runtime better than either keeping plan or collapsing writing and execution into one skill?" - ], - "external_slices": [] - }, - { - "seq": 2, - "type": "evidence_recorded", - "evidence": [ - { - "id": "E1", - "kind": "observation", - "summary": "The runtime and README both position tracked planning as an execution overlay inside the retained lane rather than as decodex's primary lifecycle authority.", - "source_family": "repo_docs" - }, - { - "id": "E2", - "kind": "observation", - "summary": "The runtime says Linear is the source of truth for issue lifecycle and coarse outcomes, forbids a second long-lived business workflow model outside Linear, and requires the issue description to remain a generic briefing surface.", - "source_family": "repo_docs" - }, - { - "id": "E3", - "kind": "observation", - "summary": "The tracker tool contract already establishes an issue-scoped structured-checkpoint pattern via issue_review_checkpoint, which decodex treats as the only authoritative structured review-policy signal.", - "source_family": "repo_docs" - }, - { - "id": "E4", - "kind": "observation", - "summary": "The current plan plugin is explicitly split into writing and execution, with linked tracked-plan documents, append-only plan-event comments, and cross-surface validation before execution can proceed.", - "source_family": "repo_code" - }, - { - "id": "E5", - "kind": "observation", - "summary": "The current plan plugin surface is about 2082 lines across skills, templates, and contract helpers, which is large for a feature now described as an execution overlay.", - "source_family": "repo_code" - }, - { - "id": "E6", - "kind": "observation", - "summary": "Prior bounded research on the plan plugin concluded that the design still had unresolved runtime task-state, write-skew, lineage, and plan-local-done semantic gaps.", - "source_family": "repo_docs" - } - ] - }, - { - "seq": 3, - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T1", - "summary": "Removing the plan plugin aligns the common path with decodex's existing issue-scoped tracker authority and reduces control-plane complexity, but it gives up durable strategy lineage across replans.", - "supporting_evidence_ids": [ - "E1", - "E2", - "E5" - ], - "disconfirming_evidence_ids": [ - "E4" - ] - }, - { - "id": "T2", - "summary": "Keeping the plan plugin preserves a stronger durable planning contract for rare multi-session planning cases, but it forces a dual-surface strategy/runtime model onto the common path and carries known semantic debt.", - "supporting_evidence_ids": [ - "E4", - "E6" - ], - "disconfirming_evidence_ids": [ - "E1" - ] - }, - { - "id": "T3", - "summary": "Collapsing writing and execution into one skill would reduce entrypoints, but it would leave the linked-document plus event-log machinery mostly intact and therefore would not remove most of the complexity.", - "supporting_evidence_ids": [ - "E4", - "E5", - "E6" - ], - "disconfirming_evidence_ids": [] - } - ] - }, - { - "seq": 4, - "type": "inventory_updated", - "remaining_option_count": 2, - "independent_option_questions": [ - "Which option better matches decodex's existing authority boundaries: removing plan in favor of one issue-scoped Linear state skill, or keeping a durable planning subsystem?", - "Which option better minimizes common-path complexity without losing execution continuity the runtime actually depends on?" - ], - "external_slices": [], - "supporting_evidence_ids": [ - "E1", - "E2", - "E3", - "E4", - "E5", - "E6" - ] - }, - { - "seq": 5, - "type": "worker_completed", - "worker": "analyst", - "summary": "The analyst preferred removing the plan plugin in favor of one Linear-backed development progress state skill because it better matches decodex's existing Linear authority and issue-scoped checkpoint model, while the strongest counterargument is that removing plan also removes durable multi-step planning authority for minority replan-heavy workflows. Confidence: 0.81.", - "target_inventory_seq": 4 - }, - { - "seq": 6, - "type": "evidence_recorded", - "evidence": [ - { - "id": "E7", - "kind": "observation", - "summary": "The analyst found that option 1 fits better because decodex already centers Linear lifecycle authority and issue-scoped checkpoints, so a single Linear-backed progress-state skill aligns with the existing architecture more directly than a separate plan subsystem.", - "source_family": "repo_docs" - }, - { - "id": "E8", - "kind": "observation", - "summary": "The analyst's strongest counterargument is that deleting plan also deletes a real capability: durable multi-step plan authority and replan lineage for minority workflows, so the simplification is a deliberate scope reduction rather than a free cleanup.", - "source_family": "repo_docs" - } - ] - }, - { - "seq": 7, - "type": "inventory_updated", - "remaining_option_count": 1, - "independent_option_questions": [], - "external_slices": [], - "supporting_evidence_ids": [ - "E1", - "E2", - "E3", - "E5", - "E6", - "E7", - "E8" - ] - }, - { - "seq": 8, - "type": "judgment_candidate_created", - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "remove-plan-plugin-and-adopt-linear-progress-skill", - "rejected_options": [ - "keep-plan-plugin-and-simplify-it", - "collapse-plan-writing-and-execution-into-one-skill" - ], - "decision_claim": "Remove the plan plugin and replace it with one Linear-backed development progress state skill. The replacement should manage only issue-scoped execution state on the current Linear issue, keep the issue description as generic briefing, reuse the issue-scoped checkpoint pattern rather than overloading issue_review_checkpoint itself, and stay strictly below decodex lifecycle authority so it cannot substitute for review handoff, delivery closeout, or terminal finalize.", - "key_evidence_ids": [ - "E1", - "E2", - "E3", - "E5", - "E6", - "E7", - "E8" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T3" - ] - }, - "judgment_hash": "sha256:bfe3105d292798eb2c3ec8ac8b72cd9c1b744ca917cc233c4f058053b378c135" - }, - { - "seq": 9, - "type": "worker_completed", - "worker": "skeptic", - "target_judgment_hash": "sha256:bfe3105d292798eb2c3ec8ac8b72cd9c1b744ca917cc233c4f058053b378c135", - "summary": "The strongest objection is non-blocking: the replacement must not overload issue_review_checkpoint itself. The judgment remains valid if the new skill uses a separate issue-scoped progress overlay on the current issue, keeps the issue description generic, and preserves issue_review_handoff, issue_terminal_finalize, and delivery_closeout as the only authoritative lifecycle signals.", - "objections": [] - }, - { - "seq": 10, - "type": "finalized_decision_ready", - "judgment_hash": "sha256:bfe3105d292798eb2c3ec8ac8b72cd9c1b744ca917cc233c4f058053b378c135", - "confidence": "medium", - "missing_evidence": [ - "The exact field list and write protocol for the replacement development progress state skill still need to be specified.", - "A migration plan for removing the plan plugin and replacing any current callers still needs to be written." - ] - } - ] -} diff --git a/docs/research/2026-04-02_plan-plugin-to-progress-skill-multiagent.json b/docs/research/2026-04-02_plan-plugin-to-progress-skill-multiagent.json deleted file mode 100644 index 4e5da8247..000000000 --- a/docs/research/2026-04-02_plan-plugin-to-progress-skill-multiagent.json +++ /dev/null @@ -1,224 +0,0 @@ -{ - "schema": "research-run/2", - "run_id": "2026-04-02_plan-plugin-to-progress-skill-multiagent", - "question": "Should decodex remove the plan plugin and replace it with one Linear-backed development progress state skill optimized for AI/agent/LLM execution state?", - "success_criteria": [ - "Determine whether removing the plan plugin is preferable to keeping or simplifying it.", - "Use explicit child-agent evaluation and challenge passes before finalizing.", - "Define the replacement as an issue-scoped Linear execution-state skill that preserves lifecycle boundaries." - ], - "constraints": [ - "Keep the routed Linear issue description as a generic briefing surface rather than plugin-private state.", - "Prefer one skill over a writing/execution split unless evidence shows the split is required.", - "Do not let the replacement skill substitute for review handoff, delivery closeout, or terminal finalize." - ], - "stop_rule": "Stop once the repository evidence plus explicit analyst and skeptic passes support a decision-ready recommendation or show that removing the plan plugin would leave unresolved lifecycle gaps.", - "primary_hypothesis": "The current repo needs one Linear-backed development progress state skill more than it needs a separate plan plugin, so the best fit is to remove the plan plugin and replace it with an issue-scoped progress-state skill.", - "rival_hypotheses": [ - "The plan plugin should stay and only be simplified because the runtime still needs durable strategy authority.", - "The best fit is to keep the plan plugin internals but collapse writing and execution into one skill instead of removing it." - ], - "falsifiers": [ - "If the runtime depends on linked-plan lineage or linked-plan documents for normal execution continuity, removing the plan plugin is insufficient.", - "If an issue-scoped Linear checkpoint cannot cover the state an agent needs for retries, verification, and review repair, the replacement skill is insufficient." - ], - "coverage": { - "mode": "standard", - "min_source_families": 0 - }, - "continuation": { - "mode": "auto_if_not_decision_ready", - "attempt": 1, - "max_attempts": 2, - "session_id": "2026-04-02_plan-plugin-to-progress-skill-multiagent" - }, - "events": [ - { - "seq": 1, - "type": "probe_completed", - "remaining_option_count": 3, - "independent_option_questions": [ - "Does normal decodex execution actually require durable strategy authority beyond issue-scoped execution checkpoints?", - "Would one Linear-backed progress-state skill fit the runtime better than either keeping plan or collapsing writing and execution into one skill?" - ], - "external_slices": [] - }, - { - "type": "evidence_recorded", - "evidence": [ - { - "id": "E1", - "kind": "observation", - "summary": "The runtime and README both position tracked planning as an execution overlay inside the retained lane rather than as decodex's primary lifecycle authority.", - "source_family": "repo_docs" - }, - { - "id": "E2", - "kind": "observation", - "summary": "The runtime says Linear is the source of truth for issue lifecycle and coarse outcomes, forbids a second long-lived business workflow model outside Linear, and requires the issue description to remain a generic briefing surface.", - "source_family": "repo_docs" - }, - { - "id": "E3", - "kind": "observation", - "summary": "The tracker tool contract already establishes an issue-scoped structured-checkpoint pattern via issue_review_checkpoint, which decodex treats as the only authoritative structured review-policy signal.", - "source_family": "repo_docs" - }, - { - "id": "E4", - "kind": "observation", - "summary": "The current plan plugin is explicitly split into writing and execution, with linked tracked-plan documents, append-only plan-event comments, and cross-surface validation before execution can proceed.", - "source_family": "repo_code" - }, - { - "id": "E5", - "kind": "observation", - "summary": "The current plan plugin surface is about 2082 lines across skills, templates, and contract helpers, which is large for a feature now described as an execution overlay.", - "source_family": "repo_code" - }, - { - "id": "E6", - "kind": "observation", - "summary": "Prior bounded research on the plan plugin concluded that the design still had unresolved runtime task-state, write-skew, lineage, and plan-local-done semantic gaps.", - "source_family": "repo_docs" - } - ], - "seq": 2 - }, - { - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T1", - "summary": "Removing the plan plugin aligns the common path with decodex's existing issue-scoped tracker authority and reduces control-plane complexity, but it gives up durable strategy lineage across replans.", - "supporting_evidence_ids": [ - "E1", - "E2", - "E5" - ], - "disconfirming_evidence_ids": [ - "E4" - ] - }, - { - "id": "T2", - "summary": "Keeping the plan plugin preserves a stronger durable planning contract for rare multi-session planning cases, but it forces a dual-surface strategy/runtime model onto the common path and carries known semantic debt.", - "supporting_evidence_ids": [ - "E4", - "E6" - ], - "disconfirming_evidence_ids": [ - "E1" - ] - }, - { - "id": "T3", - "summary": "Collapsing writing and execution into one skill would reduce entrypoints, but it would leave the linked-document plus event-log machinery mostly intact and therefore would not remove most of the complexity.", - "supporting_evidence_ids": [ - "E4", - "E5", - "E6" - ], - "disconfirming_evidence_ids": [] - } - ], - "seq": 3 - }, - { - "type": "inventory_updated", - "remaining_option_count": 2, - "independent_option_questions": [ - "Which option better matches decodex's existing authority boundaries: removing plan in favor of one issue-scoped Linear state skill, or keeping a durable planning subsystem?", - "Which option better minimizes common-path complexity without losing execution continuity the runtime actually depends on?" - ], - "external_slices": [], - "supporting_evidence_ids": [ - "E1", - "E2", - "E3", - "E4", - "E5", - "E6" - ], - "seq": 4 - }, - { - "type": "worker_completed", - "worker": "analyst", - "summary": "The analyst preferred removing the plan plugin in favor of one Linear-backed development progress state skill because it better matches decodex's existing Linear authority and issue-scoped checkpoint model, while the strongest counterargument is that removing plan also removes durable multi-step planning authority for minority replan-heavy workflows. Confidence: 0.81.", - "target_inventory_seq": 4, - "seq": 5 - }, - { - "type": "evidence_recorded", - "evidence": [ - { - "id": "E7", - "kind": "observation", - "summary": "The analyst found that option 1 fits better because decodex already centers Linear lifecycle authority and issue-scoped checkpoints, so a single Linear-backed progress-state skill aligns with the existing architecture more directly than a separate plan subsystem.", - "source_family": "repo_docs" - }, - { - "id": "E8", - "kind": "observation", - "summary": "The analyst's strongest counterargument is that deleting plan also deletes a real capability: durable multi-step plan authority and replan lineage for minority workflows, so the simplification is a deliberate scope reduction rather than a free cleanup.", - "source_family": "repo_docs" - } - ], - "seq": 6 - }, - { - "type": "inventory_updated", - "remaining_option_count": 1, - "independent_option_questions": [], - "external_slices": [], - "supporting_evidence_ids": [ - "E1", - "E2", - "E3", - "E5", - "E6", - "E7", - "E8" - ], - "seq": 7 - }, - { - "type": "judgment_candidate_created", - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "remove-plan-plugin-and-adopt-linear-progress-skill", - "rejected_options": [ - "keep-plan-plugin-and-simplify-it", - "collapse-plan-writing-and-execution-into-one-skill" - ], - "decision_claim": "Remove the plan plugin and replace it with one Linear-backed development progress state skill. The replacement should manage only issue-scoped execution state on the current Linear issue, keep the issue description as generic briefing, reuse the checkpoint pattern already established by issue_review_checkpoint, and stay strictly below decodex lifecycle authority so it cannot substitute for review handoff, delivery closeout, or terminal finalize.", - "key_evidence_ids": [ - "E1", - "E2", - "E3", - "E5", - "E6", - "E7", - "E8" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T3" - ] - }, - "seq": 8, - "judgment_hash": "sha256:5fd11b97dd08ac25be36c93ce15d03e2bd1e649cf0fd58ad669328dc22137f71" - }, - { - "type": "finalized_error", - "reason_code": "worker_timeout", - "details": "The explicit skeptic child-agent dispatch for the current judgment did not produce a collected result within the bounded collection window, so the multiagent research run cannot be finalized as decision-ready.", - "failed_workers": [ - "skeptic" - ], - "seq": 9 - } - ] -} diff --git a/docs/research/2026-04-02_plan-plugin-to-progress-skill.json b/docs/research/2026-04-02_plan-plugin-to-progress-skill.json deleted file mode 100644 index b85fe2dc1..000000000 --- a/docs/research/2026-04-02_plan-plugin-to-progress-skill.json +++ /dev/null @@ -1,206 +0,0 @@ -{ - "schema": "research-run/2", - "run_id": "2026-04-02_plan-plugin-to-progress-skill", - "question": "Should decodex remove the plan plugin and replace it with one Linear-backed development progress state skill optimized for AI/agent/LLM execution state?", - "success_criteria": [ - "Determine whether removing the plan plugin is preferable to keeping or simplifying it.", - "Define the smallest Linear-backed state-management surface that fits the current decodex lifecycle.", - "Preserve lifecycle authority boundaries so progress state cannot replace review handoff, closeout, or terminal finalize." - ], - "constraints": [ - "Keep the routed Linear issue description as a generic briefing surface rather than plugin-private state.", - "Prefer one skill over a writing/execution split unless evidence shows the split is required.", - "Do not require linked-plan documents or a separate durable strategy authority unless the runtime truly needs them." - ], - "stop_rule": "Stop once the repository evidence supports a decision-ready recommendation or shows that removing the plan plugin would leave unresolved lifecycle gaps.", - "primary_hypothesis": "The current repo needs a lightweight Linear-backed execution-state skill more than it needs a separate plan plugin, so the best fit is to remove the plan plugin and replace it with one issue-scoped progress-state skill.", - "rival_hypotheses": [ - "The plan plugin should stay and only be simplified because the runtime still needs durable strategy authority.", - "The best fit is to keep the plan plugin internals but collapse writing and execution into one skill instead of removing it." - ], - "falsifiers": [ - "If the current runtime depends on linked-plan revision lineage for normal execution continuity, removing the plan plugin is insufficient.", - "If a lightweight Linear-backed checkpoint cannot represent the state needed for retries, review repair, and verification boundaries, the replacement skill is insufficient." - ], - "coverage": { - "mode": "standard", - "min_source_families": 0 - }, - "continuation": { - "mode": "auto_if_not_decision_ready", - "attempt": 1, - "max_attempts": 2, - "session_id": "2026-04-02_plan-plugin-to-progress-skill" - }, - "events": [ - { - "seq": 1, - "type": "probe_completed", - "remaining_option_count": 3, - "independent_option_questions": [ - "Does the runtime need durable strategy authority beyond execution-state checkpoints for normal issue execution?", - "Can one issue-scoped Linear checkpoint cover the state transitions that agents actually need without reintroducing plan complexity?" - ], - "external_slices": [] - }, - { - "type": "evidence_recorded", - "evidence": [ - { - "id": "E1", - "kind": "observation", - "summary": "The runtime and README both position tracked planning as an execution overlay inside the retained lane rather than as decodex's primary lifecycle authority.", - "source_family": "repo_docs" - }, - { - "id": "E2", - "kind": "observation", - "summary": "The runtime says Linear is the source of truth for issue lifecycle and coarse outcomes, forbids a second long-lived business workflow model outside Linear, and requires the issue description to remain a generic briefing surface.", - "source_family": "repo_docs" - }, - { - "id": "E3", - "kind": "observation", - "summary": "The tracker tool contract already establishes an issue-scoped structured-checkpoint pattern via issue_review_checkpoint, which decodex treats as the only authoritative structured review-policy signal.", - "source_family": "repo_docs" - }, - { - "id": "E4", - "kind": "observation", - "summary": "The current plan plugin is explicitly split into writing and execution, with linked tracked-plan documents, append-only plan-event comments, and cross-surface validation before execution can proceed.", - "source_family": "repo_code" - }, - { - "id": "E5", - "kind": "observation", - "summary": "The current plan plugin surface is about 2082 lines across skills, templates, and contract helpers, which is large for a feature now described as an execution overlay.", - "source_family": "repo_code" - }, - { - "id": "E6", - "kind": "observation", - "summary": "Prior bounded research on the plan plugin concluded that the design still had unresolved runtime task-state, write-skew, lineage, and plan-local-done semantic gaps.", - "source_family": "repo_docs" - }, - { - "id": "E7", - "kind": "inference", - "summary": "The repo's higher-frequency need is a lightweight issue-scoped execution-state contract on Linear rather than a separate durable strategy-authority subsystem.", - "source_family": "repo_docs" - } - ], - "seq": 2 - }, - { - "type": "inventory_updated", - "remaining_option_count": 1, - "independent_option_questions": [], - "external_slices": [], - "supporting_evidence_ids": [ - "E1", - "E2", - "E3", - "E5", - "E6", - "E7" - ], - "seq": 3 - }, - { - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T1", - "summary": "Removing the plan plugin aligns the common path with decodex's existing issue-scoped tracker authority and reduces control-plane complexity, but it gives up durable strategy lineage across replans.", - "supporting_evidence_ids": [ - "E1", - "E2", - "E5" - ], - "disconfirming_evidence_ids": [ - "E4" - ] - }, - { - "id": "T2", - "summary": "A single Linear-backed progress-state skill fits the existing checkpoint pattern and the agent's real execution needs, but it must stay below lifecycle authority so it cannot replace review handoff, closeout, or terminal finalize.", - "supporting_evidence_ids": [ - "E2", - "E3", - "E7" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T3", - "summary": "Keeping the plan plugin preserves a stronger durable planning contract for rare multi-session planning cases, but it forces a dual-surface strategy/runtime model onto the common path and carries known semantic debt.", - "supporting_evidence_ids": [ - "E4", - "E6" - ], - "disconfirming_evidence_ids": [ - "E1", - "E7" - ] - }, - { - "id": "T4", - "summary": "Collapsing writing and execution into one skill would reduce surface count, but most of the complexity is in the linked-document plus event-log contract rather than in the number of skill entrypoints.", - "supporting_evidence_ids": [ - "E4", - "E5", - "E6" - ], - "disconfirming_evidence_ids": [] - } - ], - "seq": 4 - }, - { - "type": "judgment_candidate_created", - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "remove-plan-plugin-and-adopt-linear-progress-skill", - "rejected_options": [ - "keep-plan-plugin-and-simplify-it", - "collapse-plan-writing-and-execution-into-one-skill" - ], - "decision_claim": "Remove the plan plugin and replace it with one Linear-backed development progress state skill. The new skill should manage only issue-scoped execution state on the current Linear issue, keep the issue description as generic briefing, reuse the checkpoint pattern already established by issue_review_checkpoint, and stay strictly below decodex lifecycle authority so it cannot substitute for review handoff, delivery closeout, or terminal finalize.", - "key_evidence_ids": [ - "E1", - "E2", - "E3", - "E5", - "E6", - "E7" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T3", - "T4" - ] - }, - "seq": 5, - "judgment_hash": "sha256:6f37876de0e33898f204fe56e1144418894233df0ab79337b043f8e5956acebd" - }, - { - "type": "worker_completed", - "worker": "skeptic", - "summary": "The strongest objection is that removing the plan plugin also removes durable strategy lineage for rare replan-heavy workflows, but the current repo evidence shows that normal decodex execution does not depend on that authority. The replacement remains safe if the new skill is limited to issue-scoped execution state on Linear and cannot substitute for lifecycle signals such as review handoff or terminal finalize.", - "objections": [], - "seq": 6, - "target_judgment_hash": "sha256:6f37876de0e33898f204fe56e1144418894233df0ab79337b043f8e5956acebd" - }, - { - "type": "finalized_decision_ready", - "confidence": "medium", - "missing_evidence": [ - "The exact field list and write protocol for the replacement development progress state skill still need to be specified.", - "A migration plan for removing the plan plugin and replacing any current callers still needs to be written." - ], - "seq": 7, - "judgment_hash": "sha256:6f37876de0e33898f204fe56e1144418894233df0ab79337b043f8e5956acebd" - } - ] -} diff --git a/docs/research/2026-04-03_machine-first-landing-receipt.json b/docs/research/2026-04-03_machine-first-landing-receipt.json deleted file mode 100644 index 9a8ea7463..000000000 --- a/docs/research/2026-04-03_machine-first-landing-receipt.json +++ /dev/null @@ -1,309 +0,0 @@ -{ - "schema": "research-run/2", - "run_id": "2026-04-03_machine-first-landing-receipt", - "question": "How should Decodex encode machine-readable landing authority when the repository wants LLM-first history, does not care about human readability, and does not want empty commits for fast-forward landings?", - "success_criteria": [ - "Preserve machine-readable history that LLMs can inspect directly from Git.", - "Avoid squash-based loss of commit-level authority.", - "Avoid requiring empty commits when a landing can fast-forward cleanly." - ], - "constraints": [ - "Design for repository-local Git authority rather than markdown authority.", - "Assume human-readable history is not a goal.", - "Keep the protocol aligned with fully autonomous Decodex-controlled landing." - ], - "stop_rule": "Stop once one protocol shape is decision-ready with bounded repo-grounded evidence and a skeptic pass.", - "primary_hypothesis": "The best protocol separates content authority from landing receipt authority: keep machine-readable commit history on normal commits and record landing as a separate machine-readable receipt attached to the landed head without forcing a merge or empty commit.", - "rival_hypotheses": [ - "Always require a merge commit carrying the landing contract, even when fast-forward would otherwise be valid.", - "Keep squash landing and accept that landed history is not the machine authority.", - "Store landing receipts in git notes instead of a first-class Git object." - ], - "falsifiers": [ - "If the receipt cannot be fetched and enumerated reliably by default Git flows, the design is insufficient.", - "If the protocol still forces an artificial commit on a clean fast-forward landing, the design is insufficient.", - "If the protocol makes landed machine history less inspectable than the current commit history, the design is insufficient." - ], - "coverage": { - "mode": "standard", - "min_source_families": 0 - }, - "continuation": { - "mode": "auto_if_not_decision_ready", - "attempt": 1, - "max_attempts": 1, - "session_id": "2026-04-03_machine-first-landing-receipt" - }, - "events": [ - { - "seq": 1, - "type": "probe_completed", - "remaining_option_count": 1, - "independent_option_questions": [ - "Which Git-native object should carry landing receipt authority without forcing an empty commit on fast-forward landings?" - ], - "external_slices": [] - }, - { - "seq": 2, - "type": "evidence_recorded", - "evidence": [ - { - "id": "E1", - "kind": "observation", - "summary": "The current repository workflow now sets `[landing].merge_method = \"squash\"`, making GitHub-generated landed commit messages the effective mainline history shape instead of preserving machine-readable commit authority.", - "source_family": "repo_code" - }, - { - "id": "E2", - "kind": "observation", - "summary": "The merged mainline commit for PR #40 was rewritten by GitHub into a title-plus-bullets message, and the original single-line `delivery/1` JSON survived only as a bullet in the squash body rather than as the landed authority surface.", - "source_family": "repo_code" - }, - { - "id": "E3", - "kind": "observation", - "summary": "The repository allows merge commits, squash merges, and rebase merges, so preserving machine-readable landed history does not require squash and is not constrained to a single GitHub merge mode.", - "source_family": "repo_code" - }, - { - "id": "E4", - "kind": "inference", - "summary": "If landing authority is attached to the landed head as a separate first-class Git object, fast-forward landings can remain fast-forward while still carrying an explicit machine-readable receipt.", - "source_family": "repo_code" - } - ] - }, - { - "seq": 3, - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T1", - "summary": "Binding landing authority to a merge commit preserves everything in commit history, but it forces an otherwise unnecessary commit object whenever fast-forward landing is valid.", - "supporting_evidence_ids": [ - "E2", - "E4" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T2", - "summary": "Keeping commit history as the primary authority and storing a separate landing receipt preserves fast-forward behavior, but the receipt carrier must still be Git-native and easy for Decodex to enumerate.", - "supporting_evidence_ids": [ - "E1", - "E3", - "E4" - ], - "disconfirming_evidence_ids": [] - } - ] - }, - { - "seq": 4, - "type": "judgment_candidate_created", - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "commit-history-plus-annotated-tag-receipt", - "rejected_options": [ - "always-merge-commit-land-receipt", - "git-notes-landing-receipt", - "squash-based-landing" - ], - "decision_claim": "Use machine-readable per-commit history as the primary authority and represent landing as a separate receipt, preferably an annotated tag attached to the landed head. Preserve fast-forward when possible, avoid squash entirely, and never require an empty commit just to encode landing metadata.", - "key_evidence_ids": [ - "E1", - "E2", - "E3", - "E4" - ], - "key_tradeoff_ids": [ - "T1", - "T2" - ] - }, - "judgment_hash": "sha256:00db9e7beed46597b414e7ea5bc03bf2d6e3a9c9d7b617280b1650b3d4517051" - }, - { - "type": "worker_completed", - "worker": "skeptic", - "summary": "The original candidate was directionally right but not yet repo-grounded enough: this repo still sets `[landing].merge_method = \"squash\"`, and neither workflow contract nor runtime currently define receipt-tag authority or enumeration rules.", - "objections": [ - { - "id": "O1", - "summary": "Current repo policy still sets `[landing].merge_method = \"squash\"`, so the recommendation cannot be adopted immediately without an explicit workflow/spec policy change." - }, - { - "id": "O2", - "summary": "Annotated-tag receipts are not yet part of the repo-grounded contract; workflow/spec/runtime still need explicit receipt-tag fields, naming, fetch, and validation rules." - } - ], - "seq": 5, - "target_judgment_hash": "sha256:00db9e7beed46597b414e7ea5bc03bf2d6e3a9c9d7b617280b1650b3d4517051" - }, - { - "type": "evidence_recorded", - "evidence": [ - { - "id": "E5", - "kind": "contradiction", - "summary": "The active repo contract still says `[landing].merge_method = \"squash\"`, so the machine-first receipt design is not an immediate description of current behavior; it is a proposed replacement contract.", - "source_family": "repo_code" - }, - { - "id": "E6", - "kind": "missing_evidence", - "summary": "The repository does not yet define how `decodex/land/1` receipt tags are named, fetched, enumerated, validated, or cleaned up, so those rules must be added before the design can be implemented safely.", - "source_family": "repo_code" - } - ], - "seq": 6 - }, - { - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T3", - "summary": "Annotated-tag landing receipts solve the fast-forward empty-commit problem only if the repo contract explicitly teaches Decodex where receipts live and how to fetch and validate them; otherwise the design remains under-specified.", - "supporting_evidence_ids": [ - "E5", - "E6" - ], - "disconfirming_evidence_ids": [] - } - ], - "seq": 7 - }, - { - "type": "judgment_candidate_created", - "addresses_objection_ids": [ - "O1", - "O2" - ], - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "machine-first-ff-or-merge-with-annotated-tag-receipt", - "rejected_options": [ - "always-merge-commit-land-receipt", - "git-notes-landing-receipt", - "squash-based-landing" - ], - "decision_claim": "Adopt a machine-first landing contract in two layers: keep machine-readable per-commit history as the primary authority, and add a separate `decodex/land/1` landing receipt attached to the landed head as an annotated tag. To make that design valid in this repo, change `[landing]` away from `squash`, add explicit workflow/spec support for receipt tags and their fetch/enumeration rules, and teach Decodex runtime to create and validate them for both fast-forward and merge landings without requiring empty commits.", - "key_evidence_ids": [ - "E1", - "E2", - "E3", - "E4", - "E5", - "E6" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T3" - ] - }, - "judgment_hash": "sha256:7cd311b70536a0903e8d166b24089f350f98b756da8fbc1e8d7340ebb5084a08", - "seq": 8 - }, - { - "type": "worker_completed", - "worker": "skeptic", - "summary": "The revised candidate still needs one more repo-owned machine-readable policy surface: current `[landing]` only models merge, squash, or rebase, so an explicit fast-forward-vs-merge rule must be added rather than inferred.", - "objections": [ - { - "id": "O3", - "summary": "Add a machine-readable landing-mode field for `ff_then_merge`; current `[landing]` only models merge method, not the fast-forward-vs-merge choice." - } - ], - "seq": 9, - "target_judgment_hash": "sha256:7cd311b70536a0903e8d166b24089f350f98b756da8fbc1e8d7340ebb5084a08" - }, - { - "type": "evidence_recorded", - "evidence": [ - { - "id": "E7", - "kind": "observation", - "summary": "The current workflow contract only exposes `[landing].merge_method = merge|squash|rebase`, so a deterministic fast-forward-when-possible policy needs a new machine-readable field instead of runtime inference.", - "source_family": "repo_code" - } - ], - "seq": 10 - }, - { - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T4", - "summary": "Supporting fast-forward without empty commits requires a separate machine-readable landing-mode field, because merge method alone cannot express 'ff when possible, otherwise merge'.", - "supporting_evidence_ids": [ - "E7" - ], - "disconfirming_evidence_ids": [] - } - ], - "seq": 11 - }, - { - "type": "judgment_candidate_created", - "addresses_objection_ids": [ - "O3" - ], - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "machine-first-landing-with-ff-then-merge-and-annotated-tag-receipt", - "rejected_options": [ - "always-merge-commit-land-receipt", - "git-notes-landing-receipt", - "squash-based-landing" - ], - "decision_claim": "Design the protocol in three explicit layers. First, keep machine-readable per-commit history as the primary authority. Second, add `[landing].mode = \"ff_then_merge\"` so repository policy can say 'fast-forward when possible, otherwise create a merge commit', and treat existing `merge_method` as the fallback merge style when fast-forward is not available. Third, add `decodex/land/1` as a landing receipt carried by an annotated tag attached to the landed head, with explicit workflow/spec/runtime rules for naming, fetch, enumeration, validation, and cleanup. This preserves machine-readable history, avoids squash, and never requires an empty commit for fast-forward landings.", - "key_evidence_ids": [ - "E1", - "E2", - "E3", - "E4", - "E5", - "E6", - "E7" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T3", - "T4" - ] - }, - "judgment_hash": "sha256:b50de0fb7daaf465d94cc86e6e15822ff55d9d067451a0e48be6b8f0ff91204a", - "seq": 12 - }, - { - "type": "worker_completed", - "worker": "skeptic", - "summary": "The protocol direction is coherent, but two machine-authoritative contract pieces are still unspecified: the durable per-commit schema itself and the contract rules between a new fast-forward landing mode and the existing merge-method field.", - "objections": [ - { - "id": "O4", - "summary": "The repository no longer defines a durable machine-readable per-commit schema, so layer 1 needs an explicit replacement contract rather than relying on an ad hoc restored `delivery/1` commit." - }, - { - "id": "O5", - "summary": "A new `[landing].mode = \"ff_then_merge\"` field also needs explicit contract rules with `merge_method`, including which combinations are valid and which ones are forbidden." - } - ], - "seq": 13, - "target_judgment_hash": "sha256:b50de0fb7daaf465d94cc86e6e15822ff55d9d067451a0e48be6b8f0ff91204a" - }, - { - "type": "finalized_not_decision_ready", - "reason": "Bounded research found a strong direction, but the commit-level schema and landing-mode contract matrix still need explicit contract design before the protocol is safe to adopt.", - "missing_evidence": [ - "Choose the durable per-commit schema that replaces the deleted delivery contract, including required fields and authority semantics.", - "Define the exact contract rules between `[landing].mode` and `merge_method`, including which fallback merge styles remain valid when fast-forward is unavailable.", - "Specify how `decodex/land/1` annotated-tag receipts are named, fetched, enumerated, validated, and cleaned up." - ], - "seq": 14 - } - ] -} diff --git a/docs/research/2026-04-05_workspace-lifecycle-hooks-surface.json b/docs/research/2026-04-05_workspace-lifecycle-hooks-surface.json deleted file mode 100644 index f330a0295..000000000 --- a/docs/research/2026-04-05_workspace-lifecycle-hooks-surface.json +++ /dev/null @@ -1,182 +0,0 @@ -{ - "schema": "research-run/2", - "run_id": "2026-04-05_workspace-lifecycle-hooks-surface", - "question": "What is the smallest repo-owned workspace lifecycle hook surface that fits Decodex's goals without duplicating Codex host hooks or turning WORKFLOW.md into a generic plugin system?", - "success_criteria": [ - "Recommend a lifecycle-hook contract that is easy for repo owners to understand and audit.", - "Preserve Decodex runtime ownership of lane lifecycle while allowing limited repo-specific bootstrap and cleanup behavior.", - "Avoid duplicating host-level Codex controls or introducing a generic script escape hatch." - ], - "constraints": [ - "Keep the first slice aligned with the current WORKFLOW.md machine-readable style.", - "Prefer fail-closed behavior for destructive or state-changing phases.", - "Do not widen the design into a run-hook framework, plugin system, or background-service launcher." - ], - "stop_rule": "Stop once one narrow hook contract is decision-ready with repo-grounded and official-doc-backed tradeoffs.", - "primary_hypothesis": "The best first slice is an extensible workspace hook schema that only enables after_create and before_remove, leaving run-phase hooks out of scope until there is concrete repo pressure for them.", - "rival_hypotheses": [ - "Expose a fully generic lifecycle hook surface now, including before_run and after_run, so repos do not need another schema change later.", - "Do not add any repo-owned lifecycle hooks because host-level Codex hooks or runtime logic should absorb the need." - ], - "falsifiers": [ - "If current repo-specific bootstrap and cleanup needs cannot be expressed by after_create and before_remove, the proposed first slice is too narrow.", - "If the proposed hook surface lets repos smuggle orchestration policy, review policy, or host controls back into shell scripts, the design is too broad." - ], - "coverage": { - "mode": "standard", - "min_source_families": 0 - }, - "continuation": { - "mode": "auto_if_not_decision_ready", - "attempt": 1, - "max_attempts": 1, - "session_id": "2026-04-05_workspace-lifecycle-hooks-surface" - }, - "events": [ - { - "seq": 1, - "type": "probe_completed", - "remaining_option_count": 3, - "independent_option_questions": [ - "Should Decodex expose only workspace bootstrap and cleanup hooks, or also run-phase hooks such as before_run and after_run?", - "What boundary keeps repo-owned lifecycle policy from overlapping host-level Codex controls?" - ], - "external_slices": [] - }, - { - "seq": 2, - "type": "evidence_recorded", - "evidence": [ - { - "id": "E1", - "kind": "observation", - "summary": "The current workflow contract already prefers narrow, explicit, fail-closed machine-readable surfaces such as named gate profiles rather than a generic execution DSL.", - "source_family": "repo_spec" - }, - { - "id": "E2", - "kind": "observation", - "summary": "Decodex runtime already owns linked-worktree lane planning, creation, reuse, cleanup, retries, and reconciliation; repo policy should not replace that lifecycle authority.", - "source_family": "repo_spec" - }, - { - "id": "E3", - "kind": "observation", - "summary": "The current repo has no machine-readable WORKFLOW.md surface for repo-specific worktree bootstrap or pre-removal cleanup, so those behaviors still tend to live in runtime code or ad hoc local practice.", - "source_family": "repo_code" - }, - { - "id": "E4", - "kind": "observation", - "summary": "Kubernetes lifecycle hooks treat startup and shutdown hooks as explicit phase-bound handlers and emphasize that handlers may run more than once, so implementations should be idempotent and should not be treated as arbitrary orchestration logic.", - "source_family": "official_docs" - }, - { - "id": "E5", - "kind": "observation", - "summary": "systemd separates pre-start, start, stop, and post-stop actions explicitly, which keeps lifecycle sequencing understandable and keeps cleanup attached to shutdown semantics instead of general runtime scriptability.", - "source_family": "official_docs" - }, - { - "id": "E6", - "kind": "observation", - "summary": "Dev Container lifecycle scripts provide a useful cautionary pattern: named phases are workable, but once many phases exist, users must reason about subtle ordering and re-entry behavior.", - "source_family": "official_docs" - }, - { - "id": "E7", - "kind": "observation", - "summary": "npm lifecycle scripts show the downside of a broad phase matrix: once many script slots exist, repo behavior becomes harder to audit and script hooks become a catch-all escape hatch instead of a narrow contract.", - "source_family": "official_docs" - }, - { - "id": "E8", - "kind": "observation", - "summary": "Local Codex configuration exposes host-level controls such as approval policy, sandbox mode, and a codex_hooks feature flag, but there is no repo-visible stable contract here for expressing repo-owned worktree lifecycle policy.", - "source_family": "local_env" - } - ] - }, - { - "seq": 3, - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T1", - "summary": "A generic lifecycle hook system would reduce future schema additions, but it would immediately create ambiguity around attempt boundaries, continuation turns, review repair, and whether after_run failures should affect the primary run result.", - "supporting_evidence_ids": [ - "E2", - "E6", - "E7" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T2", - "summary": "Restricting the first slice to after_create and before_remove captures the most legitimate repo-specific needs, namely workspace bootstrap and cleanup, without reopening review, landing, or retry policy through shell hooks.", - "supporting_evidence_ids": [ - "E1", - "E2", - "E3", - "E5" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T3", - "summary": "Using an extensible schema with only two enabled phases keeps the architecture future-proof while still forcing the first release to earn additional phases through a separate design decision.", - "supporting_evidence_ids": [ - "E1", - "E6" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T4", - "summary": "Relying on Codex host hooks instead of WORKFLOW.md would hide repo policy in host configuration and make repo bootstrap or cleanup behavior non-portable and harder to audit in Git.", - "supporting_evidence_ids": [ - "E3", - "E8" - ], - "disconfirming_evidence_ids": [] - } - ] - }, - { - "seq": 4, - "type": "judgment_candidate_created", - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "extensible-schema-with-only-after-create-and-before-remove", - "rejected_options": [ - "generic-run-and-workspace-hook-system", - "host-hook-only-no-workflow-surface" - ], - "decision_claim": "Add a repo-owned workspace hook surface under WORKFLOW.md [execution.workspace_hooks], but only enable after_create and before_remove in the first slice. Keep runtime ownership of lane lifecycle, run hooks out of scope, hook execution serial and fail-closed, and limit the surface to lightweight idempotent bootstrap and cleanup commands rooted in the worktree.", - "key_evidence_ids": [ - "E1", - "E2", - "E3", - "E4", - "E5", - "E6", - "E7", - "E8" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T3", - "T4" - ] - }, - "judgment_hash": "sha256:7d9c597ea687e8c72297cde8a65057f4dc7a0c1d8db6e0705463e5eeb0b4e5de" - }, - { - "seq": 5, - "type": "finalized_decision_ready", - "judgment_hash": "sha256:7d9c597ea687e8c72297cde8a65057f4dc7a0c1d8db6e0705463e5eeb0b4e5de", - "summary": "Decision-ready: use a narrow workspace bootstrap and cleanup hook contract, not a generic lifecycle hook framework." - } - ] -} diff --git a/docs/research/2026-05-03_codex-cloud-task-apis.json b/docs/research/2026-05-03_codex-cloud-task-apis.json deleted file mode 100644 index 4f000378d..000000000 --- a/docs/research/2026-05-03_codex-cloud-task-apis.json +++ /dev/null @@ -1,625 +0,0 @@ -{ - "schema": "research-run/2", - "run_id": "2026-05-03_codex-cloud-task-apis", - "question": "Should Codex Cloud task APIs become part of Decodex execution modes, and under what constraints?", - "success_criteria": [ - "Map Codex Cloud task list, create, status, diff, and apply capabilities from source.", - "Compare those capabilities with Decodex's local app-server execution model and owned-lane lifecycle.", - "End with a decision-ready adopt, defer, or reject judgment while keeping local execution authoritative for the MVP." - ], - "constraints": [ - "No account-pool implementation changes.", - "No replacement of local codex app-server execution.", - "No credential or account-pool schema changes.", - "Any later implementation must be split into a separate issue." - ], - "stop_rule": "Stop once source evidence is sufficient to decide adopt, defer, or reject for Decodex's current execution model.", - "primary_hypothesis": "Codex Cloud task APIs are useful future remote-execution inputs, but should be deferred from Decodex until a separate remote-execution issue can preserve owned-lane lifecycle authority.", - "rival_hypotheses": [ - "Adopt Cloud tasks now as an alternate Decodex execution backend.", - "Reject Cloud task APIs permanently because they do not match Decodex's local app-server model." - ], - "falsifiers": [ - "If Cloud task APIs already expose Decodex-equivalent issue ownership, repo gate, and PR handoff semantics, immediate adoption would be viable.", - "If Cloud task APIs cannot expose task status, diff, or local apply primitives at all, future integration should be rejected rather than deferred.", - "If Decodex's local app-server model no longer owns execution, the local-MVP constraint would be obsolete." - ], - "coverage": { - "mode": "standard", - "min_source_families": 0 - }, - "continuation": { - "mode": "auto_if_not_decision_ready", - "attempt": 1, - "max_attempts": 3, - "session_id": "xy-451-attempt-4-1777808209" - }, - "events": [ - { - "seq": 1, - "type": "probe_completed", - "remaining_option_count": 1, - "independent_option_questions": [], - "external_slices": [] - }, - { - "seq": 2, - "type": "evidence_recorded", - "evidence": [ - { - "id": "E1", - "kind": "observation", - "summary": "The Cloud task client trait exposes list, summary/status, diff, messages/text, sibling attempts, preflight apply, apply, and create operations.", - "source_family": "codex_source", - "source_path": "/private/tmp/openai-codex/codex-rs/cloud-tasks-client/src/api.rs:133-163" - }, - { - "id": "E2", - "kind": "observation", - "summary": "The HTTP client maps Cloud list and create to backend task endpoints, with Codex API and ChatGPT backend path styles, and supports limit, task_filter, environment_id, and cursor query parameters.", - "source_family": "codex_source", - "source_path": "/private/tmp/openai-codex/codex-rs/backend-client/src/client.rs:320-424" - }, - { - "id": "E3", - "kind": "observation", - "summary": "Task summary/status derives from task_status_display/latest_turn_status_display, while task text exposes prompt, assistant messages, current turn id, sibling turn ids, placement, and attempt status.", - "source_family": "codex_source", - "source_path": "/private/tmp/openai-codex/codex-rs/cloud-tasks-client/src/http.rs:183-317" - }, - { - "id": "E4", - "kind": "observation", - "summary": "Cloud diff/apply fetches a unified diff from task details or uses an override, then applies locally from the current directory through codex_git_utils and git apply; preflight is git apply --check.", - "source_family": "codex_source", - "source_path": "/private/tmp/openai-codex/codex-rs/cloud-tasks-client/src/http.rs:252-520; /private/tmp/openai-codex/codex-rs/git-utils/src/apply.rs:37-104" - }, - { - "id": "E5", - "kind": "observation", - "summary": "The Cloud CLI wrapper surfaces exec, status, list, apply, and diff commands; exec requires an environment, can select a branch, and supports one to four attempts.", - "source_family": "codex_source", - "source_path": "/private/tmp/openai-codex/codex-rs/cloud-tasks/src/cli.rs:15-120" - }, - { - "id": "E6", - "kind": "observation", - "summary": "Decodex's MVP app-server contract is a local stdio JSON-RPC session using initialize, thread/start or thread/resume, turn/start, turn completion notifications, and dynamic tool calls for issue-scoped tracker writes.", - "source_family": "decodex_repo", - "source_path": "docs/spec/app-server.md:9-80; docs/spec/app-server.md:102-152" - }, - { - "id": "E7", - "kind": "observation", - "summary": "Decodex runtime authority is one local service, one isolated linked worktree lane per eligible issue, one direct app-server session per attempt, runtime DB ownership for active state, and Linear/GitHub as mirrors rather than live runtime backends.", - "source_family": "decodex_repo", - "source_path": "docs/spec/runtime.md:9-60; docs/spec/runtime.md:110-150" - }, - { - "id": "E8", - "kind": "observation", - "summary": "Decodex's successful completion path requires PR-backed review handoff, repo gate validation, and explicit terminal finalization; the runtime must not infer completion or bypass the handoff state.", - "source_family": "decodex_repo", - "source_path": "docs/spec/runtime.md:183-241; src/orchestrator/execution.rs:658-705" - }, - { - "id": "E9", - "kind": "observation", - "summary": "The owned-lane policy restricts runtime decisions to fixed action classes and requires manual intervention when retained lane, tracker, or PR signals disagree enough to require guessing.", - "source_family": "decodex_repo", - "source_path": "docs/spec/owned-lane-policy.md:26-69; docs/spec/owned-lane-policy.md:116-160" - }, - { - "id": "E10", - "kind": "observation", - "summary": "The operator control plane treats the runtime SQLite database as the active execution source of truth; Linear and GitHub remain collaboration and validation surfaces, not queue or lane ownership authority.", - "source_family": "decodex_repo", - "source_path": "docs/reference/operator-control-plane.md:16-57" - } - ] - }, - { - "seq": 3, - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T1", - "summary": "Cloud task list/status/diff data could help a future remote-observation or remote-execution mode, but the source surface does not carry Decodex's issue lease, repo gate, or PR handoff authority.", - "supporting_evidence_ids": [ - "E1", - "E2", - "E3", - "E6", - "E7", - "E8" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T2", - "summary": "Importing Cloud apply directly into Decodex would be unsafe unless wrapped by lane ownership, dirty-tree protection, repo gate validation, and PR-backed handoff, because Cloud apply is currently a local git apply primitive.", - "supporting_evidence_ids": [ - "E4", - "E7", - "E8", - "E9" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T3", - "summary": "Cloud create is plausible future work only as an explicit remote-execution mode that binds environment, branch, issue, and attempt identity up front, rather than an account-pool side effect.", - "supporting_evidence_ids": [ - "E2", - "E5", - "E7", - "E9" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T4", - "summary": "Deferring keeps the account-pool slice from becoming a remote-execution redesign while preserving the evidence that Cloud tasks have reusable task, diff, and apply primitives for a later scoped issue.", - "supporting_evidence_ids": [ - "E1", - "E4", - "E6", - "E7", - "E10" - ], - "disconfirming_evidence_ids": [] - } - ] - }, - { - "seq": 4, - "type": "judgment_candidate_created", - "judgment_payload": { - "judgment_type": "defer", - "preferred_option": "defer-cloud-task-integration", - "rejected_options": [ - "adopt-cloud-tasks-as-decodex-execution-backend-now", - "reject-cloud-tasks-permanently" - ], - "decision_claim": "Defer Codex Cloud task integration. Local codex app-server remains the authoritative MVP path. Cloud task APIs may belong later only behind an explicit, separately scoped remote-execution mode that maps one Cloud task to one Decodex-owned issue/lane, preserves repo-gate and PR-backed handoff, and does not reuse account-pool work as a hidden remote-execution redesign.", - "key_evidence_ids": [ - "E1", - "E2", - "E4", - "E6", - "E7", - "E8" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T3", - "T4" - ] - }, - "judgment_hash": "sha256:5a4707197057d9106e828560d302c9191a5ab44b150b1517bf6c226ae0f04019" - }, - { - "type": "worker_completed", - "worker": "skeptic", - "summary": "The defer recommendation is directionally correct, but the future-mode constraints must explicitly require issue-scoped tracker-tool and terminal-finalization parity, runtime liveness parity, and a comparison against app-server remote-environment support rather than assuming Cloud tasks are the only remote shape.", - "objections": [ - { - "id": "OBJ-001-tracker-tool-parity-missing", - "summary": "Preserving repo gate and PR-backed handoff is insufficient unless any future remote mode also preserves issue-scoped tracker tool calls and explicit issue_terminal_finalize semantics." - }, - { - "id": "OBJ-002-cloud-task-shape-may-be-the-wrong-remote-shape", - "summary": "The future path should not assume one Cloud task per lane is the right abstraction because app-server already exposes environment selection plus dynamic tools while Decodex relies on repeated turn/start calls on one thread." - }, - { - "id": "OBJ-003-operator-liveness-parity-omitted", - "summary": "The constraints must require runtime-observability parity for protocol events, liveness fields, stall detection, and recovery; Cloud task summaries and diffs alone do not satisfy Decodex's operator model." - } - ], - "seq": 5, - "target_judgment_hash": "sha256:5a4707197057d9106e828560d302c9191a5ab44b150b1517bf6c226ae0f04019" - }, - { - "type": "evidence_recorded", - "evidence": [ - { - "id": "E11", - "kind": "observation", - "summary": "Decodex's tracker bridge requires issue-scoped tool calls for transition, comment, progress checkpoint, review checkpoint, review handoff, label add, and terminal finalization; invalid or missing terminal signals must fail the attempt.", - "source_family": "decodex_repo", - "source_path": "docs/spec/tracker-tools.md:18-59; docs/spec/tracker-tools.md:63-83; docs/spec/tracker-tools.md:85-130" - }, - { - "id": "E12", - "kind": "observation", - "summary": "The Codex app-server protocol already exposes experimental thread/start and turn/start environment selections alongside dynamic tools and raw-event support, so future remote work must compare Cloud tasks with an app-server environment extension before choosing an execution shape.", - "source_family": "codex_source", - "source_path": "/private/tmp/openai-codex/codex-rs/app-server-protocol/src/protocol/v2.rs:3548-3618; /private/tmp/openai-codex/codex-rs/app-server-protocol/src/protocol/v2.rs:5519-5544; /private/tmp/openai-codex/codex-rs/app-server/src/codex_message_processor.rs:2788-2837; /private/tmp/openai-codex/codex-rs/app-server/src/codex_message_processor.rs:3001-3019" - }, - { - "id": "E13", - "kind": "observation", - "summary": "Decodex operator visibility depends on runtime DB protocol journals, active-lane heartbeat, liveness fields, stall detection, and event-count hydration, which task summaries and diffs do not provide by themselves.", - "source_family": "decodex_repo", - "source_path": "docs/spec/runtime.md:290-316; docs/spec/runtime.md:318-338; docs/spec/runtime.md:348-378" - }, - { - "id": "E14", - "kind": "observation", - "summary": "The Cloud task command runtime wires exec to create_task, status to get_task_summary, list to paginated list_tasks, diff to collected attempt diffs, and apply to selected attempt diff plus local apply_task; the TUI also supports preflight/apply and detail loading around those primitives.", - "source_family": "codex_source", - "source_path": "/private/tmp/openai-codex/codex-rs/cloud-tasks/src/lib.rs:157-180; /private/tmp/openai-codex/codex-rs/cloud-tasks/src/lib.rs:493-603; /private/tmp/openai-codex/codex-rs/cloud-tasks/src/lib.rs:614-724; /private/tmp/openai-codex/codex-rs/cloud-tasks/src/lib.rs:1845-1965" - } - ], - "seq": 6 - }, - { - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T5", - "summary": "A future remote-execution mode cannot be accepted merely because it can create a task and return a patch; it must preserve issue-scoped tracker tools, terminal finalization, repo gate validation, PR handoff, and lane-scoped Git ownership.", - "supporting_evidence_ids": [ - "E4", - "E7", - "E8", - "E11" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T6", - "summary": "Codex app-server environment support may be a better future remote abstraction than Cloud tasks because it is closer to Decodex's existing thread, turn, dynamic-tool, and event-stream model; a later issue should compare both shapes before implementation.", - "supporting_evidence_ids": [ - "E6", - "E7", - "E11", - "E12", - "E13" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T7", - "summary": "Until Cloud task APIs can provide tracker-tool parity and liveness/event parity, their safest Decodex use is read-only observation or explicit patch import/apply inside an already owned local lane, not authoritative execution replacement.", - "supporting_evidence_ids": [ - "E1", - "E3", - "E4", - "E11", - "E13", - "E14" - ], - "disconfirming_evidence_ids": [] - } - ], - "seq": 7 - }, - { - "type": "judgment_candidate_created", - "addresses_objection_ids": [ - "OBJ-001-tracker-tool-parity-missing", - "OBJ-002-cloud-task-shape-may-be-the-wrong-remote-shape", - "OBJ-003-operator-liveness-parity-omitted" - ], - "judgment_payload": { - "judgment_type": "defer", - "preferred_option": "defer-cloud-task-integration-and-keep-local-app-server-mvp", - "rejected_options": [ - "adopt-cloud-tasks-as-decodex-execution-backend-now", - "reject-cloud-task-apis-permanently", - "hide-remote-execution-inside-account-pool-work", - "choose-cloud-task-backend-before-comparing-app-server-remote-environments" - ], - "decision_claim": "Defer Codex Cloud task integration. Local codex app-server remains the authoritative Decodex MVP path. Cloud task APIs are useful future evidence for list/create/status/diff/apply and may support read-only observation or explicit patch import later, but authoritative remote execution must be a separate issue that compares Cloud tasks with app-server remote-environment support and preserves issue-scoped tracker tools, explicit terminal finalization, runtime liveness/event hydration, repo-gate validation, PR-backed handoff, and lane-scoped Git ownership. Account-pool work must not carry Cloud task execution, credential schema, or remote-execution lifecycle changes.", - "key_evidence_ids": [ - "E1", - "E2", - "E4", - "E6", - "E7", - "E8", - "E11", - "E12", - "E13", - "E14" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T4", - "T5", - "T6", - "T7" - ] - }, - "seq": 8, - "judgment_hash": "sha256:45bf9826204b1a2d32600f03cdde58526f7feeb0f5117fcef1f3952acc360c37" - }, - { - "type": "worker_completed", - "worker": "skeptic", - "summary": "The revised defer judgment addresses the earlier remote-execution objections, but its patch-import clause still needs to carry the owned-lane, dirty-tree, routed-identity, repo-gate, and PR-handoff qualifiers in the decision claim itself.", - "objections": [ - { - "id": "OBJ-004-patch-import-safety-omitted", - "summary": "The decision claim's patch-import wording must explicitly restrict any future Cloud diff/apply use to an already owned local lane with clean/checked worktree state, routed identity, repo-gate validation, and PR-backed handoff." - } - ], - "seq": 9, - "target_judgment_hash": "sha256:45bf9826204b1a2d32600f03cdde58526f7feeb0f5117fcef1f3952acc360c37" - }, - { - "type": "evidence_recorded", - "evidence": [ - { - "id": "E15", - "kind": "observation", - "summary": "Decodex lane Git and review operations depend on routed GitHub credentials and worktree-local identity inheritance; patch import/apply must therefore remain inside a Decodex-owned linked worktree with the correct routed identity rather than operating on an arbitrary cwd.", - "source_family": "decodex_repo", - "source_path": "docs/spec/runtime.md:152-166; docs/spec/tracker-tools.md:108-122; src/worktree.rs:1420-1481" - } - ], - "seq": 10 - }, - { - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T8", - "summary": "Patch import from Cloud task diffs is only acceptable as a future lane-owned workflow: preflight against the owned linked worktree, protect dirty state, preserve routed Git/Linear identity, run the repo gate, and complete PR-backed handoff through Decodex rather than treating Cloud apply as an external authority.", - "supporting_evidence_ids": [ - "E4", - "E8", - "E11", - "E15" - ], - "disconfirming_evidence_ids": [] - } - ], - "seq": 11 - }, - { - "type": "judgment_candidate_created", - "addresses_objection_ids": [ - "OBJ-004-patch-import-safety-omitted" - ], - "judgment_payload": { - "judgment_type": "defer", - "preferred_option": "defer-cloud-task-integration-and-keep-local-app-server-mvp", - "rejected_options": [ - "adopt-cloud-tasks-as-decodex-execution-backend-now", - "reject-cloud-task-apis-permanently", - "hide-remote-execution-inside-account-pool-work", - "choose-cloud-task-backend-before-comparing-app-server-remote-environments", - "allow-cloud-diff-apply-outside-an-owned-clean-decodex-lane" - ], - "decision_claim": "Defer Codex Cloud task integration. Local codex app-server remains the authoritative Decodex MVP path. Cloud task APIs are useful future evidence for list/create/status/diff/apply and may support read-only observation later. Explicit Cloud patch import/apply is only a possible future lane-owned workflow, and only if a separate issue proves preflight against the owned linked worktree, dirty-tree protection, routed Git/Linear identity, repo-gate validation, and PR-backed handoff through Decodex. Authoritative remote execution must be a separate issue that compares Cloud tasks with app-server remote-environment support and preserves issue-scoped tracker tools, explicit terminal finalization, runtime liveness/event hydration, repo-gate validation, PR-backed handoff, and lane-scoped Git ownership. Account-pool work must not carry Cloud task execution, credential schema, or remote-execution lifecycle changes.", - "key_evidence_ids": [ - "E1", - "E2", - "E4", - "E6", - "E7", - "E8", - "E11", - "E12", - "E13", - "E14", - "E15" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T4", - "T5", - "T6", - "T7", - "T8" - ] - }, - "seq": 12, - "judgment_hash": "sha256:483bc8f58842f2f113359833a3c80e63ae1b3c431c2de413a207ac80b73d2614" - }, - { - "type": "worker_completed", - "worker": "skeptic", - "summary": "The judgment is close, but the future remote-execution identity contract must explicitly bind Cloud task creation to Decodex issue, run, attempt, branch, and environment identity.", - "objections": [ - { - "id": "OBJ-005-remote-run-identity-binding-omitted", - "summary": "Any future Cloud create/execution mode must bind environment, branch, issue identity, run_id, and attempt_number up front so task, sibling-attempt, review, and closeout recovery can reconcile safely against Decodex runtime authority." - } - ], - "seq": 13, - "target_judgment_hash": "sha256:483bc8f58842f2f113359833a3c80e63ae1b3c431c2de413a207ac80b73d2614" - }, - { - "type": "evidence_recorded", - "evidence": [ - { - "id": "E16", - "kind": "observation", - "summary": "Cloud task creation currently binds environment_id, branch/git_ref, qa mode, and best_of_n attempts, while Decodex lane recovery and handoff identity are keyed by issue identity, run_id, attempt_number, branch, PR head, and runtime DB ownership; a future remote mode must bridge both identity models explicitly.", - "source_family": "mixed_source", - "source_path": "/private/tmp/openai-codex/codex-rs/cloud-tasks-client/src/api.rs:162-169; /private/tmp/openai-codex/codex-rs/cloud-tasks-client/src/http.rs:319-379; /private/tmp/openai-codex/codex-rs/cloud-tasks/src/lib.rs:157-180; docs/spec/runtime.md:72-80; docs/spec/runtime.md:110-150; docs/spec/runtime.md:217-241; docs/spec/runtime.md:348-378" - } - ], - "seq": 14 - }, - { - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T9", - "summary": "A future Cloud execution mode must establish task-to-lane identity at creation time by binding environment, branch, issue identifier/id, run_id, and attempt_number, otherwise sibling attempts, liveness, review handoff, retained recovery, and closeout cannot be reconciled safely.", - "supporting_evidence_ids": [ - "E2", - "E7", - "E8", - "E13", - "E16" - ], - "disconfirming_evidence_ids": [] - } - ], - "seq": 15 - }, - { - "type": "judgment_candidate_created", - "addresses_objection_ids": [ - "OBJ-005-remote-run-identity-binding-omitted" - ], - "judgment_payload": { - "judgment_type": "defer", - "preferred_option": "defer-cloud-task-integration-and-keep-local-app-server-mvp", - "rejected_options": [ - "adopt-cloud-tasks-as-decodex-execution-backend-now", - "reject-cloud-task-apis-permanently", - "hide-remote-execution-inside-account-pool-work", - "choose-cloud-task-backend-before-comparing-app-server-remote-environments", - "allow-cloud-diff-apply-outside-an-owned-clean-decodex-lane", - "create-cloud-tasks-without-decodex-run-and-attempt-identity" - ], - "decision_claim": "Defer Codex Cloud task integration. Local codex app-server remains the authoritative Decodex MVP path. Cloud task APIs are useful future evidence for list/create/status/diff/apply and may support read-only observation later. Explicit Cloud patch import/apply is only a possible future lane-owned workflow, and only if a separate issue proves preflight against the owned linked worktree, dirty-tree protection, routed Git/Linear identity, repo-gate validation, and PR-backed handoff through Decodex. Authoritative remote execution must be a separate issue that compares Cloud tasks with app-server remote-environment support and preserves issue-scoped tracker tools, explicit terminal finalization, runtime liveness/event hydration, repo-gate validation, PR-backed handoff, and lane-scoped Git ownership. Any future Cloud create/execution path must bind environment_id, branch/git_ref, Linear issue identity, Decodex run_id, and attempt_number before task creation so task status, sibling attempts, liveness, review handoff, retained recovery, and closeout can reconcile to one owned lane. Account-pool work must not carry Cloud task execution, credential schema, or remote-execution lifecycle changes.", - "key_evidence_ids": [ - "E1", - "E2", - "E4", - "E6", - "E7", - "E8", - "E11", - "E12", - "E13", - "E14", - "E15", - "E16" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T4", - "T5", - "T6", - "T7", - "T8", - "T9" - ] - }, - "seq": 16, - "judgment_hash": "sha256:1b33cd90ee31a9d3898380f658af5a18b5e8895688f4095ba4926d4d8565766b" - }, - { - "type": "worker_completed", - "worker": "skeptic", - "summary": "The defer judgment is still plausible, but read-only observation also needs an explicit provenance requirement because current Cloud list/create surfaces do not carry Decodex issue/run/attempt identity by themselves.", - "objections": [ - { - "id": "OBJ-006-read-only-observation-provenance-gap", - "summary": "Read-only Cloud task observation must not hydrate Decodex operator state unless a future issue proves a durable Decodex-owned mapping or backend metadata channel for issue, run_id, and attempt_number provenance." - } - ], - "seq": 17, - "target_judgment_hash": "sha256:1b33cd90ee31a9d3898380f658af5a18b5e8895688f4095ba4926d4d8565766b" - }, - { - "type": "evidence_recorded", - "evidence": [ - { - "id": "E17", - "kind": "observation", - "summary": "Current Cloud task list summaries expose task id, title, status, timestamp, environment label, diff summary, review flag, and attempt_total, with environment_id unset in list mapping; create sends metadata only for best_of_n and returns only the created task id, so Decodex provenance is not available from those surfaces alone.", - "source_family": "codex_source", - "source_path": "/private/tmp/openai-codex/codex-rs/cloud-tasks-client/src/api.rs:33-50; /private/tmp/openai-codex/codex-rs/cloud-tasks-client/src/http.rs:319-380; /private/tmp/openai-codex/codex-rs/cloud-tasks-client/src/http.rs:717-732" - } - ], - "seq": 18 - }, - { - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T10", - "summary": "Even read-only Cloud task observation must remain non-authoritative until a future issue proves provenance through a Decodex-owned task mapping or backend metadata channel that round-trips issue id, issue identifier, run_id, and attempt_number on list/details.", - "supporting_evidence_ids": [ - "E7", - "E10", - "E13", - "E16", - "E17" - ], - "disconfirming_evidence_ids": [] - } - ], - "seq": 19 - }, - { - "type": "judgment_candidate_created", - "addresses_objection_ids": [ - "OBJ-006-read-only-observation-provenance-gap" - ], - "judgment_payload": { - "judgment_type": "defer", - "preferred_option": "defer-cloud-task-integration-and-keep-local-app-server-mvp", - "rejected_options": [ - "adopt-cloud-tasks-as-decodex-execution-backend-now", - "reject-cloud-task-apis-permanently", - "hide-remote-execution-inside-account-pool-work", - "choose-cloud-task-backend-before-comparing-app-server-remote-environments", - "allow-cloud-diff-apply-outside-an-owned-clean-decodex-lane", - "create-cloud-tasks-without-decodex-run-and-attempt-identity", - "hydrate-decodex-operator-state-from-cloud-tasks-without-provenance" - ], - "decision_claim": "Defer Codex Cloud task integration. Local codex app-server remains the authoritative Decodex MVP path. Cloud task APIs are useful future evidence for list/create/status/diff/apply, but even read-only observation must stay non-authoritative until a separate issue proves a Decodex-owned task mapping or backend metadata channel that round-trips Linear issue id/identifier plus Decodex run_id and attempt_number on task list/details. Explicit Cloud patch import/apply is only a possible future lane-owned workflow, and only if a separate issue proves preflight against the owned linked worktree, dirty-tree protection, routed Git/Linear identity, repo-gate validation, and PR-backed handoff through Decodex. Authoritative remote execution must be a separate issue that compares Cloud tasks with app-server remote-environment support and preserves issue-scoped tracker tools, explicit terminal finalization, runtime liveness/event hydration, repo-gate validation, PR-backed handoff, and lane-scoped Git ownership. Any future Cloud create/execution path must bind environment_id, branch/git_ref, Linear issue identity, Decodex run_id, and attempt_number before task creation so task status, sibling attempts, liveness, review handoff, retained recovery, and closeout can reconcile to one owned lane. Account-pool work must not carry Cloud task execution, credential schema, or remote-execution lifecycle changes.", - "key_evidence_ids": [ - "E1", - "E2", - "E4", - "E6", - "E7", - "E8", - "E11", - "E12", - "E13", - "E14", - "E15", - "E16", - "E17" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T4", - "T5", - "T6", - "T7", - "T8", - "T9", - "T10" - ] - }, - "seq": 20, - "judgment_hash": "sha256:9d5873aefa6a6e9e5ceef5c8f340dbe008f8666483c1666b9c9afec48ab9c9ac" - }, - { - "type": "worker_completed", - "worker": "skeptic", - "summary": "No remaining objection blocks decision-ready finalization after the judgment requires separate issue scope, tracker/terminal/liveness parity, task-to-lane identity binding, provenance for read-only observation, and owned-lane safeguards for any patch import/apply path.", - "objections": [], - "seq": 21, - "target_judgment_hash": "sha256:9d5873aefa6a6e9e5ceef5c8f340dbe008f8666483c1666b9c9afec48ab9c9ac" - }, - { - "type": "finalized_decision_ready", - "confidence": "medium", - "missing_evidence": [ - "A live disposable Cloud task metadata round-trip was not performed; the future issue must verify whether list/details can carry Decodex issue/run/attempt provenance.", - "A live non-local codex app-server environment run with dynamic tools and event hydration was not performed; the future issue must compare that app-server shape against Cloud tasks before implementation." - ], - "seq": 22, - "judgment_hash": "sha256:9d5873aefa6a6e9e5ceef5c8f340dbe008f8666483c1666b9c9afec48ab9c9ac" - } - ] -} diff --git a/docs/research/2026-05-13_codex-radar-skill-split.json b/docs/research/2026-05-13_codex-radar-skill-split.json deleted file mode 100644 index ed0ce2657..000000000 --- a/docs/research/2026-05-13_codex-radar-skill-split.json +++ /dev/null @@ -1,243 +0,0 @@ -{ - "schema": "research-run/2", - "run_id": "2026-05-13_codex-radar-skill-split", - "question": "How should Decodex read upstream Codex code, latest commits, releases, and public posting patterns so Radar output can improve Control Plane and Publisher work without overclaiming?", - "success_criteria": [ - "Separate fast upstream triage from code-aware analysis and final signal drafting.", - "Preserve current deterministic artifact boundaries for GitHub bundles, analysis drafts, rendered signals, upstream-impact classifications, release deltas, and social drafts.", - "Use X account observations as style benchmarks only, not technical evidence.", - "End with a skill split that can be used manually now and can be wired into automation incrementally." - ], - "constraints": [ - "Do not make X posts or operate an X composer from the research pass.", - "Do not introduce new durable intermediate artifact schemas unless validators and gates are added in the same change.", - "Do not imply sparse upstream release bodies prove product behavior.", - "Keep installable Decodex plugin skills separate from repo-local development skills under dev/skills/." - ], - "stop_rule": "Stop once the skill routing decision is clear enough to update repo-local skills, docs, and the current Codex analysis prompt without changing the social publication approval boundary.", - "primary_hypothesis": "Decodex should split Radar work into repo-local reasoning skills for upstream triage, code analysis, release analysis, and X drafting, while keeping github-signal as the final analysis_draft authoring step and avoiding new intermediate artifacts.", - "rival_hypotheses": [ - "Keep one large github-signal skill for the whole workflow.", - "Create first-class checked-in triage, code-analysis, and release-analysis artifacts immediately.", - "Treat release posts and X posts as sufficient source material for public Decodex claims." - ], - "falsifiers": [ - "If the existing automation already consumes separate triage, code-analysis, and release-analysis artifacts, the manual-only split would understate current behavior.", - "If X style observations can produce a valid social_post_draft/v1 without GitHub, changelog, signal, or upstream-impact evidence, the evidence boundary would be too strict.", - "If sparse release bodies contain enough detail to support confirmed claims, the compare-first release rule would be too conservative." - ], - "coverage": { - "mode": "standard", - "min_source_families": 0 - }, - "continuation": { - "mode": "manual_if_not_decision_ready", - "attempt": 1, - "max_attempts": 1, - "session_id": "2026-05-13_codex-radar-skill-split" - }, - "events": [ - { - "seq": 1, - "type": "probe_completed", - "remaining_option_count": 3, - "independent_option_questions": [ - "Should analysis be one skill or a small staged set of repo-local skills?", - "Should intermediate triage and code-analysis outputs become durable artifacts now?", - "How should public X posting style benchmarks influence Decodex output without becoming source evidence?" - ], - "external_slices": [ - "Latest openai/codex GitHub commits and release metadata.", - "Public X account posting patterns for @Codex_Changelog, @LLMJunky, and @decodexspace." - ] - }, - { - "seq": 2, - "type": "evidence_recorded", - "evidence": [ - { - "id": "E1", - "kind": "observation", - "summary": "The latest upstream Codex commits observed on 2026-05-13 included tool-search handler encapsulation, app-server websocket listener restoration with an auth guard, plugin version/share gating, hook requirement changes, provider routing, and cleanup of an SSE fixture hook.", - "source_family": "github_api", - "source_locator": "https://api.github.com/repos/openai/codex/commits?per_page=8" - }, - { - "id": "E2", - "kind": "observation", - "summary": "Commit 51bfb5f3b115 restored an app-server websocket listener with an auth guard and touched app-server transport/auth code, which is relevant to Decodex Control Plane integration.", - "source_family": "github_api", - "source_locator": "https://github.com/openai/codex/commit/51bfb5f3b115" - }, - { - "id": "E3", - "kind": "observation", - "summary": "Commit d1430fd61e4a exposed plugin versions and gated plugin sharing, touching app-server protocol schemas and plugin summary/share surfaces.", - "source_family": "github_api", - "source_locator": "https://github.com/openai/codex/commit/d1430fd61e4a" - }, - { - "id": "E4", - "kind": "observation", - "summary": "Commit 104fc1495646 encapsulated tool-search entries in handlers and touched tool-search handler and registry code, a likely Radar trigger but still requiring code-path analysis before publication.", - "source_family": "github_api", - "source_locator": "https://github.com/openai/codex/commit/104fc1495646" - }, - { - "id": "E5", - "kind": "observation", - "summary": "Recent rust-v0.131.0 alpha GitHub release bodies were title-like and sparse, so release metadata alone is insufficient evidence for confirmed feature claims.", - "source_family": "github_release_api", - "source_locator": "https://api.github.com/repos/openai/codex/releases" - }, - { - "id": "E6", - "kind": "observation", - "summary": "@Codex_Changelog uses fast automated release-bullet posts: version headline, a few feature bullets, and source links. This is useful for release_pulse formatting but not enough for deeper Decodex claims.", - "source_family": "public_x_observation", - "source_locator": "https://x.com/Codex_Changelog" - }, - { - "id": "E7", - "kind": "observation", - "summary": "@LLMJunky posts more practical Codex workflow analysis, focusing on what a user can try, why it matters in real usage, and where the limitation remains.", - "source_family": "public_x_observation", - "source_locator": "https://x.com/LLMJunky" - }, - { - "id": "E8", - "kind": "observation", - "summary": "@decodexspace had no observed posts in the public page pass, so Decodex can define its own evidence-backed style rather than preserving existing account conventions.", - "source_family": "public_x_observation", - "source_locator": "https://x.com/decodexspace" - }, - { - "id": "E9", - "kind": "observation", - "summary": "The current automation path discovers recent upstream commits, resolves them back to PRs when possible, builds a GitHub bundle, runs Codex to produce an analysis_draft JSON, renders a signal_entry/v1, validates signal entries, and refreshes release_delta/v1.", - "source_family": "decodex_repo", - "source_path": "scripts/github/sync_latest_signals.py; scripts/github/run_codex_analysis.py; scripts/github/render_signal_entry.py" - }, - { - "id": "E10", - "kind": "observation", - "summary": "The durable content contracts currently present for this workflow are GitHub bundles, analysis drafts, rendered signal entries, upstream-impact classifications, release deltas, and social post drafts; no triage-note or code-analysis-note schema is present.", - "source_family": "decodex_repo", - "source_path": "docs/spec/github-change-bundle.md; scripts/github/analysis_draft.schema.json; docs/spec/signal-entry.md; docs/spec/upstream-impact.md; docs/spec/release-delta.md; docs/spec/social-post-draft.md" - } - ] - }, - { - "seq": 3, - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T1", - "summary": "Splitting the workflow into staged repo-local skills improves selectivity and lets Radar distinguish commit triage, behavior reading, release interpretation, final signal drafting, and public post drafting.", - "supporting_evidence_ids": [ - "E1", - "E2", - "E3", - "E4", - "E9" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T2", - "summary": "Creating durable triage or code-analysis artifacts now would add contract and gate obligations that the current scripts do not satisfy.", - "supporting_evidence_ids": [ - "E9", - "E10" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T3", - "summary": "Release analysis should compare sparse release metadata against commits, PRs, existing signals, and release_delta/v1 rather than duplicating release-bot summaries.", - "supporting_evidence_ids": [ - "E5", - "E6", - "E9" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T4", - "summary": "X observations are useful for cadence, structure, and tone, but all Decodex technical claims still need GitHub, changelog, signal, or upstream-impact evidence.", - "supporting_evidence_ids": [ - "E6", - "E7", - "E8", - "E10" - ], - "disconfirming_evidence_ids": [] - } - ] - }, - { - "seq": 4, - "type": "judgment_candidate_created", - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "split-repo-local-radar-skills-with-existing-artifact-boundaries", - "rejected_options": [ - "single-large-github-signal-skill", - "new-durable-intermediate-artifacts-now", - "social-or-release-posts-as-technical-source-evidence" - ], - "decision_claim": "Split Decodex Radar into manual reasoning skills for upstream triage, code analysis, release analysis, and X drafting; keep durable outputs limited to existing checked-in contracts; wire only in-session code-analysis into run_codex_analysis prompt for current automation.", - "key_evidence_ids": [ - "E1", - "E5", - "E6", - "E7", - "E9", - "E10" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T3", - "T4" - ] - }, - "judgment_hash": "sha256:a100c2d386d45be8039eaa5aba398de72287d58e95258cef87df6fb224179d3a" - }, - { - "seq": 5, - "type": "worker_completed", - "worker": "skeptic", - "target_judgment_hash": "sha256:a100c2d386d45be8039eaa5aba398de72287d58e95258cef87df6fb224179d3a", - "summary": "The split is useful only if it preserves artifact boundaries, avoids undocumented intermediate outputs, does not imply current automation already orchestrates all new skills, and blocks style-only social drafting.", - "objections": [ - { - "id": "OBJ-001-artifact-seam-drift", - "summary": "Keep github-signal scoped to analysis_draft authoring, not direct signal_entry/v1 production." - }, - { - "id": "OBJ-002-missing-intermediate-artifact-contracts", - "summary": "Either keep triage/code/release notes non-durable or add paths, schemas, validators, and gates." - }, - { - "id": "OBJ-003-automation-doc-drift", - "summary": "Docs must not imply current scripts already orchestrate all new skills unless scripts are wired." - }, - { - "id": "OBJ-004-style-only-social-bypass", - "summary": "A style-only X observation must not lead directly to a social_post_draft/v1." - }, - { - "id": "OBJ-005-release-analysis-overlap", - "summary": "Release analysis must feed existing upstream_impact, signal, release_delta, or social draft contracts instead of creating duplicate judgment." - } - ] - }, - { - "seq": 6, - "type": "finalized_decision_ready", - "judgment_hash": "sha256:a100c2d386d45be8039eaa5aba398de72287d58e95258cef87df6fb224179d3a", - "summary": "Decision-ready: split the repo-local Radar skills, keep triage/code/release outputs as non-durable reasoning passes, wire in-session code-analysis into the current analysis_draft prompt, and require source-backed evidence before X drafting." - } - ] -} diff --git a/docs/research/2026-06-09_decodex-loop-engineering-and-research-lane.json b/docs/research/2026-06-09_decodex-loop-engineering-and-research-lane.json deleted file mode 100644 index d5afb86cc..000000000 --- a/docs/research/2026-06-09_decodex-loop-engineering-and-research-lane.json +++ /dev/null @@ -1,510 +0,0 @@ -{ - "schema": "research-run/2", - "run_id": "2026-06-09_decodex-loop-engineering-and-research-lane", - "question": "How should Decodex incorporate loop engineering, Codex goal, and a Decodex-native research lane so ambiguous user intent can flow into better decisions, execution, validation, and self-improving automation without making the human surface more complex?", - "success_criteria": [ - "Explain loop engineering as an actionable product and runtime direction for Decodex, not only as a slogan.", - "Decide whether research should remain a separate generic skill, become a Decodex-native component, or be replaced by execution-only automation.", - "Define how Codex app-server goal should be used with Decodex retained lanes without giving up Decodex tracker, PR, validation, and recovery authority.", - "Preserve the user's natural-language-first workflow and keep DAG or loop mechanics backstage unless an operator asks for inspection.", - "Identify implementation priorities, correctness gates, and telemetry/eval hooks needed for future automation and self-improvement." - ], - "constraints": [ - "Do not make everyday users learn graph, DAG, dry-run, apply, queue, or goal commands to get value.", - "Do not treat research output as repository authority unless it is promoted into spec, runbook, reference, or decision lanes.", - "Do not let Codex goal completion bypass Decodex repo gates, PR/Linear handoff, retry policy, or needs-attention handling.", - "Do not couple Decodex to the generic research skill in a way that prevents a Decodex-native research lane from replacing it.", - "Prefer capability-gated use of Codex app-server protocol rather than assumptions about a latest Codex build." - ], - "stop_rule": "Stop once the product direction, architecture split, research role, Codex goal integration boundary, implementation slices, and unresolved risks are clear enough to write specs/issues in a later delivery pass.", - "primary_hypothesis": "Decodex should become a natural-language-first development loop runtime: a Decodex-native Research/Decision Lane turns ambiguous intent into evidence-backed decisions, an internal Execution Program/DAG tracks dependencies, Codex goal drives inner implementation continuation where available, and Decodex owns outer validation, tracker, PR, recovery, and harness-improvement loops.", - "rival_hypotheses": [ - "Keep Decodex focused on retained implementation lanes and leave research as a separate generic skill used before Decodex.", - "Make first-class DAG management the main product surface and ask users or agents to operate graph commands explicitly.", - "Use Codex goal as the whole orchestration layer and remove most Decodex continuation, retry, tracker, and validation logic.", - "Build a generic loop engine detached from Decodex-specific Linear/GitHub/worktree/runtime semantics." - ], - "falsifiers": [ - "If Codex app-server does not expose goal methods or goal continuation, Decodex cannot rely on Codex goal as the inner execution primitive.", - "If Decodex current runtime already has equivalent goal semantics and durable decision/research state, this proposal would be redundant.", - "If research artifacts cannot be replayed, validated, or converted into implementation programs, research would remain a chat artifact rather than a loop component.", - "If users must learn new graph/loop commands for ordinary requests, the product direction violates the user's explicit workflow constraint.", - "If the internal Execution Program/DAG requires plan-private parsing, arbitrary workflow node types, or tracker mutation before dry-run/readback semantics are stable, the design is too broad.", - "If Codex goal complete can be wrong often and Decodex does not add independent validation, the integration would degrade correctness instead of improving it." - ], - "coverage": { - "mode": "broad_external", - "min_source_families": 5 - }, - "continuation": { - "mode": "auto_if_not_decision_ready", - "attempt": 1, - "max_attempts": 1, - "session_id": "2026-06-09_decodex-loop-engineering-and-research-lane" - }, - "events": [ - { - "seq": 1, - "type": "probe_completed", - "remaining_option_count": 4, - "independent_option_questions": [ - "Should research remain a generic skill, or become a Decodex-native research/decision lane?", - "Should Codex goal own Decodex lane continuation, or should Decodex continue to use only max-turn bounded retries?", - "Should the execution graph/DAG be a user-facing workflow or an internal program state?", - "Which loop telemetry and eval hooks are required so research improves downstream automation instead of becoming a one-off report?" - ], - "external_slices": [] - }, - { - "seq": 2, - "type": "evidence_recorded", - "evidence": [ - { - "id": "E1", - "kind": "observation", - "summary": "OpenAI's Harness Engineering article frames the shift as humans designing environments, specifying intent, and building feedback loops so Codex agents can work reliably; it also describes PR completion through review, feedback handling, and iterative loops.", - "source_family": "openai_article", - "source_locator": "https://openai.com/index/harness-engineering/" - }, - { - "id": "E2", - "kind": "observation", - "summary": "OpenAI's App Server article says Codex surfaces share the same harness and app-server exposes it through a client-friendly bidirectional JSON-RPC API with thread lifecycle, config/auth, tool execution, persistence, and event streams.", - "source_family": "openai_article", - "source_locator": "https://openai.com/index/unlocking-the-codex-harness/" - }, - { - "id": "E3", - "kind": "observation", - "summary": "OpenAI's Codex agent-loop article identifies the harness as the core loop orchestrating user input, model reasoning, tools, observations, planning, and final responses.", - "source_family": "openai_article", - "source_locator": "https://openai.com/index/unrolling-the-codex-agent-loop/" - }, - { - "id": "E4", - "kind": "observation", - "summary": "OpenAI Symphony turns Linear into a control plane: each open issue maps to an isolated agent workspace, agents run continuously, DAG dependencies govern readiness, and agents can create follow-up work. The article also warns that rigid state-machine nodes became too limiting and teams moved toward objectives.", - "source_family": "openai_article", - "source_locator": "https://openai.com/index/open-source-codex-orchestration-symphony/" - }, - { - "id": "E5", - "kind": "observation", - "summary": "Symphony's SPEC defines a long-running automation service that reads an issue tracker, creates isolated per-issue workspaces, runs coding-agent sessions, owns orchestrator state for dispatch/retry/reconciliation, and keeps ticket-writing business logic in prompts/tools rather than in the scheduler.", - "source_family": "open_source_spec", - "source_locator": "https://raw.githubusercontent.com/openai/symphony/main/SPEC.md" - }, - { - "id": "E6", - "kind": "observation", - "summary": "The official openai/codex app-server README lists thread/goal/set, thread/goal/get, thread/goal/clear, thread/goal/updated, and thread/goal/cleared as protocol methods/notifications for a persisted materialized-thread goal.", - "source_family": "open_source_code", - "source_locator": "https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md" - }, - { - "id": "E7", - "kind": "observation", - "summary": "Local Codex 0.139.0-alpha.2 reports goals as a stable enabled feature, and the local goals SQLite schema stores per-thread objective, status, token budget, tokens used, and elapsed time.", - "source_family": "local_env", - "source_locator": "codex --version; codex features list; sqlite3 /Users/x/.codex/goals_1.sqlite .schema thread_goals" - }, - { - "id": "E8", - "kind": "observation", - "summary": "Generated local app-server JSON schema contains thread/goal/set, thread/goal/get, thread/goal/clear, thread/goal/updated, and thread/goal/cleared, proving the current local app-server protocol exposes goal methods.", - "source_family": "local_schema", - "source_locator": "codex app-server generate-json-schema --experimental --out /tmp/codex-loop-schema.rPseni" - }, - { - "id": "E9", - "kind": "observation", - "summary": "OpenAI Codex goal runtime source calls continue_if_idle for active goals, reads the active goal from state, builds a continuation steering item, and starts another turn only if the thread is idle.", - "source_family": "open_source_code", - "source_locator": "https://github.com/openai/codex/blob/main/codex-rs/ext/goal/src/runtime.rs" - }, - { - "id": "E10", - "kind": "observation", - "summary": "OpenAI Codex goal tool specs expose create_goal, get_goal, and update_goal; update_goal only lets the model mark a goal complete or blocked, while pause/resume, budget-limited, and usage-limited transitions remain user/system controlled.", - "source_family": "open_source_code", - "source_locator": "https://github.com/openai/codex/blob/main/codex-rs/ext/goal/src/spec.rs" - }, - { - "id": "E11", - "kind": "observation", - "summary": "Decodex's current app-server spec is capability-gated and supports initialize, bounded preflight, thread/start, thread/resume, turn/start, thread/archive, command/exec, and dynamic tool bridge, but it does not yet include thread/goal methods in the required contract.", - "source_family": "decodex_repo", - "source_path": "docs/spec/app-server.md" - }, - { - "id": "E12", - "kind": "observation", - "summary": "Decodex runtime currently runs one or more bounded turns on an app-server thread and decides after each turn whether to continue, validate, enter needs_attention, or yield to retry based on execution.max_turns and tracker state.", - "source_family": "decodex_repo", - "source_path": "docs/spec/runtime.md" - }, - { - "id": "E13", - "kind": "observation", - "summary": "Decodex requires explicit terminal disposition before success writeback: review_handoff and manual_attention have required signals, forbidden co-signals, repo gate behavior, and issue_terminal_finalize; checkpoints alone are not terminal completion.", - "source_family": "decodex_repo", - "source_path": "docs/spec/runtime.md" - }, - { - "id": "E14", - "kind": "observation", - "summary": "Decodex documentation policy says docs/research is supporting evidence only, not runtime truth, procedure, current state, or rationale; durable guidance must be promoted into spec, runbook, reference, or decisions.", - "source_family": "decodex_repo", - "source_path": "docs/policy.md; docs/reference/research-runs.md" - }, - { - "id": "E15", - "kind": "observation", - "summary": "little-loops frames harness loops as FSM patterns wrapping a skill or prompt in layered quality evaluation, emphasizing that running a skill is easy while knowing output quality is hard.", - "source_family": "third_party_tooling", - "source_locator": "https://docs.little-loops.ai/guides/LOOPS_GUIDE/" - }, - { - "id": "E16", - "kind": "observation", - "summary": "Wiggum's agent mode reads a backlog, prioritizes issues by labels and dependencies, generates specs, runs a Ralph loop per issue, reviews diffs against the spec, and auto-merges when checks pass.", - "source_family": "third_party_tooling", - "source_locator": "https://wiggum.app/" - }, - { - "id": "E17", - "kind": "observation", - "summary": "A Wiggum Ralph Loop explainer describes phases of plan, implement, test, verify, and PR, with checkpoints and explicit verification against the original spec to catch cases where code compiles but does not satisfy requirements.", - "source_family": "third_party_tooling", - "source_locator": "https://wiggum.app/blog/what-is-the-ralph-loop/" - }, - { - "id": "E18", - "kind": "observation", - "summary": "The AI Harness Engineering paper identifies task specification, context selection, tool access, project memory, task state, observability, failure attribution, verification, permissions, entropy auditing, and intervention recording as harness responsibilities, and reframes success as verifiably correct, attributed, maintainable change.", - "source_family": "research_paper", - "source_locator": "https://arxiv.org/abs/2605.13357" - }, - { - "id": "E19", - "kind": "observation", - "summary": "Agentic Harness Engineering proposes a closed-loop harness evolution approach with component observability, experience observability, and decision observability so harness edits are explicit, consumable, and later verified against outcomes.", - "source_family": "research_paper", - "source_locator": "https://arxiv.org/abs/2604.25850" - }, - { - "id": "E20", - "kind": "observation", - "summary": "HarnessFix argues failed agent trajectories require step-level provenance, failure attribution to harness layers, scoped repair operators, and regression-aware validation rather than broad final-outcome-only prompt changes.", - "source_family": "research_paper", - "source_locator": "https://arxiv.org/abs/2606.06324" - }, - { - "id": "E21", - "kind": "observation", - "summary": "User-provided Addy Osmani X material described Loop Engineering as replacing yourself as the person who prompts the agent, with Codex/Claude primitives such as automations, worktrees, skills/plugins/connectors, subagents, memory, and goal-like persistence.", - "source_family": "provided_material", - "source_locator": "https://x.com/addyosmani/status/2064127981161959567" - }, - { - "id": "E22", - "kind": "observation", - "summary": "User-provided Matt Van Horn X material framed a loop as a small program that prompts the coding agent, reads output, decides whether it is done, and prompts again; the newer layer is multi-agent supervision and orchestration, with verification and loop management as the hard parts.", - "source_family": "provided_material", - "source_locator": "https://x.com/mvanhorn/status/2063865685558903149" - }, - { - "id": "E23", - "kind": "observation", - "summary": "Prior Decodex workflow discussion rejected a user-visible DAG workflow after the user said graph mechanics felt more cumbersome than the current natural-language Codex workflow, and converged on internal Decision Lane / Execution Program framing.", - "source_family": "conversation_memory", - "source_locator": "/Users/x/.codex/memories/MEMORY.md" - }, - { - "id": "E24", - "kind": "missing_evidence", - "summary": "No current Decodex spec or implementation evidence shows a Decodex-native research lane with durable decision state, accepted-decision gates, reusable evidence packs, or automatic research-to-execution program generation.", - "source_family": "decodex_repo", - "source_path": "docs/; apps/decodex/src/; plugins/decodex/" - }, - { - "id": "E25", - "kind": "observation", - "summary": "The valuable part of the prior DAG direction is not a user-facing graph workflow but an internal Execution Program: broad objectives still need lineage, dependencies, stage, conflict-domain, acceptance, queue intent, ready-node selection, and drift handling, while executable nodes remain ordinary Decodex-dispatchable issues.", - "source_family": "derived_analysis", - "source_locator": "synthesis from Symphony DAG evidence, Decodex runtime constraints, and interim DAG-priority analysis" - } - ] - }, - { - "seq": 3, - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T1", - "summary": "Using Codex goal as Decodex's inner execution continuation primitive reduces duplicated turn-loop logic and aligns with current Codex app-server capability, but Decodex must keep independent outer validation because goal completion is a model claim, not proof of PR/Linear correctness.", - "supporting_evidence_ids": [ - "E6", - "E7", - "E8", - "E9", - "E10", - "E12", - "E13" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T2", - "summary": "Replacing the generic research skill with a Decodex-native Research/Decision Lane improves continuity from evidence to execution and lets research artifacts feed later harness improvements, but only if research state remains validated, replayable, and promotable into authoritative docs when needed.", - "supporting_evidence_ids": [ - "E14", - "E18", - "E19", - "E20", - "E23", - "E24" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T3", - "summary": "Keeping DAG/Execution Program internal preserves the user's natural-language workflow while still enabling ready-node queueing, dependency unlocking, parallelism, and later operator inspection.", - "supporting_evidence_ids": [ - "E4", - "E5", - "E16", - "E17", - "E23" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T4", - "summary": "A user-visible loop or graph command surface would expose useful mechanics but would recreate the friction the user explicitly rejected and would compete with the existing Codex conversation surface.", - "supporting_evidence_ids": [ - "E21", - "E22", - "E23" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T5", - "summary": "Treating research as a loop component rather than a one-off prelude increases downstream quality: better hypotheses and falsifiers become better execution programs, validators, issue slices, PR review prompts, and future harness repairs.", - "supporting_evidence_ids": [ - "E1", - "E15", - "E18", - "E19", - "E20", - "E21", - "E22" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T6", - "summary": "A generic loop engine would be reusable, but Decodex's biggest leverage is already in Decodex-specific tracker leases, worktrees, PR/Linear handoff, repo gates, operator snapshots, and recovery semantics; detaching the loop engine would lose those invariants.", - "supporting_evidence_ids": [ - "E5", - "E11", - "E12", - "E13", - "E18" - ], - "disconfirming_evidence_ids": [] - }, - { - "id": "T7", - "summary": "The DAG branch should be absorbed into the loop-runtime branch as backstage Execution Program semantics. This keeps the useful dependency and ready-node machinery while avoiding a second product surface and preserving the natural-language intake flow.", - "supporting_evidence_ids": [ - "E4", - "E5", - "E11", - "E12", - "E13", - "E23", - "E25" - ], - "disconfirming_evidence_ids": [] - } - ] - }, - { - "seq": 4, - "type": "judgment_candidate_created", - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "decodex-loop-runtime-with-native-research-lane-and-codex-goal-inner-execution", - "rejected_options": [ - "user-visible-dag-or-loop-command-surface", - "keep-research-as-standalone-external-skill", - "current-max-turns-only-without-codex-goal", - "generic-loop-engine-detached-from-decodex-runtime" - ], - "decision_claim": "Decodex should evolve into a natural-language-first development loop runtime. The front of the loop should be a Decodex-native Research/Decision Lane that converts ambiguous intent into evidence, options, objections, and accepted decisions. Accepted decisions feed an internal Execution Program/DAG and retained implementation lanes. The Execution Program should absorb the useful DAG semantics: objective lineage, dependencies, stage, conflict-domain, acceptance, queue intent, ready-node selection, and drift handling stored outside ordinary issue descriptions, with executable nodes still materialized as normal Decodex-dispatchable issues. When Codex app-server goal support is available, Decodex should set a thread goal and let Codex goal own inner idle continuation, while Decodex retains outer authority over tracker leases, validation, PR/Linear handoff, status, recovery, and harness-improvement feedback. Research should be treated as a high-leverage component that improves every downstream loop and should itself produce reusable evidence for future harness, skill, prompt, validator, and issue-template improvements.", - "key_evidence_ids": [ - "E1", - "E2", - "E3", - "E4", - "E5", - "E6", - "E7", - "E8", - "E9", - "E10", - "E11", - "E12", - "E13", - "E14", - "E15", - "E16", - "E17", - "E18", - "E25" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T3", - "T4", - "T5", - "T6", - "T7" - ] - }, - "judgment_hash": "sha256:1d6e2f771f2d0be753410808af66cc12109471759bcb75b9d1d0e366422120c0" - }, - { - "seq": 5, - "type": "worker_completed", - "worker": "skeptic", - "target_judgment_hash": "sha256:1d6e2f771f2d0be753410808af66cc12109471759bcb75b9d1d0e366422120c0", - "summary": "The recommendation is strong but only if Decodex treats goal as an inner primitive rather than a replacement control plane, keeps research outputs non-authoritative until promoted, exposes only natural-language intake by default, and builds evaluation/telemetry before claiming self-improvement.", - "objections": [ - { - "id": "OBJ-001-goal-overtrust", - "summary": "Codex goal complete can be wrong or overconfident. Decodex must treat it as a signal to validate, not as done." - }, - { - "id": "OBJ-002-research-authority-drift", - "summary": "A Decodex-native research lane can create impressive artifacts that drift into policy. Promotion into spec, runbook, reference, or decisions must remain explicit." - }, - { - "id": "OBJ-003-ux-regression", - "summary": "If users need to say dry-run, apply, queue, ready, goal, graph, or DAG for normal work, the product has failed the user's core workflow constraint." - }, - { - "id": "OBJ-004-loop-runaway", - "summary": "Goal-driven loops need budgets, no-progress detection, stale-state detection, and human decision gates or they can turn cost into churn." - }, - { - "id": "OBJ-005-research-quality-illusion", - "summary": "Research only improves downstream automation when evidence, falsifiers, objections, and accepted decisions are machine-readable and later compared against execution outcomes." - }, - { - "id": "OBJ-006-scope-creep", - "summary": "A generic loop engine would be tempting, but the first Decodex version should stay grounded in Decodex lane, tracker, worktree, PR, and repo-gate semantics." - } - ] - }, - { - "type": "tradeoffs_recorded", - "tradeoffs": [ - { - "id": "T8", - "summary": "The skeptic objections are addressed by making goal completion only a validation trigger, requiring explicit promotion for research-derived authority, keeping graph and goal mechanics backstage, enforcing budgets and no-progress/stale-state stops, measuring research-to-execution outcomes, and scoping the first implementation to Decodex lane, tracker, worktree, PR, and repo-gate semantics.", - "supporting_evidence_ids": [ - "E10", - "E13", - "E14", - "E18", - "E19", - "E20", - "E23", - "E25" - ], - "disconfirming_evidence_ids": [] - } - ], - "seq": 6 - }, - { - "type": "judgment_candidate_created", - "addresses_objection_ids": [ - "OBJ-001-goal-overtrust", - "OBJ-002-research-authority-drift", - "OBJ-003-ux-regression", - "OBJ-004-loop-runaway", - "OBJ-005-research-quality-illusion", - "OBJ-006-scope-creep" - ], - "judgment_payload": { - "judgment_type": "recommend", - "preferred_option": "decodex-loop-runtime-with-native-research-lane-and-codex-goal-inner-execution", - "rejected_options": [ - "user-visible-dag-or-loop-command-surface", - "keep-research-as-standalone-external-skill", - "current-max-turns-only-without-codex-goal", - "generic-loop-engine-detached-from-decodex-runtime" - ], - "decision_claim": "Decodex should evolve into a natural-language-first development loop runtime. The front of the loop should be a Decodex-native Research/Decision Lane that converts ambiguous intent into evidence, options, objections, and accepted decisions. Accepted decisions feed an internal Execution Program/DAG and retained implementation lanes. The Execution Program should absorb the useful DAG semantics: objective lineage, dependencies, stage, conflict-domain, acceptance, queue intent, ready-node selection, and drift handling stored outside ordinary issue descriptions, with executable nodes still materialized as normal Decodex-dispatchable issues. When Codex app-server goal support is available, Decodex should set a thread goal and let Codex goal own inner idle continuation, while Decodex retains outer authority over tracker leases, validation, PR/Linear handoff, status, recovery, and harness-improvement feedback. Research should be treated as a high-leverage component that improves every downstream loop and should itself produce reusable evidence for future harness, skill, prompt, validator, and issue-template improvements.", - "key_evidence_ids": [ - "E1", - "E2", - "E3", - "E4", - "E5", - "E6", - "E7", - "E8", - "E9", - "E10", - "E11", - "E12", - "E13", - "E14", - "E15", - "E16", - "E17", - "E18", - "E25" - ], - "key_tradeoff_ids": [ - "T1", - "T2", - "T3", - "T4", - "T5", - "T6", - "T7", - "T8" - ] - }, - "seq": 7, - "judgment_hash": "sha256:cf51a788d29f1e3bcc7c589cba665c214f486b0f50e882dcccf1eb1add64a447" - }, - { - "type": "worker_completed", - "worker": "skeptic", - "summary": "The replacement judgment addresses the prior objections by binding goal completion to independent validation, research authority to explicit promotion, UX to natural-language intake, loop continuation to budget and no-progress stops, research quality to outcome telemetry, and scope to Decodex-specific runtime invariants.", - "objections": [], - "seq": 8, - "target_judgment_hash": "sha256:cf51a788d29f1e3bcc7c589cba665c214f486b0f50e882dcccf1eb1add64a447" - }, - { - "type": "finalized_decision_ready", - "summary": "Decision-ready: build Decodex as a natural-language-first development loop runtime. Prioritize a Decodex-native Research/Decision Lane, internal Execution Program/DAG, capability-gated Codex goal integration for inner execution continuation, independent Decodex validation and handoff, and a harness-improvement loop that mines research and execution outcomes for future skills, prompts, validators, and workflow changes. The earlier DAG direction should be deleted as a separate branch and retained only as the internal Execution Program contract.", - "confidence": "high", - "missing_evidence": [ - "No implementation spike has yet proven Decodex thread/goal/set integration against a live retained lane.", - "No current Decodex spec defines the Decodex-native research lane schema, accepted-decision gate, or research-to-execution-program handoff.", - "No current metric baseline measures whether better research improves downstream PR success, validation passes, reduced manual attention, or fewer stale follow-ups." - ], - "seq": 9, - "judgment_hash": "sha256:cf51a788d29f1e3bcc7c589cba665c214f486b0f50e882dcccf1eb1add64a447" - } - ] -} diff --git a/docs/research/legacy-research-goal-audit.json b/docs/research/legacy-research-goal-audit.json new file mode 100644 index 000000000..f2b32f639 --- /dev/null +++ b/docs/research/legacy-research-goal-audit.json @@ -0,0 +1,238 @@ +{ + "schema": "decodex.research_report/1", + "title": "Legacy Research Goal Audit", + "purpose": "Consolidate the removed legacy docs/research JSON runs into one current-state audit with retained value points for future Decodex research.", + "read_when": [ + "Need to know whether an old machine-authored research target was implemented, superseded, or still contains useful follow-up direction." + ], + "not_this_artifact": [ + "The Decodex research method.", + "The runtime schema.", + "An operator runbook.", + "A raw event log archive." + ], + "scope": { + "legacy_schema": "research-run/2", + "legacy_files": [ + "docs/research/2026-03-31_decodex-plan-boundary-v2.json", + "docs/research/2026-03-31_decodex-plan-boundary-v3.json", + "docs/research/2026-03-31_decodex-plan-boundary/run.json", + "docs/research/2026-04-01_plan-linear-decoupled-design/run.json", + "docs/research/2026-04-02_delivery-skill-removal-with-agents.json", + "docs/research/2026-04-02_drop-delivery-skills.json", + "docs/research/2026-04-02_plan-plugin-to-progress-skill-multiagent-decision.json", + "docs/research/2026-04-02_plan-plugin-to-progress-skill-multiagent.json", + "docs/research/2026-04-02_plan-plugin-to-progress-skill.json", + "docs/research/2026-04-03_machine-first-landing-receipt.json", + "docs/research/2026-04-05_workspace-lifecycle-hooks-surface.json", + "docs/research/2026-05-03_codex-cloud-task-apis.json", + "docs/research/2026-05-13_codex-radar-skill-split.json", + "docs/research/2026-06-09_decodex-loop-engineering-and-research-lane.json" + ], + "cleanup_status": "Raw old-shape event logs were removed from the tracked tree after value extraction. Use Git history only when raw legacy event-log provenance is needed." + }, + "status_summary": [ + { + "legacy_target": "Plan-backed issue boundary, v2 and first run", + "current_status": "Superseded by the current generic-briefing boundary. The old not-decision-ready gap is closed by refusing to treat a machine-only issue body as the agent briefing.", + "repo_evidence": [ + "apps/decodex/src/orchestrator/dispatch_policy.rs", + "apps/decodex/src/orchestrator/tests/intake/run_and_prompting.rs" + ], + "retained_value": "Keep Decodex plan-agnostic. A machine pointer must not replace the stable human-readable issue brief unless a separate generic briefing surface exists." + }, + { + "legacy_target": "Plan-backed issue boundary, v3", + "current_status": "Implemented as current baseline.", + "repo_evidence": [ + "apps/decodex/src/orchestrator/dispatch_policy.rs" + ], + "retained_value": "Preserve the rule when future plan, progress, or MCP surfaces add richer machine context." + }, + { + "legacy_target": "Plan/Linear decoupled design", + "current_status": "Not implemented as a plan plugin; value extracted and superseded by internal Execution Program and issue-scoped checkpointing.", + "repo_evidence": [ + "docs/spec/loop-runtime.md", + "docs/spec/tracker-tools.md", + "apps/decodex/src/execution_program.rs" + ], + "retained_value": "If a plan/progress adapter returns, it needs explicit lineage, sequence, runtime-owned task state, event history, and a rule that plan-local done is not lane terminal completion." + }, + { + "legacy_target": "Delivery skill removal and drop-delivery designs", + "current_status": "Partially absorbed. Runtime-owned closeout, post-review lifecycle, and issue-scoped tracker tools exist, but the Decodex planning skill still references external delivery issue/split shaping.", + "repo_evidence": [ + "docs/spec/post-review-lifecycle.md", + "docs/spec/tracker-tools.md", + "plugins/decodex/skills/planning/SKILL.md" + ], + "retained_value": "Future Decodex plugin self-containment should remove the residual external delivery dependency only after Decodex-native issue shaping exists." + }, + { + "legacy_target": "Plan plugin to progress skill runs", + "current_status": "Superseded by the current issue_progress_checkpoint model.", + "repo_evidence": [ + "docs/spec/tracker-tools.md", + "docs/spec/linear-execution-ledger.md", + "apps/decodex/src/agent/app_server.rs" + ], + "retained_value": "Progress state is execution memory. It must not authorize review handoff, repair completion, landing, closeout, or terminal success." + }, + { + "legacy_target": "Machine-first landing receipt", + "current_status": "Not implemented. Current authority is decodex/commit/1; landing mode and process state are intentionally outside that commit contract.", + "repo_evidence": [ + "docs/spec/commit-messages.md", + "apps/decodex/src/commit_message.rs" + ], + "retained_value": "A future landing receipt needs a separate schema only if decodex/commit/1 and existing GitHub merge/admin-merge records prove insufficient. Do not smuggle landing mode into commit messages." + }, + { + "legacy_target": "Workspace lifecycle hooks", + "current_status": "Implemented.", + "repo_evidence": [ + "docs/spec/workflow-file.md", + "apps/decodex/src/workflow.rs", + "apps/decodex/src/worktree.rs" + ], + "retained_value": "No new research value remains beyond preserving the narrow after_create_commands and before_remove_commands surface." + }, + { + "legacy_target": "Codex Cloud task APIs", + "current_status": "Deferred and not implemented as a Decodex execution backend.", + "repo_evidence": [ + "docs/spec/app-server.md", + "README.md" + ], + "retained_value": "Future remote execution research must prove issue/run/attempt provenance, repo gate, diff/status readback, and PR handoff authority before adopting Cloud task APIs. Compare against app-server remote environment support first." + }, + { + "legacy_target": "Codex Radar skill split", + "current_status": "Implemented.", + "repo_evidence": [ + "dev/skills/README.md", + "dev/skills/codex-upstream-triage/SKILL.md", + "dev/skills/codex-code-analysis/SKILL.md", + "dev/skills/codex-release-analysis/SKILL.md", + "dev/skills/github-signal/SKILL.md", + "scripts/github/README.md" + ], + "retained_value": "Keep deterministic source collection separate from AI judgment and require source-backed evidence before public signal or X drafting." + }, + { + "legacy_target": "Loop engineering and research lane", + "current_status": "Implemented by the loop runtime, Decision Contract schema, research compile/promote path, Program Intake, app-server goal integration, and the current research methodology rewrite.", + "repo_evidence": [ + "docs/spec/loop-runtime.md", + "apps/decodex/src/loop_contract.rs", + "apps/decodex/src/research_design.rs", + "apps/decodex/src/execution_program.rs", + "apps/decodex/src/program_intake.rs", + "apps/decodex/src/orchestrator/harness_improvement.rs", + "plugins/decodex/references/research-method.md" + ], + "retained_value": "Continue using contract-first research. New research must expose evidence class, selected option, unresolved gaps, validation expectations, and promotion target at the top level." + } + ], + "evidence_ledger": [ + { + "id": "E1", + "kind": "repo_source", + "source": [ + "apps/decodex/src/orchestrator/dispatch_policy.rs" + ], + "supports": "Machine-only tracker descriptions are omitted and require a separate generic issue briefing surface." + }, + { + "id": "E2", + "kind": "repo_source", + "source": [ + "docs/spec/tracker-tools.md" + ], + "supports": "issue_progress_checkpoint is issue-scoped execution memory and cannot replace terminal lifecycle tools." + }, + { + "id": "E3", + "kind": "repo_source", + "source": [ + "docs/spec/post-review-lifecycle.md" + ], + "supports": "Review repair, ready-to-land, closeout, and cleanup are runtime-owned retained-lane phases." + }, + { + "id": "E4", + "kind": "repo_source", + "source": [ + "docs/spec/commit-messages.md" + ], + "supports": "decodex/commit/1 describes tree changes and forbids landing mode, CI, closeout, and lifecycle state." + }, + { + "id": "E5", + "kind": "repo_source", + "source": [ + "docs/spec/workflow-file.md", + "apps/decodex/src/workflow.rs", + "apps/decodex/src/worktree.rs" + ], + "supports": "Workspace hooks are implemented narrowly as after_create_commands and before_remove_commands." + }, + { + "id": "E6", + "kind": "repo_source", + "source": [ + "dev/skills/README.md", + "dev/skills/*/SKILL.md", + "scripts/github/README.md" + ], + "supports": "Radar was split into source triage, code/release analysis, signal drafting, and publishing skills." + }, + { + "id": "E7", + "kind": "repo_source", + "source": [ + "docs/spec/loop-runtime.md", + "apps/decodex/src/loop_contract.rs", + "apps/decodex/src/research_design.rs", + "apps/decodex/src/execution_program.rs", + "apps/decodex/src/program_intake.rs" + ], + "supports": "The loop runtime stores contract-first research and accepted decisions as runtime-local Decision Contracts and Execution Programs." + }, + { + "id": "E8", + "kind": "gap", + "source": [ + "docs/spec/app-server.md", + "README.md" + ], + "supports": "Current Decodex execution is app-server/local-runtime centered; Cloud task APIs are not a proven Decodex execution backend." + }, + { + "id": "E9", + "kind": "gap", + "source": [ + "plugins/decodex/skills/planning/SKILL.md" + ], + "supports": "Decodex planning still points to external delivery issue/split shaping, so full delivery-skill removal is not complete." + } + ], + "carry_forward_research_packet": { + "terminal_status": "decision_ready", + "selected_decision": "Remove old-shape docs/research JSON event logs from the tracked tree after extracting their implemented status and retained value points into this JSON research report.", + "promotion_target": "docs/research/legacy-research-goal-audit.json", + "validation_expectations": [ + "docs/research/ contains only JSON artifacts.", + "docs/research/ has no tracked old-shape research-run/2 event logs after cleanup.", + "Current docs route legacy research questions to this JSON report, not to removed old-shape event logs.", + "New Decodex research continues to use runtime-local decodex.decision_contract/1 records for runtime authority and does not use the old research-run/2 event-log shape." + ], + "unresolved_execution_work": [ + "Decide later whether Decodex planning should become fully self-contained and remove its residual external delivery issue/split dependency.", + "Reopen remote execution research only with live evidence for task status, diff, apply, issue/run/attempt provenance, repo gate, and PR handoff authority.", + "Reopen landing receipt research only if the current decodex/commit/1 and GitHub merge/admin-merge records fail a concrete machine-readback requirement.", + "Keep any future plan/progress adapter below lifecycle authority; progress memory cannot become terminal lane state." + ] + } +} diff --git a/docs/spec/loop-runtime.md b/docs/spec/loop-runtime.md index 0151cc7fa..bd11fd034 100644 --- a/docs/spec/loop-runtime.md +++ b/docs/spec/loop-runtime.md @@ -59,16 +59,19 @@ natural-language intent such as `research X` plus bounded research/design eviden when available, then stores a local Decision Contract candidate. It supersedes the external research skill for Decodex runtime authority: Decodex plugin `research*` skills are the current agent-facing method, and the old external `docs/research/` -artifact lane remains legacy or supporting evidence that can be imported into a -Decision Contract. It is not the authority surface for Decodex loop state. +`research-run/2` event-log shape is no longer the current research format. New +Decodex research must not use an old `research-run/2` event tail as the authority +surface for loop state. Supporting JSON research reports may live under +`docs/research/` when they are explicit reports, but runtime authority still comes +from the runtime-local Decision Contract until accepted and promoted. The native research method has these ordered gates: 1. Probe frames the decision question, scope, success criteria, constraints, stop rule, primary hypothesis, rival hypotheses, and falsifiers before broad evidence collection. -2. Evidence records an auditable ledger of observations, source references, - contradictions, inferences, and missing evidence. No evidence, no claim. +2. Evidence records an auditable ledger of external sources, repository sources, live + readbacks, contradictions, inferences, and gaps. No evidence, no claim. 3. Options compare realistic choices, including status quo or explicit no-go when relevant, with evidence-grounded tradeoffs. 4. Judgment creates a challenge-ready recommendation or explicitly states that the run @@ -81,7 +84,7 @@ The native research method has these ordered gates: A Research/Decision stage may produce a latent Loop/Decision Contract with: - objective and objective lineage -- evidence, constraints, assumptions, and rejected alternatives +- evidence ledger, constraints, assumptions, and rejected alternatives - proposed decisions and open direction questions - non-goals and scope boundaries - acceptance criteria and validation expectations @@ -90,6 +93,9 @@ A Research/Decision stage may produce a latent Loop/Decision Contract with: repository-owned domain - proposed issue split and dispatch intent - risk notes that decide whether independent review is required +- promotion target, such as `docs/spec`, `docs/runbook`, `docs/reference`, + `docs/decisions`, `plugins/decodex/skills`, runtime code, tests, or explicit + `no_promotion` The latent contract is a candidate decision package. It becomes authoritative only after the user or an accepted runtime policy promotes it. @@ -120,10 +126,10 @@ The payload carries these top-level fields: | `status` | One of `draft_latent`, `accepted_promoted`, `rejected_superseded`, or `needs_human_decision`. | | `source_intent` | Natural-language source intent, including the original utterance or issue reference when known. | | `research_provenance` | Research/design sources used to produce the candidate package. | -| `research_evidence` | Non-authoritative evidence claims retained for later review and issue shaping. | +| `research_evidence` | Non-authoritative evidence claims retained for later review and issue shaping. Each item carries `kind`, `claim`, `support`, and optional `source_ref`; `kind` identifies whether the support is an external source, repository source, live readback, inference, or unresolved gap. | | `research_options` | Non-authoritative option comparisons retained with tradeoffs, selected decision notes, or rejected-option reasons. | | `accepted_authority` | Objectives, non-goals, constraints, assumptions, objections, and stop conditions that become authority only when status is `accepted_promoted`. | -| `execution_readiness` | Natural-language readiness summary, missing decisions, validation expectations, risk notes, proposed issue summaries, conflict domains, and dispatch intent. It must not expose graph ids or require the user to operate a DAG. Accepted contracts must be ready for issue shaping and must not carry unresolved missing decisions. | +| `execution_readiness` | Natural-language readiness summary, missing decisions, validation expectations, risk notes, proposed issue summaries, promotion targets, conflict domains, and dispatch intent. It must not expose graph ids or require the user to operate a DAG. Accepted contracts must be ready for issue shaping and must not carry unresolved missing decisions. | | `promotion` | Metadata recording who or what accepted the decision, the acceptance source, and the acceptance time. Required only for `accepted_promoted`. | | `links` | Generated Linear issue ids/identifiers or internal Execution Program node ids when those exist. | | `evidence_boundary` | Local private evidence references and sparse public projection references. | @@ -147,6 +153,12 @@ Research provenance and research evidence are not execution authority. They expl why the candidate package exists and give future agents enough context to avoid asking the user to restate all details after promotion. +Decision Contracts are top-level snapshots. Terminal status, selected option, material +evidence, unresolved gaps, validation expectations, and promotion target must be +readable from the payload without replaying chat or scanning a chronological event +log. Event trails and legacy research provenance from Git history may support audit, +but they must not be the primary research output. + The runtime stores Decision Contracts in local SQLite first. Linear issue descriptions, Linear execution-ledger comments, generated issue text, and operator summaries may link to or summarize an accepted contract, but they are public/coarse mirrors and must not diff --git a/plugins/decodex/references/research-method.md b/plugins/decodex/references/research-method.md index 233c9fc2b..0040c3615 100644 --- a/plugins/decodex/references/research-method.md +++ b/plugins/decodex/references/research-method.md @@ -3,6 +3,19 @@ Use this reference when Decodex research needs the full Decision Contract protocol. Decodex is the default research surface for bounded technical investigation. +## Contract-First Rule + +The primary research output is a top-level `decodex.decision_contract/1` candidate. +The contract is a current-state snapshot of the decision, evidence, selected option, +gaps, validation expectations, and promotion target. It is not an append-only run log. + +`docs/research/` is JSON-only, but the old `docs/research/*.json` +`research-run/2` event format is not the new Decodex research shape. The tracked +legacy JSON event logs were consolidated into +`docs/research/legacy-research-goal-audit.json`; use Git history only when raw old +event logs are needed as provenance. Do not write new Decodex research as old-shape +event logs, and do not infer current authority from an old research artifact. + ## Loop Run the same decision-quality loop for bounded research: @@ -48,6 +61,30 @@ The first durable event for machine-authored runs is `probe_completed`. - Use private evidence refs for local, sensitive, or runtime-private proof. - Map supported claims into `research_evidence`. +## Evidence Ledger Shape + +Every Decision Contract candidate must carry an evidence ledger that can be read +without replaying the chat transcript. + +Use these ledger classes: + +| Class | Contract field | Use | +| --- | --- | --- | +| `external_source` | `research_provenance` or `research_evidence.kind/source_ref` | Public specifications, official docs, standards, changelogs, or vendor policy. Prefer exact URLs and version dates. | +| `repo_source` | `research_evidence.kind/source_ref` | Checked-in files, code references, fixtures, tests, docs, or command output from this repository. | +| `live_readback` | `research_evidence.kind` or `evidence_boundary.private_evidence_refs` | Current runtime, tracker, GitHub, Linear, local SQLite, or service state. Keep sensitive proof private. | +| `inference` | `research_evidence.kind/support` plus `accepted_authority.assumptions` when promoted | Reasoned conclusion derived from evidence. Name the evidence it depends on. | +| `gap` | `research_evidence.kind`, `execution_readiness.missing_decisions`, `risk_notes`, or `evidence_boundary` | Missing proof, unresolved contradiction, blocker, or human choice. | + +Evidence is sufficient only when a later agent can answer these questions from the +contract: + +- Which claims are supported by external evidence? +- Which claims are supported by repository state? +- Which claims are live readback rather than static docs? +- Which conclusions are inferences, not direct observations? +- Which gaps remain, and do they block `decision_ready`? + ## Option Rules For each option, record: @@ -112,17 +149,39 @@ No unresolved decisions, evidence gaps, or blockers may remain for `decision_rea ## Decision Contract Shape The durable output is a `decodex.decision_contract/1` payload retained in runtime -state. In chat, present the same shape plainly: +state. In chat or docs, present the same shape plainly. + +Required sections: - source intent and decision question -- evidence and provenance +- terminal decision status +- evidence ledger and provenance - realistic options and tradeoffs - selected decision or why no safe decision exists - assumptions, constraints, non-goals, objections, and stop conditions - validation expectations +- promotion target, such as `docs/spec`, `docs/runbook`, `docs/reference`, + `docs/decisions`, `plugins/decodex/skills`, runtime code, tests, or no promotion - proposed issue summaries only when downstream work is appropriate - unresolved decisions, evidence gaps, or blockers +Use the existing runtime fields this way: + +| Need | Field | +| --- | --- | +| Original request and decision question | `source_intent` | +| External docs, repo files, legacy artifacts, or subwork used | `research_provenance` | +| Supported claims, evidence class, and source/code refs | `research_evidence` | +| Compared choices and selected/rejected rationale | `research_options` | +| Objectives, constraints, assumptions, objections, non-goals, and stop rules | `accepted_authority` | +| Readiness, validation, risks, issue summaries, promotion targets, conflict domains, and dispatch intent | `execution_readiness` | +| Acceptance metadata | `promotion` | +| Generated issues or Program nodes | `links` | +| Private proof and public-safe projections | `evidence_boundary` | + +Do not bury the terminal status, selected option, or unresolved gaps only in an event +tail. They must be visible from the top-level contract. + ## Promotion Boundary Research output is latent. Promotion requires explicit acceptance or an equivalent @@ -139,3 +198,19 @@ When promoting: 4. Route accepted work to `planning`. 5. Let Program Intake persist Execution Program readiness and dispatch ready mapped nodes directly. + +Promotion must choose the correct durable lane: + +- `docs/spec/` when the accepted result defines correctness, schema, invariants, or + required behavior. +- `docs/runbook/` when it defines an operator sequence. +- `docs/reference/` when it explains current implementation or repository structure. +- `docs/decisions/` when it records durable rationale or tradeoffs. +- `docs/research/` when the user explicitly asks for a supporting JSON research report + or evidence extraction that should remain non-authoritative until promoted. +- `plugins/decodex/skills/` when it changes agent-facing workflow instructions. +- Runtime code and tests only when accepted behavior cannot be represented by docs or + skills alone. + +If the accepted contract needs multiple lanes, preserve one authority source and link +other lanes to it rather than duplicating the same rule. diff --git a/plugins/decodex/skills/research-decision/SKILL.md b/plugins/decodex/skills/research-decision/SKILL.md index b0e51f400..621e06309 100644 --- a/plugins/decodex/skills/research-decision/SKILL.md +++ b/plugins/decodex/skills/research-decision/SKILL.md @@ -12,4 +12,6 @@ End every bounded research run with one terminal status. Read - `not_decision_ready`: useful evidence, unsafe decision. - `blocked`: non-decision blocker remains. - `needs_human_decision`: remaining uncertainty is human/product/authority choice. -- Do not use multiple statuses, choose readiness because budget ended, or promote here. +- Include the promotion target and evidence ledger summary in the terminal contract. +- Do not use multiple statuses, choose readiness because budget ended, promote here, + or write a new Decodex run as an old-shape `docs/research/` event log. diff --git a/plugins/decodex/skills/research-evidence/SKILL.md b/plugins/decodex/skills/research-evidence/SKILL.md index f45701b8a..6d1079b52 100644 --- a/plugins/decodex/skills/research-evidence/SKILL.md +++ b/plugins/decodex/skills/research-evidence/SKILL.md @@ -6,10 +6,12 @@ description: Use when research needs evidence tracking. # Decodex Research Evidence Make every research claim traceable. Read `../../references/research-method.md` for -evidence rules and Decision Contract mapping. +evidence rules, evidence ledger classes, and Decision Contract mapping. - Separate observations, contradictions, inferences, gaps, source/code refs, private proof, and public-safe provenance. +- Classify evidence as `external_source`, `repo_source`, `live_readback`, + `inference`, or `gap` before relying on it. - Preserve conflicts instead of flattening them into confidence. - No evidence, no claim. - Evidence is not execution authority. diff --git a/plugins/decodex/skills/research-judgment/SKILL.md b/plugins/decodex/skills/research-judgment/SKILL.md index 12e2b2b3f..8098235ee 100644 --- a/plugins/decodex/skills/research-judgment/SKILL.md +++ b/plugins/decodex/skills/research-judgment/SKILL.md @@ -10,6 +10,8 @@ Turn evidence and options into a testable conclusion. Read - Name the recommendation or non-decision, criteria fit, evidence, assumptions, rejected alternatives, gaps, and validation. +- Keep the terminal status, selected option, and unresolved gaps visible in the + top-level Decision Contract, not only in narrative text. - Do not call judgment final before challenge. - Do not hide weak evidence behind confident language. - Do not mark decision-ready while material evidence or human direction is unresolved. diff --git a/plugins/decodex/skills/research-options/SKILL.md b/plugins/decodex/skills/research-options/SKILL.md index f8f746cba..b46008521 100644 --- a/plugins/decodex/skills/research-options/SKILL.md +++ b/plugins/decodex/skills/research-options/SKILL.md @@ -11,5 +11,6 @@ checklist. - Compare realistic options such as status quo, minimal patch, redesign, migration, or no-go/defer. - State what changes, evidence, risks, tradeoffs, and selected/rejected rationale. +- Tie each option to its promotion target and expected validation if selected. - Do not compare straw-man options. - Do not write executable briefs before judgment and challenge. diff --git a/plugins/decodex/skills/research-probe/SKILL.md b/plugins/decodex/skills/research-probe/SKILL.md index a0ac7b963..64ff97245 100644 --- a/plugins/decodex/skills/research-probe/SKILL.md +++ b/plugins/decodex/skills/research-probe/SKILL.md @@ -10,5 +10,7 @@ Prevent vague research from becoming vague execution. Read - Name the question, scope, non-goals, criteria, constraints, stop rule, hypothesis, rivals, falsifiers, and first evidence plan. +- Name the expected contract promotion target, even when the likely target is + `no_promotion`. - Do not gather broad evidence until the question and falsifiers can guide collection. - Do not turn the probe into issue writing or execution planning. diff --git a/plugins/decodex/skills/research-promote/SKILL.md b/plugins/decodex/skills/research-promote/SKILL.md index 0cc403941..034322f97 100644 --- a/plugins/decodex/skills/research-promote/SKILL.md +++ b/plugins/decodex/skills/research-promote/SKILL.md @@ -11,6 +11,9 @@ approved boundary. Read `../../references/research-method.md` for promotion rule - Identify the accepted contract or conversational contract. - Preserve objectives, non-goals, constraints, assumptions, objections, validation, issue summaries, and stop conditions. +- Promote into the correct durable lane: `docs/spec`, `docs/runbook`, + `docs/reference`, `docs/decisions`, `plugins/decodex/skills`, runtime code, tests, + or explicit `no_promotion`. - Refuse promotion while unresolved decisions, evidence gaps, or blockers remain. - Route accepted work to `planning`. - Do not infer acceptance from a research question, summary, or old artifact. diff --git a/plugins/decodex/skills/research/SKILL.md b/plugins/decodex/skills/research/SKILL.md index 536285081..fb4257595 100644 --- a/plugins/decodex/skills/research/SKILL.md +++ b/plugins/decodex/skills/research/SKILL.md @@ -5,14 +5,20 @@ description: Use when Decodex needs bounded research. # Decodex Research -Produce a latent Decision Contract candidate, not execution authority. Read -`../../references/research-method.md` for the full protocol and contract shape. +Produce a latent, contract-first Decision Contract candidate, not execution +authority. Read `../../references/research-method.md` for the full protocol, +evidence ledger, promotion target rules, and contract shape. Use `research-probe`, `research-evidence`, `research-options`, `research-judgment`, `research-challenge`, and `research-decision` in order. Use `research-promote` only after explicit acceptance. - Do not route Decodex research through the legacy external `$research`. -- Do not treat `docs/research/` artifacts as current authority. +- Do not write new Decodex research as old-shape `docs/research/` event logs or treat + old artifacts as current authority. +- Use `docs/research/` only for explicit supporting JSON research reports or evidence + extraction that remains non-authoritative until promoted. +- Do keep terminal status, evidence classes, selected option, gaps, and promotion + target visible from the top-level contract. - Do not queue work, mutate Linear, set Codex goals, implement, or dispatch Program nodes from research alone.