docs(triage-bot): as-built reference + shared architecture proposal (PP-4858) - #1355
docs(triage-bot): as-built reference + shared architecture proposal (PP-4858)#1355mauricecarrier7 wants to merge 3 commits into
Conversation
🏗️ CodeAtlas Ledger Analysis✅ All Checks Passed♿ Accessibility (via AccessLint)
✅ No accessibility issues detected 🏛️ Architecture Analysis
🔄 Dependency CyclesSee full report for cycle details. 📋 Architecture FindingsSee full report for detailed findings. 🔍 Reachability Analysis
ℹ️ No architecture-relevant files in this diff — reachability not evaluated. 📊 0 files analyzed | 📦 Download Full Report Powered by CodeAtlas Ledger |
🧪 Unit Test Results📊 View Full Interactive Report ❌ 3 TESTS FAILED8187 tests | 8043 passed | 3 failed | 139 skipped | ⏱️ 15m 7s | 📊 98.2% | 📈 45.1% coverage All 942 classes — 3 with failures (full matrix)
📊 Full interactive matrix: report ❌ Failed testsNames only — open the interactive report above for messages + stack frames. 📊 Testing Coverage BreakdownUnit Test Line Coverage (testable surfaces): 45.1% Total coverage incl. UI/lifecycle: 44.1% (17 files excluded from testable denominator — see
📈 What changed vs. baseTest count: +8
|
| Artifact | Description |
|---|---|
| test-report | 📄 Markdown + HTML reports |
| test-data | 📊 JSON data for tooling |
| test-results | 🔍 Full xcresult (open in Xcode) |
…PP-4858) Two documents for the PP-4858 spike. triage-bot-v1-as-built.md describes the bot as it works today, written as the behavioral contract another platform reproduces: the classifier's normalization, scoring and guards, the 15 redaction patterns with their order and replacement tokens, the corpus schema, and the escalation state machine. Platform-specific detail is labeled so nobody ports it by mistake. triage-bot-shared-architecture-proposal.md designs the server and Android halves. It opens with a decision memo naming what is being asked for, what is deliberately not being approved yet, and the risks that still need an accepter. Also corrects the package README, which claimed 26 tests and named the clipboard as the ticket transport, and adds a pointer from CLAUDE.md so anyone changing the package reads the contract first. **Scope:** documentation only, plus a README correction and a CLAUDE.md pointer. No production code in this commit. **Not done:** the docs describe several gaps rather than fixing them, most notably that the clipboard transport does not honor the patron's field omissions. Those are tracked under PP-4882. **Deferred:** cross-platform conformance fixtures are specified but not built; they are a Phase 2 deliverable and the Android estimate depends on them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The proposal carried a named escalation about unredacted logs in the shipped Android app, addressed to the android-core maintainer, with the affected fields and log level enumerated. Raising it was right; the venue was not. A shared architecture proposal that circulates to leadership is the wrong place for a maintainer to first encounter a finding about their own codebase, and an iOS-side document enumerating another team's credential handling reads as an audit published over their head rather than a colleague's note. The specifics belong in a direct conversation with the owner, who then has the chance to assess, confirm, or say it is already handled. What the document needs is the planning fact, which is unchanged and still stated: the existing Android report path attaches unredacted logs, the bot would use that path, so redaction is a prerequisite workstream for the Android client and is plausibly larger than the bot module itself. **Scope:** removes the escalation section and its contents entry, restates section 8.4 without the field-level detail, and neutralizes the supporting footnote. No change to any recommendation, decision, or estimate. **Not done:** the finding itself is unaffected and still needs an owner on the Android side. That conversation happens directly, not through this document. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Final editing pass before review. No facts, recommendations, numbers, or citations changed. Roles replace people throughout. The cover memo's accountable owner is now the iOS dev rather than a named individual, and every "maintainer" is now the Android dev or a phrase about the work itself. Where a sentence needed a role word to carry meaning, it was rephrased around the work: "the maintainer's to assess" became "this sits with the Android dev". Factual properties of a codebase kept the fact and dropped the title, so "single-maintainer repo" reads "single-contributor repo" and states the commit distribution instead. Documents that circulate should describe roles and work, not individuals. Voice moves from argued to documented. Removed rhetorical closers, moral framing about discipline, bold used for emphasis rather than scanning, empty intensifiers, and phrasing that praised the analysis. Reasons are stated once, factually, instead of built toward. Kept deliberately: the UNVERIFIED markers, the retractions, the "both numbers are proposals, not findings" note, and the steelmanned counter to the engine recommendation. Those read as hedging only if you mistake accuracy for timidity; three reviewers named them the documents' most useful property. One real gap closed in the recommendation path: the cover memo asked approval for the first two delivery phases without mentioning that the iOS launch gate precedes them, so a reader tracing "what happens first" hit a contradiction between the memo and the plan. Fixed with a pointer rather than more text. **Scope:** voice, role language, and one cross-reference. Both documents got shorter. **Not done:** the style is now recorded outside this repo so it applies by default to future documentation; nothing in this commit enforces it here. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
498186d to
492d330
Compare
Output of the PP-4858 spike, plus two small changes it surfaced.
Draft because these are for reading and comment first. Review inline, on the sentence.
The two documents
docs/architecture/triage-bot-v1-as-built.mddescribes the triage bot as it works today, written as the behavioral contract another platform reproduces: normalization, scoring and the four suggest guards, the redaction rules and their order, the corpus schema, and the escalation state machine. Platform-specific detail is labeled so nobody ports it by mistake.docs/architecture/triage-bot-shared-architecture-proposal.mddesigns the server and Android halves. It opens with a decision memo naming what is being asked for, what is deliberately not being approved yet, and three risks that still need someone's name against them.If you have fifteen minutes and a decision to make: read the cover memo, then the delivery plan and organizational dependencies. Everything else is reference.
Recommendation
A hybrid. The corpus ships as a versioned CDN artifact rather than a new service, because the org already distributes versioned content that way in two places. Ticket submission becomes a per-library endpoint on the existing Circulation Manager. The AI key proxy stays a hard prerequisite for the AI fallback but is sequenced last, since it is the only piece that may need new infrastructure. Classification and redaction stay on the phones. Android gets a small hand-written Kotlin module kept in step by shared test fixtures rather than shared code.
Three findings worth reading even if nothing else is
Also in this PR
scripts/triage-corpus-check.shdescribed itself as a release gate but had no caller anywhere. Its--self-test, which proves the guard goes red when redaction is disabled, was therefore never running. Wired into CI andverify-pr.sh.How it was checked
Four grounded passes over
android-core,circulation,library-registryand the analytics tooling. Three independent reviews from backend, Android and iOS perspectives. A source audit of every factual claim. And one experiment: the matching engine was rebuilt in Python from the document alone, without reading the Swift, then run against the real conformance corpora. It matched 85 of 85. The claim that another platform can build from this document is demonstrated rather than asserted.Verification
Related: PP-4882 and sub-tasks PP-4883 to PP-4886 cover the gaps that need closing before the bot's flag is turned on for patrons. The bot ships in 3.3.0 with its master switch off, so nothing is patron-facing yet.
🤖 Generated with Claude Code