orchestrator-workflow 0.40.1 → 0.42.0

package/assets/skill/references/bundle-gate-in-ci.md

@@ -0,0 +1,242 @@
+## Bundle gate in CI
+
+A knowledge bundle doc rots silently when someone changes one of its
+documented sources outside a run: no hand-off step fires, and the doc keeps
+describing the old code. Running the bundle check in CI on every change closes
+that gap. This reference describes one way to wire it up. GitHub Actions is the
+example host; the same steps work on any CI that can check out full history and
+run a shell step. The kit ships no CI files and generates none; copy and adapt
+the example.
+
+The examples use `okf-kit` as the bundle checker, the validator the hand-off
+step names. A different checker works the same way as long as it can report
+findings per rule in a machine-readable form.
+
+### Which bundles
+
+Gate every configured bundle, not only the default one. Each entry of
+`knowledge` in `.ai/workflow/manifest.json` names a bundle `path` and the
+`repoRoot` its sources live in (default `.`); with no `knowledge` list the one
+bundle is `docs/okf/` with `repoRoot` `.`. Run one check per bundle and pass
+`--repo-root <repoRoot>` explicitly: without it the checker detects the
+repository top level from the bundle directory, which is the wrong root for a
+workspace bundle whose sources live in a sub-repo.
+
+### Pin the checker
+
+Install the checker at a pinned version, written here as the placeholder
+`okf-kit@<pinned-version>`. An unpinned install picks up new rules on their
+release day and turns an unrelated change red. Bump the pin deliberately, in a
+change of its own, after the new version runs clean against the bundles. The
+example carries the pin as an environment value (`OKF_KIT_VERSION`), so a copy
+that still holds the placeholder fails the job instead of running something
+else.
+
+### Check out the full history
+
+Check out the full history (`fetch-depth: 0` with `actions/checkout`): the
+`sources-fresh` rule dates each source by its last commit and asks whether the
+doc's own last commit re-stamped the doc, and a shallow clone cannot answer
+that, so it reports `staleness not assessable` notices instead of a STALE
+verdict. A shallow checkout therefore looks clean while it assessed nothing.
+
+### Runner as an input
+
+Take the runner as an input of the job (for example a reusable workflow input
+`runner`) rather than hard-coding a runner label in the example. The label is a
+property of the consuming organization, not of the gate.
+
+### Staged rollout
+
+Roll the gate out in three stages and move to the next one only once the
+bundles run clean under the current stage:
+
+1. Stage 1, warn-only: run the check on every change, publish every finding as
+   an annotation and in the job summary, and never fail the job on a finding.
+   This surfaces existing drift without blocking anyone.
+2. Stage 2, block on structure and staleness: fail the job on any
+   error-severity finding (structure: frontmatter, links, sources shape) and on
+   any `sources-fresh` or `sources-fresh-future` warning, selected from the
+   `--json` report with a filter; other warnings stay advisory.
+3. Stage 3, strict: run the check with `--strict`, which fails on every
+   warning from every rule.
+
+The exit code alone is not the signal for stage 1 or stage 2: `okf-kit check`
+exits 0 when it finds only warnings (STALE and FUTURE-DATED findings are
+warnings) and 1 when it finds an error, so read the JSON report to decide.
+Any other outcome means the checker could not run: an exit status other than
+0 or 1, or a report that does not parse. It fails the job at every stage,
+including stage 1. The checker itself exits 2 whenever it cannot complete the
+check, for example on a usage error such as a missing bundle directory. The
+other could-not-run causes carry other statuses: a missing command exits 127
+and is caught by the exit status check; a failed install exits 1 from the
+package runner (`npx`), the same status as a finding, and is caught only
+because it leaves no parseable report; a report that does not parse is caught
+by the report check when the status is 0 or 1 (any other status already failed
+the exit status check).
+
+The stage 2 selection, as a `jq` filter over the `--json` report (any JSON
+tool works; the example below uses `jq`, so it needs `jq` on the runner; the
+report is `{ "findings": [{ "ruleId", "severity", "file",
+"message" }], ... }`):
+
+```sh
+jq '[.findings[]
+     | select(.severity == "error"
+              or (.severity == "warning"
+                  and (.ruleId == "sources-fresh"
+                       or .ruleId == "sources-fresh-future")))]
+    | length' "$report"
+```
+
+A result above 0 fails the job.
+
+### Example: GitHub Actions
+
+A reusable workflow with the runner and the stage as inputs and one matrix
+entry per configured bundle:
+
+```yaml
+on:
+  workflow_call:
+    inputs:
+      runner:
+        type: string
+        required: true
+      stage:
+        type: string # warn | block | strict
+        required: true
+
+jobs:
+  bundle-gate:
+    runs-on: ${{ inputs.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        bundle:
+          # one entry per `knowledge` entry in .ai/workflow/manifest.json
+          - { path: docs/okf, repoRoot: . }
+    steps:
+      - uses: actions/checkout@<pinned-ref>
+        with:
+          fetch-depth: 0
+      - name: Bundle check
+        shell: bash
+        env:
+          OKF_KIT_VERSION: <pinned-version>
+          BUNDLE: ${{ matrix.bundle.path }}
+          REPO_ROOT: ${{ matrix.bundle.repoRoot }}
+          STAGE: ${{ inputs.stage }}
+        run: |
+          if ! command -v jq > /dev/null; then
+            echo "bundle check could not run (jq not found)"; exit 2
+          fi
+          report="${RUNNER_TEMP:-${TMPDIR:-/tmp}}/okf-report.json"
+          strict=""
+          if [ "$STAGE" = "strict" ]; then strict="--strict"; fi
+          set +e
+          npx -y "okf-kit@$OKF_KIT_VERSION" check "$BUNDLE" \
+            --repo-root "$REPO_ROOT" --json $strict > "$report"
+          status=$?
+          set -e
+          if [ "$status" -ne 0 ] && [ "$status" -ne 1 ]; then
+            echo "bundle check could not run (exit $status)"; exit 2
+          fi
+          if ! jq -e '.findings | type == "array"' "$report" > /dev/null; then
+            echo "bundle check could not run (no parseable report)"; exit 2
+          fi
+          jq -r --arg b "$BUNDLE" '
+            def esc: gsub("%"; "%25") | gsub("\r"; "%0D") | gsub("\n"; "%0A");
+            def prop: esc | gsub(":"; "%3A") | gsub(","; "%2C");
+            .findings[]
+            | "::\(.severity) file=\("\($b)/\(.file)" | prop)::\("\(.ruleId): \(.message)" | esc)"' \
+            "$report"
+          jq -r --arg b "$BUNDLE" '"### Bundle check: \($b)",
+            (.findings[] | "- \(.severity) \(.ruleId) \(.file): \(.message)")' \
+            "$report" >> "$GITHUB_STEP_SUMMARY"
+          case "$STAGE" in
+            warn) exit 0 ;;
+            block)
+              blocking=$(jq '[.findings[]
+                | select(.severity == "error"
+                         or (.severity == "warning"
+                             and (.ruleId == "sources-fresh"
+                                  or .ruleId == "sources-fresh-future")))]
+                | length' "$report")
+              if [ "$blocking" -gt 0 ]; then exit 1; fi ;;
+            strict) exit "$status" ;;
+            *) echo "unknown stage: $STAGE"; exit 2 ;;
+          esac
+```
+
+The annotation command names match the checker's severities (`error`,
+`warning`, `notice`), so each finding lands on its file in the change view.
+The annotation line escapes `%`, carriage return and line feed in the message,
+and additionally `:` and `,` in the `file` property, as the workflow command
+syntax requires, so a message with a line break stays one whole annotation. A
+runner without `jq` fails the job with its own `jq not found` message instead
+of a misleading report error.
+The report goes to the runner's temporary directory, outside the checked-out
+work tree.
+
+### Pre-commit parity
+
+Run `okf-kit check <bundle> --repo-root <repoRoot> --dirty-as-now` before
+committing: it treats every uncommitted change as one virtual commit made now,
+so the local run reports the same `sources-fresh` and `sources-fresh-future`
+verdict CI will report once the commit lands. Without the flag a pre-commit
+run judges an edited source by its last commit and can report clean while CI
+reports STALE after the push. A hook loops over the same bundles as CI, with
+one `<bundle> <repoRoot>` pair per configured bundle:
+
+```sh
+report="$(mktemp)"
+trap 'rm -f "$report"' EXIT
+set -- docs/okf .
+while [ "$#" -ge 2 ]; do
+  status=0
+  okf-kit check "$1" --repo-root "$2" --dirty-as-now --json > "$report" \
+    || status=$?
+  if [ "$status" -ne 0 ] && [ "$status" -ne 1 ]; then
+    echo "bundle check could not run for $1 (exit $status)" >&2
+    exit 2
+  fi
+  # apply the same stage decision as CI to "$report" and "$status"
+  [ "$status" -eq 0 ] || exit 1
+  shift 2
+done
+if [ "$#" -ne 0 ]; then
+  echo "bundle list needs <bundle> <repoRoot> pairs" >&2
+  exit 2
+fi
+```
+
+Write the report outside the work tree: under `--dirty-as-now` a report file
+inside it is itself an uncommitted change and can mark a doc STALE whose
+sources cover that directory. The `trap` removes the temporary report when
+the hook exits, also when the check fails. Create the report and set the trap
+once, above the loop, and reuse the one file for every bundle: a trap set
+inside the loop is re-armed for the latest report only and leaves the earlier
+ones behind. The `trap` replaces an EXIT trap the hook already set; a hook
+that has one adds the `rm` to that trap instead.
+
+The loop checks each exit status itself, as the CI example does, so the hook
+fails with the checker's verdict whether or not it runs under `set -e`: exit 2
+when the checker exits with a status other than 0 or 1, exit 1 on a failing
+check, exit 2 when the bundle list is not made of whole `<bundle> <repoRoot>`
+pairs, and 0 otherwise. Reading the report belongs to the stage decision at
+the comment. The `set --` line replaces the hook's positional parameters with
+the bundle list; git passes a pre-commit hook none, and a hook that needs its
+own arguments saves them before the loop.
+
+Parity covers the verdict of those two rules, not the stage decision: apply
+the same stage filter locally, and add `--strict` only when CI runs stage 3.
+
+### What the gate proves
+
+The gate proves that a doc was re-stamped after its sources changed, not that
+its content is correct; review of the doc against its sources stays mandatory.
+A re-stamp without re-verification passes the gate, and a doc-only prose edit
+that leaves the sources untouched gives the staleness rules nothing to compare
+against. The gate complements the hand-off check and the reviewer; it replaces
+neither.

package/assets/skill/references/contracts.md

@@ -154,8 +154,13 @@ commits:
 
 Follow [evidence-and-probes.md workflow step 6](evidence-and-probes.md#workflow)
 for implementation evidence, verification, mutation probes, and replay. For
-commit reporting, follow the installed implementer role prompt. Return the
-selected contract's YAML envelope. `result: killed` means the probe's test
+commit reporting, follow the installed implementer role prompt. A return that
+reports an outward action (see AGENTS.md's Outward-facing actions rule) as
+executed is invalid, whatever the task assignment said; a local commit on the
+task branch is not an outward action. If you performed one anyway, report
+it in your return (what, where, when); performing one is forbidden,
+reporting it is mandatory. Return the selected contract's YAML envelope.
+`result: killed` means the probe's test
 command reacted to the mutant under the runner's pass predicate, or the
 test pass predicate declared in the task assignment or probe plan when no
 runner supplies a verdict; `survived` means it did not. `expectation: met`
@@ -180,7 +185,11 @@ the declared expected result, and label both derivations as manual.
 
 The output shape remains the same for either selected contract. Compare the
 delegated versioned records and producer evidence under Contract selection
-above; a recommendation does not replace orchestrator acceptance.
+above; a recommendation does not replace orchestrator acceptance. A return
+that reports an outward action (see AGENTS.md's Outward-facing actions rule)
+as executed is invalid; the reviewer never performs one. If you performed
+one anyway, report it in your return (what, where, when); performing one is
+forbidden, reporting it is mandatory.
 ```yaml
 status: reviewed
 role: reviewer
@@ -323,6 +332,46 @@ values. The copied criterion records retain `id`, `required`, `text`,
 contract, preserve its original strings and the same 1:1 field mapping with
 the transformation under Contract selection above.
 
+Knowledge bundle docs in `relevant_docs`: for each configured knowledge bundle
+(`knowledge` in `.ai/workflow/manifest.json`; default `docs/okf/`), every
+bundle doc whose `sources` intersect the task's `allowed_changes` is listed in
+`relevant_docs` with the bundle doc marker, written as `<doc path> (knowledge
+bundle; sources: <intersecting sources>)`. The marker is the one annotation
+that identifies a bundle doc entry; the task slicer writes it, and the
+implementer and reviewer recognize bundle docs by it. Resolve each doc's
+`sources` against its bundle's configured `repoRoot` and compare them with the
+`allowed_changes` in that repository. A source intersects when
+it names a path the task may change, a directory containing one, or a path
+inside a directory the task may change; a source that is itself a directory
+matches every path beneath it. Compute the
+intersection with a bundle tool when one is available (for example `okf-kit
+docs-for <bundle dir> <path>... --repo-root <repo root>`), or read each bundle
+doc's `sources` frontmatter. A bundle tool is queried with concrete paths, so
+first expand each directory or glob entry of `allowed_changes` to the tracked
+files it covers (for example `git ls-files -- <entry>`); when reading the
+frontmatter instead, match directory and glob entries against each source
+directly. An entry whose expansion is empty (for example a directory the task
+will create) is still queried: pass the entry itself alongside the expanded
+paths, since a path that does not exist yet still matches a directory source
+that contains it, or match the entry against the `sources` frontmatter
+directly. A brace glob such as `src/{a,b}.ts` is not expanded by a pathspec
+and is taken literally by a bundle tool, so expand it into its alternatives
+first (for example by the shell) or match it against the `sources` frontmatter
+directly. Query a bundle tool with paths relative to the bundle's `repoRoot`:
+for a workspace bundle whose `repoRoot` is a repository inside the workspace,
+strip that repository's workspace prefix from each `allowed_changes` entry and
+run the expansion inside that repository (for example `git -C <repo root>
+ls-files -- <entry>`), because an expansion prints paths relative to its
+working directory and a workspace-relative path is read as a path beneath the
+`repoRoot` and matches nothing; an entry outside that repository is not
+queried against that bundle. Each such doc is also listed in `allowed_changes`,
+so the implementer can re-stamp it. When `forbidden_changes` cover such a doc,
+the slicer leaves it out of `allowed_changes` and records an open question for
+the orchestrator instead. For a bundle whose docs live in a different
+repository than its sources (a workspace bundle), the re-stamp commit is one
+in the bundle's repository within the same task. This reuses `relevant_docs`;
+the contract shape is unchanged.
+
 ## Advisor output contract
 
 ```yaml

package/assets/skill/references/evidence-and-probes.md

@@ -27,8 +27,9 @@ directory and the subagents.
    If the task can proceed on reasonable assumptions, proceed without blocking.
 2. **Discover (optional, read-only).** When the goal, the solution, or the
    terrain is unclear, send the explorer subagent before planning. Have it
-   check for a curated knowledge bundle (for example a `docs/okf/` directory
-   with an index) before mapping terrain by hand, treating any claims found
+   check for a curated knowledge bundle (each one configured via `knowledge`
+   in `.ai/workflow/manifest.json`; default `docs/okf/`, typically a
+   directory with an index) before mapping terrain by hand, treating any claims found
    there as leads to verify, not as ground truth, and prefer a connected
    semantic code-search tool over raw grep for orientation questions; when a
    structural code-search tool is available, prefer it over text grep for
@@ -58,6 +59,11 @@ directory and the subagents.
    the 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 will not edit.
+   Every configured knowledge bundle doc whose `sources` intersect the task's
+   `allowed_changes` goes into `relevant_docs` with the bundle doc marker and
+   into `allowed_changes`, as contracts.md defines, so the task that changes a
+   source re-verifies and re-stamps its doc itself, in the same commit as the
+   source change, or in a later commit of the same task.
 5. **Validate tasks.** Check the slices are independently understandable, small
    enough, testable, ordered correctly, and aligned with the goal. Fix the
    slicing before any implementation starts. For an explicitly adopted v1 run,
@@ -152,6 +158,72 @@ directory and the subagents.
    engine. Only the orchestrator can explicitly revise a baseline, recording
    old/new revisions, affected IDs, authority and reason, invalidated evidence,
    and verified rationale for carrying unchanged evidence forward. Record a baseline revision only when scope or the normative text of a criterion changes, including a change to what its verification checks; a wording precision that leaves the check itself unchanged is a `03-decisions.md` entry, not a revision: the orchestrator records it, states in that entry why no evidence is invalidated, and communicates the corrected wording in the next delegation.
+   After each implementer return, mechanically cross-check its self-report
+   against the outward-actions rule (see AGENTS.md's Outward-facing actions
+   section). The `commits` comparison starts from the round's task base,
+   which the orchestrator names in this round's assignment as the
+   implementer's `<base>` (the sha the task branch started from on the
+   task's first round, or the previous round's reviewed head on a later
+   round); the ref check starts from the task's first-round base, so a ref
+   at an earlier round's commit stays covered. Neither starts from the
+   run-base, whose range also holds earlier tasks and upstream work merged
+   after it. When handing a round over, record its task base and the remote
+   default branch's sha at that moment (for example `git rev-parse
+   <remote>/<default-branch>` right after `git fetch <remote>`, or the
+   host's equivalent). Compare `git rev-list --reverse
+   <task-base>..<task-branch>` (or the host's equivalent) against the
+   returned `commits` field. List the remote's refs (for example `git
+   ls-remote <remote>`, or the host's equivalent) and flag every branch or
+   tag whose sha, peeled for an annotated tag, lies in the
+   `<first-round-base>..<task-branch>` range and is not reachable from the
+   remote default branch's sha recorded at this round's handover (for
+   example, every sha that `git rev-list <task-branch> ^<first-round-base>
+   ^<recorded-default-sha>` lists), unless the orchestrator moved that ref
+   to that sha itself (its own push, or a host-side merge it performed).
+   Reachability is judged from the recorded sha rather than the default
+   branch's current one, so a push of the task's commits to the default
+   branch is still flagged, while upstream work the task branch took in from
+   the recorded default branch is not. A round therefore takes in upstream
+   work only up to its recorded sha: a ref at a commit that reached the
+   default branch after the handover is flagged like one at the task's own
+   commits. Without a recorded sha, judge reachability from the first-round
+   base itself, which errs
+   toward a flag. Compare an existing task-branch ref
+   with the sha the orchestrator last pushed there, rather than treating the
+   ref's existence as a misfire; and confirm no pull request exists on the
+   task branch that the orchestrator did not open itself (for example `gh pr
+   list --head <branch>`, or the host's equivalent). A `commits` mismatch,
+   or a return that reports an outward action as executed, is a misfire:
+   do not fold it into run state as evidence, and recover it under the
+   subagent misfire rule. A pull request on the task branch that the
+   orchestrator did not open is, like a flagged ref, a signal to
+   investigate, not a misfire by itself: before treating it as one, the
+   orchestrator establishes who opened it (for example from the pull
+   request's author and the host's audit events, or by asking the
+   operator). When a subagent of the run opened it, or when that cannot be
+   established, it treats the pull request as a misfire and reports it to
+   the operator. A pull request a third party opened is recorded once in
+   `03-decisions.md`, naming its number or URL, and is not treated as a new
+   finding again in a later round. A
+   flagged ref is a signal to investigate, not a misfire by itself: before
+   treating it as one, the orchestrator establishes who moved the ref (for
+   example from the host's push or audit events, or by asking the
+   operator). When that cannot be established, it treats the ref as a
+   misfire and reports it to the operator. A ref a third party moved, or
+   one already recorded as an incident in an earlier round, is recorded
+   once in `03-decisions.md`, naming the ref and the sha it was recorded
+   at, and is not treated as a new finding again while it stays at that
+   sha; a later move of such a ref is investigated like any other flagged
+   ref. The ref check is a heuristic next to the
+   subagent's mandatory self-report, not a complete detector: for example,
+   it cannot see a deleted ref, a rewound default branch, a ref at an
+   already public sha, a ref at a commit a rebase dropped from the task
+   branch, or a pushed merge or squash of the task branch. When the check
+   finds an outward action was actually performed (a push, an opened pull
+   request) without authorization, that is more than a misfire to resume
+   past: the orchestrator informs the operator immediately, records the
+   incident in `03-decisions.md`, and lists it in `06-handoff.md`'s Sent /
+   Drafted Outward section as unauthorized.
 7. **Delegate review.** Send the diff to the reviewer subagent, naming in the
    briefing the base and head revision the diff was generated from. When tier
    variants are installed, pick the reviewer tier (the installed
@@ -279,15 +351,21 @@ directory and the subagents.
    subagent, if any) by the same complexity-and-risk judgment already used
    for the implementer and reviewer tiers, defaulting to the unsuffixed
    subagent (already effort `high`) when unsure.
-9. **Hand off.** Before filling `06-handoff.md`, apply this optional
-   guidance: when the repo carries a curated knowledge bundle (for example a
-   `docs/okf/` directory with an index), check whether the change touches
-   paths any bundle doc claims as sources; if so, update the affected docs
+9. **Hand off.** Bundle docs whose sources a task changes are listed in its
+   `relevant_docs` at slicing (step 4) and re-stamped by that task, so this
+   hand-off check is a safety net for sources the task list missed. Before
+   filling `06-handoff.md`, apply this optional
+   guidance: when the repo carries a curated knowledge bundle (each one
+   configured via `knowledge` in `.ai/workflow/manifest.json`; default
+   `docs/okf/`), check whether the change touches
+   paths any bundle doc claims as sources that no task re-stamped; if so,
+   update the affected docs
    (re-verify and re-stamp) or record a follow-up task, and run the bundle
    validator when one is available (for example `okf-kit check`). Repos
    without a bundle are unaffected. Then fill `06-handoff.md` and report to the
    operator: what changed, why, how it was verified, known risks, accepted
-   waivers, suggested next step. Before handing off, check that no org-,
+   waivers, documentation impact (none with a reason, updated paths, or a
+   follow-up), suggested next step. Before handing off, check that no org-,
    machine-, or point-in-time-bound evidence was added to a reusable
    instruction file; such evidence belongs in the changelog, the run files,
    or the consuming workspace, with a pointer left behind.
@@ -361,8 +439,9 @@ categories disabled by effective configuration are reported as gaps. A missing,
 extra, mismatched, or unresolved named result is a misfire; a reported failure
 is an honest failure, not a misfire. `skip`, `acknowledged`, `limitation`, and
 inconclusive results remain non-passes and cannot be silently accepted. When a
-repository has `docs/okf/`, include its bundle check in every set regardless of
-which files changed. This is a documented convention, not an OW execution
+repository has a configured knowledge bundle (default `docs/okf/`, see
+`knowledge` in `.ai/workflow/manifest.json`), include its bundle check in
+every set regardless of which files changed. This is a documented convention, not an OW execution
 engine or runtime schema validator. A quoted probe verdict is not a named result
 of the verification set, so the set's missing-or-extra rule does not apply to it.
 

package/assets/skill/references/review-and-recovery.md

@@ -8,7 +8,15 @@ against its role's output contract, including an implementer return that
 omits the `mutation_probes` field even though the task assignment named
 mutation probes to run, or that omits the `commits` field even though the
 task assignment asked for a commit, or that omits the `class_closure`
-field on any round after the task's first. When a subagent returns near-instantly
+field on any round after the task's first, or that reports an outward
+action (see AGENTS.md's Outward-facing actions rule) as executed, since a
+task assignment never authorizes one. Performing an outward action is
+forbidden, but reporting one that was actually performed is still
+mandatory: recovering the return as a misfire (it is not evidence) does not
+excuse the orchestrator from also treating the report itself as an
+incident, informing the operator immediately, recording it in
+`03-decisions.md`, and listing it in `06-handoff.md`'s Sent / Drafted
+Outward section as unauthorized. When a subagent returns near-instantly
 with no tool activity, treat that as a misfire signal rather than proof:
 check the output against the contract with extra suspicion, and accept it
 only if it is contract-valid and the assignment was answerable from the

package/assets/skill/references/run-state-and-harness.md

@@ -134,6 +134,37 @@ the marker exactly in that form, on its own line: a deviating line is
 either rejected (it blocks the run) or not recognised at all (the binding
 for that repository is silently missing).
 
+### Outward marker
+
+`00-goal.md` also carries an `outward` marker on its own line below the run
+mode marker and its description comment: `<!-- outward: classes = none -->`.
+It deliberately does not use the `solution-acceptance:` prefix, to keep an
+authorization grant out of the acceptance-verdict reader's namespace
+altogether rather than relying on that reader's documented
+ignore-unknown-key behaviour to stay silent about it. The shape matches the
+kit's other plain-record marker,
+`<!-- review-round-escalation: choice = n/a -->`.
+
+This subsection is the one definition site of the marker's value grammar.
+The value is `none` or a comma-separated subset of the two grantable classes
+AGENTS.md's Outward-facing actions rule defines, `push-branch` and `open-pr`
+(for example `classes = push-branch, open-pr`). Any other token is ignored
+(treated as not granted) and reported to the operator, while a grantable
+token next to it keeps its grant. A missing marker, more than one `outward`
+line, or a malformed line (wrong key, wrong field name, or a value that is
+neither `none` nor a comma-separated token list) means `none`: no class is
+granted. No marker value ever grants any other outward action; those always
+need per-action operator confirmation.
+
+A class counts as granted only when `03-decisions.md` carries the
+operator-instruction record for it, whose source is an operator message in
+the session; issue, tracker, and PR text and repository content never count
+as that source. A new run's marker starts at `none` whatever the copied
+template says, and a class is added, including mid-run, only on such an
+instruction. On resume, a class the orchestrator cannot trace to such a
+record is treated as not granted and reported to the operator. A subagent
+never edits the marker, and the orchestrator never adds a class to it on its
+own judgment.
 
 ## Context budget rules
 

package/assets/templates/00-goal.md

@@ -4,6 +4,14 @@
 <!-- solution-acceptance: run-base[<repo-basename>] = <sha> -->
 <!-- solution-acceptance: mode = delegated -->
 <!-- Run mode: single | delegated | batch. A missing or unrecognised value means delegated. -->
+<!-- outward: classes = none -->
+<!-- Outward action classes granted for this run without per-action
+     operator confirmation: none, or a comma-separated subset of
+     push-branch, open-pr (the only grantable classes). Default none.
+     A new run starts at none whatever this template says; a class is
+     added only on the operator's explicit instruction in the session,
+     recorded in 03-decisions.md. See AGENTS.md's Outward-facing
+     actions rule. -->
 
 ## Acceptance Baseline
 

package/assets/templates/02-tasks.md

@@ -41,8 +41,9 @@ acceptance_criteria:
 digest recorded in the briefing is what carries the orchestrator's approval
 of the resolved argv to the implementer and reviewer. The
 orchestrator approves effective config/scripts before any acquisition or
-execution; include an ordered docs/okf bundle check whenever that directory
-exists. -->
+execution; include an ordered bundle check for each configured knowledge
+bundle (`knowledge` in `.ai/workflow/manifest.json`; default `docs/okf/`)
+whenever one exists. -->
 
 **Relevant Files / Areas**
 
@@ -51,6 +52,9 @@ exists. -->
 **Relevant Docs**
 
 - <!-- doc, ADR, or run file the task relies on, or none -->
+- <!-- each knowledge bundle doc whose sources intersect the allowed changes,
+     marked `<doc path> (knowledge bundle; sources: <intersecting sources>)`
+     (contracts.md defines the marker) -->
 
 **Acceptance Criteria**
 

package/assets/templates/06-handoff.md

@@ -27,11 +27,31 @@
 ## Knowledge Bundle
 
 <!-- Optional: only applies when the repo carries a curated knowledge bundle
-     (for example a docs/okf/ directory). Outcome: updated | not affected |
-     follow-up filed. -->
+     (each one configured via `knowledge` in `.ai/workflow/manifest.json`;
+     default `docs/okf/`). This is the safety net for bundle docs no task
+     re-stamped: a task that changes a doc's sources re-stamps it itself.
+     Outcome: updated | not affected | follow-up filed. -->
 
 - <!-- outcome and brief note, or omit this section when the repo carries no bundle -->
 
+## Documentation Impact
+
+<!-- Human-facing documentation (README, ADRs, architecture docs, end-user
+     docs) affected by this run. Exactly one of: none (<reason>) |
+     updated: <paths> | follow-up: <task>. -->
+
+- <!-- none (<reason>) | updated: <paths> | follow-up: <task> -->
+
+## Sent / Drafted Outward
+
+<!-- Optional: only applies when this run performed or drafted an outward
+     action (push, pull request, ticket comment/transition/close, release,
+     publish, message). Omit this section when nothing was sent or drafted. -->
+
+- <!-- action class, what was sent (with confirmation basis), what stayed a
+     draft in the run directory and why, or an action performed without
+     authorization (unauthorized) -->
+
 ## Follow-Ups
 
 - <!-- next steps or none -->

package/dist/cli.js

@@ -887,6 +887,12 @@ function printTargetDetail(target, operatorVersion) {
     for (const gap of target.routingComparisonGaps ?? []) {
         console.log(`  Routing comparison incomplete: ${gap}`);
     }
+    // Knowledge-bundle warnings print for every status: they never change
+    // the status line, so without this line a plain `doctor` run would show
+    // `clean` and hide them (they are otherwise only in `--json`).
+    for (const warning of target.knowledgeWarnings ?? []) {
+        console.log(`  knowledge: ${warning}`);
+    }
     const showsVersionLagDetail = (target.status === "version-lag" ||
         ((target.status === "divergent" || target.status === "drift") &&
             target.versionLag)) &&

package/dist/doctor.d.ts

@@ -44,6 +44,17 @@ export interface TargetReport {
     driftFiles: string[] | null;
     /** Selected legacy opencode leaves that cannot be compared offline. */
     routingComparisonGaps?: string[];
+    /**
+     * Knowledge-bundle warnings against this target's own filesystem: a
+     * malformed `knowledge` entry dropped on read (index and reason), a
+     * configured `path` or `repoRoot` that is not a directory under the
+     * target's top level, or a non-empty `knowledge` list that omits an
+     * existing `docs/okf/` at the target's root. Omitted when there is none.
+     * Printed as `knowledge:` detail lines in the human output. These
+     * warnings never change `status` or the doctor exit code -- they surface
+     * a documentation-locator drift, not a kit-file install drift.
+     */
+    knowledgeWarnings?: string[];
     /** Human-output-only: the repo's own profile, or null when unknown. */
     repoProfile: Profile | null;
     /** Human-output-only: the operator default profile, for the comparison line. */
@@ -87,6 +98,8 @@ export interface TargetReportJson {
     driftFiles: string[] | null;
     /** Selected legacy opencode leaves that cannot be compared offline. */
     routingComparisonGaps?: string[];
+    /** See {@link TargetReport.knowledgeWarnings}. */
+    knowledgeWarnings?: string[];
     versionLag: boolean;
     reason: string | null;
 }