diff --git a/docs/tally/BACKLOG.md b/docs/tally/BACKLOG.md new file mode 100644 index 0000000..f7c7a31 --- /dev/null +++ b/docs/tally/BACKLOG.md @@ -0,0 +1,40 @@ +# Tally roadmap backlog (parked scope) + +Scope that any prompt, reviewer, or contributor proposes beyond the +current phase lands here — never in the current PR (see +[PROMPT_PLAYBOOK.md](./PROMPT_PLAYBOOK.md) §7.1 standing rules). Items +graduate only through a plan amendment (§7.4 deviation prompt) or when +their gating condition in [IMPROVEMENT_PLAN_2026H2.md](./IMPROVEMENT_PLAN_2026H2.md) +is met. + +## Parked by ruling (do not build this horizon) + +| Item | Why parked | Revisit condition | +| --- | --- | --- | +| GSTR-2B bulk-resolution layer | Tally native owns single-company recon; solo dev can't fight the platform now | Write substrate has run one clean quarter AND a design partner asks | +| Remote agent on client machines | Fleet product a solo dev cannot operate; reputational risk lands on the firm | Cloud relay + support capacity exist | +| Client-maintained-books drift via backup/TCP ingestion | Lighter alternative to the remote agent; still post-wedge | Drift Sentinel v1 adopted at 2+ firms | +| Tally-on-cloud (hosted RDP) topology — headless agent in VM | v1 is local single-machine only; declared `Unsupported` in Passport | A design partner runs hosted Tally; local topology at GA | +| Bank-statement PDF/OCR parsing | Format-zoo maintenance tail; CSV/Excel covers most rows | Thin product loop in daily use | +| GSTR-1 prep/validation engine | GST-rules maintenance tail worse than no tool when stale | After month 12, with a rules-update commitment | +| TDS compliance engine | Same maintenance-tail class | After month 12 | +| Multi-company control tower | Green wall over unloaded companies = silent-failure theater; sells renewals not trials | 20+ live companies at one firm; redesign around expected staleness | +| E-invoice / e-way bill | ClearTax owns it; needs GSP infra + per-machine TDL | Not planned | +| Connected banking / payment initiation | TallyPrime native; bank-API arms race | Not planned | +| Receivables dunning (SMS/WhatsApp/call) | CredFlow's company; comms infra + support headcount | Not planned (Pulse carries approvals/alerts only) | +| Mobile analytics dashboards | Biz Analyst's entrenched turf | Evidence-viewer only, post cloud relay | +| AI OCR document extraction at scale | Model arms race vs funded teams | Post cloud consent architecture | +| TDL plugin with in-Tally UI | Breaks zero-install purity; per-machine support burden | Not planned | +| Inventory depth / store-keeper flows | Not the CA/CS buyer's job | Not planned | +| Education-mode posting scheduler | Test constraint leaking into product | Never (Passport-detected restriction only) | + +## Parked engineering ideas (unscheduled) + +- ODBC read-only cross-check channel for reconciliation totals. +- JSONEX transport promotion (existing shadow-comparator machinery; needs + measured operational benefit per the legacy plan's PR 10 rules). +- Mirror data-map & key-management screen ("which machines hold which + clients' books") — adoption-critic suggestion, revisit with multi-seat. +- Proof-of-Post PDF localization (Hindi/Gujarati). + +_Add new items with date + one-line reason + revisit condition._ diff --git a/docs/tally/EXECUTION_LOG.md b/docs/tally/EXECUTION_LOG.md new file mode 100644 index 0000000..9a20e6a --- /dev/null +++ b/docs/tally/EXECUTION_LOG.md @@ -0,0 +1,20 @@ +# Tally roadmap execution log + +One line per merged PR, appended by the orchestrator after merge (see +[PROMPT_PLAYBOOK.md](./PROMPT_PLAYBOOK.md) §7.1). This log is the +orientation input for phase selection: the current phase is the lowest- +numbered phase whose exit criterion is not yet evidenced here. + +Format: + +``` +| date | PR | phase | invariant established | evidence | +``` + +Evidence must name a real artifact: a test (crate::module::test_name), a +signed compatibility-matrix receipt id, a migration version, or a demo +scenario transcript reference. "Done" is not evidence. + +| Date | PR | Phase | Invariant established | Evidence | +| --- | --- | --- | --- | --- | +| _(none yet — Phase 1 has not started)_ | | | | | diff --git a/docs/tally/GO_TO_MARKET_AND_PRICING.md b/docs/tally/GO_TO_MARKET_AND_PRICING.md new file mode 100644 index 0000000..9ec6518 --- /dev/null +++ b/docs/tally/GO_TO_MARKET_AND_PRICING.md @@ -0,0 +1,191 @@ +# Bridge × Tally: commercial model, support & go-to-market + +**Date:** 2026-07-24 · Companion to [IMPROVEMENT_PLAN_2026H2.md](./IMPROVEMENT_PLAN_2026H2.md). +Resolves the open commercial questions the plan deferred and the adoption +critic raised: if the code is open source, what is sold? who does a partner +call at 9 PM on the 10th? per-entity or per-firm pricing? how does a solo-dev +open-source tool overcome the incumbent's retraining moat? + +> Pricing figures below are **decision hypotheses** to validate against the +> live competitor-pricing research and the first design-partner conversations. +> Every number tagged _(validate)_ is a starting anchor, not a committed price. + +--- + +## 1. The three questions, answered decisively + +1. **What is sold, given the code is open?** → **Open-core.** The engine is + open and checkable (that *is* the trust brand); the commercial product is + the signed desktop build + the paid capability tiers + support + updates + + the evidence/compliance surfaces. You pay for assurance and outcomes, not + for source you could read. +2. **Who does the firm call?** → A **legal operating entity** with a brand, a + GST number, a DPA, and a **deadline-aware support SLA** (faster guaranteed + response around the 7th/11th/20th). "One developer + AI codegen" is an + internal fact, never a customer-facing disclosure; the customer buys a + company with a support commitment. +3. **Per-entity or per-firm?** → **Per firm, banded by client count** — this + is the *actual* CA-practice norm (Vyapar TaxOne: ₹10,000/yr flat, unlimited + clients ≈ ₹833/mo; AI Accountant: ₹3k/₹15k/₹20k tiers for ≤1/≤10/≤25 + clients). Per-entity is the SME-owner tools (CredFlow, Biz Analyst) and + would make Bridge look absurd at 80 clients against TaxOne's flat rate. The + **Drift Sentinel wedge is the exception — sold seasonally per audit client**, + because that maps to how audit engagements are already scoped and billed. + +--- + +## 2. Open-core boundary (what's free vs paid) + +| Layer | License | Rationale | +| --- | --- | --- | +| Rust engine crates (transport, protocol, canonical, incremental, evidence signing) | **Open source** | The verifiability claim must be checkable; open source *is* the moat, not a giveaway of the moat. | +| Deterministic simulator + fixtures | **Open source** | Contributor reproducibility; no book data. | +| Read/snapshot/mirror + Sync Beacon | **Free tier** (signed build) | Land motion — costs nothing to run, seeds the habit, demonstrates honesty. | +| **Drift Sentinel** | **Paid** (wedge SKU) | The uncontested capability; the acquisition wedge. | +| **Write pipeline** (Excel→review→post→Proof-of-Post, maker-checker, mapping rules) | **Paid** | The expansion product; the daily-use value. | +| Multi-client console, evidence/compliance exports, priority support | **Paid (firm tier)** | Renewal drivers. | +| Signed/notarized installers, auto-update, per-version qualification receipts | **Paid** | Assurance the free/self-built path doesn't carry. | + +Rule: anything that is a *checkable trust claim* stays open (so a skeptic can +verify it); anything that is an *outcome or assurance* is paid. This keeps the +"honesty brand" and the revenue model from contradicting each other. + +## 3. Pricing model + +**Unit:** **per firm, banded by client-count** — the CA-practice convention +(TaxOne flat-unlimited; AI Accountant client-count tiers). Not per user (firms +add articles seasonally and would game it). Not pure per-entity (that's the +SME-owner model and prices Bridge out of a 50–80-client firm against TaxOne's +₹833/mo). Drift is the one seasonal per-audit-client exception. + +**Competitive price anchors (cited, July 2026):** +- Vyapar TaxOne (leader): **₹10,000/yr flat, unlimited clients** (CA SKU), + ₹12,000/yr Advocate/Accountant; ICAI-CMP discount channel. ≈ **₹833/mo**. +- AI Accountant: **₹3,000 (≤1 client) / ₹15,000 (≤10) / ₹20,000 (≤25) / + Platinum custom** per year. +- CredFlow / Biz Analyst: per-company / per-device (SME model) — expensive at CA + scale, not the comparison set. +- TallyPrime base (context): Silver ₹22,500 one-time or ~₹750/mo rental + TSS + ₹4,500/yr. + +**The truth this forces:** Bridge **cannot win the CA segment on price** — +TaxOne's ₹833/mo unlimited is a floor no solo product should undercut. Bridge +must price *at a premium* justified by a capability TaxOne lacks (Drift, +Proof-of-Post verification), not compete on the wrong axis. The brand is +assurance, and assurance carries a premium. + +**Tiers (hypotheses to validate with design partners):** + +| Tier | Who | What | Anchor _(validate)_ | +| --- | --- | --- | --- | +| **Free — Verify** | Any firm | Reads, snapshot mirror, Sync Beacon, connection self-test | ₹0 | +| **Drift** (seasonal) | Audit-season buyers | Drift Sentinel per audit client, checkpoints, drift packs | per audit client per month, billed for the audit window _(validate vs ~₹500–1,000/entity TaxOne band)_ | +| **Post** | Firms doing daily entry | Everything in Drift + write pipeline + Proof-of-Post + mapping rules, single-company workspaces | per active entity per month | +| **Firm** | Multi-client firms | Post + multi-client console + priority deadline-aware support + evidence exports | per-entity with a firm-level floor + volume bands (50/80/150 clients) | + +**Packaging notes:** +- Drift is deliberately a **seasonal, low-commitment** entry — it lands inside + the firm during audit season without displacing Suvit, then Post/Firm expand + once trust is earned. +- **Free trial:** 30 days of Post on up to 3 real client entities, with the + history-seeded mapping suggestions active (so the trial is *not* the + cold-start-worst-case the incumbent's month-36 engine beats — see §5). +- Anchor to **at or below Suvit/TaxOne per-entity parity** for Post; charge the + premium only where Bridge has a capability the incumbent lacks (Drift, + Proof-of-Post), never for parity features. + +## 4. Support & SLA (the churn-objection answer) + +The profession is deadline-driven; support latency is the #1 post-sale +complaint across CredFlow/Biz Analyst. Turn it into a differentiator. + +- **Deadline-aware SLA:** guaranteed response windows tighten around statutory + deadlines (TDS 7th, GSTR-1 11th, GSTR-3B 20th) — publish the calendar. +- **In-app diagnostics first:** the "Run connection check" self-test and the + accountant-language error catalog deflect the most common tickets (gateway + off, wrong company open, Tally closed) before they become calls. +- **Named-contact for Firm tier;** business-hours email for Post; community + + docs for Free. +- **Status transparency:** a public status/known-issues page — the same + honesty brand applied to operations. +- Solo-dev reality is managed by **deflection (self-test + catalog) + scope + discipline (one supported topology) + async SLA**, not by pretending a + 24×7 desk exists. + +## 5. Overcoming the incumbent retraining moat (cold-start) + +The real switching cost is ledger-mapping history the incumbent has and Bridge +doesn't. Bridge's structural counter (turn the liability into an advantage): + +- **Read-before-write history seeding:** on connect, mine 12 months of posted + vouchers from the mirror into narration→ledger candidate rules, so Post's + suggestions are useful on **day one**, not month 36. +- **Mapping import:** ingest a firm's existing mappings (from a TaxOne/Excel + export where available) as a starting rule set. +- **Drift-first land:** Drift needs *no* mapping at all — it's read-only — so + the firm adopts Bridge before ever confronting the mapping-retraining cost; + by the time they try Post, Bridge has already read their history. + +## 6. Data-handling posture (turn "local" into a sellable answer) + +Local-first beats cloud for the paranoid partner, but "local SQLCipher on an +article's laptop" is *new* client-data sprawl the firm must answer for. + +- **Data-map screen:** which machines hold which clients' encrypted mirrors, + key custody, and a one-click wipe — so a partner can answer "who has copies + of Sharma Exports' books?" (implement alongside multi-client; parked in + [BACKLOG.md](./BACKLOG.md) until then). +- **DPA + sub-processor list:** a signable data-processing addendum so the firm + can extend its own client data-handling representations to Bridge. +- **Deletion/erasure workflow:** finish the currently-unimplemented mirror + erasure path before claiming "fully removable" (privacy-model.md gap). +- Marketing claim stays exactly: **"full-fidelity, local, SQLCipher-encrypted; + nothing leaves the machine"** — checkable because the engine is open. + +## 7. Go-to-market motion + +1. **Design partners (months 0–6):** 3–5 CA firms with licensed TallyPrime. + Recruit via direct CA network + the ComplyEaze/AXAL relationship. They get + Drift + early Post free in exchange for the scratch-company qualification + protocol and a reference. Definition-of-done (plan §NEXT) is the reference. +2. **Wedge land (months 3–9):** Drift Sentinel as an **audit-season product** — + "know every voucher your client changed after you signed off." Fear-led, + uncontested, no incumbent displacement required. +3. **Content + community:** CA-community channels (CAclubindia, ICAI study + circles, LinkedIn CA cohorts), publishing the *evidence* angle (Proof-of- + Post packs, drift catches) as concrete demos, not adjectives. +4. **Expansion (months 8–12):** Post/Firm upsell into landed Drift accounts; + the multi-client console sells the renewal. +5. **Later:** ComplyEaze/AXAL cloud relay (evidence layer first) unlocks + mobile/WhatsApp (Pulse) approval flows — a second wedge, not a pivot. + +**Anti-goals:** no paid ads arms race vs funded incumbents; no conference-badge +"verifiability" pitch that gets nods and zero trials (lead with the fear/job, +substantiate with evidence); no distribution through Tally partners (channel +conflict with the platform whose gaps Bridge exploits). + +## 8. Live-demo proof points (from the plan — the sales moment) + +On a real licensed TallyPrime, messy books, never samples: +1. **Tamper catch** — edit/back-date/delete three vouchers in Tally; Bridge + lists exactly those three with before/after diffs, including the back-dated + one. +2. **Completeness under fire** — kill Tally mid-sync; Bridge reports exactly + what's Verified vs Stale vs unread; no silent green. +3. **Full fidelity on hostile data** — custom-TDL company, 100k vouchers; + narration/GSTIN/bill refs match to the paisa and character, live. + +The sentence that closes: _"Every entry my juniors post is approved, verified +against Tally, and evidenced; and I know within a day if a client edits a +voucher I've already signed off."_ + +--- + +## 9. Open decisions for the founder + +| Decision | Options | Recommendation | +| --- | --- | --- | +| Legal entity / brand for the commercial build | New entity vs under ComplyEaze | Under an existing entity if one carries the GST/DPA; a customer-facing brand is mandatory before first paid deal. | +| Drift seasonal vs annual pricing | Per-audit-client seasonal vs flat annual | Seasonal to lower the entry barrier; convert to annual on renewal. | +| Free-tier generosity | Reads free forever vs time-limited | Reads + Beacon free forever (land motion); Drift/Post paid. | +| License for the open crates | Permissive (MIT/Apache) vs copyleft (AGPL) | AGPL for the engine to deter a funded incumbent from absorbing it cloud-side while keeping it checkable; commercial license for the paid build. _(validate with counsel.)_ | diff --git a/docs/tally/IMPROVEMENT_PLAN_2026H2.md b/docs/tally/IMPROVEMENT_PLAN_2026H2.md new file mode 100644 index 0000000..70592ef --- /dev/null +++ b/docs/tally/IMPROVEMENT_PLAN_2026H2.md @@ -0,0 +1,188 @@ +# Bridge × Tally: Market Research & Improvement Plan + +**Date:** 2026-07-24 · **Repo:** `lamemustafa/bridge` (audited at PR #78) · **Method:** codebase audit + 24-source verified web research + 4-persona ideation, 2 adversarial critiques, arbiter synthesis + +> Execution companions: [PROMPT_PLAYBOOK.md](./PROMPT_PLAYBOOK.md) (per-phase implementation/review/rectification/preservation prompts + orchestrator), [EXECUTION_LOG.md](./EXECUTION_LOG.md) (per-PR invariant log), [BACKLOG.md](./BACKLOG.md) (parked scope), [LICENSED_LAB_QUALIFICATION_CHECKLIST.md](./LICENSED_LAB_QUALIFICATION_CHECKLIST.md). Where this plan conflicts with `TALLY_INTEGRATION_RESEARCH_AND_CODEX_PLAN.md`, **this plan wins** (see the supersession note at the top of that file). + +--- + +## 0. Executive summary + +**Where Bridge is:** a superbly engineered, read-only Tally evidence console. 13 layered Rust crates, loopback-only transport, strict protocol parsing, atomic checkpointed snapshots into an encrypted SQLCipher mirror, Proof-of-Sync, Gap Map. But: **zero writes possible in any shipped build**, voucher reads deliberately stripped of narration/GSTIN/bill data, every compatibility claim `unknown` with `missing` evidence, and ~30 recent PRs spent on "sealed canary" ceremony for a synthetic write that has never touched a live Tally. The founder's diagnosis is correct: no CA will use it today. + +**Where the market is:** every serious competitor (Vyapar TaxOne née Suvit, Finsights, CredFlow, Biz Analyst, AI Accountant) ships the same architecture Bridge already has — a local desktop connector speaking to Tally's XML gateway — and every one of them is drowning in the same complaint: **sync you can't trust** (entries vanishing, duplicates, stale ledgers, 24-hour deletion lag, silent failures). Nobody proves what synced. That is Bridge's thesis, validated — but evidence must sit *under* workflows, not replace them. + +**The plan in one paragraph:** Unseal the write machinery and delete the ceremony (keep the evidence). Restore full-fidelity reads. Ship **Drift Sentinel** — "know every voucher your client changed after you signed off, with before/after" — as the read-only acquisition wedge no competitor has. Rent a licensed TallyPrime in month 2. Then build the write substrate (outbox, batch-of-1, readback-verified posting) and the expansion product: **Excel/CSV → review grid → maker-checker → post → Proof-of-Post**. Realistic solo-dev horizon: wedge in ~3 months, daily-use write product by ~8–10 months. + +**The north-star sentence** (what a partner must be able to say): *"Every entry my juniors post is approved, verified against Tally, and evidenced; and I know within a day if a client edits a voucher I've already signed off."* + +--- + +## 1. Current state of Bridge's Tally integration + +### What works today (all read-only) +- Probe/company discovery (PR #78 adds the explicit "N companies discovered → choose/verify" prompt — good, keep). +- Reads: companies, groups, ledgers, voucher types, vouchers, ledger period balances — via reviewed XML/TDL profiles, loopback-only, size/time-bounded, STATUS=1-enforced. +- Full CoreAccounting snapshot pipeline → canonical model (exact decimals, fail-closed) → reconciliation → Proof-of-Sync → SQLCipher mirror, with atomic checkpoints and resumability. +- Evidence UI: capability passport, gap map, truth states, mirror explorer. + +### The blockers +| Blocker | Detail | +|---|---| +| **No writes** | Even the single synthetic canary ledger is behind two disabled compile-time flags + attestations + sealed one-shot dispatch; no Tauri command exists. UI hard-codes `write capability: Unknown`. | +| **Minimized reads** | Vouchers lack narration, party GSTIN/address, bill allocations, inventory/GST lines — useless for recon, scrutiny, or any review UI. | +| **Zero live evidence** | Compatibility matrix: every cell `unknown`, evidence `missing`. No `Unsupported` signing key even exists. The "evidence product" has no evidence. | +| **Only CoreAccounting wired** | IndiaTax / Bills-Outstandings / Inventory packs are feature-gated parsers with no runtime. | +| **No cloud path for Tally data** | AXAL sync exists only for DSC/documents; Tally data needs a versioned destination contract (fine for now — local-first is the positioning). | +| **Velocity sink** | ~30 PRs of pre-dispatch safety ritual produced zero rows of evidence. Safety engineering has been optimizing ceremony before dispatch instead of verifiability after dispatch. | + +--- + +## 2. Market research (July 2026, verified claims) + +### 2.1 Landscape + +| Product | Write into Tally | Mechanism | Sync | Notes | +|---|---|---|---|---| +| **Vyapar TaxOne** (ex-Suvit, absorbed by Vyapar) | Ledgers + vouchers from bank/sales/purchase docs | Desktop connector → XML gateway (manual host/port) | One-way push + reads for GST | Scale leader: claims 10k+ CA firms, 30k+ accountants; AI/OCR ingestion, ledger auto-suggest from history, review-before-post, "zero duplicate entries" marketing | +| **Finsights** | Vouchers, invoices, stock entries | Desktop connector beside Tally (both must stay open) | Two-way, ~10-min cycles; **Tally deletions propagate only every 24h** | CA-focused; client-invitation model for client-maintained books; unlimited companies | +| **CredFlow** | Receipts, invoices, quotations, sales orders | Desktop connector; company must be open; **refuses Education-mode Tally** | Two-way | Receivables/dunning company (SMS/WhatsApp/call reminders); sync-reliability complaints | +| **Biz Analyst** | 10 entry types incl. sales/purchase | Desktop sync agent | Two-way | 1M+ installs, 4.2★; complaints: "unending" sync issues, missing fields, Play-Store data-safety page admits unencrypted data shared with third parties | +| **AI Accountant** | Vouchers, mappings, sales invoices | Local agent; XML for R/W, ODBC for analytics; **AlterID-tracked incremental sync** | Two-way, scheduled | Maker-checker approval, review-before-post with rationale, duplicate/voucher-lock handling; lists custom-TDL/UDF fields as a known break risk | +| **ClearTax connector** | e-invoice/e-way-bill fields | **TDL plugin inside Tally + connector app (ODBC)**; per-machine installs | Two-way (compliance fields) | Owns e-invoicing; in-Tally UI | +| **Tally native** (the platform threat) | — | — | — | Built-in GSTR-2B download + recon with granular status buckets (resolution still manual, per-company); TallyPrime 6.0 connected banking; 7.x AI features | +| **DIY long tail** | File-based XML import | Gateway of Tally → Import | One-way | NIKASH converters, TaxGuru VBA recon (6–10 hrs/GSTIN/month VLOOKUP baseline) — the actual majority workflow | + +> Deeper landscape (Zoho/Munim/Open/EnKash/GST connectors/Tally-native remote), +> cited competitor pricing, and a public-record UX teardown of the four leading +> flows are in [MARKET_RESEARCH_ADDENDUM.md](./MARKET_RESEARCH_ADDENDUM.md). Its +> findings confirm every ruling below and sharpen the UX bets (§ Now/Next). + +### 2.2 Structural takeaways +1. **The on-prem connector is unavoidable and Bridge already is one** — with a stronger engineering base than the connectors CAs complain about. +2. **Sync trust is the universal open wound.** Every incumbent's worst reviews are trust failures. None can prove completeness, attribute failures, or detect Tally-side edits/deletions promptly. +3. **Tally native is absorbing adjacent value** (2B recon, banking, AI): pure-reporting and portal-integration plays erode. Data-entry automation, multi-client practice ops, and *evidence about the books* remain defensible. +4. **Regulatory tailwind with a date:** since Jan 2026, excess ITC vs GSTR-2B auto-flags on the portal; MCA Edit-Log rules make "what changed in the books" a partner-level anxiety. +5. **Education mode:** competitors refuse it (CredFlow). It permits voucher entry only on the 1st/2nd/31st. It is a fine regression rig and an honest Passport state — but nothing can be marked `Verified` from it, and a licensed instance is a hard prerequisite for a credible write story. + +### 2.3 CA workflows that consume the hours +- **Bank statement → vouchers** (the biggest hour pool; ledger suggestions learned per-client from narration patterns). +- **Excel/CSV registers → vouchers** (pure transcription; saved per-client column mappings make month 2 near-zero-touch). +- **GSTR-2B ↔ purchase register recon** (fuzzy multi-field matching, exception queues; Tally native buckets well but resolves one voucher at a time, one company at a time). +- **Receivables follow-up** (CredFlow's turf; skip). +- **Multi-client management** (50–200 companies per firm, staff roles, per-client sync health, deadline rhythm: 7th/11th/20th). +- **Audit/verification** ("what changed since I signed off" — served by *nobody*). + +### 2.4 UX patterns to steal / fix +**Steal:** review-before-post as the *only* path to Tally (Suvit); saved mapping templates; maker-checker (AI Accountant); Tally's own recon-bucket vocabulary; duplicate detection made visible. +**Fix (the industry's sins):** silent sync failure and single green dots (show *last-verified* vs *latest-attempt* as two timestamps, always); stale data without self-degrading freshness; "posted" claims from HTTP counters (post ≠ verified until re-read); errors in XML language instead of accountant language; black-box AI suggestions (show the rationale). + +### 2.5 Technical ground truth for deep two-way sync +- Gateway: Import/Export/Execute; broad read surface (24 voucher types, 13 master types proven publicly); writes for masters and vouchers with `ACTION=Create/Alter/Cancel/Delete`. +- Import response = STATUS + CREATED/ALTERED/…/ERRORS counters + coarse LINEERROR, **no per-record IDs** (only LASTVCHID/LASTMID) → idempotency, duplicate prevention, and readback verification are the integrator's job. +- **No server-side AlterID filtering** (date-range only) → incremental sync = periodic GUID+AlterID index scan diffed locally; same GUID + higher AlterID = edited; absent from a *complete verified* scan = deleted; lower AlterID = backup restored → re-baseline. Back-dated vouchers get fresh AlterIDs, so date-unbounded scans catch them. +- ODBC strictly read-only. Inline per-request TDL shapes exports without installing anything. No concurrent writes — single-writer serialization mandatory. Omitting SVCURRENTCOMPANY writes to whatever company is open (the ecosystem's worst failure mode; Bridge already pins). +- Custom TDL/UDF fields in client Tallys break naive schemas — quarantine unknowns on read; per-installation write qualification before certifying writes there. + +--- + +## 3. The debate: what survived, what was ruled, what died + +Four persona proposals (CA operator, product strategist, protocol engineer, UX designer) were attacked by two adversarial critics (engineering-reality, CA-adoption) and reconciled by an arbiter. Full transcripts are preserved in the session scratchpad. + +### 3.1 Consensus (adopt) +1. **Full-fidelity reads first** — narration, party GSTIN/address, bill allocations, GST/inventory lines; quarantine-on-unknown for custom TDL/UDF; encoding/name-normalization hardening (non-English fixtures). Everything else depends on this. +2. **The write substrate** — outbox state machine (WAL-durable before dispatch), **batch-size-1** (counters are unattributable at N>1; the current `MAX_LEDGER_WRITE_BATCH=10` is wrong), UDF-embedded BridgeTxnID + **date/amount/ledger-set fingerprint** as mandatory secondary dedupe, readback-confirmed-only ("posted" = re-read from Tally, never counters), LASTVCHID cross-checked against the idempotency key (foreign-writer race), OutcomeUnknown recovery with pre-image AlterID checks, single-writer actor, fail-closed company pinning, **Cancel (not Delete) as the compensation primitive**, no fictional rollback. +3. **Maker-checker + Proof-of-Post** — review-before-post is the only path from file to Tally; approval identity recorded; exportable per-batch evidence pack. Marketed as *supplementary* workpaper evidence, never MCA-Edit-Log equivalence (gateway writes appear in Tally's log as the logged-in Tally user). +4. **Excel/CSV → review grid → post pipeline** with saved per-client column mappings — the expansion product. +5. **Drift Sentinel** — checkpoint → "changed/new/deleted/back-dated since sign-off" with before/after diffs. Firm-maintained books only in v1; calm "backup restored, re-baselining" state distinct from tamper alarm. +6. **Honest freshness UX** — Sync Beacon with dual timestamps; Gap Map reborn as a fix-it list; Truth States compressed to three visual tiers (Verified+time / Attention+reason+fix / Broken+remediation). +7. **Incremental sync v2** — ALTMSTID/ALTVCHID cheap probe, segmented per-FY/month GUID+AlterID scans (a full-books unbounded export can hang a 500k-voucher Tally at 11am — segment + off-hours + visible progress/cancel), verified-scan-only tombstones, wired to the existing `bridge-tally-incremental` crate (well-shaped, just unwired). +8. **Kill the ceremony, keep the evidence** — rule adopted verbatim: *no safety mechanism without a demonstrated failure mode it prevents; no capability claim without a receipt.* +9. **Declared topology honesty** — v1 supports: local single-machine, loaded-company, licensed Tally, no TallyVault, no gateway auth. Tally-on-cloud/RDP (a large and growing install base!), multi-user LAN, gateway-security setups = explicit `Unsupported` Passport states, not silent failures. + +### 3.2 Contested → rulings +| Item | Ruling | +|---|---| +| GSTR-2B recon | **Defer to Later (month 9+ gate)**, scoped to the *bulk-resolution* layer across many GSTINs (consume 2B JSON uploads; no portal OTP). Don't fight TallyPrime's flagship solo now; don't cede the only deadline-driven workflow forever. | +| Licensed-Tally timing | **Rent TallyPrime Silver in month 2** — before the first real write ships. Edu stays the daily regression rig; **nothing is ever marked `Verified` from Edu or simulator.** Cheapest de-risk in the plan. | +| Bank statements vs Excel first | **Excel/CSV first.** Same review-grid pipeline; bank statements arriving as CSV/Excel flow through unchanged. The bank-format zoo + PDF/OCR is a permanent maintenance tail — fast-follow, not v1. | +| Lead marketing claim | **Drift Sentinel + Proof-of-Post lead** (fear with a face; the answer to why firms churned). Proof-of-Sync/Passport are substance behind the demo, never the headline. Kill "data minimization" claim; rewrite to "full-fidelity, local, encrypted" in the same commit that un-minimizes reads. | +| Education-mode UX | Passport-detected restriction only. The "reschedule for the 31st" scheduling feature is **deleted** — a test constraint leaking into product design. | +| Multi-company control tower | Descoped to Later; redesigned around *expected staleness* ("open these 6 companies today" worklist) — a green wall over unloaded companies is the exact silent failure the Truth Layer exists to prevent. | +| Capability Passport | **Build it, don't sell it.** It's the internal gate, the 10-second "Run connection check" support self-test, and the topology-honesty vehicle. Never leads a pitch. | +| Remote agent on client machines | **Killed for this horizon** (solo dev cannot operate a fleet product; reputational risk lands on the firm). Drift v1 = firm-maintained books (typically ~half a firm's clients) — enough for the wedge. | + +### 3.3 Killed (don't build) +Canary/attestation/dual-flag machinery and 6 of 8 digest newtypes · e-invoice/e-way bill (ClearTax's turf, needs GSP + TDL installs) · connected banking/payments (Tally native) · receivables dunning (CredFlow's company) · mobile dashboards (Biz Analyst's turf; no mobile asset) · AI OCR at scale (arms race vs funded teams; deterministic import covers ~70% provably) · TDL plugin with in-Tally UI · inventory depth/store-keeper flows · Education-mode posting scheduler · Period Freeze as a headline product (stays as plumbing) · bank-statement PDF/OCR parsing (v1) · GSTR-1 prep engine and TDS engine (rules-maintenance tails; revisit after month 12) · "80% time saved"-style unprovable claims and cryptographic-signature marketing language. + +--- + +## 4. Strategy + +### 4.1 Positioning +> For CA/CS firms burned by "sync issues" in every Tally companion app, Bridge is the two-way Tally integration that **proves** every read and write — posted means read-back-verified, and you know when anyone changes the books after you've signed off. + +Marketable one-liners: *"Every competitor says 'synced.' Bridge proves it."* · *"Audit-grade sync for the audit profession."* + +### 4.2 The wedge and the expansion +- **Acquisition wedge — Drift Sentinel** (read-only, ships first): "Know, firm-wide, every voucher your client changed after you signed off — with before/after." No incumbent equivalent (Tally's Edit Log can't be queried across companies; Finsights takes 24h to notice deletions). Sells a *liability fear* (closes faster than a time saving), lands inside firms **without asking them to abandon Suvit**, prices per audit client in audit season, and requires none of the unproven write path. +- **Expansion product — the verified write pipeline**: Excel/CSV import → saved mappings → review grid → maker-checker → serialized post → readback-verified Proof-of-Post. Spends the trust Drift earned. +- **Cold-start weapon:** Bridge reads 12 months of posted vouchers before ever writing — reverse-engineer narration→ledger mappings from history so suggestions are good on day one (the incumbents' mapping-history moat, neutralized structurally). + +### 4.3 Live-demo proof points (on a real licensed TallyPrime, on messy books, never samples) +1. **The tamper catch:** checkpoint; someone edits one voucher, back-dates one, deletes one directly in Tally; Bridge lists exactly those three with diffs within one sync cycle — *including the back-dated one*. +2. **Completeness under fire:** kill Tally mid-sync; restart; Bridge reports exactly what is Verified vs Stale vs unread — no silent green, dual timestamps intact. +3. **Full fidelity on hostile data:** custom-TDL company, 100k vouchers — narration/GSTIN/bill refs matching to the paisa and character, "verified N minutes ago" live. (Post-writes, a fourth beat: watch a row flip "Posted — verifying…" → "Verified in Tally, 14:32".) + +--- + +## 5. Roadmap (one developer + AI codegen; honest calendar) + +### NOW — months 0–3: read-side truth becomes a sellable product +| # | Work | Exit criterion | +|---|---|---| +| 1 | **Unseal & simplify** (wks 1–3): delete canary/attestation/dual-flag machinery; writes compile in, gated by **one runtime per-company write allowlist (default off)** — the sole surviving gate (it prevents a demonstrated failure mode: dev build pointed at real books); generalize import-evidence parsing beyond ledgers | Canary code gone; write path compiles behind runtime consent | +| 2 | **Full-fidelity reads** (wks 3–8): narration, GSTIN/address, bill allocations, GST fields; quarantine lane for unknown TDL/UDF; encoding/normalization hardening; rewrite privacy docs + claims to "full-fidelity, local, encrypted" | Clean round-trip diff (export → canonical → re-export) on Edu across all wired voucher types | +| 3 | **Drift Sentinel v1 + Sync Beacon** (wks 8–12): checkpoint → changed/new/deleted/back-dated list with before/after diffs; segmented GUID+AlterID scans on `bridge-tally-incremental`; verified-scan-only tombstones; backup-restore re-baseline state; dual-timestamp Beacon | Demo proof points 1 & 2 pass on the licensed box | +| 4 | **Rent licensed TallyPrime (month 2)** — dedicated qualification VM; Edu demoted to regression rig | First real (signed) compatibility-matrix rows | + +### NEXT — months 3–8: the write substrate, then the thin product +| # | Work | Exit criterion | +|---|---|---| +| 5 | **Write core**: outbox + batch-1 + readback verification + LASTVCHID cross-check + crash-mid-dispatch recovery; ledger create/alter | `Verified` on the licensed box, kill-test passes | +| 6 | **Voucher Create** (payment/receipt/journal/contra): UDF+fingerprint idempotency qualified per version; **Cancel** qualified as compensation; Alter-by-GUID qualified per version with Cancel+Create fallback saga | Voucher CRUD `Verified` (licensed); Edu restriction honestly surfaced | +| 7 | **The thin product loop**: Excel/CSV import → saved per-client mappings → Review grid (confidence *words* + inspectable rationale + per-row errors in accountant language) → Post Queue stepper (Draft→Validated→Previewed→Approved→Posting→Posted→**Verified**) → Proof-of-Post PDF. Single company. History-seeded ledger suggestions | — | +| 8 | **One design-partner firm**: scratch company on their licensed Tally first, then one real client | **Definition of done:** one article posts one client's weekly register for four consecutive weeks with zero unexplained, duplicated, or missing vouchers, and the partner files one Proof-of-Post pack | + +### LATER — months 8–12: expand only what the wedge earned +Alter drafts + "Changed in Tally" chips in the Daybook · sales/purchase vouchers with GST ledger splits + party auto-create behind separate approval (GSTIN checksum, dedupe vs existing masters) · bank-statement CSV/Excel variants + visible/editable rule promotion · multi-client worklist designed around expected staleness and filing deadlines (7th/11th/20th) · master-hygiene reports (duplicate candidates, GSTIN checksum, propose-only) · **GSTR-2B bulk-resolution layer** (gated: substrate ran one clean quarter + partners asking) · concurrency hardening + 500-voucher soak + failure-mode playbook → GA. + +### Explicitly deferred hooks (design-compatible, no code now) +- **AXAL/ComplyEaze:** relay the *evidence layer first* (proofs, receipts, drift alerts — small, non-sensitive payloads) via a versioned destination contract before ever moving raw books; preserves the privacy positioning while enabling richer cloud/AI features. +- **Pulse/WhatsApp:** drift alarms and posting-approval requests as messages (approval flows, not dunning). +- **Tally-on-cloud topology (addendum 2026-07-24):** hosted-RDP Tally (TallyOnCloud-style providers) is a large and growing install base that v1 declares `Unsupported` in the Passport. The eventual story is a headless Bridge agent running *inside* the hosted VM with the desktop UI attaching to its mirror — architecturally compatible with the loopback-only rule (the agent is loopback-local to Tally). Parked in BACKLOG.md; revisit when a design partner runs hosted Tally, not before GA of the local topology. +- **Client-maintained books (addendum 2026-07-24):** Drift Sentinel v1 covers firm-maintained books only (~half a typical firm's clients). The remote client-machine agent stays killed for this horizon, but two lighter paths can extend Drift coverage later and are parked in BACKLOG.md: (a) periodic client backup/TCP-file ingestion — diff a restored backup against the checkpoint mirror offline, no software on client machines; (b) the Finsights-style client-invitation model once a cloud relay exists. Neither blocks the wedge. + +--- + +## 6. Engineering appendix (what to keep/simplify/delete) + +**Keep (load-bearing):** company pinning fail-closed · single-writer serialization + circuit breaker (`bridge-tally-runtime`) · ExactDecimal · STATUS=1 enforcement · SQLCipher mirror + atomic checkpoints · `bridge-tally-incremental` tombstone/checkpoint model · import-evidence + readback parsers in `bridge-tally-protocol` (generalize beyond ledgers) · compatibility-matrix schema + Ed25519 receipt signing (worthless empty, differentiating populated) · fail-closed canonicalization for known fields (quarantine for unknown). + +**Simplify:** two compile-time flags + attestations + sealed one-shot dispatch → one runtime per-company allowlist + per-batch approval · eight digest newtypes → two (payload, response) on the outbox row · qualification harness keeps receipt emission, loses synthetic-only orientation (simulator stays the regression suite; it can never mint `Verified`). + +**Delete:** all `FIXTURE_CANARY_*` machinery, attestation apparatus, sealed dispatch envelope, "write capability: Unknown" dead-ends (replaced by Passport states fed from real receipts). + +**Write-path invariants (non-negotiable):** row fsynced before dispatch · one object per import · readback + field diff before `CONFIRMED` (mismatch → `CONFIRMED_WITH_DIVERGENCE`, surfaced) · alters carry pre-image AlterID; concurrent foreign edit → `MANUAL`, never blind retry · deletion pre-checks references from the mirror · absence tombstones only from complete verified scans · a truncated scan never mass-tombstones · backup-restore (AlterID regression) → calm re-baseline, not tamper alarm. + +--- + +## 7. Immediate next actions + +1. **Merge PR #78** (it's a good, small company-discovery UX fix consistent with this plan). +2. Open the **M0 "unseal & simplify"** PR series: delete canary machinery, add the per-company write allowlist, generalize import-evidence parsing. +3. Start the **full-fidelity read** profile work (voucher FETCH extension + quarantine lane) — it gates everything. +4. **Budget the TallyPrime Silver rental** and stand up the qualification VM (month 2). +5. Rewrite `docs/tally/privacy-model.md` + README claims ("full-fidelity, local, encrypted") alongside the un-minimization commit. +6. Line up **one design-partner CA firm** with a licensed TallyPrime for the scratch-company qualification protocol. diff --git a/docs/tally/LICENSED_LAB_QUALIFICATION_CHECKLIST.md b/docs/tally/LICENSED_LAB_QUALIFICATION_CHECKLIST.md new file mode 100644 index 0000000..b1a01b0 --- /dev/null +++ b/docs/tally/LICENSED_LAB_QUALIFICATION_CHECKLIST.md @@ -0,0 +1,97 @@ +# Licensed-lab qualification checklist + +What to verify, per Tally version, on the rented licensed TallyPrime lab VM +(plan §NOW item 4; playbook Phases 3–5). Every row that completes produces a +signed compatibility-matrix receipt for the exact +(product, release, mode, platform, transport, operation) tuple — see +[compatibility/README.md](./compatibility/README.md). Nothing here may be +answered from folklore, blogs, or the Education instance; Edu results are +recorded as education-mode cells only. + +**Version matrix to run:** TallyPrime 7.1 (primary), 7.0, 6.x (one build), +each licensed; Education 7.1 for the education-mode cells. ERP 9 6.6.3 only +for read-profile compatibility cells. + +**Fixture companies (synthetic only):** +- `QF-EN` — English, small, clean chart of accounts. +- `QF-IN` — Devanagari/Gujarati/Tamil ledger + party names, non-ASCII narrations. +- `QF-UDF` — custom TDL loaded defining mandatory UDF fields on vouchers. +- `QF-BIG` — generated 100k+ vouchers across 3 FYs (scan-cost measurements). +- `QF-LOCK` — closed/locked prior period, books-from mid-FY. +- `QF-EDITLOG` — Edit Log enabled (MCA audit-trail configuration). + +Each row: **ID · question · how · consumed by**. + +## A. Write grammar (Phase 4 blockers) + +| ID | Question to answer with evidence | How | Consumed by | +| --- | --- | --- | --- | +| A1 | Ledger Create/Alter/Delete accepted shapes; Delete failure shape when ledger is referenced by a voucher | Import each; capture counters + LINEERROR | Outbox, master CRUD | +| A2 | Voucher Create accepted for payment/receipt/journal/contra incl. narration, bill allocations, cost centres | Import per type on QF-EN and QF-IN | Voucher writes | +| A3 | Voucher **Alter by REMOTEID/GUID**: required identity fields (DATE? VOUCHERTYPENAME? VOUCHERNUMBER? VCHKEY?); full-replacement vs partial semantics | Alter with progressively minimal envelopes | Alter path vs Cancel+Create fallback decision | +| A4 | Voucher **Cancel** via ACTION=Cancel: identity requirements, CANCELLED counter, voucher number stays reserved | Cancel + readback + daybook check | Compensation primitive | +| A5 | Voucher **Delete**: identity strictness, DELETED counter, absence on readback and on next index scan | Delete + verify absence | Delete path | +| A6 | LASTVCHID / LASTMID: returned when? Clobbered by a foreign write between import and readback? | Scripted foreign write race (second session typing in Tally) | Readback binding + cross-check rule | +| A7 | Counter semantics: IGNORED vs ERRORS on duplicate name create; ALTERED on no-op alter; multiple TALLYMESSAGE behavior (informational only — batch stays 1) | Matrix of malformed/duplicate imports | Evidence parser golden tests | + +## B. Idempotency & identity (Phase 4) + +| ID | Question | How | Consumed by | +| --- | --- | --- | --- | +| B1 | Inline-TDL **UDF definition on import**: accepted? persisted? exported back on read? survives foreign Alter of the voucher? | Create with BridgeTxnID UDF; read back; alter in UI; read again | Idempotency key authority decision (UDF vs narration) per version | +| B2 | Narration-suffix key: survives UI edits? truncation limits (observed narration max length)? | Long-narration create + UI edit | Fallback key + fingerprint mandate | +| B3 | Master name uniqueness: case sensitivity, leading/trailing space handling, Unicode normalization (QF-IN names differing only by case/NFC form) | Create near-collision pairs | Name-keyed idempotency, dedupe | +| B4 | Voucher **auto-numbering**: methods (Automatic, Manual, Auto-manual, Multi-user auto) vs imported VOUCHERNUMBER — is a supplied number honored, ignored, or collided? Number behavior on Cancel (reserved?) and on Alter | Import into voucher types configured per method | Duplicate prevention; number display in review grid | +| B5 | Multi-currency voucher create/read round-trip (rate, forex gain/loss ledger) | QF-EN with USD party | Scope decision: in/out of Phase 4 | + +## C. Change detection (Phase 3 blockers) + +| ID | Question | How | Consumed by | +| --- | --- | --- | --- | +| C1 | ALTMSTID / ALTVCHID company-level high-water marks: exported? bumped by every master/voucher change incl. back-dated inserts? | Export company object before/after edits | Cheap-probe availability claim | +| C2 | Back-dated voucher insert: fresh AlterID assigned? caught by date-unbounded index scan? | Insert into prior month; scan | Drift Sentinel false-negative proof point | +| C3 | AlterID regression on **backup restore**: observed values, company GUID stability across restore | Backup, edit, restore, scan | Re-baseline (calm) state | +| C4 | Server-side filter behavior: date-range honored exactly (FY boundaries, from==to); AlterID filter attempt ignored (confirm per version) | Filtered exports vs known fixture | Scan segmentation design | +| C5 | Deletion visibility: deleted voucher absent from index scan; no other observable tombstone signal | Delete in UI; scan | Verified-scan-only tombstone rule | +| C6 | Scan cost on QF-BIG: collection generation time per FY segment; Tally UI responsiveness while scanning; safe request spacing | Timed segmented scans while a user types | Off-hours scheduling defaults, spacing | + +## D. Edit Log / MCA audit trail (Phases 4–5 marketing accuracy) + +| ID | Question | How | Consumed by | +| --- | --- | --- | --- | +| D1 | Does an XML-gateway write appear in the Edit Log on QF-EDITLOG? Attributed to which user (logged-in Tally user? "admin"?) | Gateway create + inspect Edit Log | Proof-of-Post wording: "supplementary evidence", exact attribution sentence | +| D2 | Is the Edit Log itself readable/exportable programmatically (XML collection? ODBC? report export only)? | Attempt export | Possible future drift corroboration source | +| D3 | Does Cancel/Delete via gateway log distinctly from UI cancel/delete? | Compare log entries | Compensation-audit story | +| D4 | Edit Log on vs off: any write-grammar behavior differences? | Re-run A2 with log on | Matrix dimension decision | + +## E. Gateway security & topology (Passport probes) + +| ID | Question | How | Consumed by | +| --- | --- | --- | --- | +| E1 | Tally user security enabled: does the gateway require/apply auth? Which operations fail and with what shape? | Enable security controls; probe | Passport `Unsupported` states | +| E2 | TallyVault-encrypted company: visible in company list? readable? writable? | Vault a fixture company | Declared-unsupported topology honesty | +| E3 | Company not loaded / multiple companies loaded: SVCURRENTCOMPANY targeting proof; write attempt against unloaded company fails how? | Load permutations | Company-pinning failure modes, error catalog | +| E4 | Two Tally instances on one machine (different ports): endpoint identity behavior | Run both; probe | Endpoint canonicalization | +| E5 | Education mode negative tests: voucher dated 15th rejected with what shape; master writes unrestricted; 31st literal on 30-day months | Edu instance | Passport education cells; error catalog | + +## F. Encoding & robustness (Phase 2 confirmations on live builds) + +| ID | Question | How | Consumed by | +| --- | --- | --- | --- | +| F1 | Response encoding per version (UTF-8/UTF-16LE/BOM) for QF-IN exports; any ill-formed XML (unescaped `&` in names)? | Byte-capture exports | Decoder qualification | +| F2 | Round-trip fidelity: QF-IN narration/GSTIN/bill refs byte-exact through export→canonical→re-export | Diff harness | Full-fidelity exit criterion on licensed builds | +| F3 | QF-UDF: unknown-UDF quarantine on read; write REJECTED shape when mandatory custom field missing; write accepted-but-blank risk | Import minimal voucher into QF-UDF | Per-company write qualification rule ("review-in-Tally-recommended" degradation) | +| F4 | Period lock (QF-LOCK): write into locked period — LINEERROR shape; alter of pre-lock voucher | Import attempts | Error catalog ("period locked") | +| F5 | Response-cap behavior: export exceeding 32 MiB window — truncation vs error; Partial labeling honest | QF-BIG unsegmented export | Bounded-read invariant | + +## Operating rules + +1. One checklist row = one scripted, rerunnable probe in the qualification + harness; manual one-off observations don't count as evidence. +2. Every result — positive, negative, or weird — becomes a matrix receipt; + `Unsupported` requires the profile-specific unsupported signature + (playbook Phase 1 item 6), never a bare STATUS=0. +3. Rows A1–A7, B1–B4, C1–C5 are **blocking** for their consuming phase; + the rest may trail but must complete before GA claims. +4. Re-run the full checklist on every new TallyPrime release before + updating the supported-versions claim. diff --git a/docs/tally/MARKET_RESEARCH_ADDENDUM.md b/docs/tally/MARKET_RESEARCH_ADDENDUM.md new file mode 100644 index 0000000..4e2209f --- /dev/null +++ b/docs/tally/MARKET_RESEARCH_ADDENDUM.md @@ -0,0 +1,136 @@ +# Market research addendum (2026-07-24) + +Extends the landscape in [IMPROVEMENT_PLAN_2026H2.md](./IMPROVEMENT_PLAN_2026H2.md) §2 +with three gap-coverage passes: missing products, competitor pricing, and a +public-record UX teardown. Every claim is cited; items that could not be +confirmed in a primary source are marked **UNVERIFIED**. + +--- + +## A. Expanded landscape (products not in the original table) + +| Vendor | Read/Write into Tally | Mechanism | Direction | Notable | +| --- | --- | --- | --- | --- | +| **Zoho Books** | Read (import) | Manual file export/import | One-way, one-time **migration** | A *replacement* for Tally, not a co-existing sync partner — removes it as a live competitor. ([Zoho migration help](https://www.zoho.com/in/books/help/migration/tally-to-zoho-books.html)) | +| **Munim** | Read | "Tally Connector" (transport UNVERIFIED) | One-way → Munim (GST prep) | Low-cost Tally alternative; ₹3,299+/yr. ([Munim helpdesk](https://themunim.com/helpdesk/how-to-import-your-data-to-munim-gst/)) | +| **Open (open.money)** | **Write (claimed)** | **UNVERIFIED** (method undisclosed) | Two-way; auto-JV per transaction | Only banking/AP player claiming to auto-create vouchers *inside* Tally — but hides how. ([Open blog](https://open.money/blog/tally-synchronisation-integration-with-open/)) | +| **EnKash** | Sync/reconcile (write UNVERIFIED) | UNVERIFIED | Reconciliation-oriented | "Vouchers" in its marketing = its rewards product, not Tally. ([EnKash](https://www.enkash.com/auto-reconciliation)) | +| **PayMate** | None confirmed | Generic ERP API | — | No confirmed Tally voucher write. ([PayMate](https://paymate.in/enterprise.html)) | +| **GSTZen** | **Read + write-back (IRN/QR into voucher)** | TDL add-on + port-9000 XML + **Chrome extension** bridge | Two-way (e-invoicing) | Chrome-only; multi-step setup. Same class as ClearTax. ([GSTZen](https://gstzen.in/einvoicing/methods-of-e-invoice/e-invoice-integration-for-tally-prime.html)) | +| **MasterGST (Masters India)** | Read (write-back UNVERIFIED) | DLL connector plugin | One-way export | Invoices managed in MasterGST. ([MasterGST](https://mastergst.com/tally-integration-connector-for-einvoice.html)) | +| **Cygnet** | Read + return JSON/PDF | Pre-built connectors/APIs (enterprise GSP) | Round-trip (in-voucher write UNVERIFIED) | Enterprise-skewed. "Cygnature" is a separate e-sign product. ([Cygnet](https://www.cygnet.one/products/e-invoicing/india)) | +| **Hisabkitab / Giddh / Refrens / Hisab** | Read/sync (varies; some UNVERIFIED) | Tally Connector / migration plugin | Mostly one-way | Newer AI/cloud entrants; Giddh is migration-flavored. | + +### Tally's own remote/mobile/audit capabilities (competitive baseline) + +- **Remote Access (Tally.NET):** full read+write remotely, but needs a **local + TallyPrime client install + active TSS**; encrypted XML/HTTP; concurrency by + license (Silver 1 / Gold 10). Not a mobile story. ([TallyHelp](https://help.tallysolutions.com/tally-prime/connected-services/remote-access-faq-tally/)) +- **Reports in Browser (TRiB):** **read-only** — "you can only view and + download vouchers in a browser," no create/edit; report generated in the + local client and streamed; **no native mobile app**. ([TallyHelp](https://help.tallysolutions.com/tally-prime/connected-services/browser-reports-faq-tally/)) + → **Strategic point:** Tally's *own* mobile/browser offering is read-only with + no native app. A write-capable, evidence-backed local tool has real whitespace. +- **Edit Log (MCA audit trail, mandatory since 1 Apr 2023):** records + create/alter/delete for transactions **and** masters — who, when, action, + before/after values; tamper-proof. **Two caveats material to Bridge:** + 1. Programmatic export of the Edit Log change-history via XML/ODBC is + **UNVERIFIED / probably unsupported** — it's an in-product report + (PDF/Excel), not a queryable API stream. (Do not build Drift on the + assumption you can read Tally's Edit Log over the gateway.) + 2. A third-party gateway/TDL write is attributed in the Edit Log to the + **logged-in Tally user of that instance** (typically admin), not a distinct + connector identity (mechanistic inference; a licensed-lab test item — see + [LICENSED_LAB_QUALIFICATION_CHECKLIST.md](./LICENSED_LAB_QUALIFICATION_CHECKLIST.md) + D1). → **This confirms the plan's rule: Proof-of-Post is *supplementary* + workpaper evidence, never MCA-Edit-Log equivalence.** ([Tally: Audit Trail](https://tallysolutions.com/tally/audit-trail-in-tallyprime/)) + +**Cross-cutting:** GST/e-invoicing connectors (GSTZen, MasterGST, ClearTax) +converge on the **TDL-plugin + port-9000** pattern with per-machine installs — +the opposite of Bridge's zero-install-in-Tally posture. Confirms the plan's +"don't build e-invoicing" ruling and the clean-architecture differentiation. + +## B. Pricing (cited, July 2026) + +**The CA-practice pricing unit is per-firm (often flat/unlimited or client-count +banded), NOT per-entity.** Per-entity/per-device is the SME-owner segment. + +| Product | Price (INR) | Unit | Source | +| --- | --- | --- | --- | +| **Vyapar TaxOne** (leader) | ₹10,000/yr (CA, **unlimited clients**); ₹12,000/yr Advocate/Accountant | Per firm, flat | [taxone.vyapar.com/pricing](https://taxone.vyapar.com/pricing) | +| **AI Accountant** | ₹3,000 (≤1) / ₹15,000 (≤10) / ₹20,000 (≤25) / Platinum custom | Per firm, banded by client count | [softwaresuggest](https://www.softwaresuggest.com/ai-accountant) (Sep 2025) | +| **CredFlow** | ₹3,499–14,999/yr tiers (or ₹999–2,499/mo) | Per company/entity | [techjockey](https://www.techjockey.com/detail/credflow) | +| **Biz Analyst** | from ₹250/mo | Per device per Tally license | [help.bizanalyst.in](https://help.bizanalyst.in/biz-analyst-manual/faqs/pricing) | +| **Finsights** | Tally On The Go ₹999; WhatsApp Alerts ₹2,999 | Module/subscription | [technologycounter](https://technologycounter.com/products/finsights) | +| **ClearTax connector** | from ₹499/mo + volume tiers | Per module + volume | [aidukan](https://aidukan.in/cleartax-price-india/) | +| **Vouchrit / TallyGraphs** | NOT FOUND (custom / dormant) | — | — | +| **TallyPrime base** (context) | Silver ₹22,500 one-time or ~₹750/mo rental; TSS ₹4,500/yr | Per license | [markitsolutions](https://www.markitsolutions.in/pricing/) | + +**Entry price for a 50–80-client CA firm:** ~**₹800–1,700/month** (TaxOne flat +₹10k/yr ≈ ₹833/mo is the anchor). → Bridge cannot win on price; it must charge +a premium on the capability gap (Drift, Proof-of-Post). See +[GO_TO_MARKET_AND_PRICING.md](./GO_TO_MARKET_AND_PRICING.md). + +## C. UX teardown (public record) — patterns to steal and fix + +Detailed, cited per-flow findings; the three cross-cutting conclusions matter most. + +### Per-product highlights +- **Vyapar TaxOne bank→Tally:** Bulk-Upload → Banking → company + bank-ledger + select → upload (dupe-name warning) → **async processing (Excel ~30min, PDF + ~1hr, scanned PDF up to 12hrs)** → auto-map date/amount/type/narration → grid + with **search-and-bulk-assign by party** + inline ledger create (GSTIN fetch) + + rules → "Send to Tally" → **verify in Tally's Day Book (not in-product)**. + No per-row confidence shown; mapping is exact-match, brittle. ([taxone import help](https://taxone.vyapar.com/help/articles/import-the-bank-statement), [skillcourse walkthrough](https://skillcourse.in/import-pdf-transactions-into-tally-suvit/)) +- **Biz Analyst mobile entry:** FAB → Create Sales Invoice (permission-gated) → + left-drawer company switch → line items with closing-balance/godown → save → + auto-sync. **New invoices default to "optional vouchers" in Tally** (accounting + gotcha). Sync status = "Last Sync Time" stamp; **failure surfaces as figures + showing 0**, not an error. ([create sales invoice](https://help.bizanalyst.in/features/data-entry/how-to-create-sales-invoice), [figures showing 0](https://help.bizanalyst.in/biz-analyst-manual/support/sync-issues/all-figures-showing-0-in-mobile-app)) +- **AI Accountant maker-checker:** proposal queue → predict ledger + GST codes → + **Approve / Adjust / Lock-rule** (three-way) → exceptions lane for CA review → + optional maker-checker gate for "sensitive writebacks" → duplicate/naming/sync + validation. Confidence-score *display* not public (INFERRED grid). Vocabulary + ("maker-checker", "ledger scrutiny", "exceptions queue") is the differentiator. + ([Tally integration](https://www.aiaccountant.com/blog/tally-integration-with-ai-accountant), [CoA AI mapping](https://www.aiaccountant.com/blog/chart-of-accounts-ai-mapping)) +- **CredFlow connector setup:** download desktop app → keep company open → + **configure ODBC + port (manual, mismatch = #1 failure)** → Add Company → sync. + Errors (not-connected, educational-mode-unsupported, **company-name mismatch on + rename**) are deferred to Freshdesk KB, not surfaced in-app. ([add company](https://credflow.freshdesk.com/support/solutions/articles/82000909704-how-to-add-company-for-tally-software-), [syncing-issues folder](https://credflow.freshdesk.com/support/solutions/folders/82000694831)) + +### Three cross-cutting whitespace conclusions (all confirm plan bets) +1. **Confidence transparency is an open gap across all four** — everyone claims + AI mapping; none *shows* per-row confidence with a bulk-accept-above-threshold + control. → Validates plan S3 (confidence *words* + inspectable rationale + + Accept-all-Matched; Suggested behind an explicit toggle). +2. **Sync failure is universally under-communicated** — TaxOne bare "Failed", + Biz Analyst "figures → 0" (reads as *real data* — dangerous in accounting), + CredFlow KB-deferred "not connected". → Validates the Sync Beacon + (dual-timestamp, never green-from-cache) and accountant-language error catalog. +3. **Verification happens in Tally, not in-product** (TaxOne, Biz Analyst) — the + loop is left open. → Validates Proof-of-Post readback ("Verified in Tally + 14:32", echo the posted voucher number in-app). + +### New concrete refinements folded into the plan +- **Auto-detect the gateway port and running companies** (CredFlow's manual + port field is its #1 support ticket). PR #78 already added company discovery; + extend the onboarding self-test to probe/suggest the port. +- **Make optional-vs-regular voucher explicit at post time** (Biz Analyst's + silent optional-voucher default is a trust trap) — surface it in the S4 + preview with a one-line consequence. +- **Bind sync to company GUID, never name** (CredFlow breaks on rename) — + already a plan invariant; now with a named competitor failure to cite. +- **Local, synchronous Excel/CSV import is a marketable speed edge** vs TaxOne's + 30min–12hr async queue — reinforces the "Excel/CSV first, skip OCR" ruling. +- **One-click "Lock rule" from the corrected row** (AI Accountant pattern) — + tighten the plan's "rule promotion after 2 corrections" to also offer inline + rule creation from the row the user just fixed. + +## D. Research-confidence note + +The primary verification pass (deep-research workflow) confirmed 20 core +landscape claims 3-0 before hitting a model usage limit; the remainder rest on +single primary sources (vendor docs/help centers), corroborated where possible +by the repo's own prior research. Treat UNVERIFIED-tagged items above as +directional. Nothing here changes the plan's rulings; it deepens the landscape +and confirms the UX and positioning bets. diff --git a/docs/tally/PROMPT_PLAYBOOK.md b/docs/tally/PROMPT_PLAYBOOK.md new file mode 100644 index 0000000..460a9aa --- /dev/null +++ b/docs/tally/PROMPT_PLAYBOOK.md @@ -0,0 +1,934 @@ +# Bridge × Tally — Prompt Playbook + +Companion to `docs/tally/IMPROVEMENT_PLAN_2026H2.md`. Copy-paste prompts for driving AI codegen agents (Codex/Claude) through each roadmap phase: implementation, review/rectification cycles, change-preservation gates, and the overall orchestrator. + +**How to use:** every prompt below assumes the GLOBAL RULES block (§1) is pasted beneath it. Each phase runs the same cycle: + +``` +IMPLEMENT → ADVERSARIAL REVIEW → RECTIFY → (repeat review/rectify until no P0/P1 findings) → PRESERVATION GATE → PR +``` + +The ORCHESTRATOR (§7) drives phase selection, the cycle, and phase-gate advancement. + +--- + +## 1. GLOBAL RULES block (paste into every prompt) + +```text +GLOBAL RULES — Bridge × Tally (2026-07 plan revision) + +Repository: lamemustafa/bridge. Base branch: master. + +Read before editing: AGENTS.md, CONTRIBUTING.md, SECURITY.md, +review-checklist.md, docs/tally/README.md, docs/tally/privacy-model.md, +docs/tally/TALLY_INTEGRATION_RESEARCH_AND_CODEX_PLAN.md, +docs/tally/IMPROVEMENT_PLAN_2026H2.md (the current authority where the two plans +conflict), and the crates under src-tauri/crates/ relevant to your phase. + +SUPERSEDED old rules (do NOT follow these from the older plan doc): +- "Writes remain disabled until the dedicated safe-write stage" → writes now + compile into shipped builds, gated by the per-company runtime write + allowlist (default off) plus per-batch review/approval. The canary/ + attestation/dual-compile-flag machinery is deleted, not extended. +- "Data minimisation: do not fetch narrations, addresses, tax identifiers" + → reversed. Full-fidelity reads into the encrypted local mirror are the + product. The privacy stance is now "full-fidelity, local, encrypted". +- MAX_LEDGER_WRITE_BATCH = 10 → batch size is exactly 1 object per import + request, always. + +STILL NON-NEGOTIABLE (unchanged): +- Loopback-only Tally connectivity; redirects blocked; size/time caps. +- HTTP 200 is never Tally success; require application STATUS=1 parsing. +- SVCURRENTCOMPANY (company pinning) mandatory on every company-scoped + request; fail closed on mismatch. +- Exact decimals only; never floating point for amounts. +- A failed/partial/cancelled run never advances a verified checkpoint. +- "Posted" is never claimed from counters alone; only from readback. +- No automatic retry of writes without an idempotency probe first. +- Deletion tombstones only from complete, verified scans. +- Only synthetic test data. Never commit/log raw books data, GSTINs, PANs, + narrations, credentials, usernames, or machine paths. +- Nothing is marked `Verified` in the compatibility matrix from the + Education edition or the simulator. Simulator = regression only. +- Truth States vocabulary in UI: Verified / Partial / Stale / Unsupported / + Failed (rendered as 3 visual tiers). No bare green checkmarks. +- Every behavioural change ships with a regression test. Every DB change + ships as a versioned migration with rollback notes. +- Do not touch DSC/document/AXAL behaviour except minimal compile wiring. +- One roadmap phase per PR series; no scope tourism. + +RULE OF RULES: no safety mechanism without a demonstrated failure mode it +prevents; no capability claim without a receipt. + +Required validation before any PR: + corepack pnpm install --frozen-lockfile + corepack pnpm run license:all + corepack pnpm run build + corepack pnpm run cargo:fmt + corepack pnpm run cargo:check + corepack pnpm run cargo:test + corepack pnpm run cargo:clippy + corepack pnpm run security:audit:frontend + cargo audit --file src-tauri/Cargo.lock + +PR body must include: invariant established, functional summary, tests +added, exact commands/results, migration+rollback impact, Tally/security/ +privacy impact, remaining uncertainty, linked review-checklist item. +``` + +--- + +## 2. PHASE 1 — Unseal & Simplify (weeks 1–3) + +### 2.1 Implementation prompt + +```text +PHASE 1: UNSEAL & SIMPLIFY +Branch series: feat/tally-unseal-* + +Mission: delete the sealed-canary ceremony; make the write path a normal, +runtime-gated capability; generalize import-evidence parsing. This phase +removes code and adds one gate. Net LOC should be strongly negative. + +Implement, in separate reviewable PRs: +1. DELETE: all FIXTURE_CANARY_* constants and flows; the + fixture-canary-dispatch-seam and fixture-canary-runtime-dispatch + features; canary_preflight.rs, canary_dispatch_admission.rs, + canary_runtime_dispatch_coordinator.rs; the operator-attestation + enrollment commands and their UI; the sealed one-shot dispatch envelope. + Migrate (do not silently drop) any evidence-table rows: mark legacy + enrollment rows as archived in a versioned migration. +2. SIMPLIFY: collapse the eight digest newtypes in bridge-tally-write to + two (payload digest, response digest) stored per outbox row. Keep + domain-separated hashing. +3. ADD the sole surviving gate: a per-company runtime write allowlist, + default OFF, persisted in the mirror DB keyed by company GUID, exposed + as one Tauri command pair (enable/disable, with the company name echoed + back for confirmation). No writes of any kind may dispatch for a + company not on the allowlist. This gate exists because it prevents a + demonstrated failure mode: a dev/test build pointed at real books. +4. GENERALIZE: import-evidence parsing (STATUS/counters/LINEERROR) and + readback parsing in bridge-tally-protocol from ledger-only to a typed + surface usable for vouchers, stock items, cost centres. Pure parsing; + no dispatch in this phase. +5. UI: remove "write capability: Unknown" dead-ends; replace with Passport + states fed from the (still empty, but now honest) receipts store: + "Writes not yet qualified on this installation". +6. EVIDENCE UNBLOCK: implement the profile-specific `Unsupported` evidence + signature in bridge-tally-compatibility (docs/tally/compatibility/ + README.md records that no such signature exists, so live receipts + cannot promote any Unsupported claim today). Honest negative claims + are half the Truth Layer; the matrix must be able to record them + before Phase 3/4 qualification runs begin. + +Do NOT in this phase: build the outbox, dispatch any write, extend read +profiles, or add UI beyond the allowlist toggle and removed dead-ends. + +Tests: +- allowlist default-off blocks dispatch at the lowest layer (not just UI); +- allowlist is company-GUID-keyed (a renamed company stays gated correctly); +- generalized evidence parser: golden tests for CREATED/ALTERED/DELETED/ + CANCELLED/IGNORED/ERRORS combinations, duplicate containers, malformed + counters, LINEERROR redaction — for all four object kinds; +- migration test: legacy canary/enrollment rows survive as archived rows; +- grep-tests (see preservation gate) proving canary symbols are gone. + +Exit criterion: shipped build compiles with the write crates enabled, +gated only by the runtime allowlist; canary code is gone; the +`Unsupported` evidence signature exists with a passing gate run; net diff +is code-negative. +``` + +### 2.2 Adversarial review prompt + +```text +ROLE: adversarial reviewer for PHASE 1 (Unseal & Simplify). +You are reviewing actual diffs, not descriptions. Check out the branch and +read the code. Report findings as: [P0|P1|P2] file:line — claim — concrete +failure scenario. Then verify each of your own findings against the code +and mark CONFIRMED or WITHDRAWN. No style nits. + +Hunt specifically for: +1. Incomplete deletion: any surviving FIXTURE_CANARY_* symbol, feature + flag, attestation table write path, or docs/tally text still promising + the canary flow (docs/tally/compatibility/synthetic-write-canary- + fixture.md must be removed or rewritten). +2. Evidence-signature review: the new `Unsupported` signature must be + profile-specific (a generic STATUS=0 must remain `Failed`, never + `Unsupported` — see compatibility README); check signing-key rotation + and revocation handling for the new signature kind. +3. Gate bypass: any code path that reaches the transport's import/POST + surface without consulting the per-company allowlist — including test + helpers, the qualification harness, and future-facing dead code. + The allowlist check must live at or below the single-writer boundary, + not in the UI or command layer alone. +4. Gate identity confusion: allowlist keyed by company NAME anywhere + (rename → gate slips), or a missing-GUID company silently passing. +5. Evidence-parser regressions: the generalized parser accepting a + response whose counters and object kind disagree; profile-defaulted + zeros being reported as observed zeros. +6. Migration safety: canary/enrollment rows dropped without archive; + migration not reversible; schema version not bumped. +7. Dishonest UI: any surface still implying write capability exists or is + "Unknown" in the old sense; Passport text claiming qualification that + has no receipt. +8. The deletion overreaching: serialization/circuit-breaker runtime, + company pinning, STATUS=1 enforcement, ExactDecimal, checkpoint + atomicity must be untouched (see preservation checklist). +``` + +### 2.3 Rectification prompt + +```text +ROLE: rectifier for PHASE 1. Input: the CONFIRMED findings from the +adversarial review. For each finding, in severity order: +1. Restate the finding and the invariant it violates. +2. Fix it minimally; do not refactor beyond the fix. +3. Add a regression test that fails before the fix and passes after. +4. If a finding is actually invalid, prove it with a test or a code trace + and mark it REJECTED with evidence — never silently skip it. +5. Follow the repository defect process (AGENTS.md "Rectification + expectations"): for each CONFIRMED non-security defect, open a follow-up + `Bug` issue and land the fix as a dedicated `Rectify` PR carrying + root-cause and the regression check — do not fold confirmed defects + silently into the feature PR. For a suspected vulnerability, credential + leak, or sensitive-data exposure, STOP and follow SECURITY.md privately + instead (this supersedes public issue/PR creation). +Re-run the full validation suite. Output: per-finding status +(FIXED/REJECTED+evidence), the Bug issue + Rectify PR link per defect, +tests added, commands run with results. Then hand back for another +adversarial review pass. The cycle repeats until a review pass yields +zero CONFIRMED P0/P1 findings. +``` + +### 2.4 Change-preservation gate prompt + +```text +ROLE: preservation gate for PHASE 1. You are the last check before PR. +Verify each item with a command, test run, or code citation — not by +reading PR descriptions. Output PASS/FAIL per item with evidence. Any +FAIL blocks the PR. + +Must still hold after this phase: +1. Loopback-only transport: endpoint validation tests green; no new + non-loopback host acceptance. (cargo test in bridge-tally-transport) +2. Single-writer serialization + circuit breaker untouched: + bridge-tally-runtime tests green; no API changes. +3. Company pinning: every company-scoped request still requires + SVCURRENTCOMPANY; fail-closed tests green. +4. STATUS=1 enforcement and response caps unchanged in + bridge-tally-protocol / bridge-tally-transport. +5. Read pipeline unchanged: snapshot → canonical → reconcile → proof + round-trip tests green; checkpoint atomicity tests green. +6. ExactDecimal untouched; no f32/f64 introduced anywhere near amounts + (grep for "f64" in changed files; justify every hit). +7. Compatibility-matrix schema and Ed25519 receipt signing intact + (bridge-tally-compatibility tests green); matrix claims file unchanged + except where canary claims were removed. +8. Mirror encryption: SQLCipher init path unchanged; no plaintext DB. +9. No DSC/document/AXAL behavioural diff (git diff scoped check). +10. Absence-of-ceremony proof: scope the grep to implementation only, because + the planning docs legitimately discuss the removal. Run + `grep -ri "FIXTURE_CANARY\|dispatch-seam\|attestation" src-tauri src + docs/tally/compatibility docs/adr` (i.e. code + evidence/ADR docs, + NOT the roadmap/playbook/plan `.md` files) and expect only + archived-migration and changelog references. +``` + +--- + +## 3. PHASE 2 — Full-Fidelity Reads (weeks 3–8) + +### 3.1 Implementation prompt + +```text +PHASE 2: FULL-FIDELITY READS +Branch series: feat/tally-full-fidelity-* + +Mission: the mirror must hold everything a CA needs to review, reconcile, +and later verify writes: narration, party GSTIN/address, bill allocations, +GST tax lines, inventory lines, cost-centre allocations. You cannot verify +what you cannot read back — this phase gates every write phase. + +Implement: +1. Extend the voucher read profile with a NEW version. NOTE: `bridge.tally. + vouchers/2` (BRIDGE Voucher Export V2) AND `bridge.tally.vouchers/3` + (BRIDGE_SELECTED_VOUCHER_EXPORT_SCHEMA, the scope-bound selected-read + profile, pinned by a CHECK constraint in migration 0007) are both taken. + Allocate the next free version — `bridge.tally.vouchers/4` (BRIDGE Voucher + Export V4) — and migrate any stored profile identity as needed; do not + mutate V2 or V3. FETCH NARRATION, party ledger name, PARTYGSTIN, address + list, BILLALLOCATIONS.LIST, ALLINVENTORYENTRIES.LIST (+ batch/godown), + LEDGERENTRIES.LIST with GST rate/classification fields, + COSTCENTREALLOCATIONS.LIST. +2. Extend ledger/master profiles similarly (contact, GSTIN, addresses, + opening-bill allocations). +3. Wire the existing feature-gated IndiaTax and Bills/Outstandings parser + packs into the runtime read path as normal (non-default-off) profiles. +4. Canonical model: extend fail-closed canonicalization for the new KNOWN + fields; add a QUARANTINE lane for unknown TDL/UDF fields — a quarantined + voucher lands in the mirror flagged with the unknown field names as + evidence, never fails the whole snapshot, and surfaces in the Gap Map + fix-it list. +5. Encoding/normalization hardening: UTF-8/UTF-16LE/BOM fixtures; + non-English (Devanagari, Gujarati, Tamil) company/ledger/narration + fixtures in the simulator corpus; NFC normalization + case-insensitive + collation for name keys (Tally name uniqueness is effectively + case-insensitive). +6. Migration: versioned mirror schema evolution for the new fields + (voucher lines, bill allocations, inventory lines, tax lines) with + rollback notes. +7. Rewrite docs/tally/privacy-model.md and README claims in the SAME PR + that un-minimizes reads: the stance is now "full-fidelity, local, + SQLCipher-encrypted; nothing leaves the machine". + +Tests: +- golden round-trip: simulator company → snapshot → canonical → re-export + diff clean for every wired voucher type, including bill/inventory/tax + lines and non-English names; +- quarantine: a voucher with an unknown UDF is mirrored+flagged while the + snapshot completes and the proof records Partial-with-reason; +- encoding: UTF-16LE + BOM + numeric character references parse; a + malformed-entity fixture fails closed with a typed error; +- migration up/down tests. + +Exit criterion: clean round-trip diff on the Education instance across all +wired voucher types; quarantine lane demonstrated on a custom-UDF fixture. +``` + +### 3.2 Adversarial review prompt + +```text +ROLE: adversarial reviewer for PHASE 2 (Full-Fidelity Reads). Same output +contract as Phase 1 review (confirmed findings only, file:line, failure +scenario). + +Hunt specifically for: +1. Silent field loss: a FETCH list naming a field the parser then drops; + canonical model fields that never reach the mirror schema; NULL-vs- + empty-string conflation (absent narration must be absent, not ""). +2. Quarantine overreach/underreach: known fields routed to quarantine + (hides bugs) or unknown fields still failing whole snapshots; quarantine + evidence leaking raw values into logs (field NAMES are evidence; field + VALUES in logs are a privacy finding). +3. Amount fidelity: any new tax/inventory line parsed through anything but + ExactDecimal; sign conventions (IsDeemedPositive) mishandled on new + line types; Dr/Cr balance invariant not re-checked with lines present. +4. Identity/normalization traps: NFC normalization applied on read but not + on the keys used for diffing (same ledger counted twice); case-collation + asymmetry between mirror and reconciliation. +5. Bounded-resource regressions: new list explosions (AllInventoryEntries + on huge vouchers) versus the 32 MiB response cap — is there a paging or + windowing story? Does a capped response get honestly labeled Partial? +6. Profile versioning: V2 or V3 mutated instead of the new V4 added; + compatibility surface hashes not regenerated; old checkpoints silently + reinterpreted as V4 data without a forced re-baseline. +7. Privacy-doc dishonesty: code un-minimizes but privacy-model.md/README + still claim minimization (or vice versa). +``` + +### 3.3 Rectification prompt + +Use the Phase 1 rectification prompt verbatim, with "PHASE 2" substituted. (The rectification contract is identical for every phase: fix confirmed findings in severity order, regression test per fix, REJECT only with evidence, re-run validation, loop until a review pass is clean of P0/P1.) + +### 3.4 Change-preservation gate prompt + +```text +ROLE: preservation gate for PHASE 2. Verify with commands/tests/citations; +PASS/FAIL per item; any FAIL blocks. + +Must still hold: +1. All Phase 1 preservation items (re-run that checklist first). +2. Checkpoint atomicity with the new schema: kill-mid-snapshot test leaves + the previous verified checkpoint readable and consistent. +3. Old-profile compatibility: a mirror created pre-migration opens, and + the app forces an honest full re-baseline rather than mixing older + (V2/V3) and new (V4) voucher data under one Verified label. +4. Data minimization REMOVAL is complete and consistent: no residual code + path silently strips narration/GSTIN (grep the old omission tests — + they must be inverted, not deleted-and-forgotten). +5. Proof-of-Sync and Gap Map still compute; reconciliation totals still + tie out on the extended model (run the reconciliation test suite). +6. Response caps and streaming limits unchanged; no unbounded buffering + added for the bigger payloads. +7. Diagnostics/logs still value-free: run the log-redaction test suite; + grep new code for narration/GSTIN in log macros. +``` + +--- + +## 4. PHASE 3 — Drift Sentinel v1 + Sync Beacon (weeks 8–12) + +### 4.1 Implementation prompt + +```text +PHASE 3: DRIFT SENTINEL v1 + SYNC BEACON +Branch series: feat/tally-drift-sentinel-* + +Mission: the acquisition wedge. A CA checkpoints a company ("I signed off +on these books"), and Bridge thereafter reports every voucher/master +created, edited, deleted, or back-dated in Tally since that checkpoint, +with before/after diffs. Plus the Sync Beacon: dual-timestamp freshness +that never shows green from cache. + +Implement: +1. Incremental scan engine wired to the EXISTING bridge-tally-incremental + crate (do not rewrite it): + a. Cheap probe first: company-level ALTMSTID/ALTVCHID high-water marks; + if unchanged vs checkpoint, skip the scan. Availability of these + fields is a compatibility claim per Tally version — record it. + b. Index scan: per object type, minimal inline-TDL projection of + GUID, MASTERID, ALTERID (+ DATE, VOUCHERTYPENAME for vouchers), + SEGMENTED per FY/month with per-segment checkpoints, scheduled + off-hours by default, visible progress, cancellable. Never issue a + single unbounded full-books export. + c. Diff rules: new GUID → created (fetch full); higher AlterID → + edited (fetch full, diff vs mirror); absent from a COMPLETE VERIFIED + scan → deleted (tombstone); lower AlterID → backup-restore detected + → calm re-baseline flow, not a tamper alarm. +2. Sign-off checkpoints: operator-created, named, timestamped marks bound + to (company GUID, scan receipt, mirror content hash). Multiple named + checkpoints per company. +3. Drift report: per checkpoint, the list of changed/new/deleted/ + back-dated objects with field-level before/after diffs (from mirror + history), each row carrying its evidence (AlterID pair, scan receipt). + Exportable as PDF/JSON ("what changed since sign-off" pack). +4. Sync Beacon (UI): persistent pill — last-verified timestamp, latest- + attempt timestamp+outcome, next scheduled check. A failed attempt NEVER + erases last-verified; staleness self-degrades (configurable thresholds). + Clicking opens the sync drawer: 24h attempt timeline (every failure + visible), per-domain freshness table, "Run connection check" self-test. +5. Truth-state rendering compression: Verified(+time) / Attention(+reason + +one fix action) / Broken(+remediation) — five states preserved in + tooltips/evidence. + +Do NOT: write anything to Tally; build multi-company dashboards; alert +via any external channel (in-app only in v1). + +Tests (simulator + Edu instance): +- the tamper-catch scenario end-to-end: edit one, back-date one, delete + one in the fixture; drift report lists exactly those three with diffs; +- back-dated voucher outside any recent window is caught (date-unbounded + index scan or segment coverage proof); +- truncated/failed scan produces ZERO tombstones and an honest Partial; +- AlterID regression triggers re-baseline UX state, not tamper alarm; +- beacon state machine: failure preserves last-verified; staleness + transitions at thresholds; no state renders a bare green. + +Exit criterion: demo proof points 1 and 2 (tamper catch, completeness +under fire) pass live; drift pack exports. +``` + +### 4.2 Adversarial review prompt + +```text +ROLE: adversarial reviewer for PHASE 3 (Drift Sentinel + Beacon). +Confirmed findings only, file:line, concrete failure scenario. This phase +carries the product's credibility: a single false negative (missed change) +in a demo kills the wedge. Severity-rank accordingly. + +Hunt specifically for: +1. False negatives: segment boundary off-by-one (voucher dated on the FY + boundary scanned by neither segment); back-dated voucher into an + already-verified month escaping because only recent segments re-scan; + master edits that don't bump the probed high-water mark; voucher-type + filter blind spots (all 24 types covered by the scan?). +2. False tombstones: scan marked complete despite truncation/cap hit; + per-segment completeness conflated with whole-scan completeness; + company with books-from date later than scan start treated as deletion. +3. False tamper alarms: backup-restore (AlterID regression) path actually + reachable and calm; Tally company rename mid-scan; checkpoint bound to + name not GUID anywhere. +4. Beacon dishonesty: any code path where a render shows Verified without + a timestamp, or where an in-flight attempt hides a previous failure, or + where "next check" lies when the scheduler is off/backgrounded. +5. Performance landmines: scan concurrency vs a CA actively typing in + Tally (request spacing honored? cancellable mid-segment?); memory on + 500k-row index scans (streaming, not Vec-everything?). +6. Evidence gaps: drift rows without scan-receipt linkage; diffs computed + against a mirror state that wasn't the checkpoint's state (history + versioning correct?). +7. Privacy: drift PDF/JSON pack leaking full narrations/GSTINs beyond what + the operator explicitly exported; log redaction on diff paths. +``` + +### 4.3 Rectification prompt + +Phase 1 rectification contract, substituting "PHASE 3". Additional rule for this phase: + +```text +For any finding in category 1 or 2 (false negatives / false tombstones), +the regression test must be an end-to-end simulator scenario, not a unit +test of the diff function alone — the demo-killing bugs live between the +layers. +``` + +### 4.4 Change-preservation gate prompt + +```text +ROLE: preservation gate for PHASE 3. PASS/FAIL with evidence. + +Must still hold: +1. Phase 1 + Phase 2 preservation checklists (re-run). +2. Read-only guarantee intact: this phase dispatches zero imports; grep + changed code for the import/dispatch surface; allowlist untouched. +3. Snapshot pipeline unaffected: full-snapshot tests green; incremental + scans and full snapshots cannot interleave into a corrupted checkpoint + (concurrency test). +4. bridge-tally-incremental public contract: existing tests green + unmodified (wiring, not rewriting). +5. Request-spacing/circuit-breaker behaviour unchanged under scan load; + no scan path bypasses the single-endpoint queue. +6. Truth States: the five-state model still exists internally; compression + is render-only (evidence views show all five). +7. Beacon adds no new network egress; no telemetry/exporter added. +``` + +--- + +## 5. PHASE 4 — Write Core & Voucher Writes (months 3–6) + +### 5.1 Implementation prompt + +```text +PHASE 4: WRITE CORE, THEN VOUCHER WRITES +Branch series: feat/tally-write-core-*, then feat/tally-voucher-writes-* +Precondition: licensed TallyPrime lab VM exists (month-2 rental). Edu is +regression-only from here on. + +Mission: reliable, evidenced writes. Masters first (name-keyed idempotency +is simpler), then vouchers (payment/receipt/journal/contra). + +Implement — write core (masters): +1. Outbox state machine in the mirror DB: + PENDING → DISPATCHING → {CONFIRMED | CONFIRMED_WITH_DIVERGENCE | REJECTED | OUTCOME_UNKNOWN} + OUTCOME_UNKNOWN → probe → {CONFIRMED | CONFIRMED_WITH_DIVERGENCE | PENDING | MANUAL} + `CONFIRMED_WITH_DIVERGENCE` is the terminal state when readback (step 4) + proves the write landed but Tally normalized/dropped a field vs intent; + it is a distinct persisted state, never collapsed into `CONFIRMED`, and it + surfaces in the Gap Map. Aggregations that report "posted & clean" must + count only `CONFIRMED`; divergence is "posted, review". No auto-retry from + this state (the write succeeded). + Row durably committed (fsync) BEFORE dispatch, carrying: intent digest, + canonical payload, idempotency key, company GUID, operation kind, + pre-image AlterID (alters). +2. Batch size exactly 1 object per import request. Delete/replace + MAX_LEDGER_WRITE_BATCH. +3. Single-writer actor owns the import surface; reads gated during + dispatch→readback windows; queue depth visible. +4. Readback verification: after counters accept, re-export the object + (masters by normalized name; vouchers by LASTVCHID) and + ALWAYS cross-check the fetched object against the idempotency key and + the (date, amount, ledger-set, voucher-type) fingerprint before + promoting to CONFIRMED — LASTVCHID can be clobbered by a foreign + writer between import and readback. Mismatch → key-search fallback → + else OUTCOME_UNKNOWN. Persist the BridgeID ↔ GUID/MasterID binding. + Field-diff readback vs intent; divergence → CONFIRMED_WITH_DIVERGENCE, + surfaced in the Gap Map, never silent. +5. OutcomeUnknown recovery: on restart, DISPATCHING rows → probe by key + + fingerprint. A probe MATCH is not itself a confirmation: run the SAME + full field-level readback diff as the normal dispatch path (step 4) and + resolve to `CONFIRMED` or `CONFIRMED_WITH_DIVERGENCE` — never promote to + `CONFIRMED` on key+fingerprint alone (Tally can retain both identifiers + while normalizing/dropping other fields, which would report a divergent + write as clean). Re-dispatch ONLY on an unambiguous ABSENCE PROOF that + cannot be confused with an edited prior write: because a crash can be + followed by a foreign edit that changes the narration and a fingerprint + field (so a real prior write matches neither probe), a mere "not found by + probe" is inconclusive → stay `OUTCOME_UNKNOWN` or escalate to `MANUAL`, + never re-dispatch. Alter with foreign AlterID bump → `MANUAL`. Bounded + retries (3, backoff) only from a proven-absent state, then `MANUAL` with + evidence. + +Implement — voucher writes (after masters CONFIRMED-path is soak-tested): +6. Voucher Create for payment/receipt/journal/contra with full lines, + bill allocations, narration. Idempotency: client UUID in a UDF + (BridgeTxnID, defined via inline TDL per request) with narration-suffix + fallback — WHICH of the two is authoritative is a per-version + compatibility claim qualified on the licensed lab. The fingerprint + check is mandatory secondary dedupe regardless (narration is user- + editable; never trust the embedded key alone on re-dispatch). +7. Cancel qualified as the compensation primitive (ACTION=Cancel by + REMOTEID/GUID). Alter-by-GUID qualified per version; where flaky, the + fallback is a Cancel+Create saga bound in one outbox transaction with + crash recovery between legs. Delete only with mirror-side reference + pre-check; always readback-verified by absence + next-scan absence. +8. Every CONFIRMED write emits a signed receipt row (payload digest, + response digest, readback digest, operator, approver, timestamps, + company GUID) — the Proof-of-Post substrate. +9. Qualification runs on the licensed lab populate the compatibility + matrix per (product, release, operation); Edu results are labeled + education-mode and never Verified. + +Tests (the non-negotiable five, plus unit coverage): +- crash mid-dispatch → restart → recovery resolves to exactly-once (probe + finds the voucher → CONFIRMED; or absent → re-dispatch), proven by final + Tally state in the simulator AND on the licensed lab. Use an OS-agnostic + crashpoint: a test-only injected panic/abort at the point between "outbox + row committed" and "response parsed" is the primary mechanism (runs on the + Windows matrix targets). Where an external process kill is used, it must be + cross-platform — `taskkill /F /PID` on Windows, `kill -9` on POSIX — and the + licensed-lab evidence must record the Windows result specifically, since the + compatibility matrix targets Windows; +- duplicate re-dispatch with edited narration (key destroyed) is still + caught by the fingerprint check; +- foreign writer interleaves between import and readback → LASTVCHID + cross-check catches it (no false CONFIRM); +- alter with concurrent foreign edit → MANUAL, never blind retry; +- company not on allowlist / company mismatch → blocked below the + command layer. + +Exit criteria: ledger create/alter Verified on licensed lab with +kill-test; voucher create/cancel Verified for the four types; matrix rows +signed; zero unexplained/duplicated/missing vouchers across a 500-voucher +soak. +``` + +### 5.2 Adversarial review prompt + +```text +ROLE: adversarial reviewer for PHASE 4 (writes). This is the highest-risk +phase in the product's life: a single duplicated or vanished voucher at a +design partner ends adoption. Confirmed findings only; assume hostile +conditions (power cuts, foreign writers, flaky Tally versions). + +Hunt specifically for: +1. Exactly-once holes: any path where a row can dispatch twice without + passing BOTH the embedded-key probe and the fingerprint check; fsync + ordering (row durable before HTTP leaves?); crash between outbox commit + and dispatch vs between dispatch and response — are both distinguishable + on recovery? +2. Readback lies: promoting CONFIRMED from counters alone anywhere; + LASTVCHID used without cross-check; readback racing the next queued + write (actor gating actually enforced?); CONFIRMED_WITH_DIVERGENCE + downgraded to CONFIRMED in any aggregation/UI. +3. Saga integrity: Cancel+Create fallback — crash after Cancel, before + Create: is the books-state honestly represented and the recovery path + tested? Can the saga half-apply invisibly? +4. Idempotency-key fragility: UDF definition rejected by a Tally version + → does the write proceed keyless (finding!) or fail closed pending + qualification? Narration suffix colliding with user content? Key + surviving voucher Alter by a foreign writer? +5. Gate integrity: allowlist checked at actor level for EVERY operation + kind incl. Cancel/Delete/saga legs; approval evidence bound to the + exact payload digest (approve-then-mutate impossible)? +6. Matrix honesty: any Verified row sourced from Edu/simulator; receipts + signed over the right tuple (product, release, mode, operation). +7. Blast-radius: reference pre-check for master delete racing a foreign + voucher creation (pre-check stale) — is the LINEERROR path handled as + REJECTED-with-evidence, not retry? +``` + +### 5.3 Rectification prompt + +Phase 1 rectification contract, substituting "PHASE 4". Additional rules: + +```text +- Any finding in categories 1–3 (exactly-once, readback, saga) must be + fixed with BOTH a simulator end-to-end test and, where the behavior is + version-dependent, a licensed-lab qualification run recorded as a + matrix receipt. +- No finding in this phase may be resolved by weakening a check (e.g., + dropping the fingerprint verify to make a test pass). If a check is + wrong, replace it with a stronger one and say why. +``` + +### 5.4 Change-preservation gate prompt + +```text +ROLE: preservation gate for PHASE 4. PASS/FAIL with evidence. + +Must still hold: +1. Phases 1–3 preservation checklists (re-run; especially: Drift Sentinel + scans and the write actor share the endpoint queue without starvation). +2. Read paths cannot dispatch writes: type-level proof that read profiles + cannot reach the import surface (the ReadOnlyProfile boundary in + bridge-tally-read-transport is intact). +3. Allowlist default remains OFF; no migration flips existing companies on. +4. No automatic write retry beyond the bounded OutcomeUnknown probe path; + REJECTED (semantic) errors never auto-retry. +5. Checkpoint/proof semantics: a write updates the mirror only through + readback-confirmed state, never by assuming intent; snapshots and + incremental scans reconcile Bridge-originated writes without double + counting. +6. Receipts/evidence remain value-redacted (digests, not payloads) in any + exportable surface; raw XML only behind the explicit sensitive-data + reveal. +7. Simulator still covers the whole grammar (import counters, LINEERROR, + LASTVCHID) — regression suite runs without the licensed lab present + (CI must not depend on live Tally). +``` + +--- + +## 6. PHASE 5 — The Thin Product Loop (months 6–8) + +### 6.1 Implementation prompt + +```text +PHASE 5: THIN PRODUCT LOOP (Import → Review → Post → Proof) +Branch series: feat/tally-review-post-* +Precondition: Phase 4 exit criteria met. + +Mission: the first thing a CA firm USES daily. Excel/CSV in, verified +vouchers in Tally out, evidence pack in the client file. Single company +at a time. Keyboard-first. + +Implement: +1. Import (S2): Excel/CSV/paste ingestion → column-mapping step with + auto-detected chips over first 5 rows; guesses visually distinct and + confirmed once; mapping templates saved per client+source and + auto-applied ("Using saved template ✎"). Import NEVER posts: it creates + a Review batch. No PDF/OCR in this phase. +2. Review grid (S3): rows = Date | Party/Narration | Amount Dr/Cr | + Proposed Ledger | Voucher Type | Flags | Status. Filter pills as + counters (All/Ready/Needs mapping/Duplicates/Errors). Ledger + suggestions with confidence WORDS (Matched/Suggested/No match), each + with inspectable rationale ("mapped 14× previously for narrations + containing…"). History seeding: on first connect, mine the mirror's + 12 months of posted vouchers into narration→ledger candidate rules. + Rule promotion after 2 identical corrections (rules visible/editable). + Duplicate flags vs batch + mirror (fingerprint), side-by-side compare, + Skip default / Post-anyway recorded. Per-row errors in accountant + language; batch cannot advance with Errors > 0; partial submission + normal. Bulk edit: selection + set-ledger/type/date, "Accept all + Matched" (Suggested requires explicit second toggle). + Inline "+ Create ledger under " spawns a master draft ordered + before dependent vouchers in the same batch. +3. Post queue (S4): visible stepper Draft → Validated → Previewed → + Approved → Posting → Posted → Verified. Revalidation at queue time + against fresh mirror. Preview renders accountant-readable vouchers + + batch header (counts, net Dr = net Cr) + View XML disclosure. Approval + rules per company: none / any-other-user / named checker; approver + + timestamp + comment recorded and bound to the payload digest. + Posting via the Phase 4 actor (serialized, per-row live ticks, + interruptible between objects). Per-row "Posted — verifying…" → + "Verified in Tally, HH:MM" only after readback. Failed rows → + remediation list with one primary fix action each (error-translation + catalog: gateway off / wrong company / ledger missing / duplicate / + period locked / divergence), never failing the whole batch. +4. Proof-of-Post export: per-batch PDF/JSON — what was posted, who + approved, Tally response, readback verification, timestamps. Positioned + as supplementary workpaper evidence (never "MCA audit trail"). +5. Onboarding: guided connect (gateway how-to with illustrated 3-step), + company pin, allowlist enable with typed company-name confirmation, + Passport self-test ("Run connection check"). + +Tests: +- E2E simulator: 142-row CSV → review → approve → post → all rows + Verified; kill mid-batch at row 61 → resume → zero duplicates; +- mapping template round-trip; history-seeded suggestions deterministic; +- duplicate side-by-side correctness (fingerprint collision + distinct); +- error catalog: every raw condition maps to exactly one card with one + primary action; no raw XML/STATUS text in headlines; +- accessibility: full keyboard path through import→review→post. + +Exit criterion (definition of done, verbatim): one article at one real +firm posts one client's weekly register for four consecutive weeks with +zero unexplained, duplicated, or missing vouchers, and the partner +exports one Proof-of-Post pack. +``` + +### 6.2 Adversarial review prompt + +```text +ROLE: adversarial reviewer for PHASE 5 (product loop). Review as three +people: a hostile CA partner, a careless article, and an engineer. +Confirmed findings only. + +Hunt specifically for: +1. Paths from file to Tally that skip review or approval (drag-drop + shortcuts, retry flows, master drafts riding along unapproved). +2. Approval binding: batch mutated after approval (row edited, mapping + changed) still posting under the old approval; approval digest checked + at dispatch time, not queue time? +3. Suggestion honesty: confidence words backed by real rule provenance; + "Matched" ever produced by a single occurrence; rationale strings + fabricated rather than derived; history mining leaking cross-client + rules (client A's narration rules suggesting client B's ledgers). +4. Duplicate UX traps: fingerprint near-misses (same day, same amount, + different party) flagged or not; "Post anyway" decisions not recorded + in the audit feed. +5. Stepper truthfulness: any state advancing on optimistic UI; "Verified" + rendered from anything but a readback receipt; remediation retry + re-posting instead of probing first. +6. Error catalog gaps: unmapped LINEERROR falling through to raw text in + the headline; wrong-company card actionable-but-wrong (points at + switch-workspace when Tally-side switch is needed). +7. i18n/format: Indian digit grouping, Dr/Cr never signed, date-format + ambiguity in CSV import (DD/MM vs MM/DD) — a silent transposition is a + P0 (wrong-date vouchers posted). +8. Proof pack: includes rows that were remediated-then-posted? excludes + excluded rows explicitly? tamper-evident enough for its claim (and no + stronger claim than it can carry)? +``` + +### 6.3 Rectification prompt + +Phase 1 rectification contract, substituting "PHASE 5". Additional rule: + +```text +Findings in categories 1, 2, 5 and the date-transposition case are +release-blocking regardless of severity label: fix with E2E tests. UX +polish findings (3, 6 wording, 8 formatting) may batch into a follow-up +PR only if they cannot cause a wrong posting. +``` + +### 6.4 Change-preservation gate prompt + +```text +ROLE: preservation gate for PHASE 5. PASS/FAIL with evidence. + +Must still hold: +1. Phases 1–4 preservation checklists (re-run). +2. The write actor remains the ONLY dispatch path; UI holds no transport + handles; grep for invoke() surfaces that reach import besides the + outbox commands. +3. Drift Sentinel + Beacon unaffected by product-loop load (scan + batch + post concurrency test); Beacon never shows Verified during an + in-flight batch's unverified rows. +4. Evidence views (Passport, Gap Map, receipts) still reachable — demoted + to the Evidence section, not deleted. +5. Proof-of-Post claims audited: no "MCA/statutory audit trail" language + anywhere in UI/docs/marketing strings. +6. Mapping rules and history mining are strictly per-company scoped + (test: two companies, disjoint suggestions). +7. Onboarding never auto-enables the write allowlist; typed confirmation + required; fresh install is read-only end to end. +``` + +--- + +## 7. ORCHESTRATOR prompts + +### 7.1 Master orchestrator (session-level) + +```text +ROLE: Orchestrator for the Bridge × Tally roadmap. +Authority documents, in precedence order: +1. docs/tally/IMPROVEMENT_PLAN_2026H2.md (current plan) +2. docs/tally/PROMPT_PLAYBOOK.md (this file) +3. docs/tally/TALLY_INTEGRATION_RESEARCH_AND_CODEX_PLAN.md (legacy; + superseded where they conflict — see GLOBAL RULES) + +Loop, until stopped: +1. ORIENT: read the plan's roadmap table, the repo's open PRs/branches, + and the compatibility matrix. Determine the current phase = the lowest- + numbered phase whose exit criterion is not yet met with evidence. + Never skip a phase gate because later work "seems parallelizable" — + the only sanctioned parallelism is: Phase 3 UI work may overlap + Phase 2 backend once Phase 2's schema is merged. +2. DECOMPOSE: split the phase's implementation prompt into PR-sized units + (one invariant per PR, reviewable in under ~600 diff lines where + possible; deletions exempt). +3. EXECUTE the cycle per PR unit: + a. Run the phase IMPLEMENTATION prompt (scoped to the unit) + GLOBAL + RULES. + b. Run the phase ADVERSARIAL REVIEW prompt on the diff. Reviews must + be performed by a fresh context that did not write the code. + c. If CONFIRMED P0/P1 findings exist: run the RECTIFICATION prompt, + which (per AGENTS.md) opens a `Bug` issue and lands each non-security + defect as its own `Rectify` PR with root-cause + regression check — + security-sensitive findings go private via SECURITY.md instead. Then + return to (b). Hard limit: 4 review/rectify cycles per unit — if + findings persist after 4, STOP and escalate to the founder with the + unresolved findings; do not merge, do not descope silently. + d. Run the phase PRESERVATION GATE prompt. Any FAIL → rectify → back + to (b), because preservation fixes are changes too. + e. Open the PR with the required body. CI must be green. +4. PHASE GATE (see 7.2) before declaring a phase done. +5. RECORD: after each merged PR, append one line to docs/tally/ + EXECUTION_LOG.md: date, PR, invariant established, evidence link + (test name / matrix receipt). This log is the orientation input for + step 1 of the next iteration. + +Standing rules for you, the orchestrator: +- You never write code and review it in the same context. +- You never mark a phase exit criterion met without naming the artifact + that proves it (test run, matrix receipt, demo recording note). +- Scope creep from ANY prompt (including reviewer suggestions) is parked + in a BACKLOG.md list, not implemented. +- If two prompts in this playbook conflict, the phase's preservation gate + wins, then GLOBAL RULES, then the implementation prompt. +- If reality contradicts the plan (a Tally behavior, a crate assumption), + STOP the unit, write a one-paragraph deviation note with evidence, get + founder sign-off, then amend the plan file BEFORE coding around it. +``` + +### 7.2 Phase-gate advancement prompt + +```text +ROLE: Phase-gate auditor. Input: a claim that phase N is complete. +You are hostile to the claim. Output: ADVANCE or BLOCKED with reasons. + +Procedure: +1. Quote the phase's exit criterion verbatim from the plan. +2. For each clause, demand the artifact: test output, signed matrix + receipt, migration applied, demo scenario transcript, log entry. + Re-run the decisive tests yourself; do not trust pasted output. +3. Run ALL preservation gates from phases 1..N (cumulative, not just N). +4. Check the negative space: list everything the phase prompt said + "Do NOT" — verify none of it leaked in (grep, diff scan). +5. Check honesty surfaces: README, docs/tally, UI strings — no claim + exceeds current evidence (no "Verified" language for Edu-only results, + no write claims beyond qualified operations, no marketing adjectives + without a receipt). +6. Verdict: + - ADVANCE: every clause evidenced, preservation cumulative-green, + honesty surfaces clean. Name the next phase and its first PR unit. + - BLOCKED: numbered list of missing artifacts/failures, each with the + smallest action that would unblock it. +``` + +### 7.3 Cycle-controller prompt (per PR unit, if running semi-automated) + +```text +ROLE: Cycle controller for one PR unit of phase N. +State machine you enforce: IMPLEMENT → REVIEW → [RECTIFY → REVIEW]* → +PRESERVE → PR. Max 4 REVIEW iterations, then ESCALATE. + +Your job each turn: +1. Name the current state and the prompt to run (from the playbook). +2. Verify the previous state actually completed: implementation = tests + listed in the prompt exist and pass; review = findings are CONFIRMED/ + WITHDRAWN with file:line; rectification = per-finding FIXED/REJECTED + with evidence; preservation = PASS/FAIL table complete. +3. Refuse transitions on missing evidence ("review says LGTM with no + findings and no citations" → rerun review with the phase's hunt list). +4. Keep a running unit ledger: findings raised/fixed/rejected, cycles + used, scope parked to backlog. +5. On ESCALATE or completion, emit the unit summary for EXECUTION_LOG.md. +``` + +### 7.4 Deviation / plan-amendment prompt + +```text +ROLE: Deviation recorder. Trigger: implementation or review discovered +that reality contradicts the plan (Tally version behavior, crate +assumption, timeline, market fact). + +Produce, in one message: +1. The plan clause contradicted (quote + file). +2. The evidence (test output, licensed-lab observation, source link). +3. Impact set: which phase prompts / preservation items / marketing + claims are affected. +4. Two options with costs: amend plan vs work around; recommend one. +5. On founder approval: the exact edit to docs/tally/IMPROVEMENT_PLAN_2026H2.md + and to the affected playbook prompts, in the same commit, with a + dated "Deviation" note. Never let code and plan diverge silently. +``` + +--- + +## 8. Quick index + +| Phase | Implement | Review | Rectify | Preserve | +|---|---|---|---|---| +| 1 Unseal & Simplify | §2.1 | §2.2 | §2.3 (canonical) | §2.4 | +| 2 Full-Fidelity Reads | §3.1 | §3.2 | §2.3 pattern | §3.4 | +| 3 Drift Sentinel + Beacon | §4.1 | §4.2 | §4.3 | §4.4 | +| 4 Write Core + Vouchers | §5.1 | §5.2 | §5.3 | §5.4 | +| 5 Thin Product Loop | §6.1 | §6.2 | §6.3 | §6.4 | +| Orchestrator | — | 7.2 gate | 7.4 deviation | 7.1 loop / 7.3 cycle | + +Later-phase work (Alter drafts, sales/purchase GST splits, bank-statement variants, multi-client worklist, master hygiene, GSTR-2B bulk resolution) reuses this template: write the implementation prompt from the plan's LATER table, clone the nearest phase's review hunt-list and preservation gate, and always run the cumulative preservation stack. diff --git a/docs/tally/README.md b/docs/tally/README.md index 938c6e7..a87a1bb 100644 --- a/docs/tally/README.md +++ b/docs/tally/README.md @@ -13,9 +13,18 @@ capability from assumption, and a completed request from a verified snapshot. current reviewed evidence. - [Privacy model](./privacy-model.md) defines what may be retained or included in diagnostics. +- [2026H2 improvement plan](./IMPROVEMENT_PLAN_2026H2.md) is the current + execution authority: market research, phase roadmap (unseal → full-fidelity + reads → Drift Sentinel → write substrate → product loop), and rulings. +- [Prompt playbook](./PROMPT_PLAYBOOK.md) holds the per-phase implementation, + review/rectification, and change-preservation prompts plus the orchestrator + loop; [Execution log](./EXECUTION_LOG.md) and [Backlog](./BACKLOG.md) are its + working files. +- [Licensed-lab qualification checklist](./LICENSED_LAB_QUALIFICATION_CHECKLIST.md) + enumerates the per-version probes that must produce compatibility receipts. - [Research and execution plan](./TALLY_INTEGRATION_RESEARCH_AND_CODEX_PLAN.md) - contains the source research, product model, threat analysis, and staged - implementation plan. + contains the original source research, product model, threat analysis, and + staged implementation plan (superseded in part — see its header note). The architectural decisions are recorded in: diff --git a/docs/tally/TALLY_INTEGRATION_RESEARCH_AND_CODEX_PLAN.md b/docs/tally/TALLY_INTEGRATION_RESEARCH_AND_CODEX_PLAN.md index 95e0c83..b3c7e8a 100644 --- a/docs/tally/TALLY_INTEGRATION_RESEARCH_AND_CODEX_PLAN.md +++ b/docs/tally/TALLY_INTEGRATION_RESEARCH_AND_CODEX_PLAN.md @@ -1,5 +1,19 @@ # Bridge × Tally: Trustworthy Integration Research and Codex Execution Plan +> **SUPERSEDED IN PART (2026-07-24).** The current execution authority is +> [IMPROVEMENT_PLAN_2026H2.md](./IMPROVEMENT_PLAN_2026H2.md) with +> [PROMPT_PLAYBOOK.md](./PROMPT_PLAYBOOK.md). Where the two conflict, the +> 2026H2 plan wins. Specifically superseded here: (a) "writes remain +> disabled until the dedicated safe-write stage" and the sealed-canary / +> attestation / dual-compile-flag machinery of PR 11 — replaced by the +> per-company runtime write allowlist plus readback-verified outbox +> substrate; (b) the data-minimisation fetch policy of §4.6 — replaced by +> full-fidelity reads into the encrypted local mirror ("full-fidelity, +> local, encrypted"); (c) `MAX_LEDGER_WRITE_BATCH = 10` — replaced by +> batch-size-1 dispatch. The protocol evidence (§2), product principles +> (§4, except 4.6), architecture (§5), test strategy (§7), threat model +> (§8), and performance rules (§9) remain in force. + **Repository:** `lamemustafa/bridge` **Research date:** 2026-07-14 diff --git a/docs/tally/compatibility/compatibility-matrix.json b/docs/tally/compatibility/compatibility-matrix.json index 6224308..2d8d6b8 100644 --- a/docs/tally/compatibility/compatibility-matrix.json +++ b/docs/tally/compatibility/compatibility-matrix.json @@ -1,7 +1,7 @@ { "schema_version": 1, "bridge_commit_sha": "be1c20cc3fd66fa1ece196505c69f26e555e4b8e", - "compatibility_surface_sha256": "bf673860787e2dee533ae668751a014cd61104658746a78b45ee91f4ec1a5421", + "compatibility_surface_sha256": "5c8258c4cc7635b3e73fb86eccc8b839c78f236753653e43c2ddc0b78e549ad0", "claims": [ { "claim_id": "erp9-6-6-3-windows-education-xml-one-company", diff --git a/docs/tally/compatibility/compatibility-surface.json b/docs/tally/compatibility/compatibility-surface.json index 4c184e5..3420e28 100644 --- a/docs/tally/compatibility/compatibility-surface.json +++ b/docs/tally/compatibility/compatibility-surface.json @@ -31,7 +31,7 @@ }, { "path": "docs/tally/TALLY_INTEGRATION_RESEARCH_AND_CODEX_PLAN.md", - "sha256": "a520779ea4c7a96839700c231c8dc13f202391e02e950b554ff4188f45a4fce9" + "sha256": "14ebd153f3fa4c96d48e5f9e1197d1198e0c3f19680ee5ab9be3e031d47a998c" }, { "path": "docs/tally/compatibility/README.md", @@ -430,5 +430,5 @@ "sha256": "5a5c6eaaba234c3cbda52dfa040ed3314f79e535f744b87bc14d8d76a2299811" } ], - "manifest_sha256": "bf673860787e2dee533ae668751a014cd61104658746a78b45ee91f4ec1a5421" + "manifest_sha256": "5c8258c4cc7635b3e73fb86eccc8b839c78f236753653e43c2ddc0b78e549ad0" }