Add durable knowledge contracts and task observer

CHANGELOG.md

@@ -8,6 +8,7 @@ All notable changes to this portable workflow pack are documented here.
 
 #### Added
 
+- **Add durable workflow solution docs, review finding schema, readiness vocabulary, autoreview target-state fixtures, and the optional `task-observer` skill.**
 - **Add `agent-workflows-trust-audit` to check recent merged PRs against `pr-security-preflight` and draft candidate repo-local trust entries for maintainer review.**
 - **Add `trusted_metadata_bots` so workflow/status bot comments can be audited as metadata without becoming actionable trusted instructions.**
 - **Add `pr-security-preflight --strict-trust` so exact-target batches can report actor-trust findings by default while still supporting fail-closed launches.**

README.md

@@ -163,6 +163,7 @@ the managed-vs-repo-owned boundary, and `--root`/`--only`/`--all` usage.
 | `run-ci` | Choose and run repo-local CI checks. |
 | `spec` | Turn vague implementation intent into requirements, design, and tasks. |
 | `status` | Report tight progress (done/in-progress/blocked/next) without starting new work. |
+| `task-observer` | Optionally capture sanitized observations for later skill or workflow improvement review. |
 | `tdd` | Drive test-first red-green-refactor loops for features and bug fixes. |
 | `triage` | Build a whole-surface issue/PR inventory and batch split. |
 | `update-changelog` | Classify merged PRs and update a repo changelog. |

bin/install-agent-workflows

@@ -15,6 +15,8 @@ Default targets:
 Installed paths:
   <target>/skills/*
   <target>/workflows/*
+  <target>/docs/review-finding-schema.md
+  <target>/docs/solutions/*
   <target>/bin/agent-workflow-seam-doctor
   <target>/bin/agent-workflows-status
   <target>/bin/upgrade-agent-workflows
@@ -140,11 +142,24 @@ write_metadata() {
   mv "$metadata_tmp" "$metadata_path"
 }
 
+ensure_real_directory() {
+  local directory="$1"
+
+  if [[ -L "$directory" ]]; then
+    rm -f "$directory"
+  fi
+  if [[ -e "$directory" && ! -d "$directory" ]]; then
+    echo "Refusing to replace non-directory path: $directory" >&2
+    exit 1
+  fi
+  mkdir -p "$directory"
+}
+
 copy_children_preserving_unrelated() {
   local source_dir="$1"
   local target_dir="$2"
   local source_path destination
-  mkdir -p "$target_dir"
+  ensure_real_directory "$target_dir"
 
   for source_path in "$source_dir"/*; do
     [[ -e "$source_path" ]] || continue
@@ -154,6 +169,46 @@ copy_children_preserving_unrelated() {
   done
 }
 
+copy_pack_docs() {
+  local docs_target="$1"
+  local schema_destination="$docs_target/review-finding-schema.md"
+  ensure_real_directory "$docs_target"
+  ensure_real_directory "$docs_target/solutions"
+  if [[ -L "$schema_destination" ]]; then
+    rm -f "$schema_destination"
+  fi
+  if [[ -e "$schema_destination" && ! -f "$schema_destination" ]]; then
+    echo "Refusing to replace non-file path: $schema_destination" >&2
+    exit 1
+  fi
+  install -m 0644 "$repo_root/docs/review-finding-schema.md" "$schema_destination"
+  copy_children_preserving_unrelated "$repo_root/docs/solutions" "$docs_target/solutions"
+}
+
+link_pack_docs() {
+  local docs_target="$1"
+  local destination source_path
+  ensure_real_directory "$docs_target"
+  ensure_real_directory "$docs_target/solutions"
+
+  destination="$docs_target/review-finding-schema.md"
+  if [[ -e "$destination" && ! -L "$destination" ]]; then
+    echo "Refusing to replace non-symlink path: $destination" >&2
+    exit 1
+  fi
+  ln -sfn "$repo_root/docs/review-finding-schema.md" "$destination"
+
+  for source_path in "$repo_root"/docs/solutions/*; do
+    [[ -e "$source_path" ]] || continue
+    destination="$docs_target/solutions/$(basename "$source_path")"
+    if [[ -e "$destination" && ! -L "$destination" ]]; then
+      echo "Refusing to replace non-symlink path: $destination" >&2
+      exit 1
+    fi
+    ln -sfn "$source_path" "$destination"
+  done
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --host)
@@ -201,11 +256,23 @@ host="${resolved%%:*}"
 target="${resolved#*:}"
 
 if [[ "$mode" = "copy" ]]; then
-  mkdir -p "$target/skills" "$target/workflows" "$target/bin"
+  ensure_real_directory "$target/skills"
+  ensure_real_directory "$target/workflows"
+  ensure_real_directory "$target/docs"
+  ensure_real_directory "$target/bin"
   copy_children_preserving_unrelated "$repo_root/skills" "$target/skills"
   copy_children_preserving_unrelated "$repo_root/workflows" "$target/workflows"
+  copy_pack_docs "$target/docs"
   for helper in "${bin_helpers[@]}"; do
-    install -m 0755 "$repo_root/bin/$helper" "$target/bin/$helper"
+    destination="$target/bin/$helper"
+    if [[ -L "$destination" ]]; then
+      rm -f "$destination"
+    fi
+    if [[ -e "$destination" && ! -f "$destination" ]]; then
+      echo "Refusing to replace non-file path: $destination" >&2
+      exit 1
+    fi
+    install -m 0755 "$repo_root/bin/$helper" "$destination"
   done
 else
   mkdir -p "$target/skills" "$target/bin"
@@ -224,6 +291,7 @@ else
   done
   rm -f "$target/workflows"
   ln -sfn "$repo_root/workflows" "$target/workflows"
+  link_pack_docs "$target/docs"
   for helper in "${bin_helpers[@]}"; do
     destination="$target/bin/$helper"
     if [[ -e "$destination" && ! -L "$destination" ]]; then

bin/install-agent-workflows-test.bash

@@ -98,6 +98,8 @@ test_codex_host_install_writes_helpers_and_metadata() {
   assert_file "$target/skills/pr-batch/SKILL.md"
   assert_file "$target/skills/pr-batch/agents/openai.yaml"
   assert_file "$target/workflows/pr-processing.md"
+  assert_file "$target/docs/review-finding-schema.md"
+  assert_file "$target/docs/solutions/README.md"
   assert_file "$target/bin/agent-workflow-seam-doctor"
   assert_file "$target/bin/agent-workflows-status"
   assert_file "$target/bin/agent-workflows-trust-audit"
@@ -133,6 +135,8 @@ test_claude_host_install_uses_claude_home_when_target_is_omitted() {
   assert_file "$tmp/.claude/skills/pr-batch/SKILL.md"
   assert_file "$tmp/.claude/skills/pr-batch/agents/openai.yaml"
   assert_file "$tmp/.claude/workflows/pr-processing.md"
+  assert_file "$tmp/.claude/docs/review-finding-schema.md"
+  assert_file "$tmp/.claude/docs/solutions/README.md"
   assert_file "$tmp/.claude/bin/agent-workflows-status"
   assert_file "$tmp/.claude/bin/agent-workflows-trust-audit"
   [[ ! -e "$tmp/.claude/.codex-plugin/plugin.json" ]] || fail "Codex native plugin manifest must not be installed into Claude home metadata"
@@ -142,33 +146,89 @@ test_copy_mode_preserves_unrelated_agent_files() {
   local tmp target
   tmp="$(mktemp -d)"
   target="$tmp/codex-home"
-  mkdir -p "$target/skills/personal" "$target/workflows" "$target/bin"
+  mkdir -p "$target/skills/personal" "$target/workflows" "$target/docs" "$target/bin"
   printf 'personal skill\n' > "$target/skills/personal/SKILL.md"
   printf 'personal workflow\n' > "$target/workflows/personal.md"
+  printf 'personal docs\n' > "$target/docs/personal.md"
   printf '#!/usr/bin/env bash\n' > "$target/bin/personal-helper"
 
   "$ROOT/bin/install-agent-workflows" --host codex --target "$target" >/tmp/install-agent-workflows-test.out
 
   assert_file "$target/skills/personal/SKILL.md"
   assert_file "$target/workflows/personal.md"
+  assert_file "$target/docs/personal.md"
+  assert_file "$target/docs/review-finding-schema.md"
+  assert_file "$target/docs/solutions/README.md"
   assert_file "$target/bin/personal-helper"
   assert_file "$target/skills/pr-batch/SKILL.md"
 }
 
+test_copy_mode_does_not_replace_generic_consumer_docs() {
+  local tmp target
+  tmp="$(mktemp -d)"
+  target="$tmp/codex-home"
+  mkdir -p "$target/docs/adr"
+  printf 'consumer adoption docs\n' > "$target/docs/adoption.md"
+  printf 'consumer architecture decision\n' > "$target/docs/adr/0001-consumer.md"
+
+  "$ROOT/bin/install-agent-workflows" --host codex --target "$target" >/tmp/install-agent-workflows-test.out
+
+  grep -q 'consumer adoption docs' "$target/docs/adoption.md" || fail "copy mode replaced consumer docs/adoption.md"
+  grep -q 'consumer architecture decision' "$target/docs/adr/0001-consumer.md" || fail "copy mode replaced consumer docs/adr"
+  assert_file "$target/docs/review-finding-schema.md"
+  assert_file "$target/docs/solutions/README.md"
+}
+
 test_symlink_mode_links_skills_workflows_and_helpers() {
   local tmp target
   tmp="$(mktemp -d)"
   target="$tmp/codex-home"
+  mkdir -p "$target/docs"
+  printf 'personal docs\n' > "$target/docs/personal.md"
 
   "$ROOT/bin/install-agent-workflows" --host codex --target "$target" --mode symlink >/tmp/install-agent-workflows-test.out
 
   assert_symlink "$target/skills/pr-batch"
   assert_symlink "$target/workflows"
+  assert_file "$target/docs/personal.md"
+  assert_symlink "$target/docs/review-finding-schema.md"
+  [[ -d "$target/docs/solutions" && ! -L "$target/docs/solutions" ]] || fail "expected real docs/solutions directory"
+  assert_symlink "$target/docs/solutions/README.md"
   assert_symlink "$target/bin/agent-workflow-seam-doctor"
   assert_symlink "$target/bin/agent-workflows-trust-audit"
   assert_file "$target/.agent-workflows-install.json"
 }
 
+test_symlink_mode_replaces_docs_directory_symlink() {
+  local tmp target external_docs
+  tmp="$(mktemp -d)"
+  target="$tmp/codex-home"
+  external_docs="$tmp/external-docs"
+  mkdir -p "$target" "$external_docs"
+  ln -s "$external_docs" "$target/docs"
+
+  "$ROOT/bin/install-agent-workflows" --host codex --target "$target" --mode symlink >/tmp/install-agent-workflows-test.out
+
+  [[ -d "$target/docs" && ! -L "$target/docs" ]] || fail "expected real docs directory"
+  assert_symlink "$target/docs/review-finding-schema.md"
+  [[ ! -e "$external_docs/review-finding-schema.md" ]] || fail "should not write through pre-existing docs symlink"
+}
+
+test_copy_mode_after_symlink_mode_does_not_delete_source_docs() {
+  local tmp target source_doc
+  tmp="$(mktemp -d)"
+  target="$tmp/codex-home"
+  source_doc="$ROOT/docs/solutions/README.md"
+
+  "$ROOT/bin/install-agent-workflows" --host codex --target "$target" --mode symlink >/tmp/install-agent-workflows-test.out
+  assert_symlink "$target/docs/solutions/README.md"
+  "$ROOT/bin/install-agent-workflows" --host codex --target "$target" >/tmp/install-agent-workflows-test.out
+
+  assert_file "$source_doc"
+  assert_file "$target/docs/solutions/README.md"
+  [[ ! -L "$target/docs/solutions/README.md" ]] || fail "copy mode should replace pack doc symlink with a real copy"
+}
+
 test_status_reports_not_installed_and_check_failed_explicitly() {
   local tmp target output status
   tmp="$(mktemp -d)"
@@ -321,7 +381,10 @@ main() {
     test_installed_prompt_guard_ignores_unowned_docs
     test_claude_host_install_uses_claude_home_when_target_is_omitted
     test_copy_mode_preserves_unrelated_agent_files
+    test_copy_mode_does_not_replace_generic_consumer_docs
     test_symlink_mode_links_skills_workflows_and_helpers
+    test_symlink_mode_replaces_docs_directory_symlink
+    test_copy_mode_after_symlink_mode_does_not_delete_source_docs
     test_status_reports_not_installed_and_check_failed_explicitly
     test_status_reports_upgrade_available_between_source_commits
     test_upgrade_reinstalls_new_source_revision

bin/validate

@@ -61,6 +61,14 @@ ruby bin/agent-workflows-trust-audit-test.rb
 echo "== push-downstream unit tests =="
 ruby bin/push-downstream-test.rb
 
+echo "== solution docs =="
+ruby bin/validate-solutions-test.rb
+ruby bin/validate-solutions
+
+echo "== review finding schema =="
+ruby bin/validate-review-findings-test.rb
+ruby bin/validate-review-findings
+
 echo "== installer/status/upgrade tests =="
 bash bin/install-agent-workflows-test.bash
 
@@ -71,6 +79,7 @@ echo "== downstream registry dry-run =="
 bin/push-downstream --config downstream.yml >/dev/null
 
 echo "== helper tests =="
+ruby skills/autoreview/bin/autoreview-target-state-test.rb
 ruby skills/address-review/bin/fetch-pr-review-data-test.rb
 ruby skills/plan-pr-batch/bin/pr-file-touch-map-test.rb
 AGENT_WORKFLOWS_SOURCE_CHECKOUT=1 ruby skills/plan-pr-batch/scripts/check_goal_prompt_size.rb
@@ -81,6 +90,7 @@ ruby skills/pr-batch/bin/goal-completion-contract-test.rb
 ruby skills/pr-batch/bin/pr-ci-readiness-test.rb
 ruby skills/pr-batch/bin/agent-coord-bounded-test.rb
 ruby skills/pr-batch/bin/pr-security-preflight-test.rb
+ruby skills/task-observer/bin/task-observer-test.rb
 ruby skills/update-changelog/bin/changelog-merged-prs-test.rb
 
 echo "== rubocop ${RUBOCOP_VERSION} =="