orchestrator-workflow 0.33.0 → 0.35.0

package/CHANGELOG.md

@@ -7,6 +7,74 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.35.0] - 2026-09-15
+
+- The npm tarball now ships a `LICENSE` file matching the repo root LICENSE
+  (MIT), asserted by the monorepo's `lint-package-licenses` CI job.
+
+- A repo-level `lint-release-changelogs` CI job (`scripts/check-release-changelogs.mjs`
+  at the agent-dx root, named in `CONTRIBUTING.md`'s "Releasing okf-kit" steps)
+  fails a release commit whose package.json version bump has no matching top
+  `## [x.y.z]` CHANGELOG heading, whose fresh heading (checked against a
+  `--base <ref>`, the PR base sha or the previous push commit in CI) still
+  leaves `[Unreleased]` non-empty, or whose `docs/okf/log.md` entry carries a
+  `CHANGELOG.md:<n>` mention with no okf-kit anchor. Motivated by agent-tasks
+  task e077bcd8: a prior release commit (#266) bumped a version without
+  cutting its CHANGELOG unnoticed by CI, and two log.md entries had written
+  a live, unanchored `CHANGELOG.md:<n>` citation that silently resolved to
+  unrelated content after the next cut. Does not change okf-kit's own
+  citation rules or any historical CHANGELOG content.
+
+- Hardened `lint-release-changelogs` (review round 2 on the same task):
+  rule 2 now fires only when the head version is a strictly greater
+  semver release than `--base` (a head older than base, or a version
+  neither side parses as strict semver, no longer misfires); an invalid
+  `--base` (an unresolvable ref, or a flag-shaped value) is now a usage
+  error instead of a silently skipped comparison. Added an
+  `empty-release-section` rule for a cut heading with no body before the
+  next heading, and a `checked-package-scope` rule pinning the four
+  packages this repo already checks so one silently losing its
+  CHANGELOG.md is a hard failure instead of a shrinking count; packages
+  skipped for carrying no CHANGELOG.md are now printed by name. Added a
+  `--root <dir>` option (a disposable fixture tree instead of this repo)
+  backing a new fixture-based test suite, and `CONTRIBUTING.md`'s step 6
+  now names `--base origin/master` explicitly instead of implying the
+  `[Unreleased]` check runs without it.
+
+- Reduced the contracts reference's duplicate implementer prose to an explicit
+  route to workflow step 6 and the installed implementer role prompt. The
+  unchanged YAML contract remains the schema surface; conformance tests pin
+  the route, target workflow heading, and role-local verification/commit
+  obligations.
+
+- Verification sets combine trusted preflight execution with ordered repository
+  extras through one named, immutable reference. Both roles replay the complete
+  set and preserve every child result, limitation, and non-pass outcome; repos
+  with `docs/okf/` always include bundle validation. The README carries a
+  parseable checked-in-list example; no execution engine or preflight checks
+  are added. Evidence: Pandora batch 51, D-024/D-025—four briefs omitted the
+  bundle check, and CI caught drift that required one additional repair round.
+- The installed skill now has a compact orchestrator entrypoint with explicit
+  routed references for contracts, evidence/probes, review/recovery, and
+  run-state/harness behavior. Persisted probe plans are optional
+  runner-supported artifacts: immutable plan identity and mutant locator may
+  be delegated by reference, but only a checked-state result is evidence.
+  Missing/stale references block proof; intentional supersession is recorded,
+  never silently rewritten. Recovery records a cursor in existing run state
+  for invalid returns, incomplete probes, interrupted work, and bounded
+  repeated findings without changing waiver authority or requiring a CLI
+  schema.
+- The review template now records each reviewer's returned method in the machine-readable `method-applied[<round>]` marker directly below its `review-method` declaration. The marker is read by grounding-mcp's completeness reader; the accompanying `Method:` line remains its constrained prose fallback. The detailed workflow reference requires the orchestrator to write every returned value and resupply an omission or mismatch before acceptance. See agent-grounding #235.
+## [0.34.0] - 2026-09-13
+
+- Reviewer findings now carry `introduced_by_delta: yes | no | unknown`.
+  A `no` attribution requires a named base build and replay in `reproduction`;
+  it remains in the ordinary finding gate and Findings table, while only `yes`
+  and `unknown` participate in bounded halt and escalation rules. The legacy
+  five-cell table and placeholder row remain byte-compatible with the
+  completeness reader; concrete rows record attribution parenthetically in
+  their Description field.
+
 ## [0.33.0] - 2026-09-12
 
 ### Changed

package/INSTALL-AGENT.md

@@ -33,7 +33,10 @@ which is mutable. For a stable audit, pin the URL to a commit SHA instead
    If the installer reports conflicts with locally edited files, inspect the
    concrete files and reuse any overwrite authority already granted for that
    scope. Ask before a `--force` re-run only when authority or conflict scope
-   remains unresolved. **The operator
+   remains unresolved. The compact skill core and its required `references/`
+   files are one coherent bundle: the installer checks every destination for
+   conflicts before it activates a new core, and keeps the current bundle
+   unless an authorized `--force` replaces the affected files. **The operator
    path**: when an operator has already run `orchestrator-workflow setup`
    on this machine (an operator manifest exists at
    `<operator home>/manifest.json`, where the operator home is
@@ -168,6 +171,9 @@ steps in the repository you were asked to install into.
    on a re-run. If the command reports conflicts, inspect the concrete files,
    reuse prior overwrite authority for the same scope, and ask before
    `--force` only when authority or scope remains unresolved.
+   The conflict check covers the compact core and the complete required
+   `references/` set before replacing either, so a non-forced re-run preserves
+   the current coherent bundle.
 
    **Operator path**: before running `init`, check whether an operator
    manifest already exists on this machine, at
@@ -193,6 +199,11 @@ steps in the repository you were asked to install into.
    must run inline and sequentially until the automated CLI can generate
    `.codex/agents/*.toml`.
 
+   Before writing any skill core manually, check its destination and every
+   required `references/*.md` destination for local conflicts. If any conflict
+   exists, preserve the current core/reference bundle; write replacements only
+   with the same explicit overwrite authority required by the automated path.
+
    - `.ai/workflow/templates/00-goal.md` through `06-handoff.md` from
      `assets/templates/`, unchanged.
    - `.ai/runs/.gitkeep`, empty. The orchestrator later writes a
@@ -205,7 +216,8 @@ steps in the repository you were asked to install into.
      `<!-- orchestrator-workflow:begin -->` / `<!-- orchestrator-workflow:end -->`
      markers.
    - Claude Code: `.claude/skills/orchestrator-workflow/SKILL.md` from
-     `assets/skill/SKILL.md`. For each role in the chosen profile (all five
+     `assets/skill/SKILL.md`, plus every regular Markdown file in
+     `assets/skill/references/` at the matching `references/` path. For each role in the chosen profile (all five
      for `full`; only `implementer` and `reviewer` for `minimal`),
      `.claude/agents/<role>.md` from
      `assets/agents/<role>.md` with `model: <operator's choice>` added as a
@@ -219,11 +231,12 @@ steps in the repository you were asked to install into.
      `disallowedTools: Edit, Write, NotebookEdit` goes on a new line
      directly after the `effort:` line. Ensure `CLAUDE.md` exists and
      contains a line `@AGENTS.md`.
-   - Codex: `.agents/skills/orchestrator-workflow/SKILL.md`, same skill file.
+   - Codex: `.agents/skills/orchestrator-workflow/SKILL.md` and the same
+     `references/*.md` files.
      Do not hand-author `.codex/agents/*.toml`; report the native-agent
      limitation above and use the inline/sequential role fallback.
    - opencode: `.opencode/skills/orchestrator-workflow/SKILL.md` from
-     `assets/skill/SKILL.md`, unchanged.
+     `assets/skill/SKILL.md`, plus matching `references/*.md`, unchanged.
      For each role in the chosen profile (same set as Claude Code above),
      `.opencode/agents/<role>.md` from `assets/agents/<role>.md`, with the
      frontmatter rewritten to this order: `description:` (unchanged), then

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lan Nguyen Si
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -99,6 +99,12 @@ automatic upgrade. [INSTALL-AGENT.md](INSTALL-AGENT.md) makes the write surface
 and fallback behavior auditable. The link tracks `master`; pin it to a commit
 SHA for a stable audit.
 
+The compact skill entrypoint and its routed references form one installed
+bundle. On a reinstall, the installer checks the core and every required
+reference for local conflicts before activating a new core; it leaves the
+current coherent bundle intact unless an explicitly authorized `--force` run
+replaces the affected files.
+
 ### Manual and advanced CLI installation
 
 ```bash
@@ -150,6 +156,56 @@ harness to install it.
 npx orchestrator-workflow init --harness none --yes
 ```
 
+## Verification sets
+
+A repository may check in `.ai/workflow/verify.json` to name the complete
+verification set for an implementer or reviewer briefing. This generic worked
+example uses a `preflight run <repo> --json` executor and ordered extras with
+`cwd`, `argv`, and an explicit before/after-preflight phase, so an approved
+build can precede a dependent test:
+
+```json
+{
+  "format": "orchestrator-workflow-verification-set/v1",
+  "preflight": {
+    "kind": "preflight",
+    "name": "preflight",
+    "cwd": ".",
+    "argv": ["preflight", "run", ".", "--json"]
+  },
+  "extras": [
+    {
+      "kind": "command",
+      "name": "build",
+      "phase": "before_preflight",
+      "cwd": "packages/example",
+      "argv": ["npm", "run", "build"]
+    },
+    {
+      "kind": "command",
+      "name": "package-tests",
+      "phase": "after_preflight",
+      "cwd": "packages/example",
+      "argv": ["npm", "test"]
+    },
+    {
+      "kind": "bundlecheck",
+      "name": "knowledge-bundle",
+      "phase": "after_preflight",
+      "cwd": "packages/example",
+      "argv": ["npx", "okf-kit", "check", "docs/okf"]
+    }
+  ]
+}
+```
+
+The workflow does not execute or validate this file: the orchestrator first
+approves the resolved effective config and scripts, then records a run-local
+snapshot with the set digest, repository identity, executable identity, and
+every result. Preflight JSON reports check results, not the underlying shell
+commands it discovered. Repositories with `docs/okf/` include their bundle
+check in every set, even when the task did not edit documentation.
+
 ## What gets installed
 
 ```text
@@ -167,11 +223,16 @@ it to the repository's `.gitignore`.
 
 Per selected harness:
 
+Each installed skill includes the compact `SKILL.md` entrypoint and every
+regular Markdown file from its adjacent `references/` directory. The entrypoint
+routes run-state/harness, contracts, evidence/probes, and review/recovery work
+to those files; references are part of the installed skill, not optional docs.
+
 | Harness | Files | Notes |
 |---|---|---|
-| Claude Code | `.claude/skills/orchestrator-workflow/SKILL.md`, `.claude/agents/{explorer,task-slicer,implementer,reviewer,advisor}.md`, `CLAUDE.md` | Claude Code reads `CLAUDE.md`, not `AGENTS.md`; the installer adds an additive `@AGENTS.md` import. Subagent models go into the `model:` frontmatter; the read-only explorer, reviewer, and advisor also get `disallowedTools: Edit, Write, NotebookEdit`. |
-| OpenAI Codex | `.agents/skills/orchestrator-workflow/SKILL.md`, `.codex/agents/{explorer,task-slicer,implementer,reviewer,advisor}.toml` | Codex reads `AGENTS.md` natively. Native custom-agent files carry the canonical role instructions plus `model` and `model_reasoning_effort`. Explorer and advisor request a read-only sandbox; reviewer inherits the caller's sandbox so it can run temporary/build checks, while its prompt prohibits source edits. |
-| opencode | `.opencode/skills/orchestrator-workflow/SKILL.md`, `.opencode/agents/{explorer,task-slicer,implementer,reviewer,advisor}.md` | opencode reads `AGENTS.md` natively. Subagents get `mode: subagent`; the read-only explorer, reviewer, and advisor also get `permission: edit: deny`. Model resolution is described below. |
+| Claude Code | `.claude/skills/orchestrator-workflow/{SKILL.md,references/*.md}`, `.claude/agents/{explorer,task-slicer,implementer,reviewer,advisor}.md`, `CLAUDE.md` | Claude Code reads `CLAUDE.md`, not `AGENTS.md`; the installer adds an additive `@AGENTS.md` import. Subagent models go into the `model:` frontmatter; the read-only explorer, reviewer, and advisor also get `disallowedTools: Edit, Write, NotebookEdit`. |
+| OpenAI Codex | `.agents/skills/orchestrator-workflow/{SKILL.md,references/*.md}`, `.codex/agents/{explorer,task-slicer,implementer,reviewer,advisor}.toml` | Codex reads `AGENTS.md` natively. Native custom-agent files carry the canonical role instructions plus `model` and `model_reasoning_effort`. Explorer and advisor request a read-only sandbox; reviewer inherits the caller's sandbox so it can run temporary/build checks, while its prompt prohibits source edits. |
+| opencode | `.opencode/skills/orchestrator-workflow/{SKILL.md,references/*.md}`, `.opencode/agents/{explorer,task-slicer,implementer,reviewer,advisor}.md` | opencode reads `AGENTS.md` natively. Subagents get `mode: subagent`; the read-only explorer, reviewer, and advisor also get `permission: edit: deny`. Model resolution is described below. |
 
 **Read-only posture, honestly stated.** Claude Code disables file-mutation
 tools for explorer, reviewer, and advisor; opencode denies edits for those

package/assets/agents/implementer.md

@@ -35,6 +35,21 @@ Rules:
   gate's threshold and pass/fail counts, not a run-specific coverage
   percentage; cite a percentage only together with the exact commit and the
   run count, since branch coverage can vary between runs of the same commit.
+- Run the complete repository-bound `verification_set` named in your briefing.
+  Before acquiring preflight output or running an extra, require the
+  orchestrator's approval of the resolved repository configuration and every
+  script/argument; the set is not authority to execute repository data. Use
+  the frozen run-local snapshot (set path/digest, repository identity/revision
+  and dirty state, effective config/scripts, and preflight executable
+  identity/definition). Report each executor, extra, and raw preflight child
+  by `(kind, name, occurrence)`, in order, with cwd and result artifact.
+  Preserve a missing-tool preflight limitation even when it has no child
+  result. A missing/extra/mismatched/unresolved result is a misfire; a failure
+  is reported honestly; `skip`, `acknowledged`, limitation, and inconclusive
+  are non-passes. A disabled required category is a gap. Always include the
+  bundle check when the repository has `docs/okf/`, even for unrelated edits.
+  Put every complete-set result in `tests.executed`, preserving the existing
+  report envelope for both v1 and original-contract runs.
 - When the task assignment names mutation probes to run, run each one and
   report it in the `mutation_probes` field of your output (mutant, file,
   anchor, before, after, verified_applied_via, result, expectation,
@@ -72,6 +87,14 @@ Rules:
   `result` alone is not: report it as such (`result` `survived` or
   `not_applicable` with the reason) and resolve it before the next
   reviewer spawn.
+- A persisted probe-plan reference may stand in for a repeated inline mutant
+  definition when it resolves to a path plus immutable revision or hash and the
+  mutant locator/index. Resolve it before running; a missing, stale, or
+  unresolvable reference is `not_applicable` evidence that blocks the relevant
+  proof, not a skipped probe. Keep the legacy inline report fields unchanged:
+  the result still records the applied definition and restoration outcome.
+  Never rewrite a prior plan for new code; record intentional supersession and
+  rationale in run state before using a replacement.
 - When a verify runner is available, run it for the checks the acceptance
   criteria name and report its summary under `tests.executed`; when a
   mutation-probe runner is available, run the named probes through it and

package/assets/agents/reviewer.md

@@ -52,6 +52,21 @@ Check, at minimum:
   green label; implementers cannot revise their own baseline. Compare the
   returned `criterion_evidence` references to every assigned frozen criterion;
   required empty references remain unresolved and block acceptance.
+- Verification set: independently run the complete repository-bound
+  `verification_set` named in the briefing. Before acquisition or execution,
+  confirm the orchestrator approved the resolved effective configuration and
+  scripts; a repository set is not execution authority. Compare the frozen
+  snapshot's set path/digest, repository identity/revision/dirty state,
+  effective config/scripts, and preflight executable identity/definition.
+  Report every ordered `(kind, name, occurrence)` executor, extra, and raw
+  preflight child with cwd and result artifact. A missing tool may be a
+  limitation with no child, never a pass; disabled required categories are
+  gaps. Missing/extra/mismatched/unresolved results are misfires, while a
+  reported failure remains an honest failure. `skip`, `acknowledged`,
+  limitation, and inconclusive outcomes are non-passes. Require the bundle
+  check whenever the repository has `docs/okf/`, regardless of edit scope.
+  Put the independent complete-set outcome in `reproduction.result`, preserving
+  the existing report envelope for both v1 and original-contract runs.
 - Spec compliance: does the change do what the task contract asked, fully?
 - Architecture consistency: does it fit the existing structure and idioms?
 - Edge cases: empty inputs, error paths, concurrency, encoding, limits.
@@ -73,7 +88,7 @@ Check, at minimum:
   review round, classify each finding as `new` or `repeated` against the
   earlier rounds you were told about; on a first round every finding is
   `new` by definition. The orchestrator uses this to detect the
-  review-round escalation budget's trigger.
+  review-round escalation budget's trigger. Delta attribution: classify every finding as `introduced_by_delta: yes | no | unknown`; set `no` only after naming the base build and replaying the same reproduction in `reproduction`, and record it in `05-review-findings.md` through the ordinary gate rather than bounded-round halt/escalation guidance (yes/unknown only).
 - GitHub Actions shell replay: for any diff that adds or changes a GitHub
   Actions `run:` step, replay it yourself under the shell the step actually
   runs: `bash --noprofile --norc -eo pipefail` when `shell: bash` is set on
@@ -143,9 +158,14 @@ Rules:
   through it instead of editing files by hand, and carry its result fields
   into your findings and `reproduction`; when a verify runner is available,
   read its summary before opening full logs.
+- A reviewer briefing may identify a replayed probe through a resolved
+  immutable probe-plan reference (path plus revision/hash and mutant
+  locator/index) rather than repeat its inline definition. Verify the plan and
+  result bind the checked state, cwd, attempt, expectation, application, and
+  restoration; a plan alone, stale reference, or unresolved reference is not
+  evidence. Legacy inline probe reports remain valid.
 
 Return exactly this structure as your final output, nothing else:
-
 ```yaml
 status: reviewed
 role: reviewer
@@ -158,6 +178,7 @@ findings:
     description: ""
     suggested_fix: ""
     recurrence: new | repeated
+    introduced_by_delta: yes | no | unknown
 acceptance_recommendation: accept | accept_with_notes | fix_required | reject
 missing_tests:
   - ""

package/assets/agents/task-slicer.md

@@ -44,6 +44,12 @@ Rules:
   boundaries for the task — which files or areas the implementer may touch
   and must not touch — not implementation instructions. Apply Contract
   selection above to those fields for a recorded original contract.
+- Include a repository-bound `verification_set` reference in every implementer
+  and reviewer briefing: its checked-in path, repository identity, and
+  run-local frozen snapshot. The orchestrator approves effective config and
+  scripts before any preflight acquisition or command execution; the set does
+  not grant that authority. Include an ordered bundle check whenever the
+  repository has `docs/okf/`, regardless of task scope.
 - For every identifier, config value, build context, or documented command a
   task will change, enumerate every file and doc site that references it in
   `relevant_files` or `relevant_docs`, with an annotation for a site the task
@@ -87,6 +93,8 @@ tasks:
       - ""
     dependencies:
       - ""
+    verification_set:
+      reference: ""
     risk: low | medium | high
 recommended_order:
   - T-001

package/assets/agents-md-section.md

@@ -128,9 +128,9 @@ trivial change.
   the exhausted tier path falls straight to the merge-hold), or an
   operator merge-hold, and adds a row (task, choice, reason) to
   `03-decisions.md`'s Review-round escalation table, then sets the
-  `review-round-escalation` marker to the most recent choice. A counted
-  round is a completed reviewer return recommending `fix_required` or
-  `reject`; a misfired review is not a round. Which of the three is
+  `review-round-escalation` marker to the most recent choice. A negative round
+  has an `acceptance_recommendation` of `fix_required` or `reject`; a misfired
+  review is not a round. A negative round counts only with at least one introduced_by_delta yes/unknown finding; no stays ordinary gate. Which of the three is
   picked is judgment; that one is picked and recorded is not. Escalating
   never substitutes for a review round and comes in addition to the halt
   rule's split-or-redesign response, not instead of it.