ultracode-for-codex 0.3.1 → 0.3.3

package/README.md

@@ -1,23 +1,58 @@
 # Ultracode for Codex
 
-Ultracode for Codex ships two Codex skill commands plus a local npm CLI runtime.
-`$ultracode-for-codex` is the default high-visibility mode: the Codex main
-context plans adaptive phases, spawns focused parallel subagents, synthesizes
-their results, and reports progress directly in the chat.
-`$ultracode-for-codex-cli` is the explicit runtime path for package validation,
-background jobs, attached CLI runs, release checks, and reproducible local
-workflow artifacts.
+Dynamic workflows redesigned for Codex, with parallel subagents, visible
+progress, and an optional local CLI runtime.
 
-## Quick Start
+The default experience is Codex-native: you ask for `$ultracode-for-codex`, and
+the main Codex chat becomes the orchestrator. It plans the next useful phase,
+runs independent subagents in parallel when that helps, summarizes their
+findings, and shows compact progress snapshots directly in the conversation.
 
-Install from npm:
+A local CLI runtime is included for users who want background jobs, reproducible
+workflow runs, package checks, or attached terminal execution.
+
+## Why Use It
+
+- Get multi-angle reviews instead of a single linear pass.
+- Run implementation and verification work phase by phase.
+- See what agents are doing, what finished, and what still needs attention.
+- Keep long CLI workflows running in the OS background when desired.
+- Package the same workflow behavior for repeatable local use.
+
+## Install
+
+For one project:
 
 ```bash
 npm install --save-dev ultracode-for-codex
+```
+
+For global use:
+
+```bash
+npm install -g ultracode-for-codex
+```
+
+If you installed it globally, check the CLI directly:
+
+```bash
+ultracode-for-codex --version
+ultracode-for-codex --llm-guide
+```
+
+If you installed it as a project dependency, check it with `npm exec --`:
+
+```bash
+npm exec -- ultracode-for-codex --version
 npm exec -- ultracode-for-codex --llm-guide
 ```
 
-Install the Codex skill commands from the package:
+## Install The Codex Skills
+
+After installing the npm package, copy the included skill commands into your
+Codex skills folder.
+
+From a project install:
 
 ```bash
 mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
@@ -27,235 +62,171 @@ cp -R ./node_modules/ultracode-for-codex/skills/ultracode-for-codex-cli \
   "${CODEX_HOME:-$HOME/.codex}/skills/"
 ```
 
-Build and verify a local installable tarball from a source checkout:
+From a global install:
 
 ```bash
-npm install
-npm run pack:ultracode-for-codex
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+GLOBAL_NODE_MODULES="$(npm root -g)"
+cp -R "$GLOBAL_NODE_MODULES/ultracode-for-codex/skills/ultracode-for-codex" \
+  "${CODEX_HOME:-$HOME/.codex}/skills/"
+cp -R "$GLOBAL_NODE_MODULES/ultracode-for-codex/skills/ultracode-for-codex-cli" \
+  "${CODEX_HOME:-$HOME/.codex}/skills/"
 ```
 
-Install the tarball from a target project:
+Restart Codex or start a new Codex session if the skills do not appear
+immediately.
 
-```bash
-npm install --save-dev /path/to/ultracode-for-codex-<version>.tgz
+## Use In Codex
+
+Use the default skill for normal work:
+
+```text
+$ultracode-for-codex Review this change for correctness and security risks.
 ```
 
-Run through the CLI runtime when that path is explicitly wanted:
+Good tasks for the default skill:
 
-```bash
-npm exec -- ultracode-for-codex run \
-  --accept-llm-guide=v1 \
-  --cwd /path/to/target-repo \
-  --script-file .codex/workflows/review.js \
-  --args '{"prompt":"review the current change"}'
+- code review;
+- implementation planning;
+- multi-step verification;
+- architecture or design critique;
+- release readiness checks;
+- work that benefits from parallel perspectives.
+
+The default skill shows a phase plan before work starts and keeps a cumulative
+progress snapshot as agents finish.
+
+Example:
+
+```text
+Phase Review
+
+  + Runtime correctness       done      no material issue
+  > Security boundary         running   checking local state handling
+  - Package contract          queued    verify installed files
+
+Agents 1 completed | 1 running | 1 queued
+Next: synthesize material findings
 ```
 
-By default this prints a background launch record to stdout. The record contains
-`jobId`, `pid`, `resultPath`, `progressPath`, `metadataPath`, and `pidPath`.
-Use the job id to inspect or control the background run:
+## Use The CLI Runtime
+
+Use `$ultracode-for-codex-cli` or the `ultracode-for-codex` binary when you
+explicitly want a local command-owned workflow run.
+
+Run a built-in task workflow:
 
 ```bash
-npm exec -- ultracode-for-codex status <jobId> --cwd /path/to/target-repo
-npm exec -- ultracode-for-codex wait <jobId> --cwd /path/to/target-repo
-npm exec -- ultracode-for-codex logs <jobId> --cwd /path/to/target-repo --tail 40
-npm exec -- ultracode-for-codex result <jobId> --cwd /path/to/target-repo
-npm exec -- ultracode-for-codex cancel <jobId> --cwd /path/to/target-repo
-npm exec -- ultracode-for-codex jobs --cwd /path/to/target-repo
-npm exec -- ultracode-for-codex archive <jobId> --cwd /path/to/target-repo
+npm exec -- ultracode-for-codex run \
+  --accept-llm-guide=v1 \
+  --cwd /path/to/project \
+  --name task \
+  --args '{"prompt":"review correctness risks and propose fixes"}'
 ```
 
-Run attached to the current terminal:
+Run a code review:
 
 ```bash
 npm exec -- ultracode-for-codex run \
   --accept-llm-guide=v1 \
-  --execution attached \
-  --cwd /path/to/target-repo \
-  --script-file .codex/workflows/review.js \
+  --cwd /path/to/project \
+  --name code-review \
   --args '{"prompt":"review the current change"}'
 ```
 
-Named workflows are resolved from `.codex/workflows`, user workflow folders,
-plugin workflow folders, and built-ins:
+The built-in `code-review` workflow collects bounded repository evidence,
+chooses review lenses, runs finder agents in parallel, verifies each candidate,
+and returns JSON with `findings`, `provenance`, `synthesis`, and `stats`.
+Use `{"level":"high"}` to skip the final sweep, or omit it for the default
+`xhigh` review.
+
+CLI runs use OS background execution by default. The command prints a launch
+record with a `jobId`, then you can inspect or control the job:
+
+```bash
+npm exec -- ultracode-for-codex status <jobId> --cwd /path/to/project
+npm exec -- ultracode-for-codex logs <jobId> --cwd /path/to/project --tail 40
+npm exec -- ultracode-for-codex result <jobId> --cwd /path/to/project
+npm exec -- ultracode-for-codex cancel <jobId> --cwd /path/to/project
+```
+
+Use attached execution only when the terminal should stay connected until the
+workflow finishes:
 
 ```bash
 npm exec -- ultracode-for-codex run \
   --accept-llm-guide=v1 \
-  --cwd /path/to/target-repo \
+  --execution attached \
+  --cwd /path/to/project \
   --name task \
-  --args '{"prompt":"review correctness risks and propose fixes"}'
+  --args '{"prompt":"check the release plan"}'
 ```
 
-The CLI built-in `task` and `code-review` workflows use an LLM planner first,
-then run work phase by phase. Within each phase, multiple focused Codex
-subagents run in parallel by default, followed by phase and final synthesis. The
-planner may choose a single-agent path only when parallel execution would add
-risk or waste. Planner guidance includes dynamic workflow patterns such as
-classify-and-act, fan-out-and-synthesize, adversarial verification,
-generate-and-filter, tournament, and loop-until-done, so different work types
-can use different phase shapes.
-
-## Settings
-
-Package defaults live in `settings.json`:
-
-```json
-{
-  "workflow": {
-    "executionMode": "background",
-    "progress": "jsonl",
-    "permission": "ask",
-    "retryLimit": 0,
-    "timeoutMs": 0,
-    "background": {
-      "runDir": ".ultracode-for-codex/background/{jobId}",
-      "resultFile": "result.json",
-      "progressFile": "progress.jsonl",
-      "metadataFile": "metadata.json",
-      "pidFile": "pid"
-    }
-  }
-}
-```
+## What Gets Installed
 
-Use `--execution attached`, `--progress`, `--permission`, `--retry-limit`, and
-`--timeout-ms` to override settings for one run.
-The package default workflow timeout is `0`, meaning the workflow waits until it
-completes, is cancelled, or the Codex app-server exits. Set `--timeout-ms` to a
-positive value to opt into a deadline for one run.
-Use the default background execution for long Codex-launched work so Codex can
-continue other tasks and inspect the job later with `status`, `logs`, or
-`result`. Use
-`--execution attached` only when the caller must block until the final result.
-
-## CLI Controls
-
-- Use `--version` or `-v` to print the installed package version.
-- Use `status`, `wait`, `logs`, `result`, and `cancel` with a background
-  `jobId` or `metadata.json` path to inspect, wait for, read, or cancel OS
-  background runs.
-- Use `jobs` or `list` to enumerate local background runs.
-- Use `archive` or `export` to write a sensitive local JSON bundle for one run
-  without deleting runtime state.
-- Use `wait --result`, `cancel --wait`, `logs --event <event>`, and `--plain`
-  for shorter foreground checks.
-- Progress is printed to stderr as JSONL by default.
-- The final workflow result is printed as JSON to stdout.
-- JSONL records include `kind`, `version`, `event`, `status`, and `summary`;
-  agent records also include stable agent identity and label fields.
-- Built-in `task` and `code-review` emit `workflow.plan.ready` as a planning
-  snapshot, not a promise that every later phase is already known.
-- `workflow.phase.planned` is emitted immediately before each phase starts and
-  carries that phase's current planned agent role labels. Each
-  `workflow.phase.started` record repeats the same role labels when the phase
-  begins.
-- Each `workflow.agent.completed` record includes phase progress, total known
-  agent progress, and elapsed time.
-- After a completed run, `workflow.summary.ready` reports each phase with its
-  planned agent count and angle/focus list, then `workflow.review.recommended`
-  asks the current session LLM to critically re-check the final result before
-  acting on it.
-- Press `Ctrl-C` once to cancel the active workflow.
-- Use `--retry-limit <n>` to retry failed workflows inside the same process.
-- `--timeout-ms 0` waits for completion, cancellation, or app-server exit.
-  Positive values opt into a workflow deadline and per-agent silence budget;
-  that budget is not divided by the retry budget.
-- Use `--permission ask|allow|deny` for project/user/plugin/scriptPath workflow
-  permission reviews.
-- Use `--progress plain` for human-readable log lines.
-- Use `--execution background` for OS background runs and `--execution attached`
-  only when the caller should stay connected until completion.
-
-## Codex Skill Commands
-
-The npm package includes two Codex skill command folders:
-
-- `skills/ultracode-for-codex`: default Codex-native orchestration. The main
-  context plans adaptive phases, spawns parallel subagents, synthesizes each
-  phase, reports completion progress, and recommends a final critical re-check.
-  Live progress uses test-runner-style visual snapshots; completion reporting
-  uses a diffstat-style impact summary plus a plan-style result summary.
-- `skills/ultracode-for-codex-cli`: explicit CLI runtime operations, including
-  background jobs, attached runs, packaging, release checks, runtime-boundary
-  validation, and installed E2E tests.
-
-## Runtime Boundaries
-
-- The only production backend is Codex app-server over stdio.
-- Direct provider credentials are stripped from the Codex child process
-  environment.
-- Codex subagents run against the requested workflow cwd and receive bounded
-  read-only workspace tools for text file reads and directory listings.
-- CLI built-in `task` and `code-review` inject deterministic workspace context into
-  planner-selected phase-wise parallel subagents, then synthesize each phase and
-  the final result.
-- Workflow execution is local and command-owned; settings default to OS
-  background execution so long runs can keep waiting while Codex does other
-  work.
-- `.ultracode-for-codex` workflow state is sensitive local data.
-- `journalPath`, `journal.jsonl`, and journal contents stay out of CLI output.
-  Local runtime state may still contain runtime-owned
-  `transcriptDir`, `scriptPath`, and result files.
-- `resumeFromRunId` remains runtime-internal and same-session; users retry the
-  active run or rerun the workflow command.
-- `agent(..., { isolation: "worktree" })` runs the agent in a detached git
-  worktree and preserves the worktree for review, including clean worktrees.
-
-## Development
+The package includes:
 
-```bash
-npm install
-npm test
-npm run pack:ultracode-for-codex
-npm run test:e2e:ultracode-for-codex
-npm run test:all
-```
+- `ultracode-for-codex`: the local CLI binary;
+- `skills/ultracode-for-codex`: the recommended Codex-native skill;
+- `skills/ultracode-for-codex-cli`: the explicit CLI/runtime skill;
+- `settings.json`: default CLI runtime settings;
+- `ULTRACODE_INSTALL.md`: detailed install and operating guide for agents.
 
-## Publishing
+## Local State
 
-The npm package name is `ultracode-for-codex`. Public publish metadata lives in
-`package.json`, and `prepublishOnly` runs the full verification suite before
-`npm publish`.
+CLI background runs write local workflow state under `.ultracode-for-codex/` in
+the target project. Treat that folder as local runtime data. It may contain
+progress, metadata, transcripts, and results for the run.
 
-Check the package before publishing:
+Add it to `.gitignore` if your project does not already ignore it:
+
+```gitignore
+.ultracode-for-codex/
+```
+
+## Troubleshooting
+
+If Codex does not recognize `$ultracode-for-codex`, confirm that the skill
+folder exists:
 
 ```bash
-npm run publish:dry-run
+ls "${CODEX_HOME:-$HOME/.codex}/skills/ultracode-for-codex"
 ```
 
-Publish after `npm login`:
+If `npm exec -- ultracode-for-codex` fails, confirm the package is installed:
 
 ```bash
-npm run publish:npm
+npm ls ultracode-for-codex
 ```
 
-For supported CI/CD environments, provenance is available as an explicit opt-in:
+If a CLI workflow is still running, list local jobs:
 
 ```bash
-npm run publish:npm:provenance
+npm exec -- ultracode-for-codex jobs --cwd /path/to/project
 ```
 
-Optional live smoke against the local Codex CLI:
+## For Maintainers
+
+Common source checkout commands:
 
 ```bash
-ULTRACODE_LIVE_SMOKE=1 npm run smoke:live
+npm install
+npm test
+npm run test:e2e:ultracode-for-codex
+npm run test:all
+npm run pack:ultracode-for-codex
 ```
 
-Useful local run:
+Check the publish payload:
 
 ```bash
-npm run build
-node dist/cli.js run --accept-llm-guide=v1 --script-file ./workflow.js
+npm run publish:dry-run
 ```
 
-## Docs
-
-- `skills/ultracode-for-codex/SKILL.md`: default Codex-native orchestrator
-  skill command.
-- `skills/ultracode-for-codex/references/progress-visuals.md`: golden visual
-  progress and completion summary examples for native orchestration.
-- `skills/ultracode-for-codex-cli/SKILL.md`: explicit CLI runtime skill command.
-- `ULTRACODE_INSTALL.md`: install and operating guide for LLM agents.
-- `docs/ultracode-p3a-journal-design.md`: journal contract.
-- `docs/ultracode-p3b-resume-cache.md`: runtime-internal resume/cache contract.
-- `docs/ultracode-p3c-worktree-isolation.md`: worktree isolation contract.
+## More Documentation
+
+- `ULTRACODE_INSTALL.md`: detailed install and operating guide.
+- `skills/ultracode-for-codex/SKILL.md`: Codex-native orchestration behavior.
+- `skills/ultracode-for-codex/references/progress-visuals.md`: progress display
+  examples.
+- `skills/ultracode-for-codex-cli/SKILL.md`: CLI runtime behavior.

package/ULTRACODE_INSTALL.md

@@ -99,13 +99,19 @@ npm exec -- ultracode-for-codex archive <jobId> --cwd /path/to/project
 ```
 
 Use CLI built-in `task` for general work and `code-review` for review-specific
-work. Both start with an LLM planner, execute phase by phase, run multiple
-focused Codex subagents in parallel within each phase by default, and synthesize
-phase and final results. The planner chooses a single-agent path only when
-parallel execution would add risk or waste.
-Planner guidance includes classify-and-act, fan-out-and-synthesize,
-adversarial verification, generate-and-filter, tournament, and loop-until-done
-patterns so different work types can use different phase shapes.
+work. `task` starts with an LLM planner, executes phase by phase, runs multiple
+focused Codex subagents in parallel within each phase by default, and chooses a
+single-agent path only when parallel execution would add risk or waste. Planner
+guidance includes classify-and-act, fan-out-and-synthesize, adversarial
+verification, generate-and-filter, tournament, and loop-until-done patterns so
+different work types can use different phase shapes.
+
+`code-review` uses a specialized review harness. It collects bounded repository
+evidence, selects active review lenses, runs one finder per lens in parallel,
+verifies every emitted candidate with a candidate-scoped subagent, optionally
+runs an `xhigh` sweep, then synthesizes final findings by verified candidate
+index. The final JSON includes `findings`, `provenance`, `synthesis`, and
+`stats`.
 
 Settings defaults:
 
@@ -145,7 +151,9 @@ Useful controls:
 - JSONL records include `kind`, `version`, `event`, `status`, and `summary`;
   agent records also include stable agent identity and label fields.
 - Built-in `task` and `code-review` emit `workflow.plan.ready` as a planning
-  snapshot, not a promise that every later phase is already known.
+  snapshot, not a promise that every later phase is already known. In
+  `code-review`, later verifier agents are discovered after finder agents emit
+  candidates.
 - `workflow.phase.planned` is emitted immediately before each phase starts and
   carries that phase's current planned agent role labels. Each
   `workflow.phase.started` record repeats the same role labels when the phase
@@ -180,9 +188,10 @@ Useful controls:
 - Strip direct provider credentials from child CLI environments.
 - Run Codex subagents against the requested workflow cwd and provide bounded
   read-only workspace tools for text file reads and directory listings.
-- Built-in `task` and `code-review` add deterministic workspace context to
-  planner-selected phase-wise parallel subagents, then synthesize each phase and
-  the final result.
+- Built-in `task` adds deterministic workspace context to planner-selected
+  phase-wise parallel subagents. Built-in `code-review` uses deterministic
+  review evidence, allowed evidence refs, dynamic lenses, candidate verification,
+  and bounded final synthesis.
 - Install consumers from a packaged artifact.
 - Keep `journalPath`, `journal.jsonl`, and journal contents out of CLI output.
   Local runtime state may still contain runtime-owned

package/dist/cli.js

@@ -1116,31 +1116,27 @@ function workflowPhaseExecutionSummary(events) {
     for (const event of events) {
         if (event.type !== 'workflow.agent.started' || !event.phase)
             continue;
+        const startedAgent = {
+            title: event.label,
+            label: event.label,
+            angle: event.promptPreview,
+        };
         const existing = phases.get(event.phase);
         if (!existing) {
             phases.set(event.phase, {
                 title: event.phase,
                 agentCount: 1,
-                agents: [{
-                        title: event.label,
-                        label: event.label,
-                        angle: event.promptPreview,
-                    }],
+                agents: [startedAgent],
             });
             continue;
         }
-        if (phaseTitlesWithPlannedAgents.has(event.phase))
+        if (phaseTitlesWithPlannedAgents.has(event.phase)
+            && existing.agents.length > 0
+            && !phaseSummaryAllowsDynamicStartedAgents(existing))
             continue;
         if (existing.agents.some((agent) => agent.label === event.label || agent.title === event.label))
             continue;
-        const agents = [
-            ...existing.agents,
-            {
-                title: event.label,
-                label: event.label,
-                angle: event.promptPreview,
-            },
-        ];
+        const agents = [...existing.agents, startedAgent];
         phases.set(event.phase, {
             ...existing,
             agentCount: agents.length,
@@ -1149,6 +1145,14 @@ function workflowPhaseExecutionSummary(events) {
     }
     return [...phases.values()];
 }
+function phaseSummaryAllowsDynamicStartedAgents(phase) {
+    return phase.agents.some((agent) => {
+        const label = agent.label ?? '';
+        const title = agent.title ?? '';
+        const angle = agent.angle ?? '';
+        return /\bdynamic\b/i.test(`${label} ${title} ${angle}`);
+    });
+}
 function criticalReviewRecommendation() {
     return 'Session LLM should critically re-check the final result before acting: verify whether the conclusion is justified, internally consistent, supported by the observed workflow evidence, and missing material counterarguments.';
 }

package/dist/runtime/workflow-journal.d.ts

@@ -12,6 +12,7 @@ export interface WorkflowAgentSemanticOpts {
     readonly effort?: string;
     readonly isolation?: string;
     readonly agentType?: string;
+    readonly logicalKey?: string;
 }
 export type WorkflowJournalEntry = WorkflowRunStartedEntry | WorkflowAgentStartedEntry | WorkflowAgentCompletedEntry | WorkflowAgentFailedEntry | WorkflowRunCompletedEntry | WorkflowRunFailedEntry;
 interface WorkflowJournalEntryEnvelope {

package/dist/runtime/workflow-journal.js

@@ -219,6 +219,9 @@ export function computeWorkflowAgentCallKey(input) {
     if (!HASH_RE.test(input.previousAgentCallKey)) {
         throw new WorkflowJournalValidationError('previousAgentCallKey must be a 64-character sha256 hex digest.');
     }
+    if (input.semanticOpts.logicalKey) {
+        return sha256(`logical\0${input.semanticOpts.logicalKey}\0${input.prompt}\0${stableJson(input.semanticOpts)}`);
+    }
     return sha256(`${input.previousAgentCallKey}\0${input.prompt}\0${stableJson(input.semanticOpts)}`);
 }
 export function workflowJournalHash(entryWithoutEntryHash) {
@@ -473,10 +476,10 @@ function assertWorkflowAgentSemanticOpts(value) {
     const opts = asRecord(value);
     if (!opts)
         throw new WorkflowJournalValidationError('semanticOpts must be an object.');
-    rejectUnknownKeys(opts, ['schema', 'model', 'effort', 'isolation', 'agentType'], 'semanticOpts');
+    rejectUnknownKeys(opts, ['schema', 'model', 'effort', 'isolation', 'agentType', 'logicalKey'], 'semanticOpts');
     if (typeof opts.model !== 'string' || !opts.model)
         throw new WorkflowJournalValidationError('semanticOpts.model must be a string.');
-    for (const key of ['effort', 'isolation', 'agentType']) {
+    for (const key of ['effort', 'isolation', 'agentType', 'logicalKey']) {
         if (opts[key] !== undefined && typeof opts[key] !== 'string') {
             throw new WorkflowJournalValidationError(`semanticOpts.${key} must be a string.`);
         }