Incomex AI Portal
KB-4675

S177-DESIGN-E1 — Readback & Evidence Summary (2026-05-19)

8 min read Revision 1
larks177evidencereadbacke1

S177-DESIGN-E1 — Readback & Evidence Summary

Date: 2026-05-19 Scope: Evidence/readback only. No commit, no source modification, no file move, no bot/credential, no Lark write, no deploy, no self-advance. Routing: STOP after upload → back to GPT/User.

1. Source file identity

Field Value
Source file path (VPS) /opt/incomex/docs/mcp-writes/s177-architecture-design.md
Existence CONFIRMED — readback via VPS MCP read_file returned full content
On-disk byte size 31407 bytes (authoritative — VPS write_file bytes_written)
SHA-256 0440ef92ee9f5355c16902aaf417a346b1b2a97adbd7dded360cf320763639e5
Line count 502 lines
KB copy (full doc) knowledge/dev/lark/s177-controlled-crud-gateway/s177-architecture-design-2026-05-19.md (created, rev 1)

Digest provenance / caveat: VPS has no shell/exec tool (VPS MCP exposes only read_file/write_file/list_docker/docker_logs/directus_*/pg_*), so sha256sum/wc -l could not be run server-side. SHA-256 and line count were computed locally over the byte-identical readback content. Identity binding is sound: locally recomputed byte count (31407) exactly equals the VPS write_file reported bytes_written (31407) ⇒ the hashed content is byte-identical to the on-disk file. Hash tool: shasum -a 256 (macOS; sha256sum absent locally).

2. Repo / path context

Check Result
Is source file inside a git repo? CANNOT VERIFY — no exec tool on VPS; local cwd (/Users/nmhuyen) is not a git repo; /opt/incomex not reachable via shell. /opt/incomex/docs/mcp-writes is the VPS MCP write-allowlist dir; not known to be git-tracked.
cd /opt/incomex && git status/rev-parse/branch/HEAD/ls-files NOT EXECUTABLE in this environment (no VPS shell).
Final target path /opt/incomex/docs/s177-architecture-design.md exists? NO — read_file returned [DENIED] not a regular file.
/opt/incomex/lark-client/ source inspected? NO — outside VPS read_file allowlist (/opt/incomex/docs, /opt/incomex/dot/specs, /var/log/nginx); no shell. Design built from KB architecture contract only (see OQ-1).
Git commit performed? NO (out of scope this phase; also infeasible — no exec/repo).
lark-client source modified? NO.
Bot/credential created? NO.
Lark write operations run? NO.

3. Document header (verbatim)

  • Title: S177 — Architecture Design Document: Lark Base Controlled CRUD Gateway
  • Status: DRAFT for Huyên review → then Sprint 1 implementation
  • Date: 2026-05-19
  • Source of truth: knowledge/dev/lark/s177-controlled-crud-gateway-requirements-v2.md (đề bài v2.2 FINAL, GPT R3 8.8/10)
  • Author: Claude Code (Opus 4.7)

4. Architecture overview (extract)

Two tracks (Track B CLI built first, Track A MCP adapter) → shared Application Service Layer (lark_client/service.py) → SafetyLayer (lark_client/safety.py): dry-run → approval → backup(GPG) → audit-pre → lock → rate-limit → PII-scan → API call → audit-post → LarkCore (existing) → Lark Open API open.larksuite.com.

5. Sprint plan (extract)

Sprint Deliverable Track
1 writer.py + SafetyLayer core + GPG backup + 2-phase audit + tests B
2 MCP adapter over service layer + record.get/delete MCP A
3 field_manager.py (Text/Number/SingleChoice/Checkbox) + ApprovalProvider interface + Directus prototype B
4 table/base schema ops + monitoring + full integration test A+B

6. Risk register (extract)

  • R-1 (HIGH): design not validated against live source code (could not read /opt/incomex/lark-client/) → Sprint 1 step 0 code-reconcile checklist.
  • R-2 (HIGH): audit-post fail after destructive API success → 2-phase audit + emergency fallback sink.
  • R-3 (HIGH): PII leak into logs → 2 parallel PII layers + metadata-only audit + GPG backup.
  • R-4 (HIGH): GPG private key on VPS → public-key-only on VPS, private key offline.
  • R-5 (MED): batch partial failure → stop-and-report, no auto-rollback, manual rollback cmd.
  • R-6 (MED): lark-mcp not config-extensible → custom adapter, decided Sprint 2.
  • R-7 (MED): Cowork/MCP hitting production instead of Base đệm → hard app_token allowlist.

7. Open Questions OQ-1…OQ-6 (verbatim)

  • OQ-1 (BLOCKER, R-1): This design was built from the KB architecture contract, not from reading /opt/incomex/lark-client/ (no shell/file access to that path in this environment). Sprint 1 must begin with a code-reconcile checklist: confirm actual module names/signatures of LarkCore (token method, retry, rate-lock API), Registry/bases.yaml loader, lark_client.exceptions base classes, the Click group in cli/lark_tool.py, and existing test harness conventions. Any deviation from this doc's assumed names is an implementation detail to adjust, not a redesign — but it must be checked first.
  • OQ-2: GPG key — confirm the public-key-only on VPS / private-key-offline model (§E) and who custodies the private key + GSM secret name LARK_BACKUP_GPG_PUBKEY. If Huyên wants on-VPS decryption capability, R-4 mitigation weakens — needs explicit sign-off.
  • OQ-3: PII default — confirm "detect → log metadata → proceed" (NOT block) is the intended behaviour (matches req §6 wording). Decide whether --pii-strict (abort on detection) ships in Sprint 1 or later.
  • OQ-4: Track A topology — keep the existing 9-tool @larksuiteoapi/lark-mcp mounted alongside the custom adapter, or replace it entirely with the custom server? (§F.3)
  • OQ-5: Lark batch hard limit — requirements say 500/batch; confirm against Lark Open API current limit for batch_delete specifically (some endpoints cap lower). Sprint 1 will treat 500 as the configured ceiling, overridable in config.
  • OQ-6 (process): This file was written to /opt/incomex/docs/mcp-writes/s177-architecture-design.md (the only VPS write-allowlisted dir) and was not git-committed (no exec tool / repo not in scope). Huyên or an agent with repo access must move it to the intended path and run the S177-DESIGN: commit.

REVISE-LITE (not blocked, not commit-ready as-is). The design is complete and internally consistent against requirements v2.2; no rework of substance is implied. However it must NOT be committed until OQ-1 is closed (Sprint 1 step 0 code-reconcile against live /opt/incomex/lark-client/ by an agent/operator with repo+shell access) and OQ-2/OQ-3/OQ-4 are answered by Huyên. OQ-6 is a delivery-mechanics blocker for the commit step only (path move + git commit require repo/shell access this environment lacks) — it does not affect design validity.

Disposition matrix:

  • commit: ❌ not yet (OQ-1 reconcile + OQ-6 mechanics required first)
  • revise: ⚠️ light — only pending Huyên answers to OQ-2/3/4/5; no structural change anticipated
  • blocked: ❌ design is not blocked; only the commit action is blocked by environment (OQ-6)

S177-DESIGN-E1 evidence package complete. Upload done. STOP → route to GPT/User. No self-advance.

Back to Knowledge Hub knowledge/dev/lark/s177-controlled-crud-gateway/s177-design-e1-readback-summary-2026-05-19.md