@walwal-harness/cli 7.1.6 → 7.1.7

package/HR-Resource/cdo/SKILL.md

@@ -31,3 +31,6 @@ Required output sections:
 2. Worker Evidence Manifest — worker name, report path, status.
 3. CDO Decision — only decisions accepted from worker evidence.
 4. Next Handoff — CTO-ready design constraints, inputs, blockers.
+5. Implementation Notes — in English, with `Design Decisions`, `Deviations`, `Tradeoffs`, and `Open Questions`.
+
+Every CDO worker brief must require the worker to append the same English `## Implementation Notes` block to the bottom of `.harness/documents/{mission_name}/cdo/workers/{worker-name}.md`, covering risks, self-corrections, chosen direction, and unresolved questions. Use `None` for empty subsections.

package/HR-Resource/ceo/SKILL.md

@@ -34,6 +34,31 @@ You are the only direct conversation channel with the Owner.
 - Before CTO/CDO/OPS allocate runnable services, agree with the Owner on a `{xx}000` base port and write it to project `.env` as `HARNESS_BASE_PORT={xx}000`. Mentioning the value in `ceo.md` is not sufficient.
 - After writing `.env`, verify with `grep '^HARNESS_BASE_PORT=' .env` before routing service work.
 - For service monitoring, collect the Owner's server mapping first: local PC, Docker, VM, AWS/cloud, host, port, health path, log path, and contact/source.
+- Every CEO and CXX mission document must include an English `## Implementation Notes` section with the required subsections below. CEO must reject CXX reports that omit it.
+
+## Required Mission Note Format
+
+Every `ceo.md` and CXX document (`coo.md`, `cdo.md`, `cto.md`, `cqo.md`, `ops.md`) must end with this English section:
+
+```
+## Implementation Notes
+
+### Design Decisions
+- ...
+
+### Deviations
+- ...
+
+### Tradeoffs
+- ...
+
+### Open Questions
+- ...
+```
+
+Use `None` when a subsection has no entries. These notes are mandatory even for small or emergency work. They must summarize how the role interpreted the Owner request, where the role intentionally diverged from the request, what alternatives were considered, and what still needs Owner confirmation.
+
+When briefing a CXX, CEO must explicitly require the CXX to append this section to its own `{cxx}.md` and to require every worker it manages to append the same section to the bottom of that worker's report.
 
 ## Routing Gate — CEO Must Never Bypass CXX
 

package/HR-Resource/coo/SKILL.md

@@ -34,3 +34,6 @@ Required output sections:
 2. Worker Evidence Manifest — worker name, report path, status.
 3. COO Decision — only decisions accepted from worker evidence.
 4. Next Handoff — next CXX, inputs, blockers.
+5. Implementation Notes — in English, with `Design Decisions`, `Deviations`, `Tradeoffs`, and `Open Questions`.
+
+Every COO worker brief must require the worker to append the same English `## Implementation Notes` block to the bottom of `.harness/documents/{mission_name}/coo/workers/{worker-name}.md`, covering risks, self-corrections, chosen direction, and unresolved questions. Use `None` for empty subsections.

package/HR-Resource/cqo/SKILL.md

@@ -36,3 +36,26 @@ Required output sections in `cqo.md`:
 2. Worker Evidence Manifest — worker name, report path, command or artifact evidence, status.
 3. CQO Verdict — PASS, FAIL, or BLOCKED based only on worker evidence. Must reference Worker Evidence Manifest entries.
 4. Recurrence Notes — accepted gotchas, conventions, memories, or none.
+5. Implementation Notes — in English, with `Design Decisions`, `Deviations`, `Tradeoffs`, and `Open Questions`.
+
+## Worker Report Note Requirement
+
+Every CQO evaluator/tester brief must require the worker to append this English block to the bottom of `.harness/documents/{mission_name}/cqo/workers/{worker-name}.md`:
+
+```
+## Implementation Notes
+
+### Design Decisions
+- ...
+
+### Deviations
+- ...
+
+### Tradeoffs
+- ...
+
+### Open Questions
+- ...
+```
+
+The worker notes must cover risks, self-corrections, and chosen direction. Use `None` when a subsection has no entries. CQO must not accept evaluator output that omits this block.

package/HR-Resource/cto/SKILL.md

@@ -37,3 +37,26 @@ Required output sections in `cto.md`:
 3. Worker Evidence Manifest — worker name, report path, changed files or artifact paths, status.
 4. CTO Decision — only decisions accepted from worker evidence.
 5. CQO Handoff — validation scope, commands, risk areas, blockers.
+6. Implementation Notes — in English, with `Design Decisions`, `Deviations`, `Tradeoffs`, and `Open Questions`.
+
+## Worker Report Note Requirement
+
+Every CTO worker brief must require the worker to append this English block to the bottom of `.harness/documents/{mission_name}/cto/workers/{worker-name}.md`:
+
+```
+## Implementation Notes
+
+### Design Decisions
+- ...
+
+### Deviations
+- ...
+
+### Tradeoffs
+- ...
+
+### Open Questions
+- ...
+```
+
+The worker notes must cover risks, self-corrections, and chosen direction. Use `None` when a subsection has no entries. CTO must not accept worker output that omits this block.

package/HR-Resource/hiring/SKILL.md

@@ -26,6 +26,28 @@ Hire workers from `.harness/shared/HR-Resource/`.
 5. Update `.harness/shared/hr-roster.json` without deleting existing hired entries. Record `owner` as the owning CXX, `skillPath` as `.harness/shared/HR-Resource/{name}/SKILL.md`, and `skillPaths.claude` / `skillPaths.codex` as tool-specific hierarchical installed paths.
 6. The owning CXX must write worker reports under `.harness/documents/{mission}/{owning-cxx}/workers/{name}.md`. Do not write flat `.harness/documents/{mission}/workers/{name}.md` except when migrating legacy missions.
 7. Ask the `harness-resource-manager` skill to update trigger wording.
-8. Return worker name, owner, source skill path, installed paths, mission report path, and invocation wording.
+8. Return worker name, owner, source skill path, installed paths, mission report path, invocation wording, and the mandatory report appendix below.
+
+## Mandatory Worker Report Appendix
+
+Every hired worker must append this English section to the bottom of its existing report:
+
+```
+## Implementation Notes
+
+### Design Decisions
+- ...
+
+### Deviations
+- ...
+
+### Tradeoffs
+- ...
+
+### Open Questions
+- ...
+```
+
+The appendix must summarize risks, self-corrections, and chosen direction. Use `None` when a subsection has no entries.
 
 Never mark a missing worker as available.

package/HR-Resource/ops/SKILL.md

@@ -44,3 +44,6 @@ OPS must not directly perform DevOps implementation, service fixes, config rewri
 2. Environment Evidence — config path, command/service checked, observed status.
 3. Worker Evidence Manifest — worker name, report path, status for delegated monitoring or recovery tasks.
 4. OPS Event Decision — good-case silence, warning, incident, or emergency escalation.
+5. Implementation Notes — in English, with `Design Decisions`, `Deviations`, `Tradeoffs`, and `Open Questions`.
+
+Every OPS worker brief must require the worker to append the same English `## Implementation Notes` block to the bottom of `.harness/documents/{mission_name}/ops/workers/{worker-name}.md`, covering risks, self-corrections, chosen direction, and unresolved questions. Use `None` for empty subsections.

package/HR-Resource/resource-manager/SKILL.md

@@ -21,6 +21,10 @@ Manage worker availability and invocation wording.
 
 1. Check whether the requester is a CXX. CEO cannot request specialist worker assignment directly.
 2. Check whether a suitable worker is already hired for that owning CXX.
-3. If hired, return the exact skill name, owning CXX, hierarchical installed paths, and mission report path.
+3. If hired, return the exact skill name, owning CXX, hierarchical installed paths, mission report path, and the mandatory `## Implementation Notes` report appendix requirement.
 4. If not hired, suggest `.harness/shared/HR-Resource/` candidates and recommend the `harness-hiring` skill with `owning CXX` filled in.
 5. Keep aliases narrow enough to avoid accidental generic invocation.
+
+## Mandatory Worker Report Appendix
+
+Every worker assignment must require the worker to append an English `## Implementation Notes` section with these subsections: `Design Decisions`, `Deviations`, `Tradeoffs`, and `Open Questions`. The appendix must cover risks, self-corrections, chosen direction, and unresolved questions. Use `None` for empty subsections.

package/README.md

@@ -93,6 +93,30 @@ Owner /hot-fix → CEO → CTO → [dev workers] → CQO → [evaluator workers]
 | 6 | CEO routes only to CXX — never directly to workers |
 | 7 | No CXX self-execution — deliverables without matching worker records are rejected |
 | 8 | No verdict without worker evidence — CQO self-inspection is not valid |
+| 9 | Hierarchical worker ownership — worker reports live under `.harness/documents/{mission}/{owning-cxx}/workers/` |
+| 10 | Implementation Notes required — `ceo.md`, every `{cxx}.md`, and every worker report must end with an English `## Implementation Notes` section |
+
+### Implementation Notes Format
+
+Every `ceo.md`, `{cxx}.md`, and worker report must end with:
+
+```markdown
+## Implementation Notes
+
+### Design Decisions
+- How the role interpreted the Owner request
+
+### Deviations
+- Where the role intentionally diverged from the request
+
+### Tradeoffs
+- Alternatives considered and why they were rejected
+
+### Open Questions
+- What still needs Owner or CXX confirmation
+```
+
+Use `None` when a subsection has no entries. This section is mandatory even for small or emergency work. CEO must reject any CXX report that omits it. CTO and CQO must not accept worker output that omits it.
 
 ---
 
@@ -145,6 +169,7 @@ harness-hiring           → register and onboard worker
 
 | Version | Summary |
 |---|---|
+| 7.1.7 | Implementation Notes mandatory in all CXX docs and worker reports; harness-worker-evidence-validate.sh |
 | 7.1.6 | CXX hierarchy enforcement: CEO→CXX-only gate, CTO prerequisite gate, CQO worker-evidence mandate; dashboard gotchas tab, mission-specific history tab, worker file list in flow |
 | 7.1.5 | Dashboard: mission flow timeline, markdown viewer, 50vw drawer |
 | 7.1.4 | Dashboard: org-tree redesign with real `.harness/documents/` data |

package/assets/templates/AGENTS.md.template

@@ -108,6 +108,7 @@ Note: A docmeta skip decision on harness documents (ceo.md, cto.md, cqo.md, work
 8. **No CXX self-execution** — CXX agents coordinate and manage only. A CXX that produces deliverables without matching worker records has violated its scope. CEO must reject such reports.
 9. **No verdict without worker evidence** — CQO cannot issue ACCEPTED/REJECTED without a Worker Evidence Manifest referencing at least one evaluator worker. Self-inspection by CQO is not valid evidence.
 10. **Hierarchical worker ownership** — Hired workers are installed under `.claude/skills/{owning-cxx}/{worker}/` and `.codex/skills/{owning-cxx}/{worker}/`; mission worker reports live under `.harness/documents/{mission}/{owning-cxx}/workers/`. Flat `{mission}/workers/` reports are legacy and signal an ownership violation unless explicitly migrated.
+11. **Implementation Notes required** — `ceo.md`, every `{cxx}.md`, and every worker report must end with an English `## Implementation Notes` section containing `Design Decisions`, `Deviations`, `Tradeoffs`, and `Open Questions`. Use `None` for empty subsections.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "7.1.6",
+  "version": "7.1.7",
   "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-worker-evidence-validate.sh

@@ -10,6 +10,16 @@ DOC_ROOT="$PROJECT_ROOT/.harness/documents"
 mode="${2:-text}"
 violations=()
 
+has_implementation_notes() {
+  local file="$1"
+  [ -s "$file" ] || return 1
+  grep -Eq '^##[[:space:]]+Implementation Notes[[:space:]]*$' "$file" &&
+    grep -Eq '^###[[:space:]]+Design Decisions[[:space:]]*$' "$file" &&
+    grep -Eq '^###[[:space:]]+Deviations[[:space:]]*$' "$file" &&
+    grep -Eq '^###[[:space:]]+Tradeoffs[[:space:]]*$' "$file" &&
+    grep -Eq '^###[[:space:]]+Open Questions[[:space:]]*$' "$file"
+}
+
 has_worker_report() {
   local mission_dir="$1"
   local owner="${2:-}"
@@ -29,6 +39,11 @@ for mission_dir in "$DOC_ROOT"/*; do
   [ -d "$mission_dir" ] || continue
   mission_name="$(basename "$mission_dir")"
 
+  ceo_path="$mission_dir/ceo.md"
+  if [ -s "$ceo_path" ] && ! has_implementation_notes "$ceo_path"; then
+    violations+=("$mission_name:ceo.md-missing-implementation-notes")
+  fi
+
   if has_legacy_flat_worker_report "$mission_dir"; then
     violations+=("$mission_name:legacy-flat-workers")
   fi
@@ -36,9 +51,20 @@ for mission_dir in "$DOC_ROOT"/*; do
   for cxx in coo cdo cto cqo ops; do
     cxx_path="$mission_dir/$cxx.md"
     [ -s "$cxx_path" ] || continue
+    if ! has_implementation_notes "$cxx_path"; then
+      violations+=("$mission_name:$cxx.md-missing-implementation-notes")
+    fi
     if ! has_worker_report "$mission_dir" "$cxx"; then
       violations+=("$mission_name:$cxx.md")
     fi
+    workers_dir="$mission_dir/$cxx/workers"
+    [ -d "$workers_dir" ] || continue
+    for worker_report in "$workers_dir"/*.md; do
+      [ -e "$worker_report" ] || continue
+      if ! has_implementation_notes "$worker_report"; then
+        violations+=("$mission_name:$cxx/workers/$(basename "$worker_report")-missing-implementation-notes")
+      fi
+    done
   done
 
   cqo_path="$mission_dir/cqo.md"