cc-crossbeam-tw
Crossbeam TW is a source-bound document workflow for Taiwan interior-renovation submissions: route the case, check the packet, decompose corrections, and preserve the evidence needed for human review.
This repository is a prototype for architects, interior-renovation contractors, and administrative coordinators who spend more time reconciling procedures, drawings, correction notices, and missing documents than making the professional decisions themselves.
tw-law-mcp turns that work into deterministic, traceable MCP tools. A compatible assistant can inspect the local corpus and source snapshots, return the relevant artifacts and uncertainty, and stop for human confirmation when the evidence is incomplete. It is deliberately not a legal-advice or professional-sign-off system.
繁體中文說明 · Public Pages · Architecture · Acceptance evidence · v0.5.1 release notes · Contributing
Contents
Why
The difficult part of an interior-renovation submission is rarely a single lookup. The difficult part is keeping these questions connected without losing their provenance:
- Which procedure is this case actually approaching?
- Which documents, drawings, photos, and evidence belong in the submission packet?
- What does each correction item ask someone to change or confirm?
- Which source, date, gate, and professional decision support the next action?
Crossbeam TW is built around that handoff. It keeps domain logic in a standalone MCP server, makes uncertainty visible, and treats human review as a required output rather than an exception.
The current domain focus is New Taipei interior renovation. Other jurisdictions are represented by registry stubs and fail closed until their source corpus and review policy are ready.
Local-rule lifecycle
Version 0.5.0 introduced separation between legal-event dates and data-processing dates for local-government rules. A retrieval or verification timestamp is no longer allowed to silently become a promulgation, effective, or amendment date.
Version 0.5.1 closes the remaining lookup boundary: MCP get_local_rule now selects the canonical lifecycle record before returning legacy compatibility fields. A rule marked abolished, superseded, pending_reverification, ambiguous, malformed, or historically indeterminate cannot be recovered through the older corpus projection. Runtime and Python distribution versions are also kept in sync.
The first verified local-rule record is New Taipei official identifier C0170020 — 新北市建築物室內裝修審核及查驗作業事項規範. The official portal establishes a promulgation date of 2011-04-25; this repository does not have sufficient evidence to assert an effective_from or amendment date, so historical as_of_date selection intentionally fails closed until that evidence exists.
The NTPC pack keeps two evidence forms separate:
- Source snapshot — an exact, point-located source record can be citation-verified without inventing an effective date.
- Normalized requirement — point-level structured facts for points 7–11, each with an official locator and canonical hash of the normalized facts. These facts cover document evidence, simple filing, conditional fire documentation, correction/construction deadlines, and escalation conditions without pretending the normalized representation is verbatim law text.
簡易申報 is preserved as the canonical NTPC term; the legacy 簡易室內裝修 key remains only as an API compatibility alias. The generic New Taipei e-service homepage is explicitly marked discovery_reference and is not requirement evidence until a stable service/form identifier is verified.
Taipei and Taoyuan remain disabled. Enabling another jurisdiction requires an active/abolished/superseded lifecycle record, non-overlapping version selection, verified source locators, and passing lifecycle/source/scenario acceptance.
How it works
The repository has two related surfaces:
- Standalone MCP server — the host-neutral
tw-law-mcp domain boundary used by Codex, Claude Code, or another MCP client.
- Secure Web pilot — a local or single-user browser workflow for case intake, quarantine upload, masking, HITL review, artifacts, audit events, and deletion.
flowchart LR
A[Masked text + file metadata] --> B[tw-law-mcp]
B --> C[Procedure route]
B --> D[Submission packet]
B --> E[Correction items]
B --> F[Sources + lifecycle + gates]
C --> G[Human confirmation]
D --> G
E --> G
F --> G
R[Raw browser bytes] --> Q[Private quarantine]
Q --> W[Python scan + masking worker]
W --> A
G --> S[Sanitized artifacts]
The Secure Web path keeps raw bytes out of the Next.js request body, model prompt, and logs. The local Codex provider is a worker credential only; it is never the website identity provider.
Walkthrough
Captured from the running pilot against a synthetic correction notice — no real case data. Re-created by web/scripts/capture-demo.ts, which fails if any raw value from the fixture reaches a rendered page.
1. Intake — raw bytes go to private quarantine, not to Next.js. Consent is recorded with the upload intent; the browser sends the file straight to the worker.
2. After masking — evidence, and the gates that failed. Personal data is masked before analysis. Each correction item carries its own citation state: 已具證據 where the article is snapshot-verified, 候選法源，條文尚未驗證 where the corpus knows the law but not its current text, and 法源待確認 where nothing matched. citation_exists failing here is the intended result, not a defect.
3. Human confirmation is a required output. Low-confidence, professional-signature, and procedure-stage questions are asked, never inferred.
4. Response draft, with its limits stated. The draft is produced only after every question is answered, and says plainly what it is not.
The GitHub Pages site is static documentation, not a hosted instance — the pilot runs locally by design.
What it does
| Workflow | Output |
|---|
| Procedure routing | A candidate stage for drawing review, completion inspection, change-of-use plus completion inspection, or simple interior renovation, with confidence and follow-up questions. |
| Submission checks | A New Taipei document packet, missing-item list, sheet/file manifest, and source-bound references. |
| Correction handling | Masked-document parsing, atomic correction items, response-draft inputs, and a professional confirmation packet. |
| Professional-domain routing | Evidence prompts for fire equipment, fire compartments, egress, and material documentation. |
| Local-rule lifecycle | Lifecycle-aware current/historical lookup; inactive, pending, ambiguous, malformed, or indeterminate versions fail closed. |
| Auditability | Law snapshots, local-rule lifecycle/status, source policy, authority rank, license/update status, as-of dates, gate results, and human-review state. |
The server currently exposes 38 MCP tools across law lookup, source policy, procedure routing, document handling, HITL, scenario checks, and acceptance gates. The canonical tool surface is in tw_law_mcp/server.py; the complete scenario index is in docs/tw-scenario-feature-matrix.md.
Trust and security
Read the Secure Web runbook before handling real documents.
| Boundary | Rule |
|---|
| Input | Prefer masked text, metadata, and de-identified fixtures. Raw drawings and raw PDFs do not belong in an assistant prompt. |
| Quarantine | Browser uploads go directly to private quarantine and must pass scan, validation, and masking before downstream access. |
| Model | Only the minimum sanitized fields cross the model boundary. Local Codex execution is read-only, ephemeral, and isolated from the repository. |
| Domain | Taiwan procedure, source, and local-rule lifecycle logic stays in Python tw_law_mcp; the web layer does not duplicate legal decisions. |
| Uncertainty | Missing evidence, unknown legal-effective dates, pending source changes, inactive/ambiguous versions, low confidence, professional judgment, and unsupported claims fail closed and produce human-review work. |
| Production | Cloud mode rejects local auth, local storage, local DB, in-process jobs, and the local Codex provider until approved adapters and credentials exist. |
An experimental, opt-in reversible masking core (cb.mask.v1, issue #28 PR A) lives in worker/secure_worker/reversible_masking.py. It masks a UTF-8 TXT document into per-occurrence tokens and restores the original byte for byte from a private manifest, refusing on any mismatch (tampered, missing, duplicated, swapped or foreign tokens, wrong case/document/version, digest or offset errors). The manifest lives in process memory only, nothing in the upload path calls the core, and it has no endpoint, persistence, or model path; uploads still use the irreversible [MASKED_<CLASS>] masking. See ADR-0003. Privacy release and an encrypted vault (PR B), authorized restore/export (PR C) and PDF adapters (PR D) are not built.
This prototype does not:
- enable multi-user case invitations or reviewer collaboration; the current
reviewer and invitation schema is reserved for a future adapter;
- decide whether a case is legal, illegal, or an unauthorized construction;
- provide legal opinions, compliance guarantees, or professional certification;
- guarantee that an authority will approve a submission;
- decide fire-design conclusions or verify material authenticity;
- enable PDF/image parsing in the authenticated worker; only UTF-8 TXT intake is supported in the pilot.
Install
MCP server
Requirements: Python >=3.10.
git clone https://github.com/trionnemesis/cc-crossbeam-tw.git
cd cc-crossbeam-tw
python3 -m unittest discover -s tests
python3 scripts/run_local_rule_lifecycle_acceptance.py
python3 scripts/run_phase_acceptance.py
python3 scripts/tw_law_mcp_stdio.py
The repository already includes host configuration:
Secure Web pilot
Requirements: Node.js 22.x and Python 3.14 for the current CI path.
cd web
npm ci
npm run test:run
npm run typecheck
npm run lint
npm run build
npm start
In a second terminal, start the local worker:
python3 -m worker.secure_worker.server
Use web/.env.example and docs/runbook-secure-web.md for runtime modes, callback configuration, private storage, and external-credential gates. Production deployment is not implied by a green local build.
Example prompts
The safe pattern is to ask for a workflow artifact and its evidence boundary, not an unqualified legal conclusion.
Please run run_phase_acceptance with tw-law-mcp first.
Using only the masked document text and file metadata I provide, route this case
among drawing review, completion inspection, change-of-use plus completion inspection,
and simple interior renovation.
Return the procedure-stage confidence, human-confirmation questions, corpus packs,
artifacts, and reasons for anything you cannot determine.
Do not provide a legal opinion, compliance guarantee, fire-design conclusion,
material-authenticity conclusion, or approval promise.
Other useful requests:
- “Build a New Taipei completion-inspection submission packet and list missing evidence.”
- “Parse this masked correction notice into atomic items and produce a human-confirmation packet.”
- “Show the source IDs, as-of dates, failed gates, and unsupported claims behind this artifact.”
- “Look up the current New Taipei local rule and show the lifecycle status; do not return requirements if the source is pending reverification.”
Current status
This is a public prototype, not a production compliance product.
| Area | Current state |
|---|
| Domain core | 0.5.1; New Taipei interior renovation is enabled; other jurisdictions fail closed. Runtime and distribution metadata are synchronized. |
| Local-rule lifecycle | NTPC C0170020 is active and point-located; promulgation is verified as 2011-04-25; unknown effective_from causes historical as-of queries to fail closed. MCP get_local_rule is lifecycle-bound, and points 7–11 are normalized and hash-checked. |
| MCP packaging | Standalone stdio JSON-RPC subset first; Codex and Claude Code remain thin wrappers. |
| Workflow coverage | Groups 1–6 plus Phase 2.1–2.6 / Step 6: source policy, procedure/HITL, data layout, adapters, scenario tools, fixture pipeline, two-stage flow skeleton, lifecycle-aware lookup, and local-rule lifecycle acceptance. |
| Fixture evidence | 12 synthetic de-identified cases and 84 atomic correction items validate schema, gates, and HITL contract. They do not support real-case claims. |
| Secure Web | Local and single-user pilot paths cover identity, case authorization, direct quarantine upload, masking, Codex-auth worker analysis, HITL, audit, and verified deletion. |
| Still required | TPE verified lifecycle pack, TYC verified local evidence, automated official-source change monitoring, the three central-law pending snapshots tracked in #16, public Google/LINE acceptance, and a separately sandboxed PDF/image parser. |
The latest local and CI evidence is recorded in ACCEPTANCE.md. Missing external credentials are intentionally reported as pending; they are not replaced with synthetic “production accepted” claims.
Repository map
| Path | Purpose |
|---|
tw_law_mcp/ | Deterministic law/source repository, local-rule lifecycle logic, and MCP server. |
tw_law_mcp/data/local_rules/ | Versioned local-government rule records and point-level normalized requirements. |
worker/ | Secure upload, masking, domain-processing, and local model-provider boundary. |
web/ | Next.js Secure Web pilot and browser-facing workflow. |
scripts/ | stdio entrypoint, snapshots, and targeted acceptance runners. |
tests/ | Python MCP/domain/worker tests, including lifecycle/version-selection and lookup-bypass regressions. |
web/tests/ | Web, auth, upload, HITL, and security-boundary tests. |
docs/releases/v0.5.1.md | Latest hotfix release notes. |
docs/ | Pages site, ADRs, runbook, and feature matrices. |
|
Research and design
FAQ
Is this a legal-advice tool?
No. It organizes procedures, documents, sources, uncertainty, and questions for professionals. It does not issue legal opinions, compliance guarantees, or sign-off.
Can I upload a client PDF or drawing?
Not to the current authenticated worker. The pilot accepts UTF-8 TXT and metadata only. Raw files, title blocks, and unmasked personal information require an approved quarantine and parser policy first.
Why is the MCP server separate from the web app?
The domain and source-of-truth boundary should remain host-neutral. Codex, Claude Code, the Secure Web, and future consumers should call the same deterministic tools instead of copying legal logic into each surface.
Why can a current local rule be known while a historical as_of_date query still fails?
The official portal can establish that a source is currently published and identify its promulgation metadata without proving every historical effective interval. Crossbeam TW keeps those claims separate. If effective_from cannot be verified, a dated historical selection is rejected instead of treating the retrieval date as legal evidence.
What happens if an official local rule is marked pending reverification?
Lifecycle-aware lookup returns no operative requirements and requires human review. The legacy compatibility projection is consulted only after lifecycle selection has already approved the active version.
Is the Secure Web production-ready?
No. Local acceptance is documented, while live Google/LINE credentials, public HTTPS acceptance, approved production storage/model adapters, official-source refresh, and real de-identified cases remain explicit gates.
Where did the workflow idea come from?
The product workflow is informed by cc-crossbeam's document-review and correction-response flow (see Related projects for its current status). The Taiwan corpus, jurisdiction rules, source policy, and safety boundaries are implemented independently for this repository.
Related projects
- cc-crossbeam — the original document-review and correction-response workflow that this repository's product design is informed by. It is not currently published as a public repository under this account, so no working link is available; the relationship is described in the FAQ above.
- AIhouskeeperagent — a related project from the same author, covering AI-assisted operations/housekeeping agent work.
