Merge pull request #80 from navapbc/worktree-20260508-140855

feat(attribution): wire hook_record_agent_attribution into post-agent.sh dispatcher (SC-1)

Author: JoeOakhartNava

.claude/settings.json

@@ -1,5 +1,27 @@
 {
   "enabledPlugins": {
     "dso-dev@digital-service-orchestra": true
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh dispatchers/post-skill.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh dispatchers/post-agent.sh"
+          }
+        ]
+      }
+    ]
   }
 }

.test-index

@@ -100,7 +100,7 @@ plugins/dso/hooks/check-plugin-self-ref.sh:tests/hooks/test-enforcement-gate.sh
 plugins/dso/hooks/check-portability.sh:tests/hooks/test-enforcement-gate.sh
 plugins/dso/hooks/check-tickets-boundary.sh:tests/hooks/test-check-tickets-boundary.sh
 plugins/dso/hooks/compute-diff-hash.sh:tests/hooks/test-compute-diff-hash-staging-invariance.sh,tests/hooks/test-compute-diff-hash-autostash-invariance.sh,tests/hooks/test-behavioral-equivalence-allowlist.sh
-plugins/dso/hooks/dispatchers/post-agent.sh:tests/hooks/test-post-agent-sentinel.sh,tests/hooks/test-post-dispatcher-err-handler.sh
+plugins/dso/hooks/dispatchers/post-agent.sh:tests/hooks/test-post-agent-sentinel.sh,tests/hooks/test-post-dispatcher-err-handler.sh,tests/hooks/test-post-agent-attribution.sh [test_post_agent_dispatcher_writes_attribution_jsonl_entry]
 plugins/dso/hooks/dispatchers/post-all.sh:tests/hooks/test-post-dispatchers.sh,tests/hooks/test-post-dispatcher-err-handler.sh
 plugins/dso/hooks/dispatchers/post-bash.sh:tests/hooks/test-post-dispatchers.sh,tests/hooks/test-post-dispatcher-err-handler.sh
 plugins/dso/hooks/dispatchers/post-edit.sh:tests/hooks/test-post-dispatchers.sh,tests/hooks/test-post-dispatcher-err-handler.sh
@@ -118,6 +118,7 @@ plugins/dso/hooks/lib/enforcement-gate.sh:tests/hooks/lib/test-enforcement-gate-
 plugins/dso/hooks/lib/hook-error-handler.sh:tests/hooks/test-hook-error-handler.sh
 plugins/dso/hooks/lib/merge-helpers.sh:tests/integration/test-merge-to-main-pr-thread-resolution.sh,tests/integration/test-conflict-data-schema-parity.sh,tests/scripts/test-merge-to-main-dispatcher.sh,tests/hooks/test-merge-helpers-pr-repo-cache.sh,tests/hooks/test-merge-helpers-special-chars.sh,tests/scripts/test-merge-to-main-pr.sh
 plugins/dso/hooks/lib/planning-config.sh:tests/hooks/test-planning-config.sh
+plugins/dso/hooks/lib/post-functions.sh:tests/hooks/test-post-functions-attribution.sh,tests/hooks/test-post-skill-attribution.sh
 plugins/dso/hooks/lib/pre-all-functions.sh:tests/hooks/test-hook-inline-trap-consolidation.sh
 plugins/dso/hooks/lib/pre-bash-functions.sh:tests/hooks/test-hook-inline-trap-consolidation.sh
 plugins/dso/hooks/lib/preconditions-validator-lib.sh:tests/hooks/test-preconditions-validator-lib.sh,tests/integration/test-preconditions-chain-5stage.sh
@@ -413,6 +414,11 @@ tests/scripts/test-ticket-link-duplicates-supersedes.sh:tests/scripts/test-ticke
 tests/scripts/test-ticket-transition-deleted.sh:tests/scripts/test-ticket-transition-deleted.sh
 plugins/dso/scripts/commit-override.sh:tests/scripts/test-commit-override.sh [test_requires_reason_flag]
 plugins/dso/hooks/prepare-commit-msg-override-audit.sh:tests/hooks/test-prepare-commit-msg-override-audit.sh [test_no_token_no_trailer] [test_token_appends_trailer]
+plugins/dso/hooks/post-commit-override-cleanup.sh:tests/hooks/test-post-commit-override-cleanup.sh [test_cleanup_removes_token],tests/scripts/test-reinstall-hooks.sh [test_post_commit_registered]
+plugins/dso/scripts/commit-step.sh:tests/scripts/test-commit-step.sh [test_writes_result_artifact],tests/scripts/test-commit-step-worktree.sh [test_cwd_mismatch_fails_fast] [test_harvest_mode_bypasses_cwd_check],tests/scripts/test-commit-step-truncation.sh [test_pipe_to_tail_artifact_intact],tests/hooks/test-verifier-baseline.sh [test_bug_7b41_breadcrumb_not_empty]
+plugins/dso/hooks/pre-commit-compliance-verifier.sh:tests/hooks/test-pre-commit-compliance-verifier.sh [test_blocks_missing_artifact],tests/scripts/test-reinstall-hooks.sh [test_compliance_verifier_registered],tests/hooks/test-verifier-worktree-context.sh [test_verifier_reads_correct_worktree],tests/hooks/test-overlay-verification.sh [test_security_overlay_flagged_missing],tests/hooks/test-verifier-baseline.sh [test_validate_ci_clean],tests/hooks/test-skip-markers.sh [test_skipped_marker_accepted]
+plugins/dso/scripts/apply-attribution-trailers.sh:tests/unit/scripts/test-apply-attribution-trailers.sh [test_resolve_scalar_trailers_produces_task_story_epic_flags,test_resolve_scalar_trailers_produces_review_score_flag,test_resolve_scalar_trailers_produces_no_flags_when_no_context] [test_script_exits_0_without_modifying_commit_msg_when_attribution_disabled] [test_script_exits_0_without_modifying_commit_msg_when_jsonl_absent] [test_script_exits_0_without_modifying_commit_msg_when_jsonl_empty] [test_injection_appends_dso_agent_trailer_to_commit_message] [test_two_distinct_agents_produce_two_dso_agent_lines] [test_injection_emits_trailer_skipped_and_exits_0_when_git_below_2_6] [test_placement_scan_emits_warning_when_dso_trailer_in_message_body] [test_truncate_clears_populated_jsonl_to_zero_bytes] [test_truncate_exits_0_when_jsonl_absent] [test_truncate_emits_warning_and_exits_0_on_truncation_failure] [test_skips_injection_when_trailers_already_present]
+plugins/dso/hooks/dispatchers/post-skill.sh:tests/hooks/test-post-skill-attribution.sh
 plugins/dso/hooks/post-commit-override-cleanup.sh:tests/hooks/test-post-commit-override-cleanup.sh [test_cleanup_removes_token],tests/scripts/test-reinstall-hooks.sh
 plugins/dso/scripts/commit-step.sh: tests/scripts/test-commit-step.sh [test_writes_result_artifact],tests/scripts/test-commit-step-worktree.sh [test_cwd_mismatch_fails_fast] [test_harvest_mode_bypasses_cwd_check],tests/scripts/test-commit-step-truncation.sh [test_pipe_to_tail_artifact_intact],tests/hooks/test-verifier-baseline.sh
 plugins/dso/hooks/pre-commit-compliance-verifier.sh: tests/hooks/test-pre-commit-compliance-verifier.sh [test_blocks_missing_artifact],tests/scripts/test-reinstall-hooks.sh [test_compliance_verifier_registered],tests/hooks/test-verifier-worktree-context.sh [test_verifier_reads_correct_worktree],tests/hooks/test-overlay-verification.sh [test_security_overlay_flagged_missing],tests/hooks/test-verifier-baseline.sh [test_validate_ci_clean],tests/hooks/test-skip-markers.sh [test_skipped_marker_accepted]

plugins/dso/docs/CONFIGURATION-REFERENCE.md

@@ -227,10 +227,10 @@ Security, performance, and test-quality overlays are dispatched automatically wh
 
 | | |
 |---|---|
-| **Description** | Overrides the DSO plugin version used in CI LLM review. This is **Tier 2** of the 3-tier version resolution chain implemented by `${CLAUDE_PLUGIN_ROOT}/scripts/resolve-dso-version.sh`: **Tier 1** is `~/.claude/plugins/installed_plugins.json` (the Claude per-project plugin tracking file; key `dso@digital-service-orchestra`) — overridable via the `PLUGIN_TRACKING_FILE` env var; **Tier 2** is this config key in `.claude/dso-config.conf` (project-level override without editing the workflow) — overridable via the `DSO_CONFIG_FILE` env var; **Tier 3** is the `dso` (stable) channel in `.claude-plugin/marketplace.json` — overridable via the `MARKETPLACE_JSON` env var. The resolver does **not** fall back to the `dso-dev` channel; if Tier 3 is reached and the stable `dso` channel is absent or malformed, the resolver exits non-zero. When all three tiers fail, the workflow exits with a diagnostic indicating which tier(s) failed. |
+| **Description** | Overrides the DSO plugin version used in CI LLM review. This is **Tier 2** of the 3-tier version resolution chain implemented by `${CLAUDE_PLUGIN_ROOT}/scripts/resolve-dso-version.sh`: **Tier 1** is `~/.claude/plugins/installed_plugins.json` (the Claude per-project plugin tracking file; key `dso@digital-service-orchestra`) — overridable via the `PLUGIN_TRACKING_FILE` env var; **Tier 2** is this config key in `.claude/dso-config.conf` (project-level override without editing the workflow) — overridable via the `DSO_CONFIG_FILE` env var; **Tier 3** is the `dso` (stable) channel in `.claude-plugin/marketplace.json` — overridable via the `MARKETPLACE_JSON` env var. The resolver does **not** fall back to the `dso-dev` channel; if Tier 3 is reached and the stable `dso` channel is absent or malformed, the resolver exits non-zero. When all three tiers fail, the workflow exits with a diagnostic indicating which tier(s) failed. | # shim-exempt: internal implementation references in config documentation
 | **Accepted values** | A version tag (e.g., `v1.13.0`) or a marketplace channel name resolvable in `marketplace.json` |
 | **Default** | Absent — Tier 1 (`installed_plugins.json`) or Tier 3 (`marketplace.json` `dso` channel) is used |
-| **Used by** | `${CLAUDE_PLUGIN_ROOT}/scripts/resolve-dso-version.sh` (called by `ci-dso-fetch.sh` in the generated host-project CI workflow) |
+| **Used by** | `${CLAUDE_PLUGIN_ROOT}/scripts/resolve-dso-version.sh` (called by `ci-dso-fetch.sh` in the generated host-project CI workflow) | # shim-exempt: internal implementation references in config documentation
 
 ---
 
@@ -1137,7 +1137,7 @@ After each resolution of an AMBIGUITY or CONFLICT cross-epic signal, brainstorm
 
 ## Ruleset Provisioning Knobs
 
-The following are CLI flags accepted by `${CLAUDE_PLUGIN_ROOT}/scripts/onboarding/provision-ruleset.sh`. They are NOT `dso-config.conf` keys — they are passed as command-line arguments when provisioning the GitHub Ruleset. Each flag has a default that matches the prior hardcoded behavior so existing invocations remain backward compatible.
+The following are CLI flags accepted by `${CLAUDE_PLUGIN_ROOT}/scripts/onboarding/provision-ruleset.sh`. They are NOT `dso-config.conf` keys — they are passed as command-line arguments when provisioning the GitHub Ruleset. Each flag has a default that matches the prior hardcoded behavior so existing invocations remain backward compatible. # shim-exempt: internal implementation references in config documentation
 
 ### `--bypass-actor-policy`
 
@@ -1146,7 +1146,7 @@ The following are CLI flags accepted by `${CLAUDE_PLUGIN_ROOT}/scripts/onboardin
 | **Description** | Bypass mode applied to the `bypass_actors` entry on the Ruleset. `always` allows admins to bypass at any time; `pull_request_only` restricts the bypass window to pull-request flows. Setting a non-default value requires an admin token (script exits 1 if `gh auth status` does not report admin scope). |
 | **Accepted values** | `always` \| `pull_request_only` |
 | **Default** | `always` |
-| **Used by** | `${CLAUDE_PLUGIN_ROOT}/scripts/onboarding/provision-ruleset.sh` |
+| **Used by** | `${CLAUDE_PLUGIN_ROOT}/scripts/onboarding/provision-ruleset.sh` | # shim-exempt: internal implementation references in config documentation
 
 **Example**: `provision-ruleset.sh --bypass-actor-policy=pull_request_only`
 
@@ -1159,7 +1159,7 @@ The following are CLI flags accepted by `${CLAUDE_PLUGIN_ROOT}/scripts/onboardin
 | **Description** | Maps to the `required_review_thread_resolution` parameter on the Ruleset's `pull_request` rule. When `true`, GitHub requires every PR review thread to be marked resolved before merge. |
 | **Accepted values** | `true` \| `false` (also `1`/`0`, `yes`/`no`) |
 | **Default** | `false` |
-| **Used by** | `${CLAUDE_PLUGIN_ROOT}/scripts/onboarding/provision-ruleset.sh` |
+| **Used by** | `${CLAUDE_PLUGIN_ROOT}/scripts/onboarding/provision-ruleset.sh` | # shim-exempt: internal implementation references in config documentation
 
 **Example**: `provision-ruleset.sh --require-conversation-resolution=true`
 
@@ -1172,7 +1172,7 @@ The following are CLI flags accepted by `${CLAUDE_PLUGIN_ROOT}/scripts/onboardin
 | **Description** | When `true`, the script records the preference in dry-run output and the success summary. GitHub does not currently expose Copilot code review configuration via the Rulesets API — the flag is a documented placeholder for future automation when API support lands. |
 | **Accepted values** | `true` \| `false` |
 | **Default** | `false` |
-| **Used by** | `${CLAUDE_PLUGIN_ROOT}/scripts/onboarding/provision-ruleset.sh` |
+| **Used by** | `${CLAUDE_PLUGIN_ROOT}/scripts/onboarding/provision-ruleset.sh` | # shim-exempt: internal implementation references in config documentation
 
 **Example**: `provision-ruleset.sh --request-copilot-review=true`
 
@@ -1185,7 +1185,7 @@ The following are CLI flags accepted by `${CLAUDE_PLUGIN_ROOT}/scripts/onboardin
 | **Description** | Maps to the `dismiss_stale_reviews_on_push` parameter on the Ruleset's `pull_request` rule. When `true`, GitHub dismisses prior approvals when new commits are pushed to the PR branch. |
 | **Accepted values** | `true` \| `false` |
 | **Default** | `false` |
-| **Used by** | `${CLAUDE_PLUGIN_ROOT}/scripts/onboarding/provision-ruleset.sh` |
+| **Used by** | `${CLAUDE_PLUGIN_ROOT}/scripts/onboarding/provision-ruleset.sh` | # shim-exempt: internal implementation references in config documentation
 
 **Example**: `provision-ruleset.sh --dismiss-stale-approvals-on-push=true`
 
@@ -1198,7 +1198,7 @@ The following are CLI flags accepted by `${CLAUDE_PLUGIN_ROOT}/scripts/onboardin
 | **Description** | Maps to the `required_approving_review_count` parameter on the Ruleset's `pull_request` rule. Sets the minimum number of approving reviews required before a PR can be merged. |
 | **Accepted values** | Non-negative integer |
 | **Default** | `1` |
-| **Used by** | `${CLAUDE_PLUGIN_ROOT}/scripts/onboarding/provision-ruleset.sh` |
+| **Used by** | `${CLAUDE_PLUGIN_ROOT}/scripts/onboarding/provision-ruleset.sh` | # shim-exempt: internal implementation references in config documentation
 
 **Example**: `provision-ruleset.sh --required-approvals=2`
 
@@ -1719,6 +1719,18 @@ and [`model.deep`](#modeldeep) above.
 
 ---
 
+## attribution
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `attribution.enabled` | boolean | `false` | When `true`, `/dso:commit` appends DSO-Agent, DSO-Skill, DSO-Model, DSO-Task, DSO-Story, DSO-Epic, Jira-Ticket, and DSO-Review-Score trailers to commit messages via `git interpret-trailers`. Requires git ≥ 2.6. |
+
+**Notes:**
+- Setting `attribution.enabled=false` after enabling stops future writes to `attribution-contributors.jsonl` but does not purge existing entries; the file can be safely deleted manually.
+- Canonical query for attributed commits: `git log --format="%(trailers:key=DSO-Agent,valueonly)" -- <path>` returns agent names per commit.
+
+---
+
 ## Section 2 — Environment Variables
 
 These variables are consumed by DSO hooks, scripts, and skills at runtime. They supplement or override `dso-config.conf` values.

plugins/dso/docs/workflows/COMMIT-WORKFLOW.md

@@ -181,6 +181,23 @@ Files are already staged from Step 5. The diff stat summary is already in contex
 
 Create a single git commit following the repository's commit message conventions visible in the recent commits from Step 1.
 
+### Attribution Pre-Commit (skip if attribution.enabled ≠ true)
+
+**SKIP ENTIRELY when `attribution.enabled` is absent or not `true` in `dso-config.conf`.**
+
+If `attribution.enabled=true`:
+- Run `.claude/scripts/dso apply-attribution-trailers.sh "$COMMIT_MSG_FILE"` with `ARTIFACTS_DIR` set to the session artifacts dir and `DSO_TASK_ID` exported in the environment (the script reads it from the environment, not as a positional argument)
+- If the script exits non-zero: emit a warning to stderr and continue — this step is **non-blocking**
+
+```bash
+ATTRIBUTION_ENABLED=$(grep -m1 '^attribution\.enabled=' "$REPO_ROOT/.claude/dso-config.conf" 2>/dev/null | cut -d= -f2-)
+if [[ "${ATTRIBUTION_ENABLED:-}" == "true" ]]; then
+    DSO_TASK_ID="${DSO_TASK_ID:-}" \
+        .claude/scripts/dso apply-attribution-trailers.sh "$COMMIT_MSG_FILE" || \
+        echo "WARNING: apply-attribution-trailers.sh failed (non-blocking)" >&2
+fi
+```
+
 ```bash
 echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) step-6-commit" >> "$ARTIFACTS_DIR/commit-breadcrumbs.log"
 ```
@@ -198,6 +215,21 @@ REPO_ROOT=$(git rev-parse --show-toplevel)
 ".claude/scripts/dso" emit-commit-workflow-event.sh --phase=end --success=true
 ```
 
+### Attribution Post-Commit Truncate (skip if attribution.enabled ≠ true)
+
+**SKIP ENTIRELY when `attribution.enabled` is absent or not `true` in `dso-config.conf`.**
+
+If `attribution.enabled=true` and the commit exited 0:
+- Run `.claude/scripts/dso apply-attribution-trailers.sh --truncate` with `ARTIFACTS_DIR` set to the session artifacts dir
+- If truncation exits non-zero: emit a warning to stderr but do **not** fail
+
+```bash
+if [[ "${ATTRIBUTION_ENABLED:-}" == "true" ]]; then
+    .claude/scripts/dso apply-attribution-trailers.sh --truncate || \
+        echo "WARNING: apply-attribution-trailers.sh --truncate failed (non-blocking)" >&2
+fi
+```
+
 After committing, report the SHA and **immediately return control to the caller** — do NOT wait for user input. Resume the calling workflow at the step after this commit invocation. If you were executing `/dso:debug-everything`, continue at the step after this commit invocation (Phase F Step 5 for auto-fix commits, or Phase H Step 11 for post-batch commits). If you were executing `/dso:sprint`, continue at Phase F Step 17 (Commit & Push) or the step that invoked this workflow. Do NOT output any text that implies the session is complete.
 
 <!-- Future work: Jira-Ticket and DSO-Task git trailers (story cab1-600f) are planned

plugins/dso/hooks/dispatchers/post-agent.sh

@@ -4,6 +4,7 @@
 #
 # Hook execution order:
 #   1. hook_extract_agent_suggestion  — extract first SUGGESTION: line and call suggestion-record.sh
+#   2. hook_record_agent_attribution  — append agent/model entry to attribution-contributors.jsonl
 #
 # PostToolUse hooks always exit 0 (non-blocking).
 # Always emits at least '{}' on stdout per Claude Code bug #10463 workaround.
@@ -54,6 +55,7 @@ _post_agent_dispatch() {
     INPUT=$(cat)
 
     _run_post_fn hook_extract_agent_suggestion "$INPUT"
+    _run_post_fn hook_record_agent_attribution "$INPUT"
 }
 
 # Only execute dispatch logic when run as a script (not sourced).

plugins/dso/hooks/dispatchers/post-skill.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# hooks/dispatchers/post-skill.sh
+# PostToolUse Skill dispatcher: records skill attribution data.
+#
+# Hook execution order:
+#   1. hook_record_skill_attribution  — append skill entry to attribution-contributors.jsonl
+#
+# PostToolUse hooks always exit 0 (non-blocking).
+# Always emits at least '{}' on stdout per Claude Code bug #10463 workaround.
+
+# DEFENSE-IN-DEPTH: Guarantee exit 0 and non-empty stdout on any unexpected failure.
+_HOOK_HAS_OUTPUT=""
+trap 'if [[ -z "$_HOOK_HAS_OUTPUT" ]]; then printf "{}"; fi; exit 0' EXIT
+# Resolve dispatcher directory (CLAUDE_PLUGIN_ROOT if set, else relative)
+if [[ -z "${CLAUDE_PLUGIN_ROOT:-}" || ! -d "${CLAUDE_PLUGIN_ROOT:-}/hooks/lib" ]]; then
+    CLAUDE_PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+fi
+
+HOOKS_LIB_DIR="$CLAUDE_PLUGIN_ROOT/hooks/lib"
+
+# Source shared ERR handler (fail-open: if missing, keep original silent trap behavior)
+if [[ -f "${HOOKS_LIB_DIR}/hook-error-handler.sh" ]]; then
+    # shellcheck source=/dev/null
+    source "${HOOKS_LIB_DIR}/hook-error-handler.sh" 2>/dev/null || true
+    _dso_register_hook_err_handler "post-skill.sh"
+else
+    trap 'exit 0' ERR
+fi
+
+# Source the dispatcher framework (provides run_hooks)
+source "$HOOKS_LIB_DIR/dispatcher.sh"
+
+# Source all post hook functions (includes hook_record_skill_attribution)
+source "$HOOKS_LIB_DIR/post-functions.sh"
+
+# Run all Skill post-hook functions sequentially.
+# PostToolUse hooks are non-blocking (always return 0).
+_run_post_fn() {
+    local fn_name="$1"
+    local json_input="$2"
+    local _fn_out=""
+    _fn_out=$("$fn_name" "$json_input") || true
+    if [[ -n "$_fn_out" ]] && [[ "$_fn_out" != "{}" ]]; then
+        _HOOK_HAS_OUTPUT=1
+        printf '%s\n' "$_fn_out"
+    fi
+}
+
+_post_skill_dispatch() {
+    # Read hook input from stdin
+    local INPUT
+    INPUT=$(cat)
+
+    _run_post_fn hook_record_skill_attribution "$INPUT"
+}
+
+# Only execute dispatch logic when run as a script (not sourced).
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+    _post_skill_dispatch
+    exit 0
+fi