@walwal-harness/cli 7.1.56 → 7.1.58

package/commands/submission.md

@@ -10,25 +10,27 @@ Route the Owner request to the installed `harness-ceo` agent/skill as an additio
 Codex adapter:
 - If Codex does not auto-load `harness-ceo`, manually read `.codex/skills/harness-ceo/SKILL.md` and follow it.
 - Absence of `.codex/agents/` is not a failure. `.codex/skills/**/SKILL.md` is the Codex runtime protocol.
-- For CXX "fresh session context", use role-scoped context: read the CXX skill, active mission files, and required conventions/gotchas before writing that role's `{cxx}.md`.
+- Prefer a genuinely separate CQO session (Claude Agent, Codex sub-agent, or `codex exec`) from implementation. Reading another role skill in the same session is only a role switch, not independent verification. If separate execution is unavailable, record `Verification Session: same-session` and disclose the limitation to Owner; the completion gate warns but permits it.
+
+At intake, classify and record `tier` (S/M/L) using the CEO Mission Tier criteria; record the rationale in `ceo.md`. Preserve the highest historical tier when requirements change.
 
 Required flow:
 1. Locate the active goal document root under `.harness/documents/{goal_name}/`. If no active goal exists, CEO must create/select the best matching goal record from available mission context or mark the submission blocked with the recommended default; do not ask the Owner an open-ended setup question.
 2. If another child mission under the goal is active, update its `mission-state.json` to `closed`, `cancelled`, or `superseded` with `active:false` before starting this submission.
 3. Create a submission record under `.harness/documents/{goal_name}/submission-{submission_index}-{submission_name}/`.
-4. Write `.harness/documents/{goal_name}/submission-{submission_index}-{submission_name}/mission-state.json` with `{"lifecycle":"active","active":true}`.
+4. Write `.harness/documents/{goal_name}/submission-{submission_index}-{submission_name}/mission-state.json` with `{"lifecycle":"active","active":true,"tier":"S"}` (replace S with the classified tier).
 5. Record CEO decisions in `.harness/documents/{goal_name}/submission-{submission_index}-{submission_name}/ceo.md`.
 6. CEO routes only to the CXX agents needed for this additional requirement. CEO must not ask the Owner which CXX or worker path to choose.
 7. CXX roles must start in a fresh session context. Do not let the default model impersonate a missing CXX or worker.
-8. CXX roles must not directly execute specialist deliverables. They must use hired workers for research, planning, design, implementation, QA, ops checks, and documentation.
+8. At effective tier M/L, and for COO/CDO deliverables at every tier, delegate specialist execution to hired workers. At S, CTO implements directly and CQO directly runs verification in a separate session; no CTO/CQO hiring is needed. At S/M, OPS observes directly. CQO starts only after CTO's CQO Handoff — never in parallel. A CXX writes a document only when summoned; a summoned COO/CDO/OPS with no work writes only `## Not Applicable` and one reason.
 9. If a required worker is missing, the responsible CXX must invoke the installed `harness-hiring` skill before assigning the work.
 10. CXX must manage conventions for new requirements. Durable changes in behavior, architecture, UI, process, or policy must be reflected in `.harness/conventions/` when accepted.
-11. CEO must require a Worker Evidence Manifest and worker report paths under `.harness/documents/{goal_name}/submission-{submission_index}-{submission_name}/{owning-cxx}/workers/` before accepting CXX completion.
-12. When the submission is accepted, cancelled, superseded, blocked, or closed, update `mission-state.json` to `complete`, `cancelled`, `superseded`, `blocked`, or `closed` and set `active:false`. Then fire the matching runtime transition as the literal final action of the turn so the terminal document state matches the `progress.json` flag the harness reads: finished/closed → `bash scripts/harness-company-complete.sh . submission-complete`; external-authority block → `bash scripts/harness-company-block.sh . "<exact missing authority>"`. This clears `progress.json` out of `running` so the autonomous loop stops cleanly and the dashboard shows idle/done.
+11. For roles requiring workers, CEO must require a Worker Evidence Manifest and worker report paths under `.harness/documents/{goal_name}/submission-{submission_index}-{submission_name}/{owning-cxx}/workers/` before accepting CXX completion.
+12. For acceptance, leave the mission active and run `bash scripts/harness-company-complete.sh . <reason> <mission-rel>` as the final action; the script checks evidence before writing `complete` and `active:false`. On refusal, keep working. For termination without acceptance, first write lifecycle `cancelled`, `superseded`, or `closed` and `active:false`, then call the same explicit transition. `closed` means ended without acceptance; disclose “미수락 종료” in the Owner report and never archive without PASS. For an external-authority block, record `blocked`/`active:false` and run `bash scripts/harness-company-block.sh . "<exact missing authority>"`. `<mission-rel>` is the path relative to `.harness/documents/`.
 13. Do not invoke internal roles through slash commands; commands are Owner entrypoints only.
 14. Do not ask the Owner whether to continue, hire workers, choose internal options, or start the next step. If CEO cannot decide alone, convene the relevant CXX agents and decide from their written recommendations. CEO may approve reversible routine operations such as local cron/launchd/wake automation, dashboard refresh, monitoring cadence, Telegram briefing format using existing credentials, and mission consolidation/supersede cleanup. Stop only for external authority such as new credentials/secrets, payment approval, legal/business acceptance, unavailable production access, destructive data action, or direct conflict with stated Owner direction.
 
-Lessons before plan (AGENTS.md Hard Rule 20): CEO and every CXX read `.harness/conventions/{shared,role}.md` and `.harness/gotchas/{shared,role}.md`, follow only the topic links those files name, and write `## Lessons Preflight` **before** the first edit, the first measurement, and the first worker brief. Every role document and worker report closes with a one-line `## Lessons Tally` immediately above `## Implementation Notes` — `0 fired` is a valid tally and must be stated, not omitted. Requirements a CXX must satisfy that its workers must also satisfy go into the worker brief **verbatim**. The Stop hook enforces this; it is not advisory.
+Lessons before plan: read relevant shared/role conventions and gotchas before edits, measurements, or briefs. At effective tier S/M, role documents may replace Lessons Preflight + Lessons Tally with `## Lessons` containing `Preflight: <applicable items and why>` (before work) and `Fired: <items or 0 fired>` (at completion). `## Implementation Notes` may contain concise bullets. At L, retain Lessons Preflight, Lessons Tally, and all four Implementation Notes subsections. All worker reports retain the full seeded format at every tier. **Worker brief:** name the seeded report path and instruct the worker to fill its existing sections incrementally. Do not copy the report skeleton, Tally, or Notes block into the brief. Continue to pass relevant corpus links and copy behavioral requirements absent from the seed (including the browser-automation clause) verbatim.
 
 Note: `/submission` is not a new company goal and not an emergency fix. It is an additional requirement while pursuing the active goal. It belongs under that goal in history.
 

package/conventions/README.md

@@ -18,3 +18,5 @@ Only company-level roles are provided by default:
 Topic-specific convention files may use descriptive names such as `i18n-locale.md`.
 
 CXX files such as `cto.md` and `cqo.md` act as lazy-loading indexes. Add links there when a topic file applies to that CXX.
+
+**Declare the audience.** Every convention names each role that must be able to *find* it — `<!-- roles: cto, cqo -->` at the top of a topic file, or `- **Roles**: cto, cqo` inside an index entry — and is linked from each of those roles' index files, not only its author's. Lazy loading is a promise about reachability: an entry filed only under its author is indexed but invisible to the readers it names. Verify with `bash scripts/harness-corpus-reachability.sh . text` (`--fix` adds the missing links). Entries in `shared.md` need no cross-linking; every role reads it.

package/conventions/shared.md

@@ -24,6 +24,16 @@
 - CXX decisions use `{cxx}.md`.
 - Worker reports use `{owning-cxx}/workers/{worker-name}.md`.
 
+## Declared Audience
+
+Every convention and gotcha declares which roles must be able to **find** it, and is linked from each of those roles' index files.
+
+- Topic file: `<!-- roles: cto, cqo -->` near the top.
+- Entry inside an index file: `- **Roles**: cto, cqo`.
+- Registration is complete only when `bash scripts/harness-corpus-reachability.sh . text` passes. `--fix` adds the missing links.
+
+Lazy loading tells a reader to consult `{shared, own-role}` and nothing else. That is a **promise about reachability**: where the promise is not kept, the rule stops narrowing the search and starts hiding the entry. An agent following the reading rule exactly will never see an item filed only under someone else's index.
+
 ## Section-Scoped Reading
 
 Any reader that scans a role document, worker report, or mission record for sections — a script, a hook, an agent following a protocol — matches:

package/gotchas/README.md

@@ -18,3 +18,5 @@ Only company-level roles are provided by default:
 Topic-specific gotcha files may use descriptive names such as `i18n-locale-hotfix.md`.
 
 CXX files such as `cto.md` and `cqo.md` act as lazy-loading indexes. Add links there when a topic file applies to that CXX.
+
+**Declare the audience.** Every gotcha names each role that must be able to *find* it — `<!-- roles: cto, cqo -->` at the top of a topic file, or `- **Roles**: cto, cqo` inside an index entry — and is linked from each of those roles' index files, not only its author's. Lazy loading is a promise about reachability: an entry filed only under its author is indexed but invisible to the readers it names. Verify with `bash scripts/harness-corpus-reachability.sh . text` (`--fix` adds the missing links). Entries in `shared.md` need no cross-linking; every role reads it.

package/gotchas/cqo.md

@@ -19,3 +19,14 @@ An instrument's filtering behaviour is read from source and quoted — package,
 ## Audit Questions That Offer Alternatives
 
 An audit question that offers alternatives asserts that the alternatives are exhaustive. "Is it a skip rule **or** a status-conditional format?" cannot return "neither, it is upstream" — both branches locate the rule inside our own code, so the true answer is unreachable from the question's grammar. When an audit stalls, re-ask the question without the menu.
+
+## A Range Is The Two Least Representative Points
+<!-- roles: cqo, ops -->
+
+Publish a summary statistic **with its `n`**, and characterise a spiky series by **percentiles, never min–max**. A range reports the two most extreme observations in the set and reads as a finding; on a spiky series it is almost always noise wearing the shape of a result.
+
+## Cross-role Links
+
+Entries written under another role that name CQO as an audience.
+
+- [Complete Against A Spec Version, Never In The Abstract](./cto.md) — verify `spec-pins.json` before PASS and before archive.

package/gotchas/cto.md

@@ -11,3 +11,10 @@ Do not start implementation before domain, API, platform, account, and integrati
 ## Stub Report From A Worker Killed Mid-Round
 
 A report assembled at the end of a round becomes a stub when the round is cut short, and a stub halts the company. Create the worker report with every required section present **before** the worker starts, and require it to be filled in incrementally. Same failure, opposite outcome: an unseeded worker killed mid-round leaves a stub and costs a re-run; a seeded worker killed by the same limit leaves an intact partial report and costs nothing. The variable is a decision taken before the round.
+
+## Complete Against A Spec Version, Never In The Abstract
+<!-- roles: cto, cqo -->
+
+A category marked complete records *what it was complete against*. A spec moved `v0.7 → v0.9`, changing a response contract, while the category built against `v0.7` sat marked done — two later revisions landed silently and nothing in the harness recorded which version the work had been for.
+
+The symptom was not an error. A lookup key stopped matching, and three map overlays were dropped as `null`: no exception, no log, just an absence. Pin version **and content hash** with `scripts/harness-spec-pin.sh` before implementation, and re-verify before completion and archive.

package/gotchas/ops.md

@@ -19,3 +19,9 @@ Do not let CXX agents choose arbitrary ports. CEO must set `HARNESS_BASE_PORT` a
 ## Clean Log From An Unproven Instrument
 
 "Nothing bad appeared in the log" is worth nothing until a positive control proves the log could have shown it. Dev servers, log middleware, proxies, and test runners routinely drop successful or sub-threshold requests at a log level nobody chose deliberately, and that rule appears nowhere in the project's own code. Record the instrument — tool, log level, filter, control — in Environment Evidence, or report the observation as unverified rather than clean.
+
+## Cross-role Links
+
+Entries written under another role that name OPS as an audience.
+
+- [A Range Is The Two Least Representative Points](./cqo.md) — publish `n`, use percentiles, not min–max.

package/gotchas/shared.md

@@ -29,3 +29,19 @@ A reader anchored on `^#` misses the same heading written as `> ## …`, which i
 ## Rules Stated One Layer Above The Executing Layer
 
 A requirement placed on a CXX that its workers must also satisfy does not reach the workers unless it is inserted **verbatim** into the worker brief. A rule stated one layer above the layer that executes it does not apply, and the layer below cannot infer a rule it was never given.
+
+## The Author Files Under Itself
+<!-- roles: ceo, coo, cdo, cto, cqo, ops -->
+
+The recurring way an indexed entry becomes unreachable: whoever wrote it filed it under their own role index and nowhere else. Registration *feels* complete — the entry exists, it is indexed, it is linked. It is just not where its declared readers are told to look.
+
+Measured on a live corpus: 69 items, **10 unreachable role-routings, 7 of them invisible to a role the entry itself named**. The clearest case was an entry whose own text called two others "the same family" — both siblings were already reachable from the index it was missing from. An inconsistency, not a decision.
+
+Declare the audience at registration and let `scripts/harness-corpus-reachability.sh` link it. Reading is not reaching.
+
+## A Conclusion Not Written Is Not Held
+<!-- roles: ceo, coo, cdo, cto, cqo, ops -->
+
+A conclusion a session holds but has not written into its role document and the runtime state file is not held by the company. Reconcile before reporting; strike and correct in place, never delete.
+
+The cheap version: a deliverable table that contradicts three messages already sent, and a line still requesting work a peer has already delivered. The expensive version was measured — a required step completed, reported, and accepted, that never reached the state file, so the orchestration loop went on trying to spawn the finished step **70 times**. "Write your conclusions down" reads as tidiness until it reads as seventy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "7.1.56",
+  "version": "7.1.58",
   "description": "Company-style AI agent harness for Claude and Codex. Installs commands, CXX agents, skills, HR-Resource hiring pool, and project-local .harness runtime state.",
   "bin": {
     "walwal-harness": "bin/init.js"

package/scripts/harness-company-complete.sh

@@ -2,11 +2,11 @@
 # harness-company-complete.sh — mark the current v7 company mission complete.
 #
 # Usage:
-#   bash scripts/harness-company-complete.sh <project-root> [reason]
+#   bash scripts/harness-company-complete.sh <project-root> [reason] [mission-rel]
 #
 # This is the explicit running -> idle/done transition used by dashboard,
 # runner, hooks, and final CEO handoff paths. It intentionally only updates
-# runtime state; it does not archive or rewrite mission documents.
+# runtime state and mission lifecycle; it does not archive mission documents.
 
 set -uo pipefail
 
@@ -16,6 +16,7 @@ REASON="${2:-mission-complete}"
 
 PROGRESS="$PROJECT_ROOT/.harness/progress.json"
 TODOS="$PROJECT_ROOT/.harness/todos/state.json"
+DOCS="$PROJECT_ROOT/.harness/documents"
 [ -f "$PROGRESS" ] || {
   echo "[company-complete] not found: $PROGRESS" >&2
   exit 1
@@ -25,30 +26,6 @@ command -v jq >/dev/null 2>&1 || {
   exit 1
 }
 
-# Lessons-before-plan gate (AGENTS.md Hard Rule 20). The Stop hook cannot see
-# this path: once this script sets conductor.state=completed, harness-stop.sh
-# short-circuits at the top, so a mission could complete having never read the
-# corpus simply by firing the transition. Refuse the terminal transition here —
-# this is the transition P6 names, and it is the last point at which refusing
-# still means anything.
-#
-# Safe against deadlock: the gate is scoped to the latest ACTIVE mission, so the
-# stop-hook backstop (which fires only when no mission is active) always passes.
-# Opt out per project with .harness/config.json behavior.lessons_gate=false, or
-# override a single call with HARNESS_SKIP_LESSONS_GATE=1.
-if [ "${HARNESS_SKIP_LESSONS_GATE:-0}" != "1" ] && [ -x "$SCRIPT_DIR/harness-lessons-gate.sh" ]; then
-  if ! gate_out="$(bash "$SCRIPT_DIR/harness-lessons-gate.sh" "$PROJECT_ROOT" text latest-active 2>/dev/null)"; then
-    {
-      echo "[company-complete] REFUSED: the active mission has not recorded what it read before planning."
-      echo "$gate_out"
-      echo "  Add the two sections to each role document, then re-run this transition."
-      echo "  (override: HARNESS_SKIP_LESSONS_GATE=1, or behavior.lessons_gate=false in .harness/config.json)"
-    } >&2
-    echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) | company-complete | refused | lessons-gate (Hard Rule 20)" >> "$PROJECT_ROOT/.harness/progress.log" 2>/dev/null || true
-    exit 1
-  fi
-fi
-
 state_mtime() {
   stat -f %m "$1" 2>/dev/null || stat -c %Y "$1" 2>/dev/null || echo 0
 }
@@ -72,6 +49,117 @@ pick_transition_mission_state() {
   [ -n "$best" ] && printf '%s\n' "$best"
 }
 
+refuse() {
+  echo "[company-complete] REFUSED: $1" >&2
+  echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) | company-complete | refused | $1" >> "$PROJECT_ROOT/.harness/progress.log"
+  if [ -n "${target_state:-}" ] && jq -e '.lifecycle == "complete" or .lifecycle == "completed"' "$target_state" >/dev/null; then
+    echo 'Restore active:true and lifecycle:active, then retry.' >&2
+  fi
+  exit 1
+}
+
+target_state=""
+if [ "$#" -ge 3 ]; then
+  mission_rel="$3"
+  case "$mission_rel" in ""|/*|*..*) refuse invalid-mission-path ;; esac
+  target_dir="$(cd "$DOCS/$mission_rel" 2>/dev/null && pwd -P)" || refuse invalid-mission-path
+  case "$target_dir/" in "$(cd "$DOCS" && pwd -P)/"*) ;; *) refuse invalid-mission-path ;; esac
+  target_state="$target_dir/mission-state.json"
+  [ -f "$target_state" ] || refuse missing-mission-state
+else
+  target_state="$(pick_transition_mission_state)"
+fi
+ended=false
+tiered=false
+gate_scope=latest-active
+# Explicit targets scope the existing lessons gate even for legacy missions.
+if [ "$#" -ge 3 ]; then gate_scope="mission:$3"; fi
+if [ -n "$target_state" ]; then
+  lifecycle=$(jq -r '.lifecycle // .status // "unknown"' "$target_state") || refuse invalid-mission-state
+  case "$lifecycle" in cancelled|superseded|closed) ended=true ;; esac
+  if jq -e 'has("tier")' "$target_state" >/dev/null; then
+    tiered=true
+    mission_rel="${target_state#"$DOCS"/}"
+    # Explicit targets were canonicalized; retain the caller's relative path.
+    if [ "$#" -ge 3 ]; then mission_rel="$3/mission-state.json"; fi
+    mission_rel="${mission_rel%/mission-state.json}"
+    gate_scope="mission:$mission_rel"
+  fi
+fi
+
+if [ "$ended" = false ]; then
+  if [ "${HARNESS_SKIP_LESSONS_GATE:-0}" != 1 ] && [ -x "$SCRIPT_DIR/harness-lessons-gate.sh" ]; then
+    gate_out=$(bash "$SCRIPT_DIR/harness-lessons-gate.sh" "$PROJECT_ROOT" text "$gate_scope") || refuse "lessons-gate: $gate_out"
+  fi
+  if [ "$tiered" = true ]; then
+    evidence=$(bash "$SCRIPT_DIR/harness-worker-evidence-validate.sh" "$PROJECT_ROOT" text "$gate_scope") || refuse "worker-evidence: $evidence"
+    mission_dir="$(dirname "$target_state")"
+    [ -f "$mission_dir/cqo.md" ] || refuse missing-verdict
+    verdict=$(awk '
+      /^[[:space:]]*>?[[:space:]]*##[[:space:]]+CQO Verdict([[:space:]]+\([^)]*\))?[[:space:]]*$/ { inb=1; next }
+      /^[[:space:]]*>?[[:space:]]*#{1,2}[[:space:]]/ { inb=0 }
+      inb { candidate=$0; sub(/^[[:space:]>*_-]*/, "", candidate)
+        if (tolower(candidate) ~ /^verdict[*_[:space:]]*:/) last=$0 }
+      END {
+        if (last == "") print "missing"
+        else if (last ~ /^[[:space:]]*>?[[:space:]]*Verdict:[[:space:]]*(PASS|ACCEPTED|FAIL|REJECTED|BLOCKED)[[:space:]]*$/) {
+          sub(/^[[:space:]]*>?[[:space:]]*Verdict:[[:space:]]*/, "", last)
+          sub(/[[:space:]]*$/, "", last); print last
+        } else print "invalid"
+      }
+    ' "$mission_dir/cqo.md") || refuse invalid-final-verdict
+    case "$verdict" in
+      PASS|ACCEPTED) ;;
+      missing) refuse missing-verdict ;;
+      invalid) refuse invalid-final-verdict ;;
+      *) refuse verdict-not-pass ;;
+    esac
+    tier=$(jq -r 'def r: if . == "S" then 0 elif . == "M" then 1 else 2 end;
+      [.tier, (.tier_history[]? | .from, .to)] | map(r) | max' "$target_state") || refuse invalid-tier-state
+    if [ -f "$PROJECT_ROOT/.harness/config.json" ]; then
+      enabled=$(jq -r 'if .behavior.mission_tiers == null then true else .behavior.mission_tiers end' "$PROJECT_ROOT/.harness/config.json") || refuse invalid-config
+      [ "$enabled" != false ] || tier=2
+    fi
+    if [ "$tier" -eq 0 ]; then
+      grep -Eq '^[[:space:]]*>?[[:space:]]*##[[:space:]]+Direct Work[[:space:]]*$' "$mission_dir/cto.md" || refuse missing-direct-work
+      grep -Eq '^[[:space:]]*>?[[:space:]]*##[[:space:]]+Verification Commands[[:space:]]*$' "$mission_dir/cqo.md" || refuse missing-verification-commands
+      session=$(sed -nE 's/^[[:space:]]*Verification Session: (separate|same-session)[[:space:]]*$/\1/p' "$mission_dir/cqo.md" | tail -1)
+      [ -n "$session" ] || refuse missing-verification-session
+      if [ "$session" = same-session ]; then
+        echo '[company-complete] WARNING: same-session-verification; disclose to Owner.' >&2
+        echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) | company-complete | warn | same-session-verification" >> "$PROJECT_ROOT/.harness/progress.log"
+      fi
+    fi
+  fi
+fi
+
+# Corpus reachability (Hard Rule 11) and spec pins (Hard Rule 4) are re-checked
+# at the same point, for the same reason: both are promises that decay silently
+# between when they are made and when the mission claims to be done.
+if [ "${HARNESS_SKIP_LESSONS_GATE:-0}" != "1" ] && [ -x "$SCRIPT_DIR/harness-corpus-reachability.sh" ]; then
+  if ! reach_out="$(bash "$SCRIPT_DIR/harness-corpus-reachability.sh" "$PROJECT_ROOT" text 2>/dev/null)"; then
+    refuse "corpus-reachability: $reach_out"
+  fi
+fi
+
+# Spec pins are verified against the mission this transition would close. This
+# sits BEFORE the runtime transition on purpose: a refusal that runs after
+# progress.json is already `completed` has refused nothing.
+if [ "$ended" = false ] && [ "${HARNESS_SKIP_LESSONS_GATE:-0}" != "1" ] && [ -x "$SCRIPT_DIR/harness-spec-pin.sh" ] && [ -d "$DOCS" ]; then
+  pin_target="$target_state"
+  if [ -n "$pin_target" ]; then
+    mission_rel="${pin_target#"$DOCS"/}"; mission_rel="${mission_rel%/mission-state.json}"
+    if [ "$#" -ge 3 ]; then mission_rel="$3"; fi
+    if ! pin_out="$(bash "$SCRIPT_DIR/harness-spec-pin.sh" "$PROJECT_ROOT" "$mission_rel" verify text 2>/dev/null)"; then
+      refuse "spec-pin drift: $pin_out"
+    fi
+  fi
+fi
+
+if [ "$ended" = true ]; then
+  echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) | company-complete | ended-without-acceptance | $lifecycle" >> "$PROJECT_ROOT/.harness/progress.log"
+fi
+
 if ! bash "$SCRIPT_DIR/harness-progress-set.sh" "$PROJECT_ROOT" \
   '.company_state.state = "idle" |
    .company_state.active_workers = 0 |
@@ -109,13 +197,11 @@ if [ -f "$TODOS" ]; then
   ' "$TODOS" > "$tmp" && mv "$tmp" "$TODOS"
 fi
 
-DOCS="$PROJECT_ROOT/.harness/documents"
 if [ -d "$DOCS" ]; then
-  target_state="$(pick_transition_mission_state)"
   if [ -n "$target_state" ]; then
     lifecycle="$(jq -r '.lifecycle // .status // "unknown"' "$target_state" 2>/dev/null || echo unknown)"
     case "$lifecycle" in
-      closed|cancelled|superseded|complete|completed) ;;
+      closed|cancelled|superseded) ;;
       *)
         tmp="$(mktemp)"
         jq '.lifecycle = "complete" | .active = false | .completed_at = (now | todate) | del(.blocked_reason) | del(.blocked_at)' "$target_state" > "$tmp" && mv "$tmp" "$target_state"

package/scripts/harness-corpus-reachability.sh

@@ -0,0 +1,128 @@
+#!/bin/bash
+# harness-corpus-reachability.sh — AGENTS.md Hard Rule 11 (reachability clause).
+#
+# Lazy loading tells a reader to consult only {shared, own-role}. That is a
+# PROMISE ABOUT REACHABILITY. Where it is not kept, the rule does not narrow the
+# search — it hides the entry: an item can name a role as its audience, be
+# indexed, and still be invisible to that reader by the path the rule tells it
+# to use. Measured on a live corpus: 69 items, 10 unreachable role-routings,
+# 7 of them invisible to a role the item itself named.
+#
+# The mechanism is mundane and recurs on any install: THE AUTHOR FILES UNDER
+# ITSELF. Registration feels complete because the entry is indexed — just not
+# where its declared readers look.
+#
+# Declaring an audience (either form):
+#   file-level  (topic files):  <!-- roles: cto, cqo -->
+#   entry-level (index files):  - **Roles**: cto, cqo
+#
+# Usage:
+#   harness-corpus-reachability.sh <project-root> [text|json] [--fix]
+set -uo pipefail
+
+PROJECT_ROOT="${1:-.}"
+MODE="${2:-text}"
+FIX="${3:-}"
+
+ROLES="ceo coo cdo cto cqo ops hiring resource-manager brick-office shared"
+violations=()
+fixed=0
+
+is_index_file() {
+  local base="$1"
+  case " $ROLES " in *" ${base%.md} "*) return 0 ;; esac
+  return 1
+}
+
+# Roles this file/entry names as an audience, whitespace-separated, deduped.
+#
+# A declaration must OWN its line. Anchoring here is what keeps the audit from
+# reading its own documentation as data: prose that shows the syntax inline
+# (`<!-- roles: cto, cqo -->` inside backticks) is an example, not a routing,
+# and counting it makes the audit report holes that do not exist.
+declared_roles() {
+  {
+    grep -oiE '^[[:space:]]*<!--[[:space:]]*roles?:[^>]*-->' "$1" 2>/dev/null | sed -E 's/^[[:space:]]*<!--[[:space:]]*[Rr]oles?:[[:space:]]*//; s/[[:space:]]*-->//'
+    grep -oiE '^[[:space:]]*[-*][[:space:]]*\*\*Roles?\*\*:.*' "$1" 2>/dev/null | sed -E 's/.*\*\*[Rr]oles?\*\*:[[:space:]]*//'
+  } | tr ',' '\n' | tr -d ' \t' | grep -v '^$' | tr 'A-Z' 'a-z' | sort -u
+}
+
+# Does <index> reach <target basename>? Only a real markdown link target counts.
+# A bare mention of the filename in prose is not a route a reader can follow,
+# and counting it would make the audit report success on exactly the entries it
+# exists to find. Matches `](./file.md`, `](file.md`, with or without an anchor.
+reaches() {
+  local index="$1" target="$2"
+  [ -f "$index" ] || return 1
+  grep -qF -- "](./$target" "$index" || grep -qF -- "]($target" "$index"
+}
+
+audit_dir() {
+  local kind="$1" dir="$PROJECT_ROOT/.harness/$1"
+  [ -d "$dir" ] || return 0
+  local f base host_role roles role index
+  for f in "$dir"/*.md; do
+    [ -e "$f" ] || continue
+    base="$(basename "$f")"
+    [ "$base" = "README.md" ] && continue
+    # shared.md is read by every role by construction (Hard Rule 11), so an entry
+    # living there is already reachable to every audience it could name.
+    [ "$base" = "shared.md" ] && continue
+    host_role="${base%.md}"
+    roles="$(declared_roles "$f")"
+    [ -n "$roles" ] || continue
+    while IFS= read -r role; do
+      [ -n "$role" ] || continue
+      # The host file is reachable to its own role by construction.
+      if is_index_file "$base" && [ "$role" = "$host_role" ]; then continue; fi
+      case " $ROLES " in *" $role "*) ;; *) continue ;; esac
+      # Naming `shared` as an audience is satisfied by construction.
+      [ "$role" = "shared" ] && continue
+      index="$dir/${role}.md"
+      if reaches "$index" "$base"; then continue; fi
+      if [ "$FIX" = "--fix" ]; then
+        [ -f "$index" ] || printf '# %s — %s\n' "${role}" "${kind}" > "$index"
+        if ! grep -qF 'Cross-role Links' "$index"; then
+          printf '\n## Cross-role Links\n\nItems written elsewhere that name this role as an audience.\n' >> "$index"
+        fi
+        printf -- '- [%s](./%s) — declares `%s`\n' "${base%.md}" "$base" "$role" >> "$index"
+        fixed=$((fixed + 1))
+      else
+        violations+=("$kind/$base:$role")
+      fi
+    done <<EOF
+$roles
+EOF
+  done
+}
+
+audit_dir conventions
+audit_dir gotchas
+
+if [ "$FIX" = "--fix" ]; then
+  echo "[corpus-reachability] linked $fixed previously unreachable routing(s)"
+  exit 0
+fi
+
+if [ "${#violations[@]}" -eq 0 ]; then
+  [ "$MODE" = "json" ] && { jq -nc '{ok:true, unreachable:[]}' 2>/dev/null || echo '{"ok":true,"unreachable":[]}'; }
+  [ "$MODE" = "text" ] && echo "[corpus-reachability] all declared audiences reachable"
+  exit 0
+fi
+
+if [ "$MODE" = "json" ]; then
+  printf '%s\n' "${violations[@]}" | jq -Rcs '
+    split("\n")[:-1]
+    | map(capture("(?<item>[^:]+):(?<role>.*)"))
+    | {ok:false, unreachable:.}
+  '
+else
+  echo "Corpus reachability violation (AGENTS.md Hard Rule 11):"
+  for v in "${violations[@]}"; do
+    echo "- item: ${v%%:*}"
+    echo "  names role '${v#*:}' as an audience, but ${v#*:}'s index does not reach it"
+  done
+  echo "  An entry is registered only when every role it names can reach it by the"
+  echo "  path that role is told to use. Fix: harness-corpus-reachability.sh <root> text --fix"
+fi
+exit 1

package/scripts/harness-gotcha-register.sh

@@ -11,7 +11,8 @@
 #        --right "올바른 행동" \
 #        --why "근거" \
 #        --scope "적용 범위" \
-#        --source "evaluator-functional:F-003"
+#        --source "evaluator-functional:F-003" \\
+#        --roles "cqo, cto"
 #
 #   2) 일괄 등록 (JSON stdin/파일):
 #      bash harness-gotcha-register.sh <project-root> --from-json <path>
@@ -69,6 +70,7 @@ TODAY="$(date +%Y-%m-%d)"
 # ─────────────────────────────────────────
 register_one() {
   local target="$1" rule_id="$2" title="$3" wrong="$4" right="$5" why="$6" scope="$7" source="$8"
+  local roles="${9:-$target}"
   local file="$GOTCHAS_DIR/${target}.md"
   mkdir -p "$(dirname "$file")"
 
@@ -118,6 +120,7 @@ EOF
   {
     echo ""
     echo "### [$g_id] $title  <!-- rule_id: $rule_id -->"
+    echo "- **Roles**: $roles"
     echo "- **Status**: unverified"
     echo "- **Date**: $TODAY"
     echo "- **Source**: $source"
@@ -132,6 +135,13 @@ EOF
 
   echo "[gotcha-register] $target: registered $g_id ($rule_id) — unverified"
 
+  # Hard Rule 11: an entry filed only under its author is indexed but unreachable
+  # to the other roles it names. Link it now, while the audience is still known.
+  local reach="$(dirname "$0")/harness-corpus-reachability.sh"
+  if [ -x "$reach" ] && [ "$roles" != "$target" ]; then
+    bash "$reach" "$PROJECT_ROOT" text --fix >/dev/null 2>&1 || true
+  fi
+
   # Log to progress.log if present
   local progress_log="$PROJECT_ROOT/.harness/progress.log"
   if [ -f "$progress_log" ]; then
@@ -141,7 +151,9 @@ EOF
 
 # ─────────────────────────────────────────
 # JSON 배열에서 일괄 등록
-#   schema: [{ target, rule_id, title, wrong, right, why, scope, source }]
+#   schema: [{ target, rule_id, title, wrong, right, why, scope, source, roles }]
+#   `roles` is the comma-separated list of every role that must be able to FIND
+#   this entry — not only the one that wrote it (Hard Rule 11). Defaults to target.
 # ─────────────────────────────────────────
 register_from_json() {
   local json="$1"
@@ -153,7 +165,7 @@ register_from_json() {
 
   local i
   for ((i=0; i<count; i++)); do
-    local t r ti w ri wh sc so
+    local t r ti w ri wh sc so rl
     t=$(echo "$json"  | jq -r ".[$i].target // empty")
     r=$(echo "$json"  | jq -r ".[$i].rule_id // empty")
     ti=$(echo "$json" | jq -r ".[$i].title // empty")
@@ -162,12 +174,13 @@ register_from_json() {
     wh=$(echo "$json" | jq -r ".[$i].why // empty")
     sc=$(echo "$json" | jq -r ".[$i].scope // \"항상\"")
     so=$(echo "$json" | jq -r ".[$i].source // \"evaluator:auto\"")
+    rl=$(echo "$json" | jq -r ".[$i].roles // empty")
 
     if [ -z "$t" ] || [ -z "$r" ] || [ -z "$ti" ]; then
       echo "[gotcha-register] skip: missing target/rule_id/title at index $i" >&2
       continue
     fi
-    register_one "$t" "$r" "$ti" "$w" "$ri" "$wh" "$sc" "$so"
+    register_one "$t" "$r" "$ti" "$w" "$ri" "$wh" "$sc" "$so" "${rl:-$t}"
   done
 }
 
@@ -354,6 +367,7 @@ RIGHT=""
 WHY=""
 SCOPE="항상"
 SOURCE="evaluator:auto"
+ROLES_DECL=""
 MODE="single"
 FROM_JSON=""
 
@@ -367,6 +381,7 @@ while [ $# -gt 0 ]; do
     --why)      WHY="$2"; shift 2 ;;
     --scope)    SCOPE="$2"; shift 2 ;;
     --source)   SOURCE="$2"; shift 2 ;;
+    --roles)    ROLES_DECL="$2"; shift 2 ;;
     --from-json) MODE="json"; FROM_JSON="$2"; shift 2 ;;
     --scan-evaluations) MODE="scan"; shift ;;
     --scan-all) MODE="scan-all"; shift ;;
@@ -380,7 +395,7 @@ case "$MODE" in
       echo "[gotcha-register] usage: --target X --rule-id Y --title Z [...]" >&2
       exit 1
     fi
-    register_one "$TARGET" "$RULE_ID" "$TITLE" "$WRONG" "$RIGHT" "$WHY" "$SCOPE" "$SOURCE"
+    register_one "$TARGET" "$RULE_ID" "$TITLE" "$WRONG" "$RIGHT" "$WHY" "$SCOPE" "$SOURCE" "${ROLES_DECL:-$TARGET}"
     ;;
   json)
     if [ ! -f "$FROM_JSON" ]; then echo "[gotcha-register] file not found: $FROM_JSON" >&2; exit 1; fi