docs(specs): clarify kiloclaw compliance rules

[jeanduplessis]

Summary

Clarifies KiloClaw billing and data-model specs so compliance work starts from consistent product rules.

Why this change is needed

Several confirmed compliance gaps were spec-authority problems rather than clear runtime bugs. Reviewers needed one source of truth for paid self-service funding rules, soft-delete behavior, bootstrap pairing requirements, and promo-code behavior before evaluating follow-on implementation PRs.

How this is addressed

• Limit payment_source and credit_renewal_at funding invariants to paid self-service rows.
• Keep trial rows and temporary org managed-active bootstrap rows outside those paid-row invariants until org billing ships.
• Align billing and data-model specs on GDPR handling by retaining KiloClaw instance and subscription rows and anonymizing ownership instead of deleting canonical state.
• Tighten creation-order language so a persisted instance row cannot be left silently unpaired after bootstrap failure.
• Clarify that standalone Stripe checkout still allows promotional codes, and that the first-month discount must use a mechanism that does not consume promo-code input.

Verification

• pnpm format
• git push passed repo hooks

Visual Changes

N/A

Reviewer Notes

Human Reviewer

• Validate that trial and temporary org managed-active carveouts match current intended product behavior and are narrow enough to stay temporary.
• Validate that retaining canonical KiloClaw rows on soft delete matches GDPR expectations for anonymized state retention.
• Validate promo-code guidance for standalone Stripe checkout. Product intent is to preserve promo-code input while still applying the intro discount through price configuration rather than a promo-code slot.

Code Reviewer Agent

Code Reviewer Notes

- Only spec files changed: `.specs/kiloclaw-billing.md` and `.specs/kiloclaw-datamodel.md`. - This PR is stack root for follow-on implementation work. Review wording consistency, not runtime behavior. - Requirements covered here came from confirmed compliance findings plus product clarification that standalone Stripe checkout must keep promo-code support.

[kilo-code-bot]

Code Review Summary

Status: 1 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
.specs/kiloclaw-billing.md	147	Temporary org bootstrap rows are exempted from payment-source invariants, but later rules still assume every payment_source='credits' row has normal credit-renewal semantics.

Other Observations (not in diff)

Issues found in unchanged code that cannot receive inline comments:

File	Line	Issue
N/A	N/A	None.

Files Reviewed (2 files)

• .specs/kiloclaw-billing.md - 1 active issue
• .specs/kiloclaw-datamodel.md - 0 active issues

Fix these issues in Kilo Cloud

---

_{Reviewed by gpt-5.4-20260305 · 1,435,153 tokens}