ultracode-for-codex 0.3.1 → 0.3.3

package/docs/provenance-audit.md

@@ -7,7 +7,7 @@ Date: 2026-06-22
 This audit checked:
 
 - tracked repository files;
-- generated npm package contents for `ultracode-for-codex@0.3.0`;
+- generated npm package contents for `ultracode-for-codex@0.3.3`;
 - the locally installed companion Codex skill.
 
 Generated build output and package tarballs were checked as projections of the
@@ -23,8 +23,8 @@ License transition completed:
 
 - Apache-2.0 `LICENSE` file is present;
 - `package.json` and `package-lock.json` declare `Apache-2.0`;
-- release-candidate package version is `0.3.0`;
-- npm latest before this release remains `0.2.6`.
+- audited package metadata version is `0.3.3`;
+- npm publish state is verified separately during release preparation.
 
 ## Evidence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultracode-for-codex",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Run Codex-native Ultracode orchestration with an optional local CLI runtime.",
   "keywords": [
     "codex",

package/skills/ultracode-for-codex/SKILL.md

@@ -51,7 +51,10 @@ Phase Inspect - 3 agents
    file inspection, test execution, or integration planning.
 7. As agents complete, report progress with a visual snapshot rather than a
    dense sentence. Use the Default Live Snapshot golden shape from
-   `references/progress-visuals.md` by default.
+   `references/progress-visuals.md` by default. Select task-specific additions
+   from the Situation Choice Matrix in that reference. Within one user
+   request, keep a cumulative ledger: do not remove completed rows from later
+   snapshots; update their status and append newly discovered work below them.
 
 ```text
 Phase E2E Validate

package/skills/ultracode-for-codex/references/progress-visuals.md

@@ -4,6 +4,67 @@ Use these golden examples for Codex-native Ultracode progress updates. The goal
 is fast visual parsing in chat while staying portable across terminals and
 renderers. Prefer ASCII symbols and short labels.
 
+## Research Pattern Map
+
+These patterns are adapted from established CLI/TUI conventions:
+
+- multi-task progress: Rich-style multiple task rows with progress metadata;
+- test progress: pytest-style progress/count/timing summaries;
+- async build logs: Docker BuildKit-style numbered steps and plain progress;
+- folded details: GitHub Actions-style grouped log sections;
+- change plans: Terraform-style add/update/keep/destroy action symbols;
+- rollout watches: Kubernetes rollout-style "N out of M" convergence messages;
+- audit tables: npm audit-style severity/package/path/remediation columns.
+
+Map those patterns to Ultracode situations instead of using one universal
+status format.
+
+## Situation Choice Matrix
+
+Choose one row per task situation. Each row has at most three user-facing
+shapes: primary, support, and finish. Do not present profile names to the user.
+If a task mixes situations, choose the dominant row for live progress and borrow
+at most one support shape from another row.
+
+| Situation | Primary | Support | Finish |
+| --- | --- | --- | --- |
+| Ordinary or mixed work | Default Live Snapshot | Verification Gate Matrix | Plan-Style Result Summary |
+| Design or planning | Decision Tournament | Context Coverage Matrix | User Decision Gate |
+| Implementation | Implementation Work Ledger | Verification Gate Matrix | Completion Impact Summary |
+| Review or audit | Agent Lens Matrix | Context Coverage Matrix | Evidence To Finding Trace |
+| Release or install | Artifact Inventory | Rollout Or Convergence Watch | Risk Or Audit Table |
+| Retry, cancellation, or long-running work | Recovery Ledger | Resource Budget Snapshot | Rollout Or Convergence Watch |
+
+Phase Plan Preview is baseline behavior before a phase starts, not an extra
+choice. Long Async Timeline is only a temporary diagnostic appendix when the
+user explicitly asks to debug detailed event order.
+
+## Cumulative Ledger Rule
+
+Within one user request, progress snapshots are cumulative. Do not let completed
+work scroll out of the next snapshot just because new work starts. Keep completed
+rows, update their status, and append newly discovered work below them. This
+makes the current answer self-contained even if the user only sees the latest
+snapshot.
+
+```text
+Phase Commit Prep
+
+  + README install flow          done      local + global skill install
+  + Registry/install check       done      <version> published and installed
+  + Verification                 done      npm run test:all
+
+  > Commit                       running   staging release changes
+  - Push                         queued    origin/main
+
+Checks 3 passed | 0 failed | 2 running/queued
+Next: commit release changes
+```
+
+Use `+` for completed work, `>` for running work, `-` for queued work, and `!`
+for blocked or failed work. Keep earlier completed rows visible in every later
+snapshot for the same request.
+
 ## Default Live Snapshot
 
 Use this for ordinary phase progress. It is inspired by test-runner summaries:
@@ -24,8 +85,7 @@ Checks 5 passed | 0 failed | 2 running
 Elapsed 1m 12s
 ```
 
-Use `+` for completed items, `>` for running items, `!` for blocked or failed
-items, and `-` for queued items. Keep each row to one line when possible.
+Keep each row to one line when possible.
 
 ## Dense Meter Snapshot
 
@@ -123,3 +183,236 @@ Details
 ```
 
 This is best for final handoff or after multiple agents have returned.
+
+## Building Block Examples
+
+Use these shapes as building blocks selected by the Situation Choice Matrix
+above. Do not present this full list as user-facing choices.
+
+### Phase Plan Preview
+
+Use this immediately before spawning agents for a phase.
+
+```text
+Phase Inspect - planned fan-out
+
+  - Runtime contracts     check execution authority and failure semantics
+  - UX/progress           inspect visible status and completion summaries
+  - Tests/package         verify E2E, tarball, and installed skill contents
+
+Parallelism: 3 agents
+Synthesis: merge material findings and decide next phase
+```
+
+### Agent Lens Matrix
+
+Use this when several agents are reviewing the same artifact from different
+angles.
+
+```text
+Review Lenses
+
+  + Runtime correctness       no material issue       workflow-runtime.ts
+  + Capability boundary       no material issue       subagent-backend.ts
+  ! User visibility           needs fix               progress visuals
+  > Package contract          running                 tarball contents
+
+Findings 1 open | 2 clear | 1 running
+Next: fix user visibility contract
+```
+
+### Implementation Work Ledger
+
+Use this when work is split into edit scopes.
+
+```text
+Implementation Ledger
+
+  + Skill routing docs         updated   skills/ultracode-for-codex
+  + CLI skill command          added     skills/ultracode-for-codex-cli
+  > E2E package checks         editing   scripts/e2e-installed-...
+  - README install flow        queued    local/global install examples
+
+Files touched 6 | Tests queued 2 | Risk low
+```
+
+### Verification Gate Matrix
+
+Use this after tests, package checks, reviews, or publish dry-runs.
+
+```text
+Verification Gates
+
+  + unit/integration           passed    35 tests
+  + installed E2E              passed    fake Codex boundary
+  + package validation         passed    35 files in tarball
+  + publish dry-run            passed    would publish <version>
+
+Gates 4 passed | 0 failed | 0 skipped
+Residual: live Codex smoke remains opt-in
+```
+
+### Decision Tournament
+
+Use this when comparing approaches before implementation.
+
+```text
+Decision Tournament
+
+  A  CLI orchestration         rejected  low visibility
+  B  Native main orchestration selected  highest chat visibility
+  C  Hybrid auto-router        deferred  more moving parts
+
+Winner: B
+Reason: best fit for Codex-native progress and direct subagent control
+```
+
+### Blocked Or Risk Snapshot
+
+Use this when a dependency, permission, failing gate, or missing capability
+blocks progress.
+
+```text
+Blocked Snapshot
+
+  + Package contents           verified
+  ! Native subagent surface    blocked   multi-agent tools unavailable
+  - Parallel review            paused    needs subagent surface
+
+Blocker: native parallel orchestration unavailable in this session
+Fallback: continue single-context review and record residual risk
+```
+
+### Retry Or Recovery Ledger
+
+Use this for transient failures, retry loops, cancellation, or recovery.
+
+```text
+Recovery Ledger
+
+  + attempt 1                  failed    workflow_agent_stalled
+  + retry policy               applied   retry 1 / 2
+  > attempt 2                  running   narrowed review prompt
+  - synthesis                  queued    after terminal result
+
+Retries 1 used | 1 remaining
+Next: wait for attempt 2 terminal state
+```
+
+### Artifact Inventory
+
+Use this when the output is files, package artifacts, generated docs, or local
+state.
+
+```text
+Artifact Inventory
+
+  + npm tarball                artifacts/ultracode-for-codex-<version>.tgz
+  + native skill               skills/ultracode-for-codex/SKILL.md
+  + CLI skill                  skills/ultracode-for-codex-cli/SKILL.md
+  + progress examples          skills/ultracode-for-codex/references/progress-visuals.md
+
+Artifacts 4 ready | Sensitive local state not included
+```
+
+### Rollout Or Convergence Watch
+
+Use this when waiting for a target state: publish propagation, installed package
+availability, test shards, deployment checks, or background jobs.
+
+```text
+Convergence Watch
+
+  + npm registry                visible   <version> latest
+  + global CLI                  updated   /opt/homebrew/bin/ultracode-for-codex
+  > Codex skill reload          pending   next session boundary
+  - downstream smoke            queued    user project install
+
+Converged 2 / 4
+Next: verify downstream smoke after reload
+```
+
+### Risk Or Audit Table
+
+Use this for security, capability boundaries, provenance, dependency audit,
+license review, or data exposure checks.
+
+```text
+Risk Audit
+
+  severity  area                 status    evidence
+  high      provider credentials  clear     env stripping test
+  medium    local state paths     clear     .ultracode-for-codex ignored
+  low       docs ambiguity        open      install wording
+
+Open risk 1 low | Material risk 0
+Next: clarify install wording
+```
+
+### Context Coverage Matrix
+
+Use this when the quality of a result depends on which evidence was actually
+read, searched, tested, or left unverified.
+
+```text
+Context Coverage
+
+  + runtime source              read      src/runtime/workflow-runtime.ts
+  + package scripts             read      scripts/package-...
+  + installed E2E               executed  npm run test:e2e:...
+  ! live Codex smoke            skipped   opt-in local environment
+
+Coverage 3 verified | 1 residual
+Residual: live smoke remains user-triggered
+```
+
+### User Decision Gate
+
+Use this when the next step needs a product or risk choice rather than more
+execution.
+
+```text
+Decision Gate
+
+  A  Publish now                ready     all gates green
+  B  Add live smoke first       safer     needs local Codex run
+  C  Defer release              safest    no user impact yet
+
+Recommended: A
+Why: package and dry-run gates are green; live smoke is optional
+```
+
+### Resource Budget Snapshot
+
+Use this for long work where elapsed time, agent count, retry budget, or token
+budget matters.
+
+```text
+Resource Budget
+
+  agents active                3 / 6
+  retries used                 1 / 2
+  elapsed                      7m 20s
+  timeout                      none
+  token budget                 not capped
+
+Pressure: low
+Next: wait for active agents before synthesis
+```
+
+### Evidence To Finding Trace
+
+Use this when translating many observations into a smaller set of findings or
+fixes.
+
+```text
+Evidence Trace
+
+  evidence                         finding                 action
+  package files include skill refs  packaging contract ok   keep
+  npm exec run path untested        E2E gap                 add test
+  progress rows disappear           visibility gap          add ledger rule
+
+Findings 2 actionable | 1 keep
+Next: implement E2E gap and ledger rule
+```

package/skills/ultracode-for-codex-cli/SKILL.md

@@ -70,6 +70,10 @@ CLI behavior:
   phase begins;
 - each `workflow.agent.completed` record includes phase progress, total known
   agent progress, and elapsed time;
+- built-in `task` uses the generic phase planner; built-in `code-review`
+  collects bounded review evidence, selects dynamic lenses, runs parallel finder
+  agents, verifies each emitted candidate, optionally runs an `xhigh` sweep, and
+  synthesizes final findings by verified candidate index;
 - after a completed run, `workflow.summary.ready` reports phase-level agent
   counts and angles, then `workflow.review.recommended` asks the current
   session LLM to critically re-check the final result before acting on it;
@@ -89,8 +93,10 @@ CLI behavior:
 - Keep direct provider credentials out of Codex child process environments.
 - Codex subagents run against the requested workflow cwd and have bounded
   read-only workspace tools for text file reads and directory listings.
-- Built-in `task` and `code-review` inject deterministic workspace context into
-  planner-selected phase-wise parallel subagents.
+- Built-in `task` injects deterministic workspace context into 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.
 - Keep workflow execution local and command-owned; settings default to OS
   background execution so long runs can keep waiting while Codex does other
   work.