S177-DESIGN-PATCH1 — Patch Summary

Date: 2026-05-19 Scope: Patch design document only. No code, no commit/move (not yet authorized), no lark-client source touch, no Lark write, no bot/credential, no deploy. STOP after upload. Patched doc: knowledge/dev/lark/s177-controlled-crud-gateway/s177-architecture-design-2026-05-19-patch1.md (created, rev 1) Supersedes: s177-architecture-design-2026-05-19.md (base; SHA-256 0440ef92…3639e5, 31407 B, 502 ln) — base left intact, patch1 is a separate superseding doc.

---

1. The 8 patch changes → sections changed

#	Change	Sections changed
P1	Atomic approval check-and-consume — YamlApprovalProvider takes an exclusive OS file lock on write-approvals.yaml; check + consume in one critical section; one-time = exactly one concurrent winner, others ApprovalError('already_consumed'); atomicity is part of the ApprovalProvider interface	C.3 (interface renamed check→check_and_consume + locking contract), C.1, C.2 (layer 2), B.3, A (diagram + risk R-8)
P2	MCP topology hardening — existing plugin allowed for read/list/search only; its write tools forbidden in production (bypass SafetyLayer, R-6 raised to HIGH); if host can't hide tools → replace plugin entirely	F.1, F.2, F.3, A (scope + R-6), OQ-4
P3	Configurable API limits — new config/lark-api-limits.yaml; record.batch_delete default max 100 until Lark doc/Base đệm probe; no silent truncation (over-ceiling → SafetyViolation)	B.4, G.5, A (R-5), H.2 (T6b), OQ-5
P4	$LARK_AGENT nuance — required for every real write (missing → abort); CLI may default claude-code for dry-run only; audit always includes agent (both phases)	G.3, B.1, C.6
P5	Sprint 0 / S177-R0 Code Reconcile — read-only inspection of live source (LarkCore methods, registry loader, exceptions tree, CLI Click group, config/test conventions); STOP + escalate on material drift; only clean reconcile authorizes Sprint 1	I.0 (new), A (sprint table), J (OQ-1 folded)
P6	PII policy nuance — two-rule split: (1) guarded record writes NOT blocked by default; (2) PII to plaintext/export/stdout/non-GPG → block (SafetyViolation); (3) audit + rollback cmd never raw PII	D.3, C.2 (layer 7), B.1, H.2 (T10b), OQ-3
P7	Orphan backup handling — backup written then audit-pre fails ⇒ delete-if-provably-this-attempt-safe, else append /var/log/lark-ops/orphan-backups.log (no raw PII); operator sweep runbook	C.2 (layer 4), C.6, E.5 (new), A (R-9), H.2 (T11), I Sprint 4, OQ-7 (new)
P8	Sprint 1 test split — unit/mock tests mandatory commit gate; Base đệm integration gated by LARK_TEST_INTEGRATION=1 + hard token assert, required before Sprint 1 sign-off (not for unit gate)	H.3, I Sprint 1

Net: sections A, B.1, B.3, B.4, C.1, C.2, C.3, C.6, D.3, E (new E.5), F.1, F.2, F.3, G.3, G.4, G.5, H.2, H.3, I (new Sprint 0 + all sprints), J touched. New risks R-8 (approval double-spend), R-9 (orphan backup); R-6 severity raised MED→HIGH.

2. OQ list — changed?

Yes.

• OQ-1 → folded into Sprint 0 (S177-R0) as a defined gated phase with explicit STOP rule (still the top blocker).
• OQ-3 refined → confirm the two-rule PII policy + --pii-strict timing.
• OQ-4 refined → now a concrete host-capability feasibility question (does the MCP host support tool-level hiding?) driving keep-read-only-vs-replace.
• OQ-5 refined → confirm acceptance of conservative batch_delete=100 default + the raise procedure.
• OQ-2, OQ-6 unchanged.
• OQ-7 added (new) → orphan-backup sweep runbook + grace window + no unconfirmed auto-delete.

3. Is commit now recommended?

No. PATCH1 hardens robustness (concurrency, PII egress, plugin trust, limits, orphan cleanup) but does not close the gating blockers. Commit remains gated on:

1. S177-R0 Code Reconcile (OQ-1) — design assumptions not yet checked against live /opt/incomex/lark-client/; must pass clean before any code/commit.
2. Huyên decisions on OQ-2 (GPG custodian), OQ-3 (PII policy + --pii-strict), OQ-4 (MCP host tool-hiding capability), OQ-5 (batch_delete default), OQ-7 (orphan sweep runbook).
3. OQ-6 delivery mechanics — path move + git commit require repo+shell access this environment lacks; no exec/repo here.

4. Remaining blockers

Blocker	Type	Owner	Gate
S177-R0 Code Reconcile not done	Verification	agent/operator w/ repo+shell	Sprint 0, STOP on drift
OQ-2/3/4/5/7 unanswered	Design decision	Huyên / GPT	pre-Sprint-1
Git commit + path move infeasible here	Environment	repo-access agent / Huyên	OQ-6, post-authorization
Live source never inspected	Verification	Sprint 0	same as R-1/OQ-1

Non-blockers: design is internally consistent and complete vs requirements v2.2; PATCH1 introduces no known contradictions; no structural rework anticipated — only Sprint 0 confirmation + Huyên answers.

Disposition: REVISE-LITE, NOT commit-ready. Design action not blocked; commit action blocked by Sprint 0 + Huyên answers + environment (OQ-6).

---

S177-DESIGN-PATCH1 complete. Both KB uploads done. STOP → route to GPT/User. No self-advance, no commit.