docs(adr): define revision-bound host-owned writing diagnostics

[seonghobae]

ADR decision summary

Inkspan will provide a generic, provider-neutral writing-diagnostic presentation and application contract. Host applications own every semantic judgment and model call; Inkspan owns revision/selector validation, decorations, accessible navigation, explicit Apply/Ignore/Dismiss/Explain actions, stale-result rejection, and ordinary editor transactions.

Semantic keyword matching is prohibited. Inkspan may use deterministic code for schema, resource, Unicode, grapheme, revision, selector, overlap, and safety validation, but it must not infer grammar, tone, pragmatics, clarity, spelling, or technical quality from keywords, regexes, phrase lists, sender domains, language names, recipient counts, nearest-text search, word positions, or opaque category strings. When the host model path is unavailable, Inkspan shows no fabricated fallback judgment.

Current authority and contradiction repair

The previous head used ADR 0027/0028, colliding with earlier open PR #141, which is the earliest open ADR 0027 claimant. Exact-head review on predecessor b79d54969c295fbfd4d957c6172af2c7d4c1b132 requested that this lane yield 0027 and give the pair unique sequential identifiers.

Current exact head 9c26b0fae9cf7363fadd16c72efc6b0278e667db resolves that repository-owned contradiction without weakening the ADR quality gate:

• host-owned, revision-bound writing diagnostics is now ADR 0028 at docs/adr/0028-host-owned-llm-writing-diagnostics.md;
• strict v1 invalidation and semantic-neutral accessibility is now ADR 0029 at docs/adr/0029-writing-diagnostics-v1-strict-invalidation.md;
• the obsolete colliding 0027/0028 filenames are removed from this branch;
• ADR index, documentation-contract test, implementation plan, errata, and design references are synchronized to 0028/0029.

This keeps PR #141 as ADR 0027 authority and leaves the next unclaimed sequential identifier available to later lanes. The current source mutation is documentation/contract authority repair; it does not introduce runtime diagnostic behavior.

Corrected v1 architecture

ADR 0029 resolves two lower-level contradictions in the original design direction:

1. every local or collaborative docChanged transaction invalidates the complete diagnostic generation; no mapping/remapping/nearest-text/quote/keyword repair preserves a diagnostic; and
2. Inkspan derives no semantic ARIA state from opaque categoryCode or other host text. Decorations contain static Inkspan classes, priority styling, and opaque IDs; the named panel carries the semantic information as plain text/native controls.

The implementation plan and machine-readable documentation contract now reference ADR 0028/0029 consistently. Task 10 still requires temporary errata to be folded into the complete canonical document graph before the feature stack can become Ready.

First-release boundaries

• plain-text replacements only;
• every local or collaborative document change invalidates all active diagnostics;
• no stale selector repair, nearest-text lookup, semantic remapping, or category-derived semantic accessibility state;
• one shared contract/controller/extension for standalone and collaborative editors;
• revision-scoped W3C selector verification before display and again before mutation;
• accessible built-in navigation and explicit Apply/Ignore/Dismiss/Explain actions;
• React-free writing-diagnostics package subpath;
• exact 100% production statement/branch/function/line coverage and complete public API documentation;
• packed ESM/CommonJS/types/CSS, SSR, cross-engine, hostile-input, collaboration, security, supply-chain, and rollback evidence; and
• a separate release-only PR before a host may consume the feature.

Cross-repository boundary

The first planned host is ContextualWisdomLab/naruon; Naruon owns email/thread/recipient context and contextual-orchestrator calls. ContextualWisdomLab/fast-mlsirm may support criterion-level judge calibration and validation. None of those product semantics or dependencies enter Inkspan's deterministic runtime package.

A host may integrate only an immutable released Inkspan artifact whose version, tarball integrity, source commit, package manifest, browser evidence, and rollback contract are recorded. Mutable branches, source archives, copied forks, and local paths are not production dependencies.

Scope and current truth

This remains a design-and-implementation-plan Draft PR. It introduces no runtime API or shipped behavior, changes no package version, and makes no model-accuracy or language-coverage claim.

• current exact head: 9c26b0fae9cf7363fadd16c72efc6b0278e667db;
• independently resolved live protected truth: main@e8109ec2a17de8bd6594487aa12c8c8a93cb2c03;
• GitHub reports this PR Draft and mergeable;
• predecessor-head CI/Security/SAST/reviews do not transfer to this source-changing head;
• the predecessor Cursor CHANGES_REQUESTED ADR-numbering finding has been addressed in source, but the historical formal review remains non-approval until re-evaluated on this exact head;
• fresh exact-head required checks/reviews and qualifying independent approval remain required before any Ready/merge decision.

Issue #118 still owns the protected v0.6.0 release source and registry operational-acceptance boundary. Keep this PR Draft and unmerged while that freeze and current governance gates remain unresolved.

Review focus

1. ADR 0027 ownership remains with earlier PR feat(office): add bounded DOCX page layout contract #141; this lane is uniquely 0028/0029;
2. host/editor/model authority boundary;
3. prohibition of semantic keyword fallback and category-derived semantic ARIA;
4. strict v1 invalidation across local and collaborative changes;
5. revision and W3C selector lifecycle;
6. accessibility and privacy-minimized callbacks; and
7. additive package compatibility, release sequencing, and rollback.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ad4a4585-05bd-46f6-8bdf-742710b9ef30

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}

[seonghobae]

Exact-current-head read-only review request for e580aec1961673b49f98e2a62debfb6ce4e48df6 against current protected base main@a430b1c153702de3b6439def801732d7453b4940.

Direct exact-head gates are complete: CI 31589641563, Security Scan 31589641505, and SAST Semgrep 31589641541 succeeded; unresolved inline threads are currently zero. Review ADR 0027/0028, the design, implementation plan, and v1 errata for contradictory lifecycle, semantic-authority, accessibility, privacy, packaging, rollback, or stack instructions. In particular, verify strict invalidation after every local/remote docChanged transaction and the prohibition on deriving semantic ARIA or behavior from opaque host strings.

@coderabbitai review
@opencode-agent review
@cwl-noema-review review
@strix review

Review only. Do not mutate branches, dispatch repair writers, reuse predecessor/stale/synthetic evidence, or synthesize author approval. Bind any verdict and actionable finding to this exact unchanged head.

[coderabbitai]

Rate Limit Exceeded

@seonghobae have exceeded the limit for the number of chat messages per hour. Please wait 5 minutes and 45 seconds before sending another message.

[cursor]

Review (head b79d549)

The revision-bound, host-owned writing-diagnostics contract is the right authority split: Inkspan validates untrusted proposals; the host owns model policy and transport. Keep this Draft while #118 owns v0.6.0.

Blocking

ADR 0027 collides with earlier open #141 (bounded DOCX page layout). This stack also occupies 0028. Later #320 and #360 reused 0027 again.

Next action: yield 0027 to #141, refetch the open ADR queue, and give this pair unique sequential numbers. Propagate the same identifiers through #249/#285. Do not merge any diagnostics slice until the numbers are unique.

  

_{Sent by Cursor Automation: Fix Issues}