From 8a63c5cf689a23584d15c458d356e21dbe0b48f6 Mon Sep 17 00:00:00 2001 From: Yvette Carlisle Date: Mon, 15 Jun 2026 12:48:12 +0800 Subject: [PATCH 1/2] {"schema":"decodex/commit/1","summary":"Tighten Decodex plugin skill budget","authority":"manual"} --- plugins/decodex/.codex-plugin/plugin.json | 12 +- plugins/decodex/references/research-method.md | 127 +++++++++++++++++ plugins/decodex/references/routing.md | 124 +++++++++++++++++ plugins/decodex/skills/automation/SKILL.md | 116 ++-------------- plugins/decodex/skills/commit/SKILL.md | 48 ++----- plugins/decodex/skills/decodex/SKILL.md | 130 ++---------------- plugins/decodex/skills/labels/SKILL.md | 106 ++------------ plugins/decodex/skills/land/SKILL.md | 80 ++--------- plugins/decodex/skills/manual-cli/SKILL.md | 94 ++----------- plugins/decodex/skills/planning/SKILL.md | 125 ++--------------- .../skills/research-challenge/SKILL.md | 41 +----- .../decodex/skills/research-decision/SKILL.md | 46 ++----- .../decodex/skills/research-evidence/SKILL.md | 41 +----- .../decodex/skills/research-judgment/SKILL.md | 34 +---- .../decodex/skills/research-options/SKILL.md | 43 +----- .../decodex/skills/research-probe/SKILL.md | 38 +---- .../decodex/skills/research-promote/SKILL.md | 39 ++---- plugins/decodex/skills/research/SKILL.md | 70 ++-------- 18 files changed, 392 insertions(+), 922 deletions(-) create mode 100644 plugins/decodex/references/research-method.md create mode 100644 plugins/decodex/references/routing.md diff --git a/plugins/decodex/.codex-plugin/plugin.json b/plugins/decodex/.codex-plugin/plugin.json index 55d3ef998..373b1cf54 100644 --- a/plugins/decodex/.codex-plugin/plugin.json +++ b/plugins/decodex/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "decodex", "version": "0.2.0", - "description": "Agent-facing workflows for Decodex bounded research, Decision Contract promotion, planning, manual CLI use, and runtime-owned automation.", + "description": "Decodex agent workflows.", "author": { "name": "hack-ink", "email": "hi@hack.ink", @@ -20,8 +20,8 @@ "skills": "./skills/", "interface": { "displayName": "Decodex", - "shortDescription": "Use Decodex for bounded research, Decision Contract promotion, planning, manual CLI work, or retained-lane automation.", - "longDescription": "Routes Codex agents through Decodex natural-language-first bounded research, such as \"research X\", with probe, evidence, options, judgment, challenge, and decision gates that produce latent Decision Contracts before execution. Follow-ups such as \"arrange this\" or \"推进\" can promote accepted work into planning and Program Intake where ready mapped nodes dispatch directly, while graph, DAG, goal, and dispatch mechanics backstage remain hidden from ordinary users.", + "shortDescription": "Research, plan, and operate Decodex.", + "longDescription": "Routes Decodex research, promotion, planning, CLI, labels, commit, landing, and automation.", "developerName": "hack-ink", "category": "Development", "capabilities": [ @@ -32,9 +32,9 @@ "privacyPolicyURL": "https://github.com/hack-ink/decodex", "termsOfServiceURL": "https://github.com/hack-ink/decodex", "defaultPrompt": [ - "Research how Decodex should handle this.", - "Arrange the accepted Decodex research contract into executable issues.", - "Use Decodex to inspect this lane." + "Research this with Decodex.", + "Arrange accepted research.", + "Inspect this Decodex lane." ], "brandColor": "#0F766E" } diff --git a/plugins/decodex/references/research-method.md b/plugins/decodex/references/research-method.md new file mode 100644 index 000000000..a6ec92061 --- /dev/null +++ b/plugins/decodex/references/research-method.md @@ -0,0 +1,127 @@ +# Decodex Research Method Reference + +Use this reference when Decodex research needs the full Decision Contract protocol. + +## Loop + +Run the same decision-quality loop for bounded research: + +1. Probe: frame the decision, scope, success criteria, constraints, stop rule, + hypotheses, rival hypotheses, and falsifiers. +2. Evidence: collect traceable observations, contradictions, inferences, source + references, missing evidence, and private/public provenance. +3. Options: compare realistic choices, including status quo, minimal patch, + architecture redesign, staged migration, and explicit no-go/defer when relevant. +4. Judgment: form one challenge-ready recommendation or an explicit non-decision. +5. Challenge: attack the judgment with skeptic objections. +6. Decision: finish as exactly one terminal status. +7. Promote: only after explicit acceptance. + +## Probe Checklist + +Record these before broad search or implementation: + +- decision question +- in-scope and out-of-scope surfaces +- success criteria and acceptance threshold +- constraints and non-goals +- stop rule or budget +- primary hypothesis +- realistic rival hypotheses +- falsifiers for the primary hypothesis +- initial evidence plan + +## Evidence Rules + +- No evidence, no claim. +- Keep source or code references close to each claim. +- Separate observations, contradictions, inferences, and missing evidence. +- Prefer primary sources for code, APIs, specifications, policies, and live project + state. +- Preserve conflicting evidence and name what would resolve it. +- Use private evidence refs for local, sensitive, or runtime-private proof. + +## Option Rules + +For each option, record: + +- what changes +- supporting evidence +- tradeoffs and risks +- what becomes easier or harder +- why the option is selected or rejected + +Do not compare straw-man options or select an option without evidence or explicit +assumptions. + +## Judgment Rules + +A challenge-ready judgment includes: + +- recommended option or explicit non-decision outcome +- why it best satisfies the decision criteria +- evidence ids, source references, or code references +- assumptions and constraints +- rejected alternatives +- unresolved evidence gaps +- expected validation if promoted + +Do not call the judgment final before challenge. + +## Challenge Rules + +Challenge the judgment against: + +- missing or contradictory evidence +- unexamined alternatives +- scope creep +- hidden operational cost +- compatibility or migration risk +- security, privacy, data, billing, or destructive-action risk +- authority mismatch +- validation gaps + +Record each objection as resolved, unresolved, or out of scope. Unresolved material +objections block `decision_ready`. + +## Decision Statuses + +Use exactly one terminal outcome: + +- `decision_ready`: evidence, options, resolved challenge, objectives, validation, + and proposed issue summaries are sufficient for issue shaping after promotion. +- `not_decision_ready`: useful evidence exists, but a decision would be unsafe or + under-supported. +- `blocked`: research cannot proceed until a non-decision blocker is removed. +- `needs_human_decision`: remaining uncertainty is a human/product/authority choice. + +Never use `decision_ready` because budget ended. + +## Decision Contract Shape + +The durable output is a `decodex.decision_contract/1` payload retained in runtime +state. In chat, present the same shape plainly: + +- source intent and decision question +- evidence and provenance +- realistic options and tradeoffs +- selected decision or why no safe decision exists +- assumptions, constraints, non-goals, objections, and stop conditions +- validation expectations +- proposed issue summaries only when downstream work is appropriate +- unresolved decisions, evidence gaps, or blockers + +## Promotion Boundary + +Research output is latent. Promotion requires explicit acceptance or an equivalent +follow-up such as "arrange this", "push this forward", "推进", or "做". + +When promoting: + +1. Identify the accepted contract. +2. Preserve its objectives, non-goals, constraints, assumptions, objections, + validation expectations, proposed issue summaries, and stop conditions. +3. Refuse promotion when unresolved decisions, evidence gaps, or blockers remain. +4. Route accepted work to `planning`. +5. Let Program Intake persist Execution Program readiness and dispatch ready mapped + nodes directly. diff --git a/plugins/decodex/references/routing.md b/plugins/decodex/references/routing.md new file mode 100644 index 000000000..5ace8420c --- /dev/null +++ b/plugins/decodex/references/routing.md @@ -0,0 +1,124 @@ +# Decodex Routing Reference + +Use this reference when a Decodex task crosses research, planning, manual CLI, +labels, retained automation, commit, or landing boundaries. + +## Mode Map + +- Research/design: use `research` and the `research-*` phase skills. The result is a + latent Decision Contract candidate only. +- Promotion: use `research-promote` only after explicit acceptance such as "arrange + this", "push this forward", "推进", or "做". +- Planning: use `planning` after promotion or another explicit execution instruction + to create Decodex-friendly issue slices and Program readiness. +- Manual CLI: use `manual-cli` when a human is driving local commands, status, + project registration, dry-run checks, recovery inspection, commit, or land. +- Retained automation: use `automation` when Decodex owns issue intake, Program + Intake, retained lanes, review handoff, repair, landing, closeout, cleanup, or + operator recovery. +- Labels: use `labels` only for ordinary non-Program tracker intake and retained-lane + ownership signals. + +## First Reads + +- In the Decodex repo, read `README.md`, `docs/index.md`, and `Makefile.toml` before + repository validation. +- For registered projects, read `~/.codex/decodex/projects//project.toml` + and `WORKFLOW.md`, or the project directory supplied by `--config`. +- For runtime semantics, prefer `docs/spec/` and `docs/runbook/` over global host + policy. + +## Research To Execution + +1. A natural-language research request never queues work, mutates Linear, starts + implementation, creates Codex goals, or dispatches Program nodes. +2. A decision-ready result remains latent until promotion. +3. Promotion preserves the accepted objectives, non-goals, constraints, assumptions, + objections, validation expectations, proposed issue summaries, and stop conditions. +4. Planning turns accepted work into user-readable Linear issue briefs and, when + appropriate, persisted Execution Program readiness. +5. Program Intake dispatches ready mapped nodes directly. Queue labels are not the + Program DAG scheduler. + +## Program Versus Label Intake + +- Program Intake starts from a persisted Execution Program and dispatches ready mapped + nodes with `program` dispatch mode. +- Ordinary issue intake starts from `decodex:queued:` and must still pass + `WORKFLOW.md` eligibility, terminal-state, dependency, opt-out, and active-lease + checks. +- `decodex:active:` is runtime ownership, not "please start work". +- `decodex:manual-only` opts out of automation. +- `decodex:needs-attention` is a human-required stop. Clear it only after resolving + the recorded blocker or through a runbook-approved recovery path. + +## Manual Commands + +Use installed `decodex` when operating an installed runtime. Use +`cargo run -p decodex --bin decodex -- ...` when developing this repository. + +Common probes: + +```sh +decodex probe stdio:// +decodex project add "$HOME/.codex/decodex/projects/" +decodex project list +decodex status +decodex status --live +decodex run --dry-run +``` + +Repo-development equivalents: + +```sh +cargo run -p decodex --bin decodex -- probe stdio:// +cargo run -p decodex --bin decodex -- status +cargo run -p decodex --bin decodex -- run --dry-run +``` + +## Commit And Land + +For human-driven commit: + +1. Inspect the diff and stage only intended files. +2. Run the validation required for the touched surface. +3. Use `decodex commit ""`, or + `decodex commit --manual-authority ""` for a deliberate non-issue lane. +4. Stop unless the user separately asks to push, open/update a PR, request review, or + land. + +For human-driven PR landing: + +1. Confirm the PR, base, head, mergeability, and required checks. +2. Use `decodex land ""`, or + `decodex land --manual-authority --pr ""` for a deliberate + non-issue lane. +3. If issue-authority land reports missing retained handoff state for a human-owned PR + created from a managed worktree, dry-run `decodex recover review-handoff adopt` + before any live adopt. +4. Remove merged linked worktrees and lane branches only after Decodex landing + succeeds and the repo-root default branch is current. + +## Recovery Boundaries + +- Use lane-control specs and runbooks before interrupting, steering, retrying, + resuming, relabeling, or escalating a lane. +- Use `recover review-handoff diagnose` and then `recover review-handoff rebind` for + retained PR handoff state drift. +- Use `recover review-handoff adopt` only for a verified human-owned PR created from + a managed Decodex worktree that should enter normal `decodex land --authority` + closeout. +- Use `recover merged-closeout` only when Decodex still reports stale retained + attention after a PR was already merged and the tracker issue is completed. +- Run recovery dry-runs first unless the referenced runbook says otherwise. + +## Hard Boundaries + +- Do not use global `AGENTS.md` as Decodex runtime, tracker, identity, landing, + closeout, or cleanup authority. +- Do not hand-edit runtime DB rows, kill hidden `_attempt` children, or mutate Linear + state to simulate lane controls. +- Do not substitute raw GitHub merge, merge queue, `gh pr merge`, direct API mutation, + or hand-assembled merge commits for `decodex land` when Decodex owns landing. +- Do not expose graph ids, DAG edge editing, hidden goal ids, or Program dispatch + mechanics as the ordinary user workflow. diff --git a/plugins/decodex/skills/automation/SKILL.md b/plugins/decodex/skills/automation/SKILL.md index f7b9089ae..ad1213a6b 100644 --- a/plugins/decodex/skills/automation/SKILL.md +++ b/plugins/decodex/skills/automation/SKILL.md @@ -1,110 +1,18 @@ --- name: automation -description: "Use when Decodex owns runtime automation: registered projects, serve, issue intake, retained lanes, tracker tools, review handoff, repair, landing, closeout, cleanup, or operator recovery." +description: Use when Decodex owns retained automation. --- # Automation -## Goal - -Operate Decodex as the retained-lane control plane for automatic development. - -Automation starts only after execution authority exists. Natural-language `research X` -may create a latent Decision Contract, but latent research must not dispatch retained -lanes, set Codex goals, mutate tracker state, or create Program/queue intake until a later -promotion request clearly accepts the contract. - -## Read First - -- Read `project.toml` and `WORKFLOW.md` under - `~/.codex/decodex/projects//` before interpreting runtime policy. -- Read `README.md`, `docs/index.md`, and `Makefile.toml` when developing Decodex - itself. -- Read `docs/spec/runtime.md`, `docs/spec/tracker-tools.md`, - `docs/spec/post-review-lifecycle.md`, and `docs/reference/operator-control-plane.md` - when the exact runtime/status contract matters. -- Read `docs/spec/lane-control.md` and `docs/runbook/lane-control-recovery.md` before - interrupting, steering, retrying, resuming, relabeling, or escalating a lane. - -## Core Workflow - -1. Confirm authority: accepted/promoted Decision Contract, explicit human execution - request, or normal issue brief that grants implementation authority. -2. Inspect current state with `decodex status`, `decodex status --json`, or - `decodex lane inspect ` before mutating anything. -3. For accepted Program work, use Program Intake (`decodex intake goal --apply` or - `decodex intake issues --apply`) and let the scheduler directly dispatch ready - mapped nodes. Blocked, stale, paused, active, terminal, or unmapped internal nodes - remain held. -4. For ordinary non-Program issues, queue only ready issues with - `decodex:queued:` and use the `labels` skill for Decodex Linear labels. - Request `POST /api/linear-scan` only when ordinary tracker label changes should be - observed before the next poll. -5. Let retained lanes finish through runtime-owned review, repair, handoff, landing, - closeout, and cleanup unless the operator explicitly moves the lane to a manual - path. - -## Immediate Commands - -Installed runtime: - -```sh -decodex probe stdio:// -decodex project add "$HOME/.codex/decodex/projects/" -decodex status -decodex run --dry-run -decodex run -decodex serve -``` - -Decodex repo development: - -```sh -cargo run -p decodex --bin decodex -- probe stdio:// -cargo run -p decodex --bin decodex -- status -cargo run -p decodex --bin decodex -- run --dry-run -cargo run -p decodex --bin decodex -- run -cargo run -p decodex --bin decodex -- serve -``` - -## Required Signals - -- Ordinary issue intake starts from `decodex:queued:` and active ownership - uses `decodex:active:`. -- Program Intake starts from persisted Execution Programs. Ready mapped nodes dispatch - directly with `program` dispatch mode; the scheduler does not apply, retain, or - remove service queue labels for Program readiness. -- `decodex:manual-only` opts out of automation. -- `decodex:needs-attention` is a human-required stop that automation must not silently - retry. The only runtime-owned clear path is the explicit review-handoff rebind - recovery where a current same-PR same-head marker proves stale failure-state drift. -- `recover review-handoff adopt` is an explicit human/operator manual takeover path, - not an automation retry path. Use it only when a verified human-owned PR from a - managed worktree should be adopted into the retained review/landing lifecycle. It may - reuse an existing worktree mapping only when that mapping points at the same current - checkout; a stale mapping branch name is repaired by the successful adopt write. If - the active service label is missing, dry-run must report whether live adopt will - restore it after validation. Adopt must not clear needs-attention or replace normal - retained-lane rebind. -- `recover merged-closeout` is the explicit stale retained-attention reconciliation - path after a PR was already merged and the issue is already completed. Use dry-run - first; live recovery requires manual authority and writes `closeout` plus - `cleanup_complete` only after PR lineage, origin/default containment, labels, and - retained worktree safety checks pass. -- A lane is terminal only after exactly one terminal path is finalized: - `review_handoff` or `manual_attention`. -- `phase = terminal_pending` means the agent already called terminal finalize and - Decodex is finishing lifecycle writeback. Do not interrupt, requeue, or manually - clear it from the side. - -## Boundaries - -- Do not expose graph ids, DAG edge editing, hidden goal ids, or Program dispatch mechanics - as the ordinary user workflow. -- Do not directly edit runtime DB rows, kill hidden `_attempt` children, or mutate - Linear state to simulate lane controls. -- Do not substitute manual `decodex land` for runtime-owned retained-lane landing - unless the operator explicitly moves the lane to a human-driven landing path. -- Treat `skills/list` preflight diagnostics as evidence to inspect. Missing cwd - coverage or zero enabled skills are blockers; unrelated installed-skill scan - diagnostics alone are not. +Operate Decodex retained lanes after execution authority exists. Read +`../../references/routing.md` for Program Intake, labels, recovery, and lane-control +details. + +- Confirm authority before tracker or runtime mutation. +- Inspect `decodex status` or `decodex lane inspect ` first. +- Use Program Intake for accepted Program work. +- Use `labels` only for ordinary non-Program issue intake. +- Treat `decodex:needs-attention` and `terminal_pending` as stop signals. +- Do not edit runtime DB rows, hidden children, Linear state, or retained worktrees + from the side. diff --git a/plugins/decodex/skills/commit/SKILL.md b/plugins/decodex/skills/commit/SKILL.md index f423205af..8013887c3 100644 --- a/plugins/decodex/skills/commit/SKILL.md +++ b/plugins/decodex/skills/commit/SKILL.md @@ -1,47 +1,17 @@ --- name: commit -description: Use whenever a human-driven Decodex lane reaches commit creation or the user asks to use `decodex commit`. Owns the narrow signed local commit path and `decodex/commit/1` message contract, including `--manual-authority` commits. Does not own PR creation, review, landing, cleanup, retained-lane automation, or runtime-owned orchestration. +description: Use when Decodex must commit a human lane. --- # Commit -## Goal +Create human-driven Decodex commits through `decodex commit`. Read +`../../references/routing.md` for the full commit boundary. -Create the local commit for a human-driven Decodex lane through `decodex commit` -instead of hand-assembling the `decodex/commit/1` message. +1. Inspect the diff and stage only intended files. +2. Run the touched surface's validation when useful. +3. Run `decodex commit ""`, or + `decodex commit --manual-authority ""` for non-issue work. -## Use When - -- The user asks to commit current work with Decodex. -- The next durable action is a local commit in a human-driven lane. -- The task needs the `decodex/commit/1` commit-message contract. -- The task is explicit `--manual-authority` work with no authoritative tracker issue. - -## Do Not Use - -- PR creation, PR update, review requests, review repair, or resolving review threads. -- PR landing, tracker closeout, default-branch sync, or branch/worktree cleanup. -- Retained-lane automation through `decodex run`, `decodex serve`, or runtime-owned - commit/landing/closeout behavior. -- Service-scoped Linear labels such as `decodex:queued:` or - `decodex:active:`. - -## Sequence - -1. Inspect the current diff and stage only the intended files with normal Git tooling. -2. Run the repository-native validation required for the touched surface before - committing when it can prevent avoidable CI or handoff failure. -3. Use `decodex commit ""`. -4. For a deliberate non-issue lane, use - `decodex commit --manual-authority ""`. -5. Stop at the committed lane state unless the user separately asks to push, open or - update a PR, request review, or land. - -## Fail-Closed Rules - -- If `decodex commit` is required, it must run and succeed. -- Do not substitute raw `git commit`, direct Git object creation, or a hand-written - `decodex/commit/1` JSON message for a failed or unavailable `decodex commit`. -- Do not use `decodex land`, GitHub merge tools, merge queue operations, or branch - rewrites to finish a commit-only task. -- Do not add, remove, or repurpose Decodex automation labels as a commit fallback. +Do not substitute raw `git commit`, and do not use this skill for PR creation, +landing, cleanup, retained-lane automation, or runtime-owned orchestration. diff --git a/plugins/decodex/skills/decodex/SKILL.md b/plugins/decodex/skills/decodex/SKILL.md index ba5860089..1fad7b61e 100644 --- a/plugins/decodex/skills/decodex/SKILL.md +++ b/plugins/decodex/skills/decodex/SKILL.md @@ -1,127 +1,19 @@ --- name: decodex -description: Use when the user asks to use, configure, operate, debug, or author Decodex. Routes research/design, planning, manual CLI, and runtime-owned automation workflows through Decodex-specific authority. +description: Use when routing Decodex work. --- # Decodex -## Goal +Route Decodex work to the narrowest surface. Read `../../references/routing.md` when +research, promotion, planning, labels, runtime, commit, or landing boundaries matter. -Route agent work through the right Decodex surface without duplicating the runtime -specs. Decodex has these supported use modes: +- `research`: bounded investigation before execution. +- `research-promote`: explicit acceptance of latent research. +- `planning`: accepted work needs issues or Program readiness. +- `manual-cli`: a human drives local commands. +- `automation`: retained lanes, Program Intake, recovery, closeout. +- `labels`, `commit`, `land`: only their narrow surfaces. -- Research/design mode: natural-language requests such as `research X` enter the - Decodex-native bounded research method. Probe, evidence, options, judgment, - challenge, and final decision all feed a latent Decision Contract, not execution - authority. -- Manual CLI mode: a human is driving local development, commits, PR preparation, - landing, status inspection, project registration, account selection, or dry-run - checks. -- Automation mode: Decodex owns retained-lane execution through registered project - contracts, `serve`, `run`, Program Intake, tracker labels for ordinary issues, - issue-scoped tools, review handoff, - landing, closeout, and operator status. -- Planning support: agents shape Decodex-friendly issue sets, dispatch readiness, - dependency boundaries, and concurrency after a human request or accepted/promoted - Decision Contract needs executable issue shaping. - -## Natural-Language Research Routing - -Keep the everyday user surface conversational. Do not require the user to mention -Research Lanes, Decision Lanes, DAGs, Execution Programs, queue labels, or Codex goal -commands. - -Route by intent: - -1. If the user says `research X`, asks for a design investigation, or asks Decodex to - figure out what should be done before implementation, use `research` plus its phase - skills: `research-probe`, `research-evidence`, `research-options`, - `research-judgment`, `research-challenge`, and `research-decision`. Produce or - update a latent Decision Contract with evidence, assumptions, options, objections, - non-goals, acceptance criteria, stop conditions, readiness, and open decisions. Do - not queue work, create execution authority, mutate tracker state, or start - implementation from the research request alone. -2. If the user later says `arrange this`, `push this forward`, `推进`, `做`, or an - equivalent follow-up that clearly accepts or promotes the prior contract, use - `research-promote`. Preserve the accepted contract boundary; if direction is still - missing or contradictory, ask for the missing decision instead of starting work. -3. After promotion, use `planning` to convert the accepted contract into normal - Linear issues with clear natural-language briefs, dependencies, acceptance, and - validation, then persist an Execution Program for direct scheduler dispatch. Keep - Execution Program and graph mechanics as internal readiness state. -4. Use `automation` for Program Intake and retained execution. Persisted Program - Intake dispatches ready mapped nodes directly with Program dispatch mode. Use - `labels` only for ordinary non-Program issues that should enter service-scoped - tracker intake. Queue labels are not the Program DAG scheduler; they remain an - ordinary issue intake signal and never bypass blockers, opt-outs, terminal states, - active leases, or missing briefing. - -## First Steps - -1. Identify the mode before choosing commands. -2. Read `README.md` and `docs/index.md` when the current checkout is the Decodex repo. -3. Read `Makefile.toml` before running repository validation. -4. For automation questions, read the registered project `project.toml` and - `WORKFLOW.md` under `~/.codex/decodex/projects//` or the project - directory supplied through a project-scoped command's `--config`. -5. Use the narrow skill for the current action: - - `research` for bounded Decodex research/design intake. - - `research-probe` for framing decisions, hypotheses, falsifiers, and stop rules. - - `research-evidence` for auditable evidence ledgers and missing-evidence tracking. - - `research-options` for evidence-grounded option comparison. - - `research-judgment` for challenge-ready recommendations. - - `research-challenge` for skeptic objections before finalization. - - `research-decision` for the terminal decision-ready/not-ready/blocked/human gate. - - `research-promote` for accepted research-to-execution authority. - - `manual-cli` for normal operator CLI use. - - `planning` for Decodex-friendly issue splitting, dispatch readiness, and concurrency. - - `automation` for retained-lane control-plane use. - - `commit` for `decodex commit`. - - `land` for `decodex land`. - - `labels` for Decodex Linear labels. - -Use explicit `decodex research compile` and `decodex research promote` commands only -when the operator is asking for the manual CLI surface. Ordinary conversational -research/promotion should still follow the same latent-then-promoted authority -boundary without making the user learn the commands. - -## Authority Split - -- Runtime behavior belongs to `apps/decodex/src/` and `docs/spec/`. -- Decodex-native research/design behavior belongs to `apps/decodex/src/research_design.rs` - and `docs/spec/loop-runtime.md`. The Decodex plugin's `research*` skills are the - default agent-facing method for bounded research. The legacy external `$research` - skill and `docs/research/` artifacts are supporting evidence or import material only - for Decodex runtime semantics. -- Harness-improvement recommendations from `decodex evidence` are advisory runtime - feedback. Treat them as candidates for an explicit accepted improvement path; do not - auto-edit prompts, skills, validators, issue templates, or loop policies solely - because a private outcome record suggested them. -- Architecture recovery may change implementation strategy only inside the accepted - Authority Envelope. Authority Boundary Check outcomes that require human direction, - lack evidence, depend on external/manual state, or exhaust recovery budget route to - manual attention instead of asking a detached Codex conversation mid-run. -- Operator lane-control capabilities belong to `docs/spec/lane-control.md`, with the - low-level app-server method boundary in `docs/spec/app-server.md`. -- Operator procedures belong to `docs/runbook/`. -- Current repository layout belongs to `docs/reference/`. -- Registered project execution policy belongs to project-local `WORKFLOW.md`. -- Service paths and credential environment-variable names belong to project-local - `project.toml`. -- This plugin owns reusable agent-facing Decodex usage instructions. - -Treat this plugin and the Decodex repository docs as the Decodex-specific authority. - -## Boundaries - -- Do not use global `AGENTS.md` as the source of truth for Decodex runtime, tracker, - identity, landing, closeout, or cleanup policy. -- Do not replace `decodex land` with GitHub UI, `gh pr merge`, merge queue actions, - raw `git`, or direct API merge mutations for a Decodex-owned landing path. -- Do not infer service identity, token variables, or Linear workspace from ambient - shell state when a registered project config declares them. -- Do not turn a manual CLI task into retained-lane automation unless the user asks for - automation or the current registered workflow requires it. -- Do not treat a research summary, `docs/research/` artifact, or compiled latent - contract as accepted execution authority. A Decodex research/design result must be - promoted before later issue shaping or Execution Program readiness can consume it. +Research is latent until promoted. Program Intake is not queue-label polling. +Decodex-owned landing uses `decodex land`, not raw GitHub merge paths. diff --git a/plugins/decodex/skills/labels/SKILL.md b/plugins/decodex/skills/labels/SKILL.md index 70c8a9cbc..aca110fad 100644 --- a/plugins/decodex/skills/labels/SKILL.md +++ b/plugins/decodex/skills/labels/SKILL.md @@ -1,100 +1,18 @@ --- name: labels -description: Use when applying, clearing, or interpreting Decodex Linear labels that control automation intake, active ownership, opt-out, or human-required stops. Covers service-scoped queued and active labels plus manual-only and needs-attention labels. +description: Use when Decodex labels affect intake. --- # Labels -## Goal - -Handle Decodex-related Linear labels without changing runtime ownership by accident. - -Labels are retained-lane intake and ownership signals. They are not the user-facing -research/design workflow and they do not promote latent Decision Contracts by -themselves. - -## Label Catalog - -| Label | Meaning | -| --- | --- | -| `decodex:queued:` | Candidate for automatic intake by one registered Decodex service. | -| `decodex:active:` | Runtime-owned active lane marker for one registered service. | -| `decodex:manual-only` | Human opt-out from automatic selection. | -| `decodex:needs-attention` | Automation stopped and a human must resolve the blocker. | - -## Service ID - -For `queued` and `active`, read `` from the registered project -`project.toml`. Do not guess it from repository name, branch name, issue number, or -Linear project. - -The project config is usually under: - -```sh -$HOME/.codex/decodex/projects//project.toml -``` - -If a project-scoped command supplies `--config `, read that project's -`project.toml` instead. - -## Human Label Actions - -- Humans may add or clear `decodex:queued:` when deciding whether a - specific service should intake the issue. -- Humans may add or clear `decodex:manual-only`. -- Humans may clear `decodex:needs-attention` only after addressing the underlying - blocker recorded by the runtime or agent. -- `decodex recover review-handoff rebind` may clear `decodex:needs-attention` itself - only when a current same-PR same-head handoff marker proves stale failure-state drift. -- Humans should not normally add or clear `decodex:active:` unless doing - explicit recovery and the runtime-owned state has been verified. -- For `recover review-handoff adopt`, do not hand-add - `decodex:active:` just to satisfy the command. The dry-run reports - missing active ownership and whether live adopt will restore it. The live command - restores the active label only after validating the issue, service ID, managed - worktree, PR branch, and PR head belong to the same manual takeover lane. -- For `recover merged-closeout`, queue, active, and needs-attention labels must already - be absent. The command reconciles stale runtime/ledger attention after merged PR - proof; it does not clear labels as a shortcut. - -## Queue an Issue - -1. Read the target service ID from the registered project config. -2. Read the registered project `WORKFLOW.md` for startable states, terminal states, - dependency policy, and other eligibility constraints. -3. Ensure the issue is intended to be startable for that service; the queued label is - only an intake signal and does not bypass `WORKFLOW.md` eligibility, terminal-state - checks, dependency checks, or active-lease checks. -4. Ensure `decodex:manual-only` is absent. -5. Ensure any prior blocker behind `decodex:needs-attention` is resolved. -6. For research-to-execution work, ensure the source is an accepted/promoted Decision - Contract or an equivalent explicit human execution instruction, not only a plain - `research X` result or latent contract. -7. Add `decodex:queued:`. - -## Pause or Opt Out - -1. Remove `decodex:queued:`. -2. Add `decodex:manual-only` if the issue should stay manual until someone deliberately - opts it back in. - -## Resume After Attention - -1. Read the failure or attention comment first. -2. Resolve the underlying blocker. -3. Clear `decodex:needs-attention`, or use `decodex recover review-handoff rebind` - when the blocker is verified current-marker failure-state drift. -4. Re-add `decodex:queued:` only when the issue should resume automation. - -## Boundaries - -- Do not use `decodex:active:` to mean "please start work". -- Do not clear `decodex:needs-attention` just to silence a failed lane. -- Do not add a service-scoped label for the wrong registered service. -- Do not add `decodex:active:` just to make `decodex land` pass; use it - only for verified retained-lane recovery or manual PR takeover adopt. -- Do not ask ordinary users to apply queue labels, mention DAG/goal mechanics, or - manage internal readiness state just to move from research to execution; route that - through promotion, planning, and automation policy. -- Use `land` when the task is really about human-driven PR landing. -- Use `commit` when the task is really about human-driven commit creation. +Handle Decodex Linear labels without changing runtime ownership by accident. Read +`../../references/routing.md` for service-id and recovery details. + +- `decodex:queued:`: ordinary issue intake candidate. +- `decodex:active:`: runtime-owned active lane marker. +- `decodex:manual-only`: human opt-out. +- `decodex:needs-attention`: human-required stop. +- Read `` from `project.toml`. +- Queue only issues startable under `WORKFLOW.md`. +- Require promoted research or explicit execution intent before research-derived + intake. diff --git a/plugins/decodex/skills/land/SKILL.md b/plugins/decodex/skills/land/SKILL.md index 27ff8844d..19f1c3113 100644 --- a/plugins/decodex/skills/land/SKILL.md +++ b/plugins/decodex/skills/land/SKILL.md @@ -1,77 +1,19 @@ --- name: land -description: Explicit opt-in only. Use when the user asks to land a human-driven pull request with `decodex land` or invokes this skill. Owns manual PR landing, landing fail-closed rules, tracker closeout, local default-branch sync, and post-landing cleanup. Does not own commit creation, PR creation, review repair, retained-lane automation, or runtime-owned orchestration. +description: Use when Decodex must land a human PR. --- # Land -## Goal +Land a human-driven PR through `decodex land`. Read `../../references/routing.md` for +full landing and recovery boundaries. -Land a human-driven PR through Decodex's manual landing surface without replacing it -with GitHub UI, `gh pr merge`, merge queue actions, raw `git`, or direct API mutations. +1. Confirm PR, base, head, mergeability, and checks. +2. Run `decodex land ""`, or + `decodex land --manual-authority --pr ""` for non-issue work. +3. Dry-run `decodex recover review-handoff adopt` before any live adopt. +4. Clean worktrees and branches only after Decodex landing succeeds and default branch + syncs. -## Use When - -- The user explicitly asks to land a PR through Decodex. -- A PR already exists and the intended merge path is `decodex land`. -- The task asks whether another merge path is acceptable for a Decodex-owned landing. -- A human-owned PR should be landed with issue authority after first being adopted into - Decodex's retained review handoff state. -- The lane is deliberate `--manual-authority` work with no authoritative tracker issue - but still needs Decodex-owned PR landing. - -## Do Not Use - -- Commit creation or commit-message shape. Use `commit`. -- PR creation, PR update, pushed-head preparation, review requests, review repair, or - resolving review threads. -- Runtime-owned retained-lane automation through `decodex run` or `decodex serve`. -- Runtime-owned Linear intake or active ownership labels. - -## Sequence - -1. Confirm the PR exists, the intended base and head are the ones being landed, required - checks are green, and the repository expects Decodex-owned landing. -2. Run `decodex land ""`. -3. If issue-authority land reports missing retained handoff state for a human-owned PR - created from a managed lane worktree, run - `decodex recover review-handoff adopt --pr --dry-run` from that - worktree, then rerun it live only after validation passes. Retry - `decodex land --authority --pr ""` after the adopt succeeds. -4. For a deliberate non-issue lane, run - `decodex land --manual-authority --pr ""`. -5. If `decodex land` succeeds and the repo-root default branch is current, finish the - cleanup tail: remove merged linked worktrees and local/remote lane branches when - no retained automation state still owns them. - -## What `decodex land` Owns - -- PR repository, base branch, head freshness, mergeability, and required-check - validation. -- The merge execution details needed to preserve Decodex's landing contract. -- The expected merge commit message shape. -- Tracker closeout when an authoritative tracker issue exists. -- Local default-branch fast-forward after the remote merge is authoritative. - -In `--manual-authority` mode, `decodex land` still owns merge and default-branch sync, -but intentionally skips tracker closeout and active-label ownership checks. - -## Fail-Closed Rules - -- If `decodex land` is required, it must run and succeed. -- If `decodex land` reports that checks are still pending or expected, treat that as a - wait condition: keep the tracker issue in its retained review state, keep the active - ownership label in place, wait for CI, and retry `decodex land`. -- Use `recover review-handoff adopt` only when no retained review handoff marker exists, - any existing worktree mapping points at the same current managed checkout, and the - current clean worktree exactly matches the PR head branch and SHA. A stale mapping - branch name is repaired by adopt; if the active service label is missing, live adopt - may restore it after all other validation passes. If a retained marker exists or the - mapping points elsewhere, use normal land or `recover review-handoff rebind` instead. -- Do not substitute `gh pr merge`, GitHub UI, merge queue, raw `git`, direct GitHub API - mutation, or a hand-assembled merge for a failed or unavailable `decodex land`. -- If GitHub merge already happened but `decodex land` stopped during closeout or - local default-branch sync, rerun `decodex land` from the same lane before deleting - the lane manually. -- Do not delete a lane worktree or branch before the repo-root default branch is up to - date and no runtime-owned retained lane is still using it. +Use this only after explicit landing intent. Do not substitute GitHub UI, `gh pr +merge`, merge queue, raw Git, or direct API mutation. diff --git a/plugins/decodex/skills/manual-cli/SKILL.md b/plugins/decodex/skills/manual-cli/SKILL.md index d7034c50c..937de80c5 100644 --- a/plugins/decodex/skills/manual-cli/SKILL.md +++ b/plugins/decodex/skills/manual-cli/SKILL.md @@ -1,93 +1,15 @@ --- name: manual-cli -description: "Use when a human is driving Decodex CLI workflows: project registration, probe, status, dry-run checks, live-run routing, commit, land, archive hygiene, or local operator inspection." +description: Use when a human drives Decodex CLI. --- # Manual CLI -## Goal +Assist human-driven Decodex CLI work without taking over retained automation. Read +`../../references/routing.md` for commands and recovery boundaries. -Use Decodex as a CLI assistant for human-driven work without accidentally taking over -runtime-owned retained-lane lifecycle. - -## Read First - -- `README.md` for current CLI shape. -- `Makefile.toml` before repository-native checks. -- `docs/reference/operator-control-plane.md` when interpreting `status` or dashboard - fields. -- `docs/spec/lane-control.md` and `docs/runbook/lane-control-recovery.md` before - interrupting, steering, retrying, resuming, relabeling, or escalating lanes. -- `docs/runbook/linear-archive-hygiene.md` before archiving old terminal Linear issues. -- `docs/runbook/self-dogfood-pilot.md` for the full self-dogfood operator sequence. - -## Command Surface - -Use installed `decodex` when operating an installed runtime. Use -`cargo run -p decodex --bin decodex -- ...` when developing this repository itself. - -Common installed-runtime probes: - -```sh -decodex probe stdio:// -decodex project add "$HOME/.codex/decodex/projects/" -decodex project list -decodex status -decodex status --live -decodex run --dry-run -``` - -Repo-development equivalents: - -```sh -cargo run -p decodex --bin decodex -- probe stdio:// -cargo run -p decodex --bin decodex -- status -cargo run -p decodex --bin decodex -- status --live -cargo run -p decodex --bin decodex -- run --dry-run -``` - -## Live Run Warning - -`decodex run` and `decodex run ` enter runtime-owned automation, even when a -human starts one pass manually. Before live run, read the `automation` skill and the -registered project's `WORKFLOW.md`. - -## Manual Lifecycle - -- Use `commit` before creating a Decodex-formatted local commit. -- Use `land` only when the user asks to land a human-driven PR through Decodex. -- Use `run --dry-run` only as an intake/worktree-planning check. It does not prove live - tracker writes, PR handoff, closeout, or app-server execution will succeed. -- Use `recover review-handoff diagnose` and then `recover review-handoff rebind` for - retained PR handoff state drift; the live rebind owns marker refresh plus the narrow - current-marker failure-state label/state repair described in the runbook. -- Use `recover review-handoff adopt` for a verified human-owned PR that was created - from a managed Decodex worktree and should enter normal `decodex land --authority` - closeout. Run dry-run first from the lane worktree, then rerun live only after it - confirms active-label state, clean worktree, exact PR branch/head match, and green - landable PR gates. If the active service label is missing, live adopt may restore it - after all other validation passes and will report that in dry-run. Adopt may reuse an - existing worktree mapping only when it points at the same current managed checkout; a - stale mapping branch name is repaired during the successful adopt write. Do not use - adopt when a retained review handoff marker already exists; use rebind or normal land - there. -- Use `recover merged-closeout` when Decodex still reports stale retained attention - but the PR was already merged, the tracker issue is completed, and no real retained - patch remains. Run dry-run first with the merged PR URL; live recovery requires - `--manual-authority` and writes `closeout` plus `cleanup_complete` only after it - validates completed issue state, absent queue/active/attention labels, matching PR - head branch, merge commit containment in `origin/`, and clean or - absent retained worktree state. -- Use `probe stdio://` before relying on the Codex app-server boundary. -- Use `POST /api/linear-scan` after label or issue-state changes when the scheduler - should refresh before its next 5-minute Linear poll. - -## Boundaries - -- Do not hand-edit runtime DB state unless a runbook explicitly says to. -- Do not clean up retained automation worktrees from the side when status shows a live - or recovery-owned lane. -- Do not kill hidden `_attempt` children or directly mutate Linear tracker state to - simulate lane controls. -- Do not treat app-server `skills/list` diagnostics as blockers without checking - whether cwd coverage and enabled skills are actually missing. +- Use installed `decodex` for installed runtime work. +- Use `cargo run -p decodex --bin decodex -- ...` in this repository. +- Treat `run --dry-run` as planning evidence, not proof of live writes or closeout. +- Before live `decodex run`, read `automation` and project `WORKFLOW.md`. +- Do not hand-edit runtime DB state or clean retained worktrees from the side. diff --git a/plugins/decodex/skills/planning/SKILL.md b/plugins/decodex/skills/planning/SKILL.md index 2e0039164..fa1644259 100644 --- a/plugins/decodex/skills/planning/SKILL.md +++ b/plugins/decodex/skills/planning/SKILL.md @@ -1,122 +1,17 @@ --- name: planning -description: Use when shaping Decodex-friendly issue sets, dispatch readiness, project capacity, dependencies, or concurrency. Helps agents split work so retained lanes can run independently without overlapping ownership or bypassing registered project policy. +description: Use when accepted Decodex work needs slicing. --- # Planning -## Goal +Shape accepted work into safe Decodex lanes. Read `../../references/routing.md` for +project policy and Program-vs-label dispatch rules. -Shape work so Decodex can run the right lanes in parallel while each issue remains -independently executable, reviewable, and recoverable. - -Use this before shaping a broad feature, migration, or cleanup effort into Decodex. -For durable issue text, pair this skill with the delivery plugin's `split` or `issue` -skill. Use the `labels` skill only for ordinary non-Program issues that should enter -the service-scoped tracker queue. - -Use this after a natural-language promotion follow-up such as `arrange this`, -`push this forward`, `推进`, or `做` when the accepted Decision Contract is ready to -become executable work. Do not use planning to turn a plain `research X` request or -latent contract into queued implementation. - -## Read First - -- The registered project `project.toml` for `service_id`, repo path, worktree root, - and credential environment-variable names. -- The registered project `WORKFLOW.md` for startable states, terminal states, - dependency policy, validation commands, gate profiles, and context files. -- `docs/spec/runtime.md` for eligibility, one-lane-per-issue ownership, and dispatch - slots. -- `docs/spec/workflow-file.md` for `max_concurrent_agents`, gate profile semantics, - and workspace hooks. -- `docs/spec/owned-lane-policy.md` and `docs/spec/post-review-lifecycle.md` for - retained review, landing, closeout, cleanup, and manual-intervention boundaries. -- `docs/reference/operator-control-plane.md` when using `status` or the dashboard to - understand current queue, active lanes, review waits, and cleanup debt. - -## Good Decodex Issues - -Each issue should have: - -- one concrete outcome that can land as one PR-backed lane -- required reading and current authority files -- explicit scope and non-goals -- a narrow landing zone, preferably one module, service, docs lane, or workflow seam -- acceptance criteria that can be checked without asking product intent again -- validation commands or the applicable `WORKFLOW.md` gate profile -- explicit blockers or dependency issues when the issue cannot start yet -- enough natural-language briefing in the Linear description for generic dispatch - -Do not make the description only a machine-readable fenced block. Generic normal -dispatch requires a usable briefing surface. - -When issues come from an accepted/promoted Decision Contract, each issue should also -carry: - -- objective lineage back to the accepted contract in plain language -- the accepted scope, non-goals, constraints, objections, and stop conditions relevant - to that issue -- dependency and conflict-domain notes needed to decide whether the issue is ready -- validation expectations copied from the accepted contract, not from latent evidence - alone - -Keep internal Execution Program ids, graph edges, and goal mechanics out of the user -workflow. They may inform issue readiness, but the Linear issue remains the executable -brief. - -## Parallelism Rules - -- Split by ownership boundary, validation surface, or deployable behavior, not by - arbitrary chronology. -- Prefer several independent issue lanes over one broad issue when their file sets, - contracts, and verification can be isolated. -- Put shared contracts, schema changes, and cross-cutting migrations in a foundation - issue first; let Program DAG dependencies hold downstream slices until the blocking - contract lands, or mark the dependency explicitly in the tracker for ordinary issue - queues. -- Avoid dispatching issues that are likely to edit the same hot files, branch lineage, - config authority, or generated artifacts unless the ordering is explicit. -- Keep one issue responsible for any user-facing wording or spec contract that several - implementation slices depend on, then link the other issues to that authority. -- Use `decodex:queued:` only for ordinary issues that are startable under - the registered `WORKFLOW.md`; the label does not bypass state, blocker, - terminal-state, active-lease, or capacity checks. Program DAG nodes do not need this - label; persisted Execution Programs dispatch ready mapped nodes directly. -- Set `[execution] max_concurrent_agents = 0` only when the project is intentionally - uncapped. Use a positive value when the repo, accounts, CI budget, or review surface - needs bounded parallelism. - -## Dispatch Shaping - -1. Use `decodex status` or the dashboard to read active lanes, queued candidates, - Program Intake dispatchability, retry waits, review waits, landing state, recovery - worktrees, cleanup debt, and available capacity. -2. Use `decodex run --dry-run` to confirm project loading, issue discovery, - eligibility, dependency blockers, and worktree planning before live automation. -3. For ordinary issue queues, label only the next independent slice set. For Program - DAGs, persist the whole accepted graph and let dispatchability select the ready - subset without manual queue labels. Leave future or blocked slices held until the - dependency is terminal or the `WORKFLOW.md` policy makes them startable. -4. If capacity is finite, keep the highest-value independent slices queued first - instead of flooding the queue with dependent work. -5. When a lane stops with `decodex:needs-attention`, resolve the recorded blocker - before clearing the label or re-queueing. -6. When the source is a promoted Decision Contract, do not manually queue mapped - Program issues. Persist the Execution Program and let the scheduler directly - dispatch nodes whose dependencies, conflict domains, acceptance, validation - expectations, and registered workflow state make them ready. Blocked, stale, - paused, active, terminal, or unmapped nodes stay held. - -## Boundaries - -- This skill does not replace project-local `WORKFLOW.md` policy or runtime - eligibility. -- Do not use planning guidance to manually mutate active labels, runtime DB rows, or - retained worktrees. -- Do not convert a human-driven manual task into retained-lane automation unless the - user asks for automation or the registered workflow requires it. -- Do not use parallelism as a reason to split one atomic behavior across dependent - issues that cannot be validated or reviewed independently. -- Do not promote, accept, or execute a latent research/design result just because it - has proposed issue summaries. Promotion is a separate authority boundary. +- Use this only after promotion or explicit execution instruction. +- Pair with delivery `issue` or `split` for durable issue text. +- Give each issue one outcome, scope, landing zone, acceptance, validation, + dependencies, and dispatch-ready briefing. +- Preserve accepted Decision Contract constraints, objections, stop conditions, + validation, and conflict-domain notes. +- Do not replace `WORKFLOW.md`, mutate active state, or queue latent research. diff --git a/plugins/decodex/skills/research-challenge/SKILL.md b/plugins/decodex/skills/research-challenge/SKILL.md index ad94a8fff..09998b77e 100644 --- a/plugins/decodex/skills/research-challenge/SKILL.md +++ b/plugins/decodex/skills/research-challenge/SKILL.md @@ -1,42 +1,15 @@ --- name: research-challenge -description: Use before finalizing Decodex research to run skeptic objections against the current judgment. Unresolved objections block decision-ready status. +description: Use when research needs skeptic challenge. --- # Decodex Research Challenge -## Goal - -Make the recommendation survive adversarial review before it can become -decision-ready. - -## Challenge Pass - -Challenge the current judgment against: - -- missing evidence -- contradictory evidence -- unexamined alternatives -- scope creep -- hidden operational cost -- compatibility or migration risk -- security, privacy, data, billing, or destructive-action risk -- authority mismatch with the user's request or accepted Decision Contract -- validation gaps - -Record each objection as resolved, unresolved, or out of scope. Resolved objections -should explain what evidence or constraint resolves them. Unresolved objections become -`unresolved_decisions`, `evidence_gaps`, `risk_notes`, or `blockers`. - -## Worker Use - -Use a bounded skeptic worker only when it materially improves independence. The skeptic -must not edit files, mutate tracker state, promote contracts, dispatch work, or recurse -into further workers. - -## Boundaries +Make the recommendation survive adversarial review. Read +`../../references/research-method.md` for the full checklist. +- Classify objections as resolved, unresolved, or out of scope. +- Convert unresolved material objections into decisions, evidence gaps, risks, or + blockers. - Do not finalize `decision_ready` while material objections remain unresolved. -- Do not downgrade real blockers into cosmetic risk notes. -- Do not let challenge create execution authority; it only decides whether the latent - contract can be safely promoted later. +- Do not let challenge create execution authority. diff --git a/plugins/decodex/skills/research-decision/SKILL.md b/plugins/decodex/skills/research-decision/SKILL.md index b2cf720a0..b0e51f400 100644 --- a/plugins/decodex/skills/research-decision/SKILL.md +++ b/plugins/decodex/skills/research-decision/SKILL.md @@ -1,45 +1,15 @@ --- name: research-decision -description: Use to finalize a Decodex research run as decision_ready, not_decision_ready, blocked, or needs_human_decision and prepare the latent Decision Contract boundary. +description: Use when research needs terminal status. --- # Decodex Research Decision -## Goal +End every bounded research run with one terminal status. Read +`../../references/research-method.md` for outcome gates and contract shape. -End every bounded Decodex research run with one clear status. The result is a latent -Decision Contract candidate unless and until promotion occurs. - -## Outcome Gate - -Use exactly one terminal outcome: - -- `decision_ready`: evidence, option comparison, resolved challenge, accepted - objectives, validation expectations, and proposed issue summaries are sufficient for - issue shaping after promotion. No unresolved decisions, evidence gaps, or blockers - remain. -- `not_decision_ready`: useful evidence exists, but the decision would be unsafe or - under-supported. Preserve missing evidence and next research needed. -- `blocked`: the research pass cannot proceed until a non-decision blocker is removed. -- `needs_human_decision`: the remaining uncertainty is a human/product/authority choice - rather than a research gap. - -## Decision Contract Checklist - -Before `decision_ready`, verify: - -- the decision question and falsifiers were framed -- every material claim has evidence -- realistic options were compared -- skeptic objections were addressed or classified -- the chosen boundary preserves user intent and Decodex authority rules -- validation expectations are concrete -- proposed issue summaries are scoped and non-overlapping -- the output is still latent and does not execute by itself - -## Boundaries - -- Do not produce multiple terminal statuses. -- Do not choose `decision_ready` because the budget ended. Use - `not_decision_ready`, `blocked`, or `needs_human_decision` when the gate is not met. -- Do not promote the contract in this skill. Promotion is a separate authority step. +- `decision_ready`: safe for post-promotion shaping. +- `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. diff --git a/plugins/decodex/skills/research-evidence/SKILL.md b/plugins/decodex/skills/research-evidence/SKILL.md index ad4d2195a..f45701b8a 100644 --- a/plugins/decodex/skills/research-evidence/SKILL.md +++ b/plugins/decodex/skills/research-evidence/SKILL.md @@ -1,42 +1,15 @@ --- name: research-evidence -description: Use during Decodex research evidence collection. Builds an auditable ledger of observations, sources, contradictions, inferences, missing evidence, and source-family coverage. +description: Use when research needs evidence tracking. --- # Decodex Research Evidence -## Goal - -Make every research claim traceable. Evidence is retained as context for a latent -Decision Contract, not as execution authority by itself. - -## Evidence Rules +Make every research claim traceable. Read `../../references/research-method.md` for +evidence rules and Decision Contract mapping. +- Separate observations, contradictions, inferences, gaps, source/code refs, private + proof, and public-safe provenance. +- Preserve conflicts instead of flattening them into confidence. - No evidence, no claim. -- Give evidence items stable ids when the run is more than a short chat answer. -- Record source or code references close to the claim. -- Separate observation, contradiction, inference, and missing evidence. -- For external research, record source family or perspective when coverage breadth - matters. -- Prefer primary sources for code, APIs, specifications, policies, and live project - state. -- When evidence conflicts, preserve the contradiction and decide what would resolve it. - -## Decodex Mapping - -Map evidence into the Decision Contract as: - -- `research_provenance` for source families, inspected files, commands, run outputs, or - prior artifacts -- `research_evidence` for supported claims -- `evidence_gaps` for missing proof that blocks decision-ready status -- `private_evidence_refs` when the proof is local, sensitive, or runtime-private -- `public_projection_refs` only for sparse public-safe references - -## Boundaries - -- Do not use a research summary as authority to execute. It remains latent until - promotion. -- Do not mirror private runtime payloads into public issue text. -- Do not flatten contradictions into a single confident claim unless the resolution is - explicitly evidenced. +- Evidence is not execution authority. diff --git a/plugins/decodex/skills/research-judgment/SKILL.md b/plugins/decodex/skills/research-judgment/SKILL.md index 67de32804..12e2b2b3f 100644 --- a/plugins/decodex/skills/research-judgment/SKILL.md +++ b/plugins/decodex/skills/research-judgment/SKILL.md @@ -1,35 +1,15 @@ --- name: research-judgment -description: Use after Decodex evidence and option comparison to form a challenge-ready recommendation or an explicit not-decision-ready conclusion. +description: Use when research needs judgment. --- # Decodex Research Judgment -## Goal +Turn evidence and options into a testable conclusion. Read +`../../references/research-method.md` for the full judgment shape. -Turn evidence and options into a testable conclusion without skipping unresolved -uncertainty. - -## Judgment Shape - -A challenge-ready judgment must include: - -- recommended option or explicit non-decision outcome -- why this option best satisfies the decision criteria -- evidence ids, source references, or code references that support it -- important assumptions and constraints -- rejected alternatives and why they lost -- unresolved evidence gaps, if any -- expected validation if promoted into execution - -For machine-authored runs that need replayability, assign a stable judgment id or hash -over the normalized conclusion and cited evidence. The Decision Contract remains the -Decodex authority boundary. - -## Boundaries - -- Do not call a judgment final before skeptic challenge. +- Name the recommendation or non-decision, criteria fit, evidence, assumptions, + rejected alternatives, gaps, and validation. +- Do not call judgment final before challenge. - Do not hide weak evidence behind confident language. -- Do not mark the result `decision_ready` if the judgment depends on unresolved human - direction, unavailable evidence, or untested assumptions that materially affect the - chosen option. +- 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 37eb438b8..f8f746cba 100644 --- a/plugins/decodex/skills/research-options/SKILL.md +++ b/plugins/decodex/skills/research-options/SKILL.md @@ -1,44 +1,15 @@ --- name: research-options -description: Use after Decodex research evidence collection to compare realistic implementation, architecture, or policy options with evidence-grounded tradeoffs before judgment. +description: Use when research needs option comparison. --- # Decodex Research Options -## Goal - -Force a real choice. A Decodex research answer is not decision-ready merely because one -plan sounds plausible. - -## Option Comparison - -Include realistic options such as: - -- keep current behavior or status quo -- minimal patch -- architecture-level redesign -- staged migration -- explicit no-go or defer outcome - -For each option, record: - -- what changes -- evidence supporting it -- tradeoffs and risks -- what it would make easier -- what it would make harder -- why it is selected or rejected - -## Decision Contract Mapping - -Use `research_options` for option records. A `decision_ready` result must have at least -one realistic option comparison and should preserve rejected alternatives when they -would otherwise be rediscovered later. - -## Boundaries +Force a real choice. Read `../../references/research-method.md` for the full option +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. - Do not compare straw-man options. -- Do not select an option without tying the decision to evidence or explicit - assumptions. -- Do not expand into executable issue briefs until the selected option survives - judgment and challenge. +- 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 de3cfd157..a0ac7b963 100644 --- a/plugins/decodex/skills/research-probe/SKILL.md +++ b/plugins/decodex/skills/research-probe/SKILL.md @@ -1,38 +1,14 @@ --- name: research-probe -description: Use at the start of a Decodex research run to frame the decision, scope, success criteria, hypotheses, falsifiers, constraints, and stop rule before broad evidence collection. +description: Use when starting Decodex research. --- # Decodex Research Probe -## Goal +Prevent vague research from becoming vague execution. Read +`../../references/research-method.md` for the full probe checklist. -Prevent vague research from becoming vague execution. Start every Decodex research run -by defining what decision is being made and what would prove the answer wrong. - -## Required Probe - -Record these before broad search or implementation: - -- decision question -- in-scope and out-of-scope surfaces -- success criteria and acceptance threshold -- constraints and non-goals -- stop rule or budget -- primary hypothesis -- realistic rival hypotheses -- falsifiers for the primary hypothesis -- initial evidence plan - -The first durable research event for a machine-authored run should be -`probe_completed`. In normal chat, the same information can be a concise section in -the research answer or Decision Contract candidate. - -## Boundaries - -- Do not gather broad evidence until the question, success criteria, and falsifiers - are clear enough to guide collection. -- Do not skip rival hypotheses for architecture choices. A plan is not decision-ready - until serious alternatives have been named and compared. -- Do not turn the probe into issue writing or execution planning. Proposed issues come - only after evidence, options, and challenge. +- Name the question, scope, non-goals, criteria, constraints, stop rule, hypothesis, + rivals, falsifiers, and first evidence plan. +- 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 2b2af5b1c..0cc403941 100644 --- a/plugins/decodex/skills/research-promote/SKILL.md +++ b/plugins/decodex/skills/research-promote/SKILL.md @@ -1,37 +1,16 @@ --- name: research-promote -description: Use when a user explicitly accepts a Decodex research result or asks to arrange, push forward, implement, or turn it into executable work. Owns the research-to-planning authority boundary. +description: Use when accepted research becomes execution. --- # Decodex Research Promote -## Goal +Convert accepted latent research into execution authority without changing the +approved boundary. Read `../../references/research-method.md` for promotion rules. -Convert an accepted latent Decision Contract into execution authority without changing -what was researched or approved. - -Use this only after explicit acceptance or an equivalent follow-up such as `arrange -this`, `push this forward`, `推进`, or `做`. - -## Promotion Rules - -1. Identify the latent Decision Contract or conversational contract being accepted. -2. Confirm the accepted boundary: objectives, non-goals, constraints, assumptions, - objections, validation expectations, proposed issue summaries, and stop conditions. -3. If unresolved decisions, evidence gaps, or blockers remain, do not promote. Ask for - the missing human decision or return to research. -4. If the operator is using the manual CLI surface, use `decodex research promote - ` to record acceptance in local runtime state. -5. After promotion, route issue shaping through `planning`. -6. Let Program Intake persist the internal Execution Program and dispatch ready mapped - nodes directly. Do not use queue labels as the Program scheduler. - -## Boundaries - -- Do not infer acceptance from a research summary, old `docs/research/` artifact, or - merely because the user asked a research question. -- Do not silently expand scope while promoting. New product behavior, public API, - config, workflow, security, privacy, data, billing, validation, or authority changes - require explicit acceptance. -- Do not bypass planning or Program Intake by manually creating queue-label work from a - research result. +- Identify the accepted contract or conversational contract. +- Preserve objectives, non-goals, constraints, assumptions, objections, validation, + issue summaries, and stop conditions. +- 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 dd5462cc5..2fbf87c64 100644 --- a/plugins/decodex/skills/research/SKILL.md +++ b/plugins/decodex/skills/research/SKILL.md @@ -1,68 +1,18 @@ --- name: research -description: Use when Decodex should run bounded evidence-based research or design investigation before execution. Owns the Decodex-native probe, evidence, options, judgment, challenge, decision, and promotion method through latent Decision Contracts. +description: Use when Decodex needs bounded research. --- # Decodex Research -## Goal +Produce a latent Decision Contract candidate, not execution authority. Read +`../../references/research-method.md` for the full protocol and contract shape. -Make Decodex the default research surface for bounded technical investigation. A -research request produces a latent Decision Contract candidate. It does not create -execution authority until the user or accepted runtime policy promotes it. +Use `research-probe`, `research-evidence`, `research-options`, `research-judgment`, +`research-challenge`, and `research-decision` in order. Use `research-promote` only +after explicit acceptance. -Use this skill when the user says `research X`, asks for a design investigation, asks -whether a plan is the best architecture, or wants a decision-ready answer before -implementation. - -## Method - -Run the same decision-quality loop every time: - -1. Use `research-probe` to frame the decision, scope, success criteria, constraints, - stop rule, primary hypotheses, rival hypotheses, and falsifiers before broad - evidence collection. -2. Use `research-evidence` to collect an auditable evidence ledger. No evidence, no - claim. Separate observations, contradictions, inferences, and missing evidence. -3. Use `research-options` to compare realistic options, including the status quo when - relevant. Tie tradeoffs back to evidence ids or explicit assumptions. -4. Use `research-judgment` to form one challenge-ready recommendation or to state why - the run is not decision-ready. -5. Use `research-challenge` to attack the judgment with skeptic objections. Unresolved - objections block `decision_ready`. -6. Use `research-decision` to finish as `decision_ready`, `not_decision_ready`, - `blocked`, or `needs_human_decision`. -7. Use `research-promote` only after explicit acceptance or an equivalent follow-up - such as `arrange this`, `push this forward`, `推进`, or `做`. - -## Decision Contract Output - -The durable Decodex output is a `decodex.decision_contract/1` payload retained in -runtime state. In chat, present the same shape plainly: - -- source intent and decision question -- evidence and provenance -- realistic options and tradeoffs -- selected decision or why no safe decision exists -- assumptions, constraints, non-goals, objections, and stop conditions -- validation expectations -- proposed issue summaries only when downstream work is appropriate -- unresolved decisions, evidence gaps, or blockers - -`decision_ready` is allowed only when the result has enough evidence, option -comparison, resolved challenge, accepted objective, validation expectations, and -proposed issue summaries for downstream issue shaping after promotion. It is still -latent until promoted. - -## Boundaries - -- Do not route Decodex research through the legacy external `$research` skill as the - primary method. -- Do not treat `docs/research/` artifacts as current authority. They are legacy or - supporting evidence that can be cited or imported into a Decision Contract. -- Do not queue work, mutate Linear, set Codex goals, start implementation, or dispatch - Program nodes from research alone. -- Do not hide missing evidence. Return `not_decision_ready`, `blocked`, or - `needs_human_decision` instead of forcing a recommendation. -- Use subagents only for bounded scout, analyst, or skeptic support. The main agent - owns the coherent Decision Contract and final decision status. +- Do not route Decodex research through legacy `$research`. +- Do not treat `docs/research/` artifacts as current authority. +- Do not queue work, mutate Linear, set Codex goals, implement, or dispatch Program + nodes from research alone. From 5f40eece10c8104b623ca632c19ab1948f1e99e1 Mon Sep 17 00:00:00 2001 From: Yvette Carlisle Date: Mon, 15 Jun 2026 12:56:09 +0800 Subject: [PATCH 2/2] {"schema":"decodex/commit/1","summary":"Align Decodex plugin surface tests","authority":"manual"} --- apps/decodex/src/plugin_surface_tests.rs | 142 +++++++++--------- plugins/decodex/references/research-method.md | 14 ++ plugins/decodex/references/routing.md | 7 +- plugins/decodex/skills/research/SKILL.md | 2 +- 4 files changed, 95 insertions(+), 70 deletions(-) diff --git a/apps/decodex/src/plugin_surface_tests.rs b/apps/decodex/src/plugin_surface_tests.rs index 9580942f6..01c70ccf9 100644 --- a/apps/decodex/src/plugin_surface_tests.rs +++ b/apps/decodex/src/plugin_surface_tests.rs @@ -52,6 +52,14 @@ const RESEARCH_PROMOTE_SKILL: &str = include_str!(concat!( env!("CARGO_MANIFEST_DIR"), "/../../plugins/decodex/skills/research-promote/SKILL.md" )); +const ROUTING_REF: &str = include_str!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../plugins/decodex/references/routing.md" +)); +const RESEARCH_METHOD_REF: &str = include_str!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../plugins/decodex/references/research-method.md" +)); #[test] fn packaged_plugin_manifest_routes_natural_language_research_to_decodex() { @@ -72,92 +80,90 @@ fn packaged_plugin_manifest_routes_natural_language_research_to_decodex() { .filter_map(Value::as_str) .collect::>() .join("\n"); + let manifest_surface = + format!("{long_description}\n{default_prompts}\n{ROUTING_REF}\n{RESEARCH_METHOD_REF}"); - assert_contains(long_description, "natural-language-first"); - assert_contains(long_description, "bounded research"); - assert_contains( - long_description, - "probe, evidence, options, judgment, challenge, and decision gates", - ); - assert_contains(long_description, "\"research X\""); - assert_contains(long_description, "latent Decision Contracts"); - assert_contains(long_description, "\"arrange this\""); - assert_contains(long_description, "\"推进\""); - assert_contains(long_description, "ready mapped nodes dispatch directly"); - assert_contains(long_description, "graph, DAG, goal, and dispatch mechanics backstage"); - assert_contains(&default_prompts, "Research how Decodex should handle this."); - assert_contains( - &default_prompts, - "Arrange the accepted Decodex research contract into executable issues.", - ); + assert_contains(&manifest_surface, "natural-language-first"); + assert_contains(&manifest_surface, "bounded research"); + assert_contains(&manifest_surface, "probe, evidence, options, judgment, challenge, decision"); + assert_contains(&manifest_surface, "`research X`"); + assert_contains(&manifest_surface, "latent Decision Contract"); + assert_contains(&manifest_surface, "\"arrange this\""); + assert_contains(&manifest_surface, "\"推进\""); + assert_contains(&manifest_surface, "ready mapped nodes directly"); + assert_contains(&manifest_surface, "DAG"); + assert_contains(&default_prompts, "Research this with Decodex."); + assert_contains(&default_prompts, "Arrange accepted research."); } #[test] fn packaged_skills_preserve_research_promotion_and_queue_boundaries() { - assert_contains(DECODEX_SKILL, "## Natural-Language Research Routing"); - assert_contains(DECODEX_SKILL, "`research X`"); - assert_contains(DECODEX_SKILL, "`research-probe`"); - assert_contains(DECODEX_SKILL, "`research-promote`"); - assert_contains(DECODEX_SKILL, "legacy external `$research`"); - assert_contains(DECODEX_SKILL, "latent Decision Contract"); - assert_contains(DECODEX_SKILL, "`arrange this`"); - assert_contains(DECODEX_SKILL, "`推进`"); - assert_contains_normalized(DECODEX_SKILL, "Do not queue work"); - assert_contains(DECODEX_SKILL, "dispatches ready mapped nodes directly"); - assert_contains(PLANNING_SKILL, "accepted Decision Contract"); - assert_contains(PLANNING_SKILL, "Do not use planning to turn a plain `research X`"); - assert_contains_normalized(PLANNING_SKILL, "scheduler directly dispatch nodes"); - assert_contains(PLANNING_SKILL, "Promotion is a separate authority boundary"); - assert_contains(AUTOMATION_SKILL, "Automation starts only after execution authority exists"); - assert_contains_normalized( - AUTOMATION_SKILL, - "latent research must not dispatch retained lanes", + let skill_surface = format!( + "{DECODEX_SKILL}\n{PLANNING_SKILL}\n{AUTOMATION_SKILL}\n{LABELS_SKILL}\n{RESEARCH_SKILL}\n{ROUTING_REF}\n{RESEARCH_METHOD_REF}" ); - assert_contains(AUTOMATION_SKILL, "accepted/promoted Decision Contract"); - assert_contains_normalized(AUTOMATION_SKILL, "directly dispatch ready mapped nodes"); - assert_contains(AUTOMATION_SKILL, "Blocked, stale, paused, active, terminal"); - assert_contains_normalized(LABELS_SKILL, "not the user-facing research/design workflow"); - assert_contains(LABELS_SKILL, "accepted/promoted Decision"); - assert_contains(LABELS_SKILL, "Do not ask ordinary users to apply queue labels"); + + assert_contains(&skill_surface, "## Natural-Language Research Routing"); + assert_contains(&skill_surface, "`research X`"); + assert_contains(&skill_surface, "`research-probe`"); + assert_contains(&skill_surface, "`research-promote`"); + assert_contains(&skill_surface, "legacy external `$research`"); + assert_contains(&skill_surface, "latent Decision Contract"); + assert_contains(&skill_surface, "\"arrange this\""); + assert_contains(&skill_surface, "\"推进\""); + assert_contains_normalized(&skill_surface, "never queues work"); + assert_contains(&skill_surface, "dispatches ready mapped nodes directly"); + assert_contains(&skill_surface, "accepted Decision Contract"); + assert_contains(&skill_surface, "Do not replace `WORKFLOW.md`"); + assert_contains_normalized(&skill_surface, "Program Intake dispatches ready mapped nodes"); + assert_contains(&skill_surface, "Promotion is a separate authority step"); + assert_contains(&skill_surface, "after execution authority exists"); + assert_contains_normalized(&skill_surface, "never queues work, mutates Linear"); + assert_contains(&skill_surface, "ordinary non-Program issue intake"); + assert_contains(&skill_surface, "not queue-label polling"); + assert_contains(&skill_surface, "Require promoted research"); } #[test] fn packaged_research_skills_encode_decodex_methodology() { - assert_contains(RESEARCH_SKILL, "default research surface"); - assert_contains(RESEARCH_SKILL, "probe, evidence, options, judgment, challenge, decision"); - assert_contains_normalized(RESEARCH_SKILL, "No evidence, no claim"); - assert_contains(RESEARCH_SKILL, "runtime state"); + let research_surface = format!( + "{RESEARCH_SKILL}\n{RESEARCH_PROBE_SKILL}\n{RESEARCH_EVIDENCE_SKILL}\n{RESEARCH_OPTIONS_SKILL}\n{RESEARCH_JUDGMENT_SKILL}\n{RESEARCH_CHALLENGE_SKILL}\n{RESEARCH_DECISION_SKILL}\n{RESEARCH_PROMOTE_SKILL}\n{RESEARCH_METHOD_REF}" + ); + + assert_contains(&research_surface, "default research surface"); + assert_contains(&research_surface, "probe, evidence, options, judgment, challenge, decision"); + assert_contains_normalized(&research_surface, "No evidence, no claim"); + assert_contains_normalized(&research_surface, "runtime state"); assert_contains( - RESEARCH_SKILL, + &research_surface, "Do not route Decodex research through the legacy external `$research`", ); - assert_contains(RESEARCH_PROBE_SKILL, "primary hypothesis"); - assert_contains(RESEARCH_PROBE_SKILL, "rival hypotheses"); - assert_contains(RESEARCH_PROBE_SKILL, "falsifiers"); - assert_contains(RESEARCH_PROBE_SKILL, "`probe_completed`"); - assert_contains(RESEARCH_EVIDENCE_SKILL, "No evidence, no claim"); + assert_contains(&research_surface, "primary hypothesis"); + assert_contains(&research_surface, "rival hypotheses"); + assert_contains(&research_surface, "falsifiers"); + assert_contains(&research_surface, "`probe_completed`"); + assert_contains(&research_surface, "No evidence, no claim"); assert_contains( - RESEARCH_EVIDENCE_SKILL, - "Separate observation, contradiction, inference, and missing evidence", + &research_surface, + "Separate observations, contradictions, inferences, and missing evidence", ); - assert_contains(RESEARCH_EVIDENCE_SKILL, "`research_evidence`"); - assert_contains(RESEARCH_OPTIONS_SKILL, "status quo"); - assert_contains(RESEARCH_OPTIONS_SKILL, "evidence-grounded"); - assert_contains(RESEARCH_OPTIONS_SKILL, "`research_options`"); - assert_contains(RESEARCH_JUDGMENT_SKILL, "challenge-ready"); - assert_contains(RESEARCH_JUDGMENT_SKILL, "stable judgment id or hash"); - assert_contains(RESEARCH_JUDGMENT_SKILL, "not-decision-ready"); + assert_contains(&research_surface, "`research_evidence`"); + assert_contains(&research_surface, "status quo"); + assert_contains(&research_surface, "evidence"); + assert_contains(&research_surface, "`research_options`"); + assert_contains(&research_surface, "challenge-ready"); + assert_contains(&research_surface, "stable judgment id or hash"); + assert_contains(&research_surface, "not_decision_ready"); assert_contains( - RESEARCH_CHALLENGE_SKILL, + &research_surface, "Do not finalize `decision_ready` while material objections remain unresolved", ); - assert_contains(RESEARCH_CHALLENGE_SKILL, "skeptic worker"); - assert_contains(RESEARCH_DECISION_SKILL, "Use exactly one terminal outcome"); - assert_contains(RESEARCH_DECISION_SKILL, "No unresolved decisions, evidence gaps, or blockers"); - assert_contains(RESEARCH_DECISION_SKILL, "Promotion is a separate authority step"); - assert_contains(RESEARCH_PROMOTE_SKILL, "research-to-planning authority boundary"); - assert_contains(RESEARCH_PROMOTE_SKILL, "Do not infer acceptance"); - assert_contains(RESEARCH_PROMOTE_SKILL, "Program Intake"); + assert_contains(&research_surface, "skeptic worker"); + assert_contains(&research_surface, "Use exactly one terminal outcome"); + assert_contains(&research_surface, "No unresolved decisions, evidence gaps, or blockers"); + assert_contains(&research_surface, "Promotion is a separate authority step"); + assert_contains_normalized(&research_surface, "research-to-planning authority boundary"); + assert_contains(&research_surface, "Do not infer acceptance"); + assert_contains(&research_surface, "Program Intake"); } fn assert_contains(haystack: &str, needle: &str) { diff --git a/plugins/decodex/references/research-method.md b/plugins/decodex/references/research-method.md index a6ec92061..233c9fc2b 100644 --- a/plugins/decodex/references/research-method.md +++ b/plugins/decodex/references/research-method.md @@ -1,6 +1,7 @@ # Decodex Research Method Reference Use this reference when Decodex research needs the full Decision Contract protocol. +Decodex is the default research surface for bounded technical investigation. ## Loop @@ -17,6 +18,9 @@ Run the same decision-quality loop for bounded research: 6. Decision: finish as exactly one terminal status. 7. Promote: only after explicit acceptance. +The compact phase order is: probe, evidence, options, judgment, challenge, decision, +promote. + ## Probe Checklist Record these before broad search or implementation: @@ -31,6 +35,8 @@ Record these before broad search or implementation: - falsifiers for the primary hypothesis - initial evidence plan +The first durable event for machine-authored runs is `probe_completed`. + ## Evidence Rules - No evidence, no claim. @@ -40,6 +46,7 @@ Record these before broad search or implementation: state. - Preserve conflicting evidence and name what would resolve it. - Use private evidence refs for local, sensitive, or runtime-private proof. +- Map supported claims into `research_evidence`. ## Option Rules @@ -53,6 +60,7 @@ For each option, record: Do not compare straw-man options or select an option without evidence or explicit assumptions. +Map option records into `research_options`. ## Judgment Rules @@ -67,6 +75,8 @@ A challenge-ready judgment includes: - expected validation if promoted Do not call the judgment final before challenge. +For replayable machine-authored runs, assign a stable judgment id or hash over the +normalized conclusion and cited evidence. ## Challenge Rules @@ -83,6 +93,7 @@ Challenge the judgment against: Record each objection as resolved, unresolved, or out of scope. Unresolved material objections block `decision_ready`. +Use a bounded skeptic worker only when it materially improves independence. ## Decision Statuses @@ -96,6 +107,7 @@ Use exactly one terminal outcome: - `needs_human_decision`: remaining uncertainty is a human/product/authority choice. Never use `decision_ready` because budget ended. +No unresolved decisions, evidence gaps, or blockers may remain for `decision_ready`. ## Decision Contract Shape @@ -115,6 +127,8 @@ state. In chat, present the same shape plainly: Research output is latent. Promotion requires explicit acceptance or an equivalent follow-up such as "arrange this", "push this forward", "推进", or "做". +Promotion is a separate authority step and the research-to-planning authority +boundary. When promoting: diff --git a/plugins/decodex/references/routing.md b/plugins/decodex/references/routing.md index 5ace8420c..188907baa 100644 --- a/plugins/decodex/references/routing.md +++ b/plugins/decodex/references/routing.md @@ -28,7 +28,12 @@ labels, retained automation, commit, or landing boundaries. - For runtime semantics, prefer `docs/spec/` and `docs/runbook/` over global host policy. -## Research To Execution +## Natural-Language Research Routing + +Keep Decodex natural-language-first. Requests such as `research X` route through +`research`, `research-probe`, `research-evidence`, `research-options`, +`research-judgment`, `research-challenge`, and `research-decision` before any +promotion. 1. A natural-language research request never queues work, mutates Linear, starts implementation, creates Codex goals, or dispatches Program nodes. diff --git a/plugins/decodex/skills/research/SKILL.md b/plugins/decodex/skills/research/SKILL.md index 2fbf87c64..536285081 100644 --- a/plugins/decodex/skills/research/SKILL.md +++ b/plugins/decodex/skills/research/SKILL.md @@ -12,7 +12,7 @@ Use `research-probe`, `research-evidence`, `research-options`, `research-judgmen `research-challenge`, and `research-decision` in order. Use `research-promote` only after explicit acceptance. -- Do not route Decodex research through legacy `$research`. +- Do not route Decodex research through the legacy external `$research`. - Do not treat `docs/research/` artifacts as current authority. - Do not queue work, mutate Linear, set Codex goals, implement, or dispatch Program nodes from research alone.