orchestrator-workflow 0.40.1 → 0.41.0

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

@@ -0,0 +1,193 @@
+## 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 (exit 2 for a usage error
+such as a missing bundle directory, a failed install, a missing command, or a
+report that does not parse), and it fails the job at every stage, including
+stage 1.
+
+The stage 2 selection, as a `jq` filter over the `--json` report (any JSON
+tool works; 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: |
+          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" '.findings[]
+            | "::\(.severity) file=\($b)/\(.file)::\(.ruleId): \(.message)"' \
+            "$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 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:
+
+```sh
+report="$(mktemp)"
+okf-kit check docs/okf --repo-root . --dirty-as-now --json > "$report"
+# apply the same stage decision as CI to "$report"
+```
+
+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.
+
+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,32 @@ 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. 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,62 @@ 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,
+   a pull request the orchestrator did not open, 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
+   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` 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,10 +341,15 @@ 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
@@ -361,8 +428,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;
 }

package/dist/doctor.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { PACKAGE_VERSION } from "./assets.js";
-import { MANIFEST_PATH, readInstalledManifest } from "./init.js";
+import { MANIFEST_PATH, knowledgeEntryProblems, readInstalledManifest, } from "./init.js";
 import { DEFAULT_MODELS, rolesForProfile } from "./models.js";
 import { compareRoutingState } from "./routing-state.js";
 import { OPERATOR_MANIFEST_FILENAME, operatorManifestState, updateOperatorManifest, } from "./operator-manifest.js";
@@ -17,6 +17,9 @@ export function targetReportToJson(report) {
         ...(report.routingComparisonGaps?.length
             ? { routingComparisonGaps: report.routingComparisonGaps }
             : {}),
+        ...(report.knowledgeWarnings?.length
+            ? { knowledgeWarnings: report.knowledgeWarnings }
+            : {}),
         versionLag: report.versionLag,
         reason: report.reason,
     };
@@ -111,6 +114,61 @@ function computeDriftFiles(targetPath, manifest) {
     }
     return drifted;
 }
+/** The kit-wide implicit default knowledge-bundle location every site falls
+ * back to when a target configures no `knowledge` list at all. */
+const DEFAULT_KNOWLEDGE_PATH = "docs/okf";
+/** The raw `knowledge` value of a target's manifest file, before
+ * `readInstalledManifest` drops invalid entries; `undefined` when the field
+ * is absent or the file cannot be re-read. */
+function readRawKnowledge(targetPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(targetPath, MANIFEST_PATH), "utf8"));
+        if (typeof parsed !== "object" || parsed === null)
+            return undefined;
+        return parsed.knowledge;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isDirectoryAt(path) {
+    const stat = statOrClassify(path);
+    return stat.kind === "ok" && stat.stat.isDirectory();
+}
+/**
+ * Checks a target's configured `knowledge` list against its own filesystem.
+ * Each raw entry `readInstalledManifest` dropped as malformed is reported
+ * with its index and reason. For each kept entry, `path` and `repoRoot` are
+ * resolved against the target's top level independently (the manifest's
+ * model; `path` is not nested under `repoRoot`) and each one that is not a
+ * directory is reported by name. A non-empty list whose normalised `path`s
+ * omit an existing `docs/okf/` at the target's root (the implicit default
+ * every kit site assumes absent a `knowledge` field) is reported once.
+ * Absent or empty `knowledge` is today's default behaviour and never warns
+ * about `docs/okf/`: a repo that never configured `knowledge` is not warned
+ * about lacking an entry for its own default.
+ */
+function computeKnowledgeWarnings(targetPath, manifest) {
+    const knowledge = manifest.knowledge ?? [];
+    const warnings = knowledgeEntryProblems(readRawKnowledge(targetPath));
+    for (const bundle of knowledge) {
+        if (!isDirectoryAt(join(targetPath, bundle.path))) {
+            warnings.push(`missing configured knowledge path: ${bundle.path}`);
+        }
+        if (bundle.repoRoot !== "." &&
+            !isDirectoryAt(join(targetPath, bundle.repoRoot))) {
+            warnings.push(`missing configured knowledge repoRoot: ${bundle.repoRoot}`);
+        }
+    }
+    if (knowledge.length > 0) {
+        const docsOkfExists = isDirectoryAt(join(targetPath, DEFAULT_KNOWLEDGE_PATH));
+        const docsOkfConfigured = knowledge.some((bundle) => bundle.path === DEFAULT_KNOWLEDGE_PATH);
+        if (docsOkfExists && !docsOkfConfigured) {
+            warnings.push(`${DEFAULT_KNOWLEDGE_PATH}/ exists but is not in the configured knowledge list`);
+        }
+    }
+    return warnings;
+}
 function baseReport(target, operator, status, reason) {
     return {
         path: target.path,
@@ -210,6 +268,7 @@ export function inspectTarget(target, operator, kitVersion) {
     const versionLag = hasPin
         ? manifest.pin !== manifest.version
         : manifest.version !== kitVersion;
+    const knowledgeWarnings = computeKnowledgeWarnings(target.path, manifest);
     let status;
     if (driftFiles.length > 0) {
         status = "drift";
@@ -236,6 +295,7 @@ export function inspectTarget(target, operator, kitVersion) {
         ...(routingComparison.gaps.length > 0
             ? { routingComparisonGaps: routingComparison.gaps }
             : {}),
+        ...(knowledgeWarnings.length > 0 ? { knowledgeWarnings } : {}),
         repoProfile: manifest.profile,
         operatorProfile: operator.defaults.profile,
         repoTiers: manifest.tiers,