@dzhechkov/skills-bto 1.1.1 → 1.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dzhechkov/skills-bto",
-  "version": "1.1.1",
-  "description": "Build-Test-Optimize skill pack for Claude Code — structured BTO pipeline with quality gates, testing strategies, and optimization workflows",
+  "version": "1.2.0",
+  "description": "Build-Test-Optimize skill pack for Claude Code — structured BTO pipeline with quality gates, witness chain verification, judge attestation, and optimization workflows",
   "main": "src/cli.js",
   "bin": {
     "skills-bto": "./bin/cli.js"
@@ -39,5 +39,13 @@
   "homepage": "https://github.com/dzhechko/product-keysarium-2026#readme",
   "bugs": {
     "url": "https://github.com/dzhechko/product-keysarium-2026/issues"
+  },
+  "peerDependencies": {
+    "@dzhechkov/keysarium-core": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@dzhechkov/keysarium-core": {
+      "optional": true
+    }
   }
 }

package/templates/.claude/commands/verify-chain.md

@@ -0,0 +1,168 @@
+# /verify-chain — Witness Chain and Judge Attestation Verification
+
+> Verify the integrity of SHA-256 witness chains and BTO judge attestation chains.
+
+## Usage
+
+```
+/verify-chain [path]       — Verify a specific research directory
+/verify-chain all          — Verify all research directories
+```
+
+## Arguments
+
+- `path`: Path to a research directory (e.g., `researches/bank_kc_automation/`) or `"all"` to scan all directories under `researches/`.
+
+$ARGUMENTS
+
+## Protocol
+
+### Step 1: Parse Arguments and Discover Targets
+
+Determine which directories to verify:
+
+```bash
+TARGET="$ARGUMENTS"
+
+if [ "${TARGET}" = "all" ]; then
+  # Find all research directories
+  DIRS=$(find researches/ -mindepth 1 -maxdepth 1 -type d 2>/dev/null)
+  if [ -z "${DIRS}" ]; then
+    echo "No research directories found under researches/"
+    exit 0
+  fi
+else
+  # Single directory
+  DIRS="${TARGET}"
+  if [ ! -d "${TARGET}" ]; then
+    echo "ERROR: Directory '${TARGET}' not found"
+    exit 1
+  fi
+fi
+```
+
+### Step 2: Load Protocols
+
+Read the witness chain and judge attestation protocols for reference:
+
+```
+Read: lib/witness-chain.md
+Read: lib/judge-attestation.md
+```
+
+### Step 3: Verify Each Directory
+
+For each target directory, perform two verification passes:
+
+#### Pass A: Witness Chain Verification
+
+1. Check if `.witness-chain.json` exists in the directory
+2. If not found: report `NOT_FOUND` for this directory (not an error — chain may not have been enabled)
+3. If found:
+   a. Parse the JSON file
+   b. Detect platform SHA-256 command (`sha256sum` or `shasum -a 256`)
+   c. For each record in the chain:
+      - Read the artifact file
+      - If file missing: record FAIL with "artifact file not found"
+      - Compute the chained hash: `SHA-256(file_content + previous_hash)`
+        - For sequence 0: previous_hash = NULL_HASH (64 zeros)
+        - For sequence N: previous_hash = chain[N-1].hash (without "sha256:" prefix)
+      - Compare computed hash with stored hash
+      - If match: record PASS
+      - If mismatch: record FAIL with expected vs actual hash
+   d. Verify sequence numbers are contiguous (0, 1, 2, ...)
+   e. Verify timestamps are chronologically ordered
+
+#### Pass B: Judge Attestation Verification
+
+1. Check if `.judge-attestations.json` exists in the directory
+2. If not found: skip (attestations are optional — only present if BTO was run)
+3. If found:
+   a. Parse the JSON file
+   b. For each evaluation round:
+      - Verify `artifact_hash` by recomputing SHA-256 of the artifact file (if file path available)
+      - For each attestation:
+        - Reconstruct evaluation_hash from: `judge_id|artifact_hash|score|rationale_summary`
+        - Compare reconstructed hash with stored `evaluation_hash`
+        - Verify `previous_attestation_hash` matches the preceding attestation's `evaluation_hash`
+        - Verify timestamp is after the preceding attestation's timestamp
+      - Report isolation status (all hashes valid = isolation confirmed)
+
+### Step 4: Produce Verification Report
+
+Display a formatted report for each directory:
+
+```
+===============================================================
+WITNESS CHAIN VERIFICATION REPORT
+===============================================================
+
+Directory: researches/bank_kc_automation/
+
+--- Artifact Chain ---
+  [PASS] #0 phase-0  00_product_discovery.md
+  [PASS] #1 phase-1  01_case_brief.md
+  [PASS] #2 phase-2  02_research_findings.md
+  [FAIL] #3 phase-2.5 02.5_trend_brief.md
+         Expected: sha256:abc123...
+         Actual:   sha256:def456...
+         >> Artifact may have been modified after checkpoint
+  [SKIP] #4 phase-3  03_solution_strategy.md (upstream chain broken)
+
+  Chain Status: BROKEN at record #3
+  Verified: 3/5 records
+
+--- Judge Attestations ---
+  Evaluation: bto-eval-2026-03-01T12:00:00Z
+  [PASS] domain-expert    score=8.2  hash verified
+  [PASS] critic           score=7.5  hash verified, chain link valid
+  [PASS] completeness-auditor score=8.0  hash verified, chain link valid
+
+  Isolation Status: CONFIRMED
+  All 3 judges evaluated independently.
+
+===============================================================
+SUMMARY
+===============================================================
+
+Directories verified: 1
+  PASS: 0
+  FAIL: 1 (broken chain in bank_kc_automation)
+  NOT_FOUND: 0
+
+Attestation sets verified: 1
+  Isolation confirmed: 1
+  Isolation violated: 0
+
+===============================================================
+```
+
+### Step 5: Handle Edge Cases
+
+| Scenario | Behavior |
+|----------|----------|
+| No `.witness-chain.json` in directory | Report NOT_FOUND, do not treat as error |
+| Empty chain (no records) | Report WARNING: "Chain exists but contains no records" |
+| Artifact file deleted | Report FAIL: "Artifact file not found" |
+| Invalid JSON | Report FAIL: "Chain file corrupted — invalid JSON" |
+| `sha256sum` not available | Try `shasum -a 256`, if also missing report ERROR |
+| Directory does not exist | Report ERROR: "Directory not found" |
+| Chain has gaps in sequence numbers | Report WARNING: "Non-contiguous sequence numbers" |
+| Timestamps not monotonic | Report WARNING: "Timestamps not in chronological order" |
+
+### Step 6: Summary and Recommendations
+
+After all directories are verified, provide actionable recommendations:
+
+- If a chain is broken: "Run the pipeline phase again to re-hash from the modified artifact forward"
+- If attestation isolation is violated: "Review the BTO evaluation process — judges may have shared context"
+- If no chains found: "Witness chains are created automatically during the /casarium pipeline when witness-chain rules are active"
+
+## Quality Gates
+
+- [ ] All target directories scanned
+- [ ] Each record verified with hash recomputation (not just format check)
+- [ ] Broken links reported with specific artifact name and hash values
+- [ ] Judge attestation isolation checked (if attestations present)
+- [ ] Clear summary with pass/fail counts
+- [ ] Actionable recommendations provided for failures

package/templates/.claude/rules/witness-chain.md

@@ -0,0 +1,153 @@
+# Witness Chain Integration Rules
+
+## Purpose
+
+These rules define when and how SHA-256 witness records and BTO judge attestations are created during the Keysarium pipeline. They integrate with the existing checkpoint protocol and BTO quality gates.
+
+## Rule 1: Witness Record at Every Phase Checkpoint
+
+**WHEN:** A phase checkpoint is reached and the phase artifact has been created.
+**THEN:** Create a witness record before displaying the checkpoint banner.
+
+### Procedure
+
+1. After creating the phase artifact file, compute its witness record
+2. If this is Phase 0 (first phase): create genesis record in `.witness-chain.json`
+3. If this is Phase 1+: append record to existing `.witness-chain.json`
+4. Include the witness hash in the checkpoint banner
+
+### Integration with Checkpoint Format
+
+The checkpoint banner gains a witness hash line:
+
+```
+=============================================================
+CHECKPOINT N: [Phase Name] Complete
+<promise>[PROMISE_TAG]</promise>
+Witness: sha256:<hash>  (chain link #N)
+
+[2-3 line summary of what was done]
+Files created: [list]
+
+* "ok" -- next phase
+* "углуби [section]" -- elaborate
+* "[specific feedback]" -- adjust
+=============================================================
+```
+
+## Rule 2: Chain Structure Per Research
+
+Each research directory (`researches/<slug>/`) has its own independent witness chain stored in `researches/<slug>/.witness-chain.json`.
+
+### Chain initialization
+
+- Created at Phase 0 (Discovery) with the genesis record
+- Uses NULL_HASH (64 zeros) as the previous_hash for the first record
+
+### Standard chain sequence
+
+| Sequence | Phase | Artifact | Promise Tag |
+|----------|-------|----------|-------------|
+| 0 | phase-0 | 00_product_discovery.md | DISCOVERY_COMPLETE |
+| 1 | phase-1 | 01_case_brief.md | CASE_EXPLORED |
+| 2 | phase-2 | 02_research_findings.md | RESEARCH_PARANOID_PASSED |
+| 3 | phase-2.5 | 02.5_trend_brief.md | CJM_VALIDATED |
+| 4 | phase-3 | 03_solution_strategy.md | SOLUTION_DESIGNED |
+| 5 | phase-4 | 04_architecture.md | ARCHITECTURE_DEFINED |
+| 6 | phase-5 | 05_presentation_content.md | PRESENTATION_READY |
+
+Additional artifacts (06_speaker_script.md, 07_qa_preparation.md, 08_executive_summary.md) may be added as additional chain records after sequence 6 if desired.
+
+## Rule 3: Required Fields Per Witness Record
+
+Every witness record MUST contain ALL of the following fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sequence` | integer | 0-based position, monotonically increasing |
+| `phase` | string | Phase identifier (phase-0 through phase-5) |
+| `artifact` | string | Filename relative to research directory |
+| `hash` | string | `sha256:` prefix + 64 hex chars |
+| `previous_hash` | string | `sha256:` prefix + 64 hex chars (or null hash for genesis) |
+| `timestamp` | string | ISO-8601 UTC timestamp |
+| `promise_tag` | string | The semantic promise tag for this phase |
+
+No field may be empty, null, or omitted.
+
+## Rule 4: BTO Judge Attestation Integration
+
+**WHEN:** A BTO Layer 2 judge panel completes evaluation.
+**THEN:** Create judge attestations in `.judge-attestations.json`.
+
+### Procedure
+
+1. Before the panel starts: compute the artifact_hash of the evaluated artifact
+2. After each judge submits its score and rationale:
+   a. Compute evaluation_hash = SHA-256(judge_id|artifact_hash|score|rationale_summary)
+   b. Link to previous attestation hash (or NULL_HASH for first judge)
+   c. Record timestamp
+3. After all judges complete: write `.judge-attestations.json` alongside the evaluation files
+4. If meta-judge is invoked (disagreement > 3 points): append meta-judge attestation
+
+### Attestation placement
+
+The `.judge-attestations.json` file is stored in the same directory as the BTO evaluation output. If the BTO evaluation is for a skill, this could be:
+- `researches/<slug>/` if BTO was run on a research artifact
+- `.claude/skills/<name>/` if BTO was run on a skill
+- The current working directory if path was specified explicitly
+
+## Rule 5: Chain Repair After Legitimate Edits
+
+If a user provides feedback at a checkpoint and the artifact is modified:
+
+1. Re-hash the modified artifact using the same previous_hash
+2. Update the record's hash in `.witness-chain.json`
+3. If subsequent records exist: re-hash ALL downstream records (cascade)
+4. Update `last_updated` timestamp
+5. Log the repair in a `chain_repairs` array at the top level of the JSON:
+
+```json
+{
+  "chain_repairs": [
+    {
+      "repaired_at": "2026-03-01T11:30:00Z",
+      "sequence": 2,
+      "artifact": "02_research_findings.md",
+      "reason": "User requested additional research depth",
+      "records_rehashed": 3
+    }
+  ]
+}
+```
+
+This is expected behavior, not an error. The repair log provides audit context.
+
+## Rule 6: Verification Recommendation
+
+After completing a full pipeline (all phases through packaging):
+- Recommend running `/verify-chain researches/<slug>/` as a final integrity check
+- Include verification in the Phase 6 (Packaging) checklist
+
+After completing a BTO evaluation:
+- Recommend running `/verify-chain` on the evaluation directory to confirm judge isolation
+
+## Rule 7: Graceful Degradation
+
+If witness chain creation fails for any reason (sha256sum not available, file permission error, JSON write failure):
+- Log a WARNING but do NOT block the pipeline
+- The witness chain is an integrity enhancement, not a pipeline gate
+- The pipeline must complete even without witness records
+
+Exception: In banking domain (detected by Phase 0 domain detection), witness chain failure should be escalated to the user as a WARNING at the checkpoint, since audit trail is especially important for ФЗ-152 compliance.
+
+## Rule 8: No Witness Chain for Feature ADR Pipeline
+
+The `/feature-adr` pipeline does NOT require witness chains. Witness chains are designed for the Keysarium research pipeline (`/casarium`) and BTO evaluation pipeline (`/bto-test`).
+
+If a user explicitly requests witness chain verification for a feature directory, `/verify-chain` should handle it gracefully (scan for `.witness-chain.json`, report NOT_FOUND if absent).
+
+## Rule 9: Chain Files in .gitignore
+
+The `.witness-chain.json` and `.judge-attestations.json` files SHOULD be committed to git alongside research artifacts. They are part of the audit trail and should be version-controlled.
+
+Do NOT add these files to `.gitignore`.

package/templates/lib/judge-attestation.md

@@ -0,0 +1,322 @@
+# Judge Attestation Protocol
+
+> Cryptographic proof of BTO judge isolation via SHA-256 hash chain attestations.
+
+## Purpose
+
+This protocol defines how BTO judges (Domain Expert, Critic, Completeness Auditor) create cryptographic attestations proving their evaluations were performed independently. Each judge records a hash of its evaluation before seeing other judges' scores. The attestations are chained to provide ordering proof.
+
+## Constants
+
+```
+NULL_HASH = "0000000000000000000000000000000000000000000000000000000000000000"
+ATTESTATION_FILE = ".judge-attestations.json"
+HASH_PREFIX = "sha256:"
+STANDARD_PANEL_SIZE = 3
+HIGH_STAKES_PANEL_SIZE = 5
+```
+
+## Section 1: Attestation Creation
+
+### Hash Input Construction
+
+Each judge's evaluation hash is computed from a deterministic concatenation of:
+
+```
+evaluation_hash = SHA-256(judge_id + "|" + artifact_hash + "|" + score + "|" + rationale_summary)
+```
+
+The pipe character `|` serves as a delimiter to prevent ambiguity in concatenation.
+
+**Fields:**
+- `judge_id`: One of `"domain-expert"`, `"critic"`, `"completeness-auditor"` (or `"meta-judge"` for escalation)
+- `artifact_hash`: SHA-256 hash of the artifact being evaluated (computed before evaluation starts)
+- `score`: The numeric score as a string with one decimal place (e.g., `"8.2"`)
+- `rationale_summary`: First 500 characters of the judge's rationale text, trimmed of leading/trailing whitespace
+
+### Computing the Artifact Hash
+
+Before any judge starts evaluation, compute the artifact hash:
+
+```bash
+ARTIFACT_HASH=$(${SHA_CMD} "path/to/artifact.md" | awk '{print $1}')
+```
+
+This hash is shared with all judges and recorded in each attestation. It proves all judges evaluated the same artifact.
+
+### Computing the Evaluation Hash
+
+After a judge completes its evaluation:
+
+```bash
+JUDGE_ID="domain-expert"
+ARTIFACT_HASH="<computed above>"
+SCORE="8.2"
+RATIONALE_SUMMARY="<first 500 chars of rationale>"
+
+EVAL_HASH=$(printf '%s' "${JUDGE_ID}|${ARTIFACT_HASH}|${SCORE}|${RATIONALE_SUMMARY}" | ${SHA_CMD} | awk '{print $1}')
+```
+
+**Important:** The rationale_summary must be trimmed to exactly 500 characters (or fewer if the rationale is shorter) to ensure deterministic reproduction during verification.
+
+## Section 2: Chain Linking
+
+### Attestation Order
+
+Judges are recorded in a fixed order within each evaluation round:
+
+1. Domain Expert (first, previous = NULL_HASH)
+2. Critic (second, previous = Domain Expert's evaluation_hash)
+3. Completeness Auditor (third, previous = Critic's evaluation_hash)
+
+For a 5-judge high-stakes panel:
+4. Additional Expert (fourth, previous = Auditor's evaluation_hash)
+5. Tiebreaker (fifth, previous = Additional Expert's evaluation_hash)
+
+### Chain Link Protocol
+
+```bash
+# Judge 1 (Domain Expert)
+PREV_ATTESTATION_HASH="${NULL_HASH}"
+# ... compute evaluation_hash_1 ...
+# Record attestation with previous = NULL_HASH
+
+# Judge 2 (Critic)
+PREV_ATTESTATION_HASH="${EVAL_HASH_1}"
+# ... compute evaluation_hash_2 ...
+# Record attestation with previous = evaluation_hash_1
+
+# Judge 3 (Completeness Auditor)
+PREV_ATTESTATION_HASH="${EVAL_HASH_2}"
+# ... compute evaluation_hash_3 ...
+# Record attestation with previous = evaluation_hash_2
+```
+
+### Ordering Note
+
+The chain records the ORDER in which attestations were finalized, not the order in which judges started evaluating. Since judges evaluate in parallel but record sequentially, the chain proves:
+- Each attestation was recorded after the previous one
+- The evaluation_hash was computed from the judge's OWN data only
+- The previous_attestation_hash links to the preceding record (not to the preceding judge's score)
+
+## Section 3: Isolation Verification
+
+### Verification Algorithm
+
+```
+1. Load .judge-attestations.json
+2. For each evaluation round:
+   a. Verify artifact_hash matches across all attestations
+   b. For each attestation (index i):
+      i.   Reconstruct evaluation_hash from (judge_id, artifact_hash, score, rationale_summary)
+      ii.  Compare reconstructed hash with stored evaluation_hash
+      iii. If i == 0: verify previous_attestation_hash == NULL_HASH
+      iv.  If i > 0: verify previous_attestation_hash == attestations[i-1].evaluation_hash
+      v.   Verify timestamp > attestations[i-1].timestamp (if i > 0)
+3. Produce verification report
+```
+
+### Isolation Proof Logic
+
+The isolation proof works as follows:
+
+1. **Hash Independence:** Each evaluation_hash is computed from `judge_id|artifact_hash|score|rationale`. If a judge had seen another judge's score, it would not affect its own hash computation -- but it would be detectable if the rationale text references specific scores from other judges.
+
+2. **Chain Integrity:** The previous_attestation_hash links attestations in order but does NOT include other judges' scores in the hash input. This means the chain proves ORDER but the evaluation content is provably independent.
+
+3. **Timestamp Monotonicity:** Timestamps must be strictly increasing. If Judge B's timestamp is BEFORE Judge A's, but Judge B's previous_attestation_hash points to Judge A, then something is wrong.
+
+### Verification Script
+
+```bash
+python3 << 'VERIFY_ATTESTATION'
+import json, subprocess, sys
+
+NULL_HASH = "0" * 64
+
+def sha256(content):
+    result = subprocess.run(
+        ["sha256sum"],
+        input=content.encode(),
+        capture_output=True
+    )
+    if result.returncode != 0:
+        result = subprocess.run(
+            ["shasum", "-a", "256"],
+            input=content.encode(),
+            capture_output=True
+        )
+    return result.stdout.decode().split()[0]
+
+DIR = sys.argv[1] if len(sys.argv) > 1 else "."
+
+with open(f"{DIR}/.judge-attestations.json") as f:
+    data = json.load(f)
+
+for eval_round in data.get("evaluations", [data]):
+    attestations = eval_round.get("attestations", [])
+    artifact_hash = eval_round.get("artifact_hash", "")
+    violations = []
+
+    for i, att in enumerate(attestations):
+        # Reconstruct evaluation hash
+        hash_input = f"{att['judge_id']}|{artifact_hash}|{att['score']}|{att.get('rationale_summary', '')}"
+        expected = sha256(hash_input)
+        actual = att["evaluation_hash"].replace("sha256:", "")
+
+        if expected != actual:
+            violations.append(f"Judge {att['judge_id']}: evaluation_hash mismatch")
+
+        # Verify chain link
+        if i == 0:
+            expected_prev = NULL_HASH
+        else:
+            expected_prev = attestations[i-1]["evaluation_hash"].replace("sha256:", "")
+
+        actual_prev = att["previous_attestation_hash"].replace("sha256:", "")
+        if expected_prev != actual_prev:
+            violations.append(f"Judge {att['judge_id']}: chain link broken")
+
+    if not violations:
+        print(f"PASS: All {len(attestations)} judge attestations verified. Isolation confirmed.")
+    else:
+        print(f"FAIL: {len(violations)} violations detected:")
+        for v in violations:
+            print(f"  - {v}")
+
+VERIFY_ATTESTATION
+```
+
+## Section 4: File Format
+
+### .judge-attestations.json Schema
+
+```json
+{
+  "evaluations": [
+    {
+      "evaluation_id": "string — unique ID for this evaluation round",
+      "artifact_path": "string — path to the evaluated artifact",
+      "artifact_hash": "string — sha256:<hex> of the artifact content",
+      "panel_size": "integer — 3 (standard) or 5 (high-stakes)",
+      "started_at": "ISO-8601 — when evaluation round began",
+      "completed_at": "ISO-8601 — when last attestation recorded",
+      "attestations": [
+        {
+          "judge_id": "string — domain-expert|critic|completeness-auditor",
+          "score": "float — 0.0-10.0",
+          "rationale_summary": "string — first 500 chars of rationale",
+          "evaluation_hash": "string — sha256:<hex>",
+          "timestamp": "ISO-8601 — when attestation was recorded",
+          "previous_attestation_hash": "string — sha256:<hex> or null hash"
+        }
+      ],
+      "final_score": "float — weighted average",
+      "weights": {
+        "domain-expert": 0.4,
+        "critic": 0.3,
+        "completeness-auditor": 0.3
+      }
+    }
+  ]
+}
+```
+
+### Example Attestation File
+
+```json
+{
+  "evaluations": [
+    {
+      "evaluation_id": "bto-eval-2026-03-01T12:00:00Z",
+      "artifact_path": ".claude/skills/explore/SKILL.md",
+      "artifact_hash": "sha256:abc123def456789012345678901234567890123456789012345678901234fedc",
+      "panel_size": 3,
+      "started_at": "2026-03-01T12:00:00Z",
+      "completed_at": "2026-03-01T12:01:45Z",
+      "attestations": [
+        {
+          "judge_id": "domain-expert",
+          "score": 8.2,
+          "rationale_summary": "Strong SKILL.md with clear protocol steps. References directory provides good examples...",
+          "evaluation_hash": "sha256:111222333444555666777888999000aaabbbcccdddeeefff000111222333444555",
+          "timestamp": "2026-03-01T12:00:30Z",
+          "previous_attestation_hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+        },
+        {
+          "judge_id": "critic",
+          "score": 7.5,
+          "rationale_summary": "Missing edge case handling for multi-language inputs. Error recovery protocol unclear...",
+          "evaluation_hash": "sha256:222333444555666777888999000aaabbbcccdddeeefff000111222333444555666",
+          "timestamp": "2026-03-01T12:01:00Z",
+          "previous_attestation_hash": "sha256:111222333444555666777888999000aaabbbcccdddeeefff000111222333444555"
+        },
+        {
+          "judge_id": "completeness-auditor",
+          "score": 8.0,
+          "rationale_summary": "All required sections present. References directory has 3 examples. Missing: performance benchmarks...",
+          "evaluation_hash": "sha256:333444555666777888999000aaabbbcccdddeeefff000111222333444555666777",
+          "timestamp": "2026-03-01T12:01:30Z",
+          "previous_attestation_hash": "sha256:222333444555666777888999000aaabbbcccdddeeefff000111222333444555666"
+        }
+      ],
+      "final_score": 7.94,
+      "weights": {
+        "domain-expert": 0.4,
+        "critic": 0.3,
+        "completeness-auditor": 0.3
+      }
+    }
+  ]
+}
+```
+
+## Section 5: Integration with BTO Pipeline
+
+### When to Create Attestations
+
+Attestations are created during **BTO Layer 2 evaluation** (the judge panel stage):
+
+1. **Before panel starts:** Compute `artifact_hash` of the artifact being evaluated
+2. **After each judge completes:** Create attestation record with evaluation_hash
+3. **After all judges complete:** Write `.judge-attestations.json`
+4. **If meta-judge is invoked:** Add a 4th attestation with `judge_id: "meta-judge"`
+
+### Integration Points
+
+| BTO Stage | Attestation Action |
+|-----------|-------------------|
+| Layer 0 (structural) | No attestation needed (deterministic checks) |
+| Layer 1 (semantic) | No attestation needed (single haiku agent) |
+| Layer 2 (judge panel) | Create attestation set with 3 attestations |
+| Meta-judge (escalation) | Append meta-judge attestation to the set |
+| Optimization rounds | Create new attestation set per round's final evaluation |
+
+### Disagreement Detection Enhancement
+
+With attestations, disagreement detection gains cryptographic backing:
+
+```
+If max_score - min_score > 3.0:
+  1. Verify all attestations are valid (no tampering)
+  2. Verify isolation (no judge influenced another)
+  3. If isolation verified: escalate to meta-judge (genuine disagreement)
+  4. If isolation violated: flag conformity collapse warning
+```
+
+## Section 6: Meta-Judge Attestation
+
+When the meta-judge is invoked (disagreement > 3 points), it creates its own attestation:
+
+```json
+{
+  "judge_id": "meta-judge",
+  "score": 7.8,
+  "rationale_summary": "Disagreement between domain-expert (8.5) and critic (5.2) on dimension 'completeness'...",
+  "evaluation_hash": "sha256:...",
+  "timestamp": "2026-03-01T12:02:00Z",
+  "previous_attestation_hash": "sha256:<last judge's eval hash>"
+}
+```
+
+The meta-judge's rationale MAY reference other judges' scores (it has access to them for arbitration). This is expected and does not violate isolation -- the meta-judge is explicitly a synthesizer, not an independent evaluator.

package/templates/lib/witness-chain.md

@@ -0,0 +1,372 @@
+# Witness Chain Protocol
+
+> SHA-256 hash-chain for tamper-evident artifact integrity verification.
+
+## Purpose
+
+This protocol defines how to compute SHA-256 hashes of pipeline artifacts and link them into a chain. Each artifact's hash includes the previous artifact's hash, making the chain tamper-evident: modifying any artifact breaks all downstream hashes.
+
+## Constants
+
+```
+NULL_HASH = "0000000000000000000000000000000000000000000000000000000000000000"
+CHAIN_FILE = ".witness-chain.json"
+HASH_PREFIX = "sha256:"
+```
+
+## Section 1: Hash Computation
+
+### Platform Detection
+
+Detect the available SHA-256 command:
+
+```bash
+# Try sha256sum first (Linux), then shasum (macOS)
+if command -v sha256sum &>/dev/null; then
+  SHA_CMD="sha256sum"
+elif command -v shasum &>/dev/null; then
+  SHA_CMD="shasum -a 256"
+else
+  echo "ERROR: No SHA-256 command found. Install coreutils."
+  exit 1
+fi
+```
+
+### Computing a File Hash
+
+Hash a single file's content:
+
+```bash
+HASH=$(${SHA_CMD} "path/to/file.md" | awk '{print $1}')
+```
+
+### Computing a Chained Hash
+
+Hash file content concatenated with the previous hash to create a chain link:
+
+```bash
+# Read file content and previous hash
+FILE_CONTENT=$(cat "path/to/file.md")
+PREV_HASH="<previous hash value>"
+
+# Compute chained hash
+CHAINED_HASH=$(printf '%s%s' "${FILE_CONTENT}" "${PREV_HASH}" | ${SHA_CMD} | awk '{print $1}')
+```
+
+**Important:** Use `printf '%s%s'` (not `echo`) to avoid trailing newline issues. The content is the raw file bytes followed immediately by the 64-character hex hash string.
+
+### Content Normalization
+
+Before hashing, the content should be the raw file content as stored on disk. Do NOT:
+- Trim whitespace
+- Normalize line endings
+- Strip BOM markers
+
+The hash must match the exact bytes in the file so that verification produces the same result.
+
+## Section 2: Chain Operations
+
+### Operation: Create Genesis Record
+
+Called at Phase 0 (Discovery) to initialize the chain for a new research.
+
+**Preconditions:**
+- Research directory `researches/<slug>/` exists
+- Phase 0 artifact `00_product_discovery.md` has been created
+- No `.witness-chain.json` exists yet
+
+**Procedure:**
+
+```bash
+SLUG="<research-slug>"
+DIR="researches/${SLUG}"
+ARTIFACT="00_product_discovery.md"
+PREV_HASH="${NULL_HASH}"
+
+# Compute genesis hash
+FILE_CONTENT=$(cat "${DIR}/${ARTIFACT}")
+HASH=$(printf '%s%s' "${FILE_CONTENT}" "${PREV_HASH}" | ${SHA_CMD} | awk '{print $1}')
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Create .witness-chain.json
+cat > "${DIR}/.witness-chain.json" << ENDOFCHAIN
+{
+  "research_slug": "${SLUG}",
+  "created_at": "${TIMESTAMP}",
+  "last_updated": "${TIMESTAMP}",
+  "chain": [
+    {
+      "sequence": 0,
+      "phase": "phase-0",
+      "artifact": "${ARTIFACT}",
+      "hash": "${HASH_PREFIX}${HASH}",
+      "previous_hash": "${HASH_PREFIX}${PREV_HASH}",
+      "timestamp": "${TIMESTAMP}",
+      "promise_tag": "DISCOVERY_COMPLETE"
+    }
+  ]
+}
+ENDOFCHAIN
+```
+
+### Operation: Append Record
+
+Called at each subsequent phase checkpoint to add a new record to the chain.
+
+**Preconditions:**
+- `.witness-chain.json` exists in the research directory
+- The new artifact file has been created
+- The previous phase's record exists in the chain
+
+**Procedure:**
+
+1. Read `.witness-chain.json` and extract the last record's hash
+2. Compute the new chained hash: `SHA-256(new_content + last_hash)`
+3. Append the new record to the chain array
+4. Update `last_updated` timestamp
+
+```bash
+SLUG="<research-slug>"
+DIR="researches/${SLUG}"
+ARTIFACT="<artifact-filename>"
+PHASE="<phase-id>"
+PROMISE="<promise-tag>"
+
+# Get the latest hash from the chain
+PREV_HASH=$(cat "${DIR}/.witness-chain.json" | python3 -c "
+import json, sys
+chain = json.load(sys.stdin)
+last = chain['chain'][-1]
+print(last['hash'].replace('sha256:', ''))
+")
+
+# Compute new hash
+FILE_CONTENT=$(cat "${DIR}/${ARTIFACT}")
+HASH=$(printf '%s%s' "${FILE_CONTENT}" "${PREV_HASH}" | ${SHA_CMD} | awk '{print $1}')
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+SEQUENCE=$(cat "${DIR}/.witness-chain.json" | python3 -c "
+import json, sys
+chain = json.load(sys.stdin)
+print(len(chain['chain']))
+")
+
+# Append to chain (using python3 for safe JSON manipulation)
+python3 -c "
+import json, sys
+with open('${DIR}/.witness-chain.json', 'r') as f:
+    chain = json.load(f)
+chain['chain'].append({
+    'sequence': ${SEQUENCE},
+    'phase': '${PHASE}',
+    'artifact': '${ARTIFACT}',
+    'hash': 'sha256:${HASH}',
+    'previous_hash': 'sha256:${PREV_HASH}',
+    'timestamp': '${TIMESTAMP}',
+    'promise_tag': '${PROMISE}'
+})
+chain['last_updated'] = '${TIMESTAMP}'
+with open('${DIR}/.witness-chain.json', 'w') as f:
+    json.dump(chain, f, indent=2)
+"
+```
+
+### Operation: Get Latest Hash
+
+Retrieve the most recent hash from the chain (needed as input for the next append).
+
+```bash
+LATEST_HASH=$(python3 -c "
+import json
+with open('${DIR}/.witness-chain.json') as f:
+    chain = json.load(f)
+print(chain['chain'][-1]['hash'].replace('sha256:', ''))
+")
+```
+
+## Section 3: Verification
+
+### Operation: Verify Chain
+
+Walk the entire chain and verify each hash matches the current file content.
+
+**Algorithm:**
+
+```
+1. Load .witness-chain.json
+2. For each record in chain (index i):
+   a. Read the artifact file
+   b. Get previous_hash:
+      - If i == 0: previous_hash = NULL_HASH
+      - Else: previous_hash = chain[i-1].hash (without prefix)
+   c. Compute expected = SHA-256(file_content + previous_hash)
+   d. Compare expected with record.hash (without prefix)
+   e. If mismatch: record broken link
+3. Produce verification report
+```
+
+**Bash implementation:**
+
+```bash
+DIR="researches/<slug>"
+
+python3 << 'VERIFY_SCRIPT'
+import json, subprocess, sys
+
+NULL_HASH = "0" * 64
+DIR = sys.argv[1] if len(sys.argv) > 1 else "."
+
+def sha256(content):
+    """Compute SHA-256 of a string."""
+    result = subprocess.run(
+        ["sha256sum"],
+        input=content.encode(),
+        capture_output=True
+    )
+    if result.returncode != 0:
+        # Fallback to shasum
+        result = subprocess.run(
+            ["shasum", "-a", "256"],
+            input=content.encode(),
+            capture_output=True
+        )
+    return result.stdout.decode().split()[0]
+
+# Load chain
+with open(f"{DIR}/.witness-chain.json") as f:
+    chain_data = json.load(f)
+
+records = chain_data["chain"]
+broken = []
+verified = 0
+
+for i, record in enumerate(records):
+    artifact_path = f"{DIR}/{record['artifact']}"
+    try:
+        with open(artifact_path) as f:
+            content = f.read()
+    except FileNotFoundError:
+        broken.append({
+            "sequence": i,
+            "artifact": record["artifact"],
+            "reason": "File not found"
+        })
+        continue
+
+    if i == 0:
+        prev_hash = NULL_HASH
+    else:
+        prev_hash = records[i-1]["hash"].replace("sha256:", "")
+
+    expected = sha256(content + prev_hash)
+    actual = record["hash"].replace("sha256:", "")
+
+    if expected == actual:
+        verified += 1
+    else:
+        broken.append({
+            "sequence": i,
+            "artifact": record["artifact"],
+            "expected_hash": f"sha256:{expected}",
+            "actual_hash": record["hash"],
+            "reason": "Hash mismatch - artifact may have been modified"
+        })
+
+# Report
+total = len(records)
+if not broken:
+    print(f"PASS: All {total} records verified successfully")
+else:
+    print(f"FAIL: {len(broken)} broken links out of {total} records")
+    for b in broken:
+        print(f"  - Record {b['sequence']} ({b['artifact']}): {b['reason']}")
+
+VERIFY_SCRIPT
+```
+
+## Section 4: File Format
+
+### .witness-chain.json Schema
+
+```json
+{
+  "research_slug": "string — research directory name",
+  "created_at": "ISO-8601 — when chain was initialized",
+  "last_updated": "ISO-8601 — when last record was added",
+  "chain": [
+    {
+      "sequence": "integer — 0-based position in chain",
+      "phase": "string — phase-0, phase-1, ..., phase-5",
+      "artifact": "string — filename relative to research dir",
+      "hash": "string — sha256:<64 hex chars>",
+      "previous_hash": "string — sha256:<64 hex chars> or sha256:<null hash>",
+      "timestamp": "ISO-8601 — when record was created",
+      "promise_tag": "string — semantic completion promise"
+    }
+  ]
+}
+```
+
+### Standard Phase-to-Artifact Mapping
+
+| Phase | Artifact | Promise Tag |
+|-------|----------|-------------|
+| phase-0 | 00_product_discovery.md | DISCOVERY_COMPLETE |
+| phase-1 | 01_case_brief.md | CASE_EXPLORED |
+| phase-2 | 02_research_findings.md | RESEARCH_PARANOID_PASSED |
+| phase-2.5 | 02.5_trend_brief.md | CJM_VALIDATED |
+| phase-3 | 03_solution_strategy.md | SOLUTION_DESIGNED |
+| phase-4 | 04_architecture.md | ARCHITECTURE_DEFINED |
+| phase-5 | 05_presentation_content.md | PRESENTATION_READY |
+
+### Example Complete Chain
+
+```json
+{
+  "research_slug": "bank_kc_automation",
+  "created_at": "2026-03-01T10:00:00Z",
+  "last_updated": "2026-03-01T14:30:00Z",
+  "chain": [
+    {
+      "sequence": 0,
+      "phase": "phase-0",
+      "artifact": "00_product_discovery.md",
+      "hash": "sha256:a1b2c3d4e5f6789012345678901234567890123456789012345678901234abcd",
+      "previous_hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+      "timestamp": "2026-03-01T10:00:00Z",
+      "promise_tag": "DISCOVERY_COMPLETE"
+    },
+    {
+      "sequence": 1,
+      "phase": "phase-1",
+      "artifact": "01_case_brief.md",
+      "hash": "sha256:b2c3d4e5f67890123456789012345678901234567890123456789012345bef01",
+      "previous_hash": "sha256:a1b2c3d4e5f6789012345678901234567890123456789012345678901234abcd",
+      "timestamp": "2026-03-01T10:30:00Z",
+      "promise_tag": "CASE_EXPLORED"
+    }
+  ]
+}
+```
+
+## Section 5: Chain Repair
+
+If an artifact is legitimately modified (e.g., user requested changes during checkpoint review), the chain must be repaired:
+
+1. Re-hash the modified artifact using the previous record's hash
+2. Update the modified record's hash in `.witness-chain.json`
+3. Re-hash ALL subsequent records (cascade update)
+4. Update `last_updated` timestamp
+
+This is expected and normal. The witness chain protects against *undetected* modifications, not against all modifications.
+
+## Section 6: Platform Compatibility
+
+| Platform | Command | Notes |
+|----------|---------|-------|
+| Linux (Ubuntu, Debian, etc.) | `sha256sum` | Available by default in coreutils |
+| macOS | `shasum -a 256` | Available by default |
+| Windows (WSL) | `sha256sum` | Available in WSL |
+| Windows (Git Bash) | `sha256sum` | Available in Git for Windows |
+| Alpine Linux | `sha256sum` | Available in coreutils |
+
+The protocol should attempt `sha256sum` first, then fall back to `shasum -a 256`.