docs(adr): design Inkspan-based LLM email writing guidance

[seonghobae]

Scope

Documentation/design root for Inkspan-backed contextual email-writing guidance. This PR adds no runtime dependency, database migration, editor package, provider route, diagnostic, send behavior, or release identity.

Naruon owns authorized email/thread/recipient/project context, review contracts/API, prompt/rubric/policy consumption, privacy-minimized evidence/feedback, and mail workflow. contextual-orchestrator owns provider-neutral routing/test-time compute; fast-mlsirm owns criterion-level Judge/measurement contracts; Inkspan owns revision-bound editor/diagnostic behavior. Candidate Reviewer and Judge remain separate roles/calls. Semantic judgments must fail closed or abstain when the released owner capability is unavailable; lexical/keyword/regex heuristics are not semantic fallbacks.

Current exact authority

• protected base: develop@042b0c70531b229af3acbd0421a2f23098d848b3
• exact head: 9f1836d09e6b4db97855d701d8220268e9fb4d87
• lifecycle: Draft / mechanically mergeable / central review evidence incomplete
• effective delta: five documentation/design files

The active task-owned lineage remains #1322 → #1327 → #1328 → #1329 → #1356 → #1375 → #1524 → #1530 → #1535 → #1536. Descendants are preparatory and do not authorize skipping immutable dependency order; any parent movement requires ordinary non-destructive restack and fresh exact-head evidence.

Immutable owner boundary

The latest evidence recorded by this design root is still insufficient for runtime adoption:

• fast-mlsirm v0.9.1 exposes the intended Judge surface but its GitHub release does not itself establish the approved immutable distributable/provenance path required by Naruon; consumer admission remains gated through [Dependency] verify and hash-lock immutable fast-mlsirm Judge artifact for Task 7 #1385 / owner publication work.
• Inkspan v0.3.1 does not expose the required writing-diagnostics public package surface; mutable writing-diagnostics branches are not consumer contracts.
• mutable branches, Git URLs, source copies, local stubs, workspace paths, and direct-provider fallback are prohibited.

Candidate confidence is never Judge evidence. A publishable policy must preregister thresholds and holdout/protocol hashes before label access and produce calibration, Brier, test-retest, DIF, temporal-drift, and Candidate→Judge→adjudicator evidence. Guidance remains advisory, revision-bound, purpose-authorized, and must not leak raw mail/draft/model/Judge content to ordinary logs or telemetry.

Current delivery boundary

Repository-local checks previously observed on this unchanged head are not sufficient by themselves. The live PR state still lacks complete central merge authority: required OpenCode/review-gate evidence remains incomplete and there is no qualifying current-head independent approval. The PR was therefore returned to Draft rather than leaving a mechanically mergeable design root marked Ready.

Merge only after this unchanged head satisfies every then-live repository/organization required check, all valid findings/threads are resolved, and the qualifying independent post-last-push approval required by live governance exists. Queued, in-progress, failed, skipped-required, absent, stale, predecessor, synthetic, model-only, status-only, or author-only evidence is non-passing. No force-push, destructive rebase, self-approval, bypass, or gate weakening.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR updates ADR governance and documents a proposed Inkspan-based LLM email guidance workflow. It adds design, implementation, calibration, security, verification, release, rollback, and documentation requirements. It does not add product implementation.

Changes

Email writing guidance

Layer / File(s)	Summary
Governance and architecture docs/adr/*, docs/superpowers/plans/..., docs/superpowers/specs/...	Defines ADR status rules, workflow scope, component boundaries, immutable dependencies, semantic judgment, and deterministic validation responsibilities.
Review contracts and orchestration docs/adr/0005-..., docs/superpowers/plans/..., docs/superpowers/specs/...	Specifies authorized context retrieval, strict model contracts, candidate generation, independent judging, policy admission, and authenticated review APIs.
Editor integration and safety controls docs/adr/0005-..., docs/superpowers/plans/..., docs/superpowers/specs/...	Defines Inkspan editing, revision-safe controls, privacy-minimized evidence, feedback, accessibility, security, degraded operation, and rollback behavior.
Calibration and verification docs/doctoring/..., docs/superpowers/plans/..., docs/superpowers/specs/...	Documents immutable fast-mlsirm release evidence, fixed evaluation splits, minimum slice sizes, locked-holdout controls, benchmark requirements, and verification coverage.
Release and documentation controls docs/adr/0005-..., docs/superpowers/plans/..., docs/superpowers/specs/...	Defines documentation reconciliation, exact-head acceptance, staged release, immutable artifacts, monitoring, rollback, traceability, and product-claim limits.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: 🟡 Moderate · up to ec0e1

The PR is documentation-only, but it currently defines conflicting criterion identifiers and incomplete publication-policy fields, including evaluation states, publish decisions, and required calibration metadata. Implementing the design as written could make guidance admission and publication behave inconsistently across components, so the design is not merge-ready until these contracts are aligned.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the documentation change and the main subject: Inkspan-based LLM email-writing guidance. It is concise and related to the primary purpose of the pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/inkspan-email-writing-guide

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

PR governance metadata gate update for 9f1836d09e6b4db97855d701d8220268e9fb4d87: no current blocking failures remain.

PR governance metadata gate is waiting on current-head requirements; see the latest check for pending reasons.

[seonghobae]

@coderabbitai review

Please review exact head 0dd28a3d4df5faa3c9007ec33785f73a16ded835, focusing on the semantic-authority boundary, cross-repository dependency and release contracts, privacy controls, measurement validity, and rollback/acceptance criteria.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '== HEAD =='
git rev-parse HEAD
git status --short
printf '%s\n' '== DIFF SUMMARY VS DEVELOP =='
git diff --stat develop...HEAD
git diff --name-status develop...HEAD
printf '%s\n' '== DOCUMENT FILES =='
fd -t f . docs | sort
printf '%s\n' '== CHANGED DOCUMENT HEADINGS =='
git diff --name-only develop...HEAD | while IFS= read -r f; do
  case "$f" in
    *.md)
      printf '\n--- %s ---\n' "$f"
      rg -n '^(#|##|###) ' "$f" || true
      ;;
  esac
done
printf '%s\n' '== FOCUSED TERMS IN CHANGED DOCS =='
git diff --name-only develop...HEAD | while IFS= read -r f; do
  case "$f" in
    *.md)
      printf '\n--- %s ---\n' "$f"
      rg -n -i -C 2 'keyword|regex|fallback|candidate|judge|adjudicat|calibrat|evaluation_only|PII|privacy|retention|Inkspan|release|lockfile|verif|rollback|acceptance|stale|selector|send gate|undo|DIF|drift|reliability' "$f" || true
      ;;
  esac
done
printf '%s\n' '== PR METADATA =='
gh pr view 1322 --repo ContextualWisdomLab/naruon --json number,title,headRefOid,baseRefName,files,url --jq '{number,title,headRefOid,baseRefName,url,files:[.files[].path]}'

Length of output: 232437

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '== ADR: WORKFLOW, PRIVACY, ACCEPTANCE, ROLLBACK =='
sed -n '21,197p' docs/adr/0001-inkspan-backed-llm-email-writing-guidance.md

printf '%s\n' '== DESIGN: API, ADMISSION, MEASUREMENT, PRIVACY, RELEASE =='
sed -n '112,180p' docs/superpowers/specs/2026-08-12-inkspan-llm-email-writing-guidance-design.md
sed -n '223,371p' docs/superpowers/specs/2026-08-12-inkspan-llm-email-writing-guidance-design.md
sed -n '373,558p' docs/superpowers/specs/2026-08-12-inkspan-llm-email-writing-guidance-design.md

printf '%s\n' '== PLAN: DEPENDENCY, PRIVACY, POLICY, ACCEPTANCE, RELEASE =='
sed -n '39,160p' docs/superpowers/plans/2026-08-12-llm-email-writing-guidance-implementation.md
sed -n '275,395p' docs/superpowers/plans/2026-08-12-llm-email-writing-guidance-implementation.md
sed -n '546,705p' docs/superpowers/plans/2026-08-12-llm-email-writing-guidance-implementation.md

printf '%s\n' '== CROSS-DOCUMENT TERM CONSISTENCY =='
for term in \
  'evaluation_only' \
  'approved policy' \
  'immutable released' \
  'rollback' \
  'no raw' \
  'send gate' \
  'candidate reviewer' \
  'independent judge' \
  'adjudicat'; do
  printf '\n-- %s --\n' "$term"
  rg -n -i --glob '*.md' "$term" \
    docs/adr/0001-inkspan-backed-llm-email-writing-guidance.md \
    docs/doctoring/llm-email-writing-guidance-and-fast-mlsirm-judge.md \
    docs/superpowers/specs/2026-08-12-inkspan-llm-email-writing-guidance-design.md \
    docs/superpowers/plans/2026-08-12-llm-email-writing-guidance-implementation.md \
    || true
done

printf '%s\n' '== COMPANION PR METADATA =='
gh pr view 248 --repo ContextualWisdomLab/inkspan \
  --json number,state,title,headRefOid,baseRefName,mergedAt,url \
  --jq '{number,state,title,headRefOid,baseRefName,mergedAt,url}' || true

printf '%s\n' '== FAST-MLSIRM PR METADATA =='
gh pr view 733 --repo ContextualWisdomLab/fast-mlsirm \
  --json number,state,title,headRefOid,baseRefName,mergedAt,url \
  --jq '{number,state,title,headRefOid,baseRefName,mergedAt,url}' || true

Length of output: 76893

---

@seonghobae I reviewed exact head 0dd28a3d4df5faa3c9007ec33785f73a16ded835.

I found one measurement-validity issue.

• docs/superpowers/plans/2026-08-12-llm-email-writing-guidance-implementation.md, Lines 569-575: Task 14 requires measured outputs to generate the first approved policy. It does not require pre-specified publication thresholds or a locked final holdout set. The same benchmark can therefore drive policy selection and serve as the acceptance evidence. This permits post-hoc threshold selection and benchmark overfitting. Define the publication thresholds, evaluation protocol, and data split before final evaluation. Use a locked human-labeled holdout set only for the final publish/no-publish decision. Record the protocol and holdout hash in the policy artifact.

The reviewed documents otherwise define the requested boundaries clearly:

• Semantic judgments have no keyword, regex, phrase-list, positional, or nearest-text fallback.
• Candidate reviewer, independent Judge, optional adjudicator, policy admission, and deterministic integrity validation have separate roles.
• Runtime consumes a published policy. Calibration, IRT fitting, DIF, and drift analysis remain offline or nearline.
• Naruon requires immutable released Inkspan and fast-mlsirm artifacts. ContextualWisdomLab/inkspan#248 remains open, so the release gate is necessary.
• Privacy controls preserve context required for valid interpretation while prohibiting raw-content telemetry and ordinary logging.
• Review failure, stale revisions, invalid selectors, and policy failure preserve editing and sending.
• Rollback preserves Inkspan authoring and the existing send path.

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[seonghobae]

@coderabbitai review

Please review the unchanged exact current head bfc2df112136bb9fe358778d701e78bf9e78b685 (normal merge of live develop@dd8d1519). Predecessor b4953c15 evidence does not transfer. Email-writing decision is now ADR-0005 so accepted calendar ADR-0004 from #1367 stays unique. Local ADR validation: 5 unique identifiers, 5 indexed links, 11 required sections, 0 conflict markers. Independent non-author APPROVE is still required; this comment is not an approval.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

expected_head='bfc2df112136bb9fe358778d701e78bf9e78b685'
base='dd8d1519'

printf '%s\n' '== EXACT HEAD AND MERGE =='
git rev-parse HEAD
git show -s --format='commit=%H%nparents=%P%nsubject=%s' HEAD
git status --short
git merge-base --is-ancestor "$base" HEAD && echo "base_is_ancestor=yes" || echo "base_is_ancestor=no"
if [ "$(git rev-parse HEAD)" != "$expected_head" ]; then
  echo "ERROR: checked-out HEAD does not match requested exact head" >&2
  exit 1
fi

printf '%s\n' '== DIFF AGAINST LIVE DEVELOP COMMIT =='
git diff --stat "$base...HEAD"
git diff --name-status "$base...HEAD"

printf '%s\n' '== CHANGED MARKDOWN HEADINGS =='
git diff --name-only "$base...HEAD" | while IFS= read -r f; do
  case "$f" in
    *.md)
      printf '\n--- %s ---\n' "$f"
      rg -n '^(#{1,4}) ' "$f" || true
      ;;
  esac
done

printf '%s\n' '== ADR INDEX AND IDENTIFIER CHECK =='
if [ -f docs/adr/README.md ]; then
  sed -n '1,240p' docs/adr/README.md
fi
fd -t f -e md . docs/adr | sort | while IFS= read -r f; do
  printf '\n--- %s ---\n' "$f"
  sed -n '1,45p' "$f"
done

printf '%s\n' '== FOCUSED CONTRACTS IN REVIEW DOCUMENTS =='
for f in \
  docs/adr/0005-inkspan-backed-llm-email-writing-guidance.md \
  docs/superpowers/specs/2026-08-12-inkspan-llm-email-writing-guidance-design.md \
  docs/superpowers/plans/2026-08-12-llm-email-writing-guidance-implementation.md \
  docs/doctoring/llm-email-writing-guidance-and-fast-mlsirm-judge.md
do
  if [ -f "$f" ]; then
    printf '\n--- %s ---\n' "$f"
    rg -n -i -C 3 \
      'keyword|regex|fallback|candidate|independent judge|adjudicat|policy artifact|calibrat|threshold|holdout|data split|evaluation protocol|publish|PII|privacy|retention|raw.content|telemetry|immutable|release|lockfile|rollback|acceptance|stale|selector|send' \
      "$f" || true
  else
    echo "MISSING: $f"
  fi
done

printf '%s\n' '== POLICY AND EVALUATION CONTEXT FROM IMPLEMENTATION PLAN =='
plan='docs/superpowers/plans/2026-08-12-llm-email-writing-guidance-implementation.md'
if [ -f "$plan" ]; then
  rg -n '^(##|###) ' "$plan"
  sed -n '530,680p' "$plan"
fi

printf '%s\n' '== PR METADATA =='
gh pr view 1322 --repo ContextualWisdomLab/naruon \
  --json number,headRefOid,baseRefName,state,mergeable,reviewDecision,url \
  --jq '{number,headRefOid,baseRefName,state,mergeable,reviewDecision,url}'

Length of output: 124240

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '== ADR IDENTIFIERS AND INDEX LINKS =='
printf 'ADR headers: '
rg -n '^# ADR-[0-9]{4}:' docs/adr --glob '*.md' | wc -l
printf 'Unique ADR header identifiers: '
rg '^# ADR-[0-9]{4}:' docs/adr --glob '*.md' \
  | sed -E 's/^# (ADR-[0-9]{4}):.*/\1/' | sort -u | wc -l
printf 'Indexed ADR markdown links: '
rg -o '\[ADR-[0-9]{4}\]\([^)]*\.md\)' docs/adr/README.md | wc -l
printf 'Conflict markers in changed docs: '
git diff --name-only dd8d1519...HEAD | while IFS= read -r f; do
  case "$f" in *.md) printf '%s\0' "$f" ;; esac
done | xargs -0 -r rg -n '^(<<<<<<<|=======|>>>>>>>)' || true

printf '%s\n' '== REQUIRED ADR-0005 SECTIONS =='
for heading in \
  'Context' \
  'Alternatives considered' \
  'Decision' \
  'Consequences' \
  'Failure and recovery' \
  'Security and privacy impact' \
  'Accessibility' \
  'Compatibility and migration' \
  'Verification and acceptance evidence' \
  'Research and standards traceability' \
  'Rollback or supersession'
do
  if rg -qx "## ${heading}" docs/adr/0005-inkspan-backed-llm-email-writing-guidance.md; then
    printf 'present: %s\n' "$heading"
  else
    printf 'MISSING: %s\n' "$heading"
  fi
done

printf '%s\n' '== ALL MEASUREMENT-PUBLICATION REFERENCES =='
rg -n -i -C 2 \
  'pre.?specif|pre.?register|threshold|holdout|data split|evaluation protocol|publication job|policy artifact|dataset.*hash|hash.*dataset' \
  docs/adr/0005-inkspan-backed-llm-email-writing-guidance.md \
  docs/superpowers/specs/2026-08-12-inkspan-llm-email-writing-guidance-design.md \
  docs/superpowers/plans/2026-08-12-llm-email-writing-guidance-implementation.md \
  docs/doctoring/llm-email-writing-guidance-and-fast-mlsirm-judge.md

printf '%s\n' '== TASK 14 WITH LINE NUMBERS =='
nl -ba docs/superpowers/plans/2026-08-12-llm-email-writing-guidance-implementation.md | sed -n '546,578p'

Length of output: 16518

---

@seonghobae I reviewed exact head bfc2df112136bb9fe358778d701e78bf9e78b685.

I found one issue.

• docs/superpowers/plans/2026-08-12-llm-email-writing-guidance-implementation.md, Line 574: Task 14 requires the publication job to fail when thresholds are missed. It does not require thresholds, the evaluation protocol, or data splits to be fixed before final evaluation. It also does not reserve a locked human-labeled holdout set for the publish/no-publish decision. The policy artifact requires dataset/provenance hashes, but not the final holdout hash. The same benchmark can therefore select thresholds and justify publication. This permits post-hoc threshold selection and benchmark overfitting. Define the publication thresholds, evaluation protocol, and train/calibration/final-holdout split before evaluation. Use the locked holdout only for the final policy-publication decision. Record the protocol version and holdout hash in the approved policy artifact.

The requested ADR checks are consistent at this head:

• There are five unique ADR identifiers and five indexed ADR links.
• ADR-0005 contains all eleven required sections.
• ADR-0004 remains the accepted calendar ADR.
• ADR-0005 remains the proposed email-writing ADR.
• No conflict markers were detected in the changed Markdown files.

The documents also retain the required semantic-authority boundary, immutable dependency gates, privacy controls, fail-closed review behavior, and rollback that preserves Inkspan authoring and the existing send path.

This review does not provide the required qualifying non-author approval.

_{You are interacting with an AI system.}

Stale review: all review-thread comments on this PR are resolved and the reviewer's cited commit predates the current head, which passes all non-metadata-gate required checks (verified via gh pr checks and the reviewThreads GraphQL query — 0 unresolved threads). Dismissing as superseded per AGENTS.md stale-review guidance.

[seonghobae]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[devin-ai-integration]

Devin Review found 3 new potential issues.

All findings in this predecessor-head CHANGES_REQUESTED review were verified against the descendant current head and addressed; the associated review threads are resolved. Dismissing only as obsolete predecessor-head review state after head movement, not as approval or passing evidence.

[seonghobae]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.