docs: establish the Kiwi SDD architecture control plane

[AlexStocks]

SDD Traceability

• Work package: WP0
• SDD baseline: main@0c4795ec716299598686fc7c5e0fac03a30e044d
• Primary issue: Fixes docs(sdd): establish a single architecture and delivery control plane #413
• Parent or Epic: N/A
• Related issues: N/A
• Design context: Discussions Kiwi Raft Apply Correctness：父 Issue 与子 Issue 拆分方案 #330, 决策记录：Kiwi 当前暂不支持 Multi-Key 命令（P2） #346, Kiwi Rust 与 kiwi-cpp 实现对比：可复用经验、已建 Issue 与后续优先级 #411 and the live Issue/PR inventory recorded in the SDD
• Requirements:
  • REQ-WORK-001
  • REQ-WORK-002
  • REQ-WORK-003
  • REQ-WORK-004
  • REQ-WORK-005
  • REQ-WORK-006
  • REQ-WORK-007
• Decisions:
  • D013
  • D014
  • D015
  • D016
  • D017
  • D018

Description

Establish .planning/SDD.md as Kiwi's sole authoritative architecture and delivery-control entry. The document binds current claims to an exact source and GitHub snapshot, separates current behavior from target design, defines M0-M10 milestones and WP0-WP7 work packages, and records architecture state machines, storage/Raft boundaries, dependencies, non-goals, acceptance criteria, and verification gates.

Replace the independent live state in ROADMAP.md, STATE.md, and KANBAN.md with compatibility pointers. Update repository navigation and the PR template so future implementation PRs identify one work package, one precise primary Issue, applicable REQ entries, decisions, and evidence.

Add a fail-closed SDD validator and CI job for the WP0 control plane. The validator checks the 63 Requirement definitions, 18 Decisions, 20 target-invariant mappings, all WP field contracts, the exact 20-file artifact/Diff set, current-state mirrors, Markdown links and fences, and the normative WP0 exit/verification gate text. It does not implement a general future PR-body traceability checker or authorize WP1-WP7 runtime work.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Performance improvement
• Code refactoring
• Test or verification infrastructure

Scope Completion

• This PR has one primary work-package objective.
• The primary Issue still matches the current source and PR scope.
• Fixes is used only for a completely satisfied Issue.
• Deferred acceptance items are represented by separate open Issues.
• Required documentation and documentation-specific verification are included.
• Frozen work such as Embedded Redis Hot Tier is not implemented.

Verification

• Environment: Windows PowerShell and WSL/Linux in the independent mirror D:\test\github\review\arana-db-kiwi-pr-414\source; live GitHub queries through gh.
• Commands: python -B scripts/validate_sdd.py --self-test; python -B scripts/validate_sdd.py; equivalent WSL python3 -B commands; external PR docs: establish the Kiwi SDD architecture control plane #414 contract probe; Python AST parse; GitHub Actions YAML parse; exact Base-to-Head 20-file set check; git diff --check; live Issue/PR/check/thread queries; git ls-remote branch reconciliation; three independent incremental reviews.
• Results: 20 changed artifacts closed against the SDD scope; 63 Requirement definitions, 18 Decisions, and 20 invariant mappings closed; all WP0-WP7 field contracts complete; 25 failure-path mutations fail closed; the implemented lifecycle transition and ordinary-prose Issue-keyword guard pass; Windows and WSL validators report zero errors; local incremental review found no remaining P0/P1 on Head e2bfc7deb481590a757f0034874b7f21a4a31aa2.
• Uncovered risks: Rust build, Clippy, runtime tests, integration tests, and sanitizers were not rerun locally because no Rust, Cargo, or runtime behavior changed. Fresh GitHub CI on the final Head remains required before merge.
• After merge, record the PR number, merge SHA, exact main commit, commands, environment, result, and residual risk in .planning/SDD.md before marking WP0 verified or accepted.

Checklist

• Target branch is main.
• Documentation follows the repository conventions.
• Formatting and whitespace checks pass for the changed files.
• Clippy checks pass locally — not run; no Rust changes.
• Targeted runtime tests pass locally — not run; no runtime changes.
• Required existing runtime tests pass locally — not run; no runtime changes.
• Public behavior is unchanged; Redis 8.8.1 Oracle evidence is not required for a behavior change.
• Storage/Raft behavior is unchanged; Linux/WSL fault evidence is not required for a behavior change.
• Documentation and traceability contracts are updated.
• No required documentation verification was silently skipped.
• No sensitive data, dependency, binary, or third-party license scope was added.

Additional Context

The original user checkout D:\test\github\kiwi was not modified, checked out, stashed, cleaned, or reset during this review/fix cycle. Review, implementation, probes, logs, and temporary evidence stayed under D:\test\github\review\arana-db-kiwi-pr-414. Merge remains intentionally outside this task's authorization.

Summary by CodeRabbit

• Documentation
  • Added a single authoritative project guide covering architecture, roadmap, work packages, requirements, validation gates, and current execution status.
  • Updated contributor, planning, product, and quality documentation to reference the unified project guide.
  • Clarified request flow, expiration behavior, compatibility rules, and project governance requirements.
  • Converted legacy roadmap, status, and Kanban documents into compatibility pointers.
• Project Governance
  • Added decisions covering traceability, lifecycle boundaries, persistence compatibility, Multi-Key behavior, and validation requirements.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR establishes .planning/SDD.md as the sole project authority for architecture, delivery planning, traceability, state, and verification. It converts legacy planning files into compatibility pointers, updates project documentation, and adds CI validation for the SDD control plane.

Changes

SDD control plane

Layer / File(s)	Summary
Architecture and lifecycle contracts .planning/SDD.md, .planning/REQUIREMENTS.md, docs/architecture/*, docs/quality/*	Adds architecture facts, request and storage flows, lifecycle state machines, compatibility boundaries, resource policies, linearizable-read requirements, and validation gates.
Roadmap and delivery governance .planning/SDD.md, .planning/DECISIONS.md, .planning/OPEN_QUESTIONS.md, .planning/REQUIREMENTS.md	Adds M0–M10 milestones, WP0–WP7 work packages, traceability rules, acceptance gates, frozen scope, execution state, maintenance rules, and decisions D013–D018.
Planning pointer migration and documentation alignment .planning/*, CLAUDE.md, README.md, CONTRIBUTING.md, docs/*	Makes SDD.md authoritative. Converts ROADMAP.md, STATE.md, and KANBAN.md to compatibility pointers. Updates request-flow, TTL, contributor, PRD, and documentation references.
Implementation PR and validation controls .github/pull_request_template.md, .github/workflows/ci.yml, scripts/validate_sdd.py, docs/quality/*	Requires SDD traceability and verification details. Adds validator self-tests, artifact checks, governance checks, and CI control-plane validation.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• arana-db/kiwi#371: Both PRs define Redis compatibility, stability gates, recovery rules, and validation governance.
• arana-db/kiwi#394: Both PRs update planning governance documents, including requirements and open-question rules.

Suggested labels: 📒 Documentation

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes satisfy Issue #413 by establishing SDD authority, compatibility pointers, traceability rules, validation, and CI without implementing excluded runtime work.
Out of Scope Changes check	✅ Passed	The changes remain within the documentation and delivery-control scope, including SDD validation and CI, with no runtime or deferred feature implementation.
Title check	✅ Passed	The title clearly summarizes the primary change: establishing the Kiwi SDD architecture control plane.
Description check	✅ Passed	The description is detailed and covers traceability, scope, change type, verification, checklist items, risks, and additional context.

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/kiwi-sdd-architecture

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/pull_request_template.md:
- Around line 40-46: Extend the Verification section in the pull request
template with a post-merge evidence block requesting the PR number, merge SHA,
exact main commit, and SDD evidence update. Keep the existing pre-merge fields
and exact-main flag, and align the new fields with the acceptance record
required by CONTRIBUTING.md.
- Around line 3-15: Standardize the Issue relationship convention in
`.github/pull_request_template.md` lines 3-15 and `CONTRIBUTING.md` lines 76-79:
use `Fixes` or `Closes` only when the PR fully satisfies every acceptance
criterion, and use `Refs` or `Related` for partial work; replace all `Part of`
guidance in both sites while preserving the surrounding template and
contribution instructions.

In @.planning/KANBAN.md:
- Around line 3-5: Keep milestone and work-package identifiers distinct by
replacing “M0-M6” with “WP0-WP7” in .planning/KANBAN.md lines 3-5,
.planning/README.md lines 17-19, and docs/INDEX.md lines 17-19; retain “M0-M10”
for milestones.

In @.planning/SDD.md:
- Around line 470-492: 将第 6 节明确标记为仅代表 Target，不要把 20 条不变量直接作为当前控制平面合同。围绕每条不变量补充
Section 1.2 要求的 Current、Target、Gap、Work Package 和 Acceptance 映射，至少反映 Section 4
已记录的 Storage-to-Raft 无界队列与 snapshot metadata 接受未来版本等差距；保留现有不变量内容，并使其验收门禁可追踪。
- Around line 912-918: 在 SDD.md 的“验证门禁”与 WP0 退出门禁中加入可执行检查：针对 REQUIREMENTS.md 和
DECISIONS.md 定义精确及范围化的 REQ/Decision 范围，校验定义/引用闭包并在未定义或重复状态时以非零状态失败；同时约束 WP0、主
Issue/PR 仅存在一个获认可状态条目，并验证预期输出产物已生成。将现有仅打印标识符或文件名的检查替换或补充为明确的授权状态与产物断言。

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ac869240-6db3-40cf-8e3e-6cf23ce56a53

📥 Commits

Reviewing files that changed from the base of the PR and between 0c4795e and 2c4903f.

📒 Files selected for processing (16)

• .github/pull_request_template.md
• .planning/DECISIONS.md
• .planning/KANBAN.md
• .planning/OPEN_QUESTIONS.md
• .planning/README.md
• .planning/REQUIREMENTS.md
• .planning/ROADMAP.md
• .planning/SDD.md
• .planning/STATE.md
• CLAUDE.md
• CONTRIBUTING.md
• README.md
• docs/INDEX.md
• docs/personas-and-user-stories.md
• docs/prd.md
• docs/quality/quality-gates.md

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (3)

scripts/validate_sdd.py (3)

788-797: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Derive the baseline SHA from the front matter instead of hardcoding it.

break_baseline hardcodes baseline_ref: 0c4795ec716299598686fc7c5e0fac03a30e044d. When the baseline advances, .planning/SDD.md changes but this literal does not. str.replace then performs no substitution, the mutated copy stays valid, and expect_failure reports mutation did not fail for 'baseline_ref must be a full'. That message does not identify the stale literal as the cause.

Read the current value from the copy so the mutation tracks the document.

♻️ Proposed change

     def break_baseline(candidate: Path) -> None:
         path = candidate / ".planning/SDD.md"
-        text = read_text(path).replace(
-            "baseline_ref: 0c4795ec716299598686fc7c5e0fac03a30e044d",
-            "baseline_ref: deadbeef",
-            1,
-        )
+        text = re.sub(
+            r"(?m)^baseline_ref: [0-9a-f]{40}$",
+            "baseline_ref: deadbeef",
+            read_text(path),
+            count=1,
+        )
         path.write_text(text, encoding="utf-8")

The same coupling applies to the other literal-bound mutations, but those literals are contract text that the gate already pins. The SHA is the only value that changes on every baseline refresh.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/validate_sdd.py` around lines 788 - 797, Update break_baseline to
read the current baseline_ref value from the copied .planning/SDD.md front
matter, then replace that discovered SHA with the invalid value deadbeef. Remove
the hardcoded baseline SHA while preserving the existing mutation and
expect_failure behavior.

---

570-571: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Anchor the deprecated-keyword check to the Issue-reference form.

"Part of" in text is a plain substring test. It matches ordinary English prose in CONTRIBUTING.md and docs/prd.md, for example "Part of the request path". The error message then reports a deprecated partial-Issue keyword that is not present. Match the keyword only when it introduces an Issue reference.

♻️ Proposed change

-        if "Part of" in text:
+        if re.search(r"(?mi)\bPart of\b\s*:?\s*(?:#\d+|https://github\.com/)", text):
             errors.append(f"deprecated partial-Issue keyword remains in {relative}")

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/validate_sdd.py` around lines 570 - 571, Update the
deprecated-keyword check in the validation logic around the “Part of” test so it
matches only the Issue-reference form, not ordinary prose such as “Part of the
request path.” Preserve the existing error reporting and use a pattern that
requires “Part of” to introduce an Issue reference.

---

645-654: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add failure-path coverage for the Markdown gate.

Every mutation calls validate with check_markdown=False. validate_markdown therefore has no failure-path coverage, although line 104 lists Markdown link and fence checks as a WP0 verification gate. Add at least one mutation that injects a broken relative link and one that injects an unpaired fence, then run those two mutations with check_markdown=True.

The copied contract contains only the 20 registry artifacts, so a link that points outside the registry would break in the temporary directory. Scope the markdown-enabled mutations to a single copied file to avoid that.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/validate_sdd.py` around lines 645 - 654, The expect_failure test
helper currently disables Markdown validation for every mutation, leaving
validate_markdown failure paths uncovered. Add mutations for a broken relative
link and an unpaired fence, apply each to a single copied registry artifact, and
invoke validate with check_markdown=True while preserving the existing checks
for other mutations.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/ci.yml:
- Around line 40-42: Update the actions/checkout step in the CI workflow to set
persist-credentials to false alongside fetch-depth, ensuring the GitHub token is
not retained in .git/config after checkout.

In `@scripts/validate_sdd.py`:
- Around line 218-222: Update validate_registries to handle absent
.planning/REQUIREMENTS.md and .planning/DECISIONS.md before calling read_text,
allowing validation to continue and produce the existing missing WP0 artifact
error instead of raising FileNotFoundError. Preserve the current registry
parsing behavior when both files exist.

---

Nitpick comments:
In `@scripts/validate_sdd.py`:
- Around line 788-797: Update break_baseline to read the current baseline_ref
value from the copied .planning/SDD.md front matter, then replace that
discovered SHA with the invalid value deadbeef. Remove the hardcoded baseline
SHA while preserving the existing mutation and expect_failure behavior.
- Around line 570-571: Update the deprecated-keyword check in the validation
logic around the “Part of” test so it matches only the Issue-reference form, not
ordinary prose such as “Part of the request path.” Preserve the existing error
reporting and use a pattern that requires “Part of” to introduce an Issue
reference.
- Around line 645-654: The expect_failure test helper currently disables
Markdown validation for every mutation, leaving validate_markdown failure paths
uncovered. Add mutations for a broken relative link and an unpaired fence, apply
each to a single copied registry artifact, and invoke validate with
check_markdown=True while preserving the existing checks for other mutations.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8319f7ef-dd6d-4d8b-a999-ed345ab2179f

📥 Commits

Reviewing files that changed from the base of the PR and between 2c4903f and b3afe55.

📒 Files selected for processing (12)

• .github/pull_request_template.md
• .github/workflows/ci.yml
• .planning/DECISIONS.md
• .planning/KANBAN.md
• .planning/REQUIREMENTS.md
• .planning/SDD.md
• CONTRIBUTING.md
• docs/INDEX.md
• docs/architecture/redis-8.8.1-system-boundaries.md
• docs/prd.md
• docs/quality/system-stability-gate.md
• scripts/validate_sdd.py

🚧 Files skipped from review as they are similar to previous changes (8)

• .planning/KANBAN.md
• .planning/DECISIONS.md
• .github/pull_request_template.md
• CONTRIBUTING.md
• docs/prd.md
• .planning/SDD.md
• docs/INDEX.md
• .planning/REQUIREMENTS.md

[AlexStocks]

Review #4838049902 中 3 个非行内 nitpick 已在 e2bfc7d 处理：baseline mutation 通过当前 SDD front matter 的 40 位 SHA 动态派生并检查替换次数；Part of 仅在引入 Issue 引用时判定为废弃关键字，普通英文 prose 有正向防误报测试；Markdown gate 新增 broken relative link 与 unpaired fence 两个 scoped 失败路径。连同行内的 checkout 凭据和 registry 缺失处理，最终自测为 25 个失败路径变异、1 个 lifecycle transition、1 个 prose guard；Windows、WSL 及 GitHub 21/21 CI 均通过。