@metasession.co/devaudit-cli 0.1.66 → 0.1.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.1.66",
+  "version": "0.1.67",
   "description": "DevAudit CLI — installs, syncs, and operates the Metasession SDLC across consumer projects.",
   "type": "module",
   "bin": {

package/sdlc/ai-rules/INSTRUCTIONS-SDLC.md

@@ -109,7 +109,14 @@ Upload to DevAudit (NEVER commit to git):
 - E2E results (JSON), screenshots (PNG/JPG), SAST results (JSON), dependency audit (JSON), unit test output (TXT), test reports (HTML)
 
 Keep in git (small markdown, needs PR review):
-- compliance/RTM.md, test-scope.md, security-summary.md, ai-use-note.md, ai-prompts.md, release tickets
+- compliance/RTM.md, test-scope.md, security-summary.md, ai-use-note.md (YAML frontmatter — devaudit-installer#197), ai-agent-handoff.md (if AI agent changed mid-implementation), ai-prompts.md, release tickets
+
+### AI Contributor Tracking (devaudit-installer#197)
+
+- `ai-use-note.md` uses YAML frontmatter with an `ai_contributors` list supporting multiple entries (tool, version, session_id, date_range, commits).
+- The `prepare-commit-msg` git hook warns when the `Co-Authored-By` trailer changes between commits on the same branch, prompting creation of an `ai-agent-handoff.md` entry.
+- The release ticket template includes an AI Contributors table with handoff and verification fields.
+- Legacy `ai-use-note.md` files without YAML frontmatter are still accepted (portal falls back to text parsing).
 
 ### After Implementation
 

package/sdlc/ai-rules/SDLC_RULES.md

@@ -192,10 +192,20 @@ Tell the user: **"Let me create a test plan that maps the acceptance criteria to
 
 ### Step 9: Document AI involvement (if applicable)
 
-Create `compliance/evidence/REQ-XXX/ai-use-note.md`:
+Create `compliance/evidence/REQ-XXX/ai-use-note.md` with YAML frontmatter (devaudit-installer#197):
 
 ```markdown
-AI Tool: [tool name]
+---
+ai_contributors:
+  - tool: "[tool name]"
+    version: "[tool version]"
+    session_id: "[session id]"
+    date_range: "[YYYY-MM-DD to YYYY-MM-DD]"
+    commits: []
+---
+
+# AI Use Record — REQ-XXX
+
 Risk Classification Impact: [original risk] → [adjusted risk if AI involved]
 Areas of AI involvement: [list]
 ```
@@ -391,7 +401,8 @@ Evidence uploaded to DevAudit project: [PROJECT_SLUG]
 Verify these also exist in git:
 - `compliance/evidence/REQ-XXX/test-scope.md` (from planning)
 - `compliance/evidence/REQ-XXX/implementation-plan.md` (MEDIUM/HIGH risk — from implementation plan step)
-- `compliance/evidence/REQ-XXX/ai-use-note.md` (if AI was used)
+- `compliance/evidence/REQ-XXX/ai-use-note.md` (if AI was used — YAML frontmatter, devaudit-installer#197)
+- `compliance/evidence/REQ-XXX/ai-agent-handoff.md` (if AI agent changed mid-implementation — devaudit-installer#197)
 - `compliance/evidence/REQ-XXX/ai-prompts.md` (if AI was used, MEDIUM/HIGH risk)
 
 ### Step 4: Update RTM status
@@ -402,10 +413,11 @@ Change the requirement status from `DRAFT` or `IN PROGRESS` to `TESTED - PENDING
 
 Create `compliance/pending-releases/RELEASE-TICKET-REQ-XXX.md` with:
 - Summary of changes
+- AI Contributors table (tool, version, session, commits, date range) — devaudit-installer#197
+- AI handoffs (if any — reference `ai-agent-handoff.md`)
 - Test changes (which test files were added/modified, what they cover, any gaps)
 - Test evidence table (reference DevAudit portal for binary evidence)
 - Security evidence (reference `security-summary.md` in git)
-- AI involvement summary
 - Post-deploy actions (data migrations, backfill scripts, or "None required")
 - Audit trail
 

package/sdlc/files/_common/1-plan-requirement.md

@@ -407,9 +407,17 @@ If AI will generate code (Medium/High risk):
 
 ```bash
 cat > compliance/evidence/REQ-XXX/ai-use-note.md << 'EOF'
+---
+ai_contributors:
+  - tool: "[tool name]"
+    version: "[tool version]"
+    session_id: "[session id]"
+    date_range: "[YYYY-MM-DD to YYYY-MM-DD]"
+    commits: []
+---
+
 # AI Use Record — REQ-XXX
 
-**AI Tool:** [tool name]
 **Planned AI Use:** [implementation / test generation / both / none]
 **Risk Classification Impact:** [note if risk was raised due to AI involvement]
 EOF

package/sdlc/files/_common/3-compile-evidence.md

@@ -260,19 +260,88 @@ For Medium/High risk, add access control and audit log verification to the secur
 
 ### Step 5: Save AI Evidence (If Applicable)
 
-Verify `ai-use-note.md` and `ai-prompts.md` exist (if AI was used). If missing:
+Verify `ai-use-note.md` and `ai-prompts.md` exist (if AI was used). If missing, create `ai-use-note.md` with YAML frontmatter (devaudit-installer#197):
 
 ```bash
 cat > compliance/evidence/REQ-XXX/ai-use-note.md << 'EOF'
+---
+ai_contributors:
+  - tool: "[tool name]"
+    version: "[tool version]"
+    session_id: "[session id]"
+    date_range: "[YYYY-MM-DD to YYYY-MM-DD]"
+    commits: ["[commit sha]", "[commit sha]"]
+---
+
 # AI Use Record — REQ-XXX
-**AI Tool:** [tool name]
-**Code Generated By AI:** [list files]
-**Human Reviewer:** [name]
-**Review Date:** [date]
-**Regenerations:** [none / list]
+
+## Summary
+[Brief description of what the AI tool was used for]
+
+## Code Generated By AI
+- [list files]
+
+## Human Reviewer
+- **Name:** [name]
+- **Review Date:** [date]
+- **Regenerations:** [none / list]
+
+## Risk Classification Impact
+[original risk] → [adjusted risk if AI involved]
 EOF
 ```
 
+For multiple AI contributors (e.g. agent handoff mid-implementation), add additional entries to the `ai_contributors` YAML list:
+
+```yaml
+ai_contributors:
+  - tool: "OpenAI Codex"
+    version: "cascade-2024-06"
+    session_id: "cascade-13654549920348561833"
+    date_range: "2026-06-15 to 2026-06-17"
+    commits: ["b7c1d29", "5a538f6"]
+  - tool: "Claude"
+    version: "claude-3.5-sonnet"
+    session_id: "claude-987654321"
+    date_range: "2026-06-18"
+    commits: ["abc1234"]
+```
+
+**Backward compatibility:** Legacy `ai-use-note.md` files without YAML frontmatter are still accepted by the portal (falls back to text parsing). New files should use YAML.
+
+If an AI agent handoff occurred mid-implementation, also create `ai-agent-handoff.md` (see Step 5b below).
+
+### Step 5b: AI Agent Handoff Log (If Applicable)
+
+If the AI tool changed mid-implementation (detected by the `prepare-commit-msg` git hook or observed manually), create `compliance/evidence/REQ-XXX/ai-agent-handoff.md`:
+
+```markdown
+# AI Agent Handoff Log — REQ-XXX
+
+## Handoff 1
+
+**Date:** [YYYY-MM-DD]
+**From:** [tool name] (session [session id])
+**To:** [tool name] (session [session id])
+
+**Context Summary:**
+- Completed: [what the previous agent finished]
+- In Progress: [what was left incomplete]
+- Blockers: [any known blockers]
+
+**Files Modified by Previous Agent:**
+- [list of files]
+
+**Next Steps for New Agent:**
+- [remaining tasks]
+
+**Link to Full Context:**
+- Previous session: [URL if available]
+- REQ release ticket: compliance/pending-releases/RELEASE-TICKET-REQ-XXX.md
+```
+
+This file is uploaded as evidence with `evidence_type: compliance_document` and `evidence_category: ai_handoff` so the portal can query for it specifically.
+
 ### Step 6: Verify Test Scope and Implementation Plan
 
 Review `compliance/evidence/REQ-XXX/test-scope.md` (created during PLAN stage). Confirm all testing items have been addressed:
@@ -331,11 +400,17 @@ Create `compliance/pending-releases/RELEASE-TICKET-REQ-XXX.md`:
 ## Summary
 [1-3 sentences]
 
-## AI Involvement
-- **AI Tool Used:** [tool / none]
-- **AI-Generated Files:** [list, or "none"]
-- **Human Reviewer of AI Code:** [name]
-- **Components Regenerated:** [none / list]
+## AI Contributors
+
+| Tool | Version | Session | Commits | Date Range |
+|------|---------|---------|---------|------------|
+| [tool / none] | [version] | [session id] | [N] | [YYYY-MM-DD to YYYY-MM-DD] |
+
+**Handoffs:** [None / list — see `ai-agent-handoff.md` if applicable]
+**Verification:** Claims match Co-Authored-By trailers in git history.
+**AI-Generated Files:** [list, or "none"]
+**Human Reviewer of AI Code:** [name]
+**Components Regenerated:** [none / list]
 
 ## Implementation Details
 **Files Modified:**

package/sdlc/files/stacks/node/adapter.json

@@ -5,7 +5,7 @@
   "manifest_file": "package.json",
   "hook_framework": "husky",
   "hook_install_dir": ".husky",
-  "hooks": ["commit-msg", "pre-commit", "pre-push"],
+  "hooks": ["commit-msg", "pre-commit", "pre-push", "prepare-commit-msg"],
   "hook_config_files": ["commitlint.config.mjs", "lint-staged.config.mjs", ".prettierrc.json"],
   "stack_scripts": ["check-requirement-jsdoc.sh"],
   "required_dev_dependencies": [

package/sdlc/files/stacks/node/hooks/prepare-commit-msg

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Husky prepare-commit-msg hook — detects AI agent changes mid-branch.
+#
+# When the Co-Authored-By trailer in the new commit message differs from
+# the AI tool signature in the previous commit on the same branch, warns
+# the operator to create an ai-agent-handoff.md entry (devaudit-installer#197).
+#
+# This is a WARNING-only hook — it never blocks the commit. The operator
+# decides whether a handoff entry is warranted (e.g. same tool, different
+# session → no handoff needed; different tool → handoff recommended).
+#
+# Install: cp this file to .husky/prepare-commit-msg && chmod +x .husky/prepare-commit-msg
+#
+# To disable: delete .husky/prepare-commit-msg or set DEVAUDIT_NO_AI_HOOK=1
+
+# Allow opt-out
+if [ -n "${DEVAUDIT_NO_AI_HOOK:-}" ]; then
+  exit 0
+fi
+
+COMMIT_MSG_FILE="$1"
+COMMIT_SOURCE="$2"
+
+# Skip merge commits, squash, etc. — only check normal commits
+if [ -n "$COMMIT_SOURCE" ] && [ "$COMMIT_SOURCE" != "message" ]; then
+  exit 0
+fi
+
+# Extract Co-Authored-By from the incoming commit message (if present)
+CURRENT_AI=$(grep -i 'Co-Authored-By:' "$COMMIT_MSG_FILE" 2>/dev/null | head -1 | sed 's/.*Co-Authored-By:[[:space:]]*//' | tr -d '\r')
+
+# Extract Co-Authored-By from the previous commit on this branch
+LAST_AI=$(git log -1 --format='%b' 2>/dev/null | grep -i 'Co-Authored-By:' | head -1 | sed 's/.*Co-Authored-By:[[:space:]]*//' | tr -d '\r')
+
+# Only warn if both exist and differ — a missing trailer on either side
+# is not an agent change (the commitlint hook handles missing trailers)
+if [ -z "$CURRENT_AI" ] || [ -z "$LAST_AI" ]; then
+  exit 0
+fi
+
+if [ "$CURRENT_AI" != "$LAST_AI" ]; then
+  echo ""
+  echo "⚠️  AI agent change detected (devaudit-installer#197):"
+  echo "    Previous: $LAST_AI"
+  echo "    Current:  $CURRENT_AI"
+  echo ""
+  echo "    Consider creating an ai-agent-handoff.md entry in"
+  echo "    compliance/evidence/REQ-XXX/ to document the handoff."
+  echo "    See SDLC/3-compile-evidence.md Step 5b for the template."
+  echo ""
+  echo "    To suppress this warning: DEVAUDIT_NO_AI_HOOK=1"
+  echo ""
+fi
+
+exit 0