@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/apple/AGENTS.md

@@ -0,0 +1,397 @@
+# Apple Application Delivery Standard
+
+> Owner: product identity, store materials, commercial configuration and release decisions.
+> Tool: the pinned `@stackonward/cli` Apple commands. Ruby dependencies are locked in `Gemfile.lock`.
+> Runtime authentication, notifications, payment verification and entitlements belong to application services.
+
+## Project Structure
+
+```text
+app.json                 Validated product manifest
+manifest.schema.json     Distributed configuration schema
+Gemfile / Gemfile.lock   Fixed build and signing tools
+metadata/                Product-owned localized store text
+screenshots/             Product-owned store screenshots
+previews/                Product-owned videos
+review/                  Review notes and non-secret attachments
+declarations/            Product evidence and legal declarations
+.claude/docs/            Durable delivery standards
+```
+
+Private account, signing, reviewer and tester files stay outside this directory. Plans and receipts use a private state directory. Never add `.p8`, `.p12`, account passwords or signed upload URLs to version control.
+
+## Commands and Reading Order
+
+Read [.claude/docs/stack.md](.claude/docs/stack.md), [Security and Lifecycle](.claude/docs/security-lifecycle.md) and [Verification](.claude/docs/verification.md) before operations. [Architecture](.claude/docs/architecture.md) defines owners. [Index](.claude/docs/index.md) provides navigation.
+
+```bash
+stackonward apple preflight --manifest app.json --scope setup --offline
+stackonward apple plan --manifest app.json --scope setup --account /private/account.json --out /private/state/setup.json
+stackonward apple apply --manifest app.json --scope setup --account /private/account.json --plan /private/state/setup.json --yes
+stackonward apple verify --manifest app.json --scope setup --account /private/account.json
+```
+
+The private paths above are operator-selected examples. Use actual protected files; command examples never authorize price changes, tester invitations, review submission or publication.
+
+## Workflow Proportionality (CRITICAL)
+
+| Level         | Proven boundary                                             | Required workflow                                                                |
+| ------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| LOCAL         | One owner, no public-contract, security or lifecycle change | Read owner and direct consumers; correct the cause and run targeted verification |
+| FOCUSED       | One existing contract or high-risk behavior                 | Focused design and producer-consumer verification                                |
+| ARCHITECTURAL | New shared abstraction or cross-module architecture         | Complete applicable design, primary-source research and relevant review          |
+
+Semantic impact selects depth before file count or document size. Local corrections do not require architecture research. Findings expand scope only when they caused the request, were introduced by the change or block verification.
+
+## Pre-implementation Declarations (CRITICAL)
+
+For non-trivial additions, declare `PLACEMENT/NAMING` (owner, name, kind, responsibility, searched reuse and business nouns), `PATTERN / WHY / SCOPE`, `EXISTING / APPROACH / SCOPE` and `RULES / REUSE / LAYER` before editing.
+
+External calls, user-selectable alternatives, variable business policy, replaceable technology, standard extension points and multi-tenant behavior require `EXTENSIBILITY-INTENT`: signal, current and expected implementations, confidence, pattern, interface/configuration first, and exact files a second adapter would change. Otherwise state `NO-ABSTRACTION-JUSTIFICATION` and its refactor trigger.
+
+---
+
+# AI Execution Standard
+
+> Mandatory workflow for every task, regardless of language or subproject.
+> Stack-specific rules are in `.claude/docs/stack.md` and applicable nested rules.
+
+---
+
+## Phase 1: Understand
+
+Before touching code, fully understand the task and its context.
+
+### 1.1 Read Project Documentation
+
+1. Read this file for shared execution rules.
+2. Read the subproject `CLAUDE.md` for stack-specific rules, starting with `.claude/docs/stack.md`.
+3. Read subproject specs, and shared specs under `.claude/docs/` that are relevant to the task.
+4. Read existing architecture documents for affected modules.
+
+**Read specs before designing. Do not rely on memory or assumptions about project conventions.**
+
+### 1.2 Scope the Impact
+
+For each task, answer:
+
+- Which modules are affected?
+- Which files need modification?
+- Does data cross a module boundary?
+- Does this affect build or generation steps, such as manifest validation, native project configuration, signing or archive production?
+
+### 1.3 Read All Affected Source Files
+
+Read every file that will be modified. Understand:
+
+- Current function signatures and parameter types.
+- Current data structures and behavior.
+- Current data flow from input to output.
+- Existing patterns and conventions in the file.
+
+**Do not modify any file you have not read in the current session. Do not assume code shape from memory.**
+
+---
+
+## Phase 2: Design
+
+Design the solution before writing code. This is the most important phase.
+
+### 2.1 Research Industry Standards (MANDATORY)
+
+Before proposing any design, research industry best practices first. This is not optional.
+
+For every design decision, answer: "How does an industry leader solve this exact problem?"
+
+Required research sources by domain:
+
+| Domain             | Must reference                                            |
+| ------------------ | --------------------------------------------------------- |
+| API design         | Stripe API, GitHub API, Slack API                         |
+| Domain modeling    | Stripe, Shopify, AWS service models                       |
+| Event architecture | AWS EventBridge, Stripe Events, CloudEvents spec          |
+| Auth / Identity    | Auth0, AWS Cognito, Keycloak                              |
+| Audit / Logging    | AWS CloudTrail, Google Cloud Audit Logs, GitHub Audit Log |
+| Database schema    | PostgreSQL official docs and relevant mature OSS projects |
+| State machines     | Stripe payment lifecycle, AWS Step Functions              |
+
+Research output must appear as a concrete table in the design document:
+
+```markdown
+| Decision Point | Industry Pattern     | Used By         | Our Choice | Rationale                                     |
+| -------------- | -------------------- | --------------- | ---------- | --------------------------------------------- |
+| Event delivery | Transactional Outbox | Stripe, Shopify | Outbox     | Guarantees at-least-once delivery without 2PC |
+```
+
+Missing this table means the design is incomplete and implementation is forbidden.
+
+Refactoring rule: do not propose removing, replacing, or rewriting existing architecture until you have analyzed what the current design was trying to achieve and how industry leaders solve the same problem.
+
+### 2.2 Decision Autonomy (CRITICAL)
+
+AI must make standard technical decisions autonomously. Never ask the user to choose when an industry-standard answer exists.
+
+| Level          | Condition                                                                                              | Action                                                                                            |
+| -------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| **Autonomous** | Industry consensus exists; two or more major platforms use the same pattern                            | Decide and implement. State the decision and cite the standard. Do not ask                        |
+| **Recommend**  | Two or three viable options exist with clear trade-offs, and one is likely better                      | State the recommendation with reasoning. Implement the recommended option unless the user objects |
+| **Escalate**   | Genuine trade-off with no clear winner, business/product decision, or irreversible architecture choice | Present options with concrete trade-off analysis and wait for user input                          |
+
+Examples of autonomous decisions:
+
+- Outbox vs dual-write -> Outbox.
+- Soft delete vs hard delete -> Soft delete with `deleted_at`.
+- Event naming convention -> `{resource}.{action}` in past tense.
+- Pagination style -> Cursor-based for large datasets, offset for admin screens.
+- Password hashing algorithm -> bcrypt or argon2.
+- API error format -> RFC 9457-style semantics in the agreed HTTP `{ error: {...} }` envelope.
+- Idempotency mechanism -> Idempotency key header following the Stripe pattern.
+
+Examples of escalation decisions:
+
+- Which payment provider to integrate.
+- Whether to split a monolith into microservices.
+- Pricing model or billing structure.
+- Which third-party SaaS to adopt when vendor lock-in is material.
+
+The user is a developer, not an architect. If the correct technical decision is clear, make it.
+
+### 2.3 Define the Target State
+
+For each touched area, define the exact desired end state. The design must include concrete code architecture, not just a list of edits.
+
+Be concrete. "Add a status field" is insufficient. Specify exact types, constraints, behavior, and ownership.
+
+Design code architecture in the plan, not while editing files.
+
+### 2.4 Validate the Design
+
+Patch-vs-design check: before proposing a fix, ask whether the change is being made in the one place that owns the responsibility. If it is a workaround, find the owning location first.
+
+Check every design decision against the subproject's forbidden-pattern table. If any check fails, revise the design before implementation.
+
+### 2.5 Determine Design Document Level
+
+```text
+New module or major architecture change?
+  -> Level A: full architecture document
+
+Change an existing public contract or security/lifecycle boundary?
+  -> Level B: focused design document
+
+Otherwise?
+  -> Level C: fix design
+```
+
+| Level | Required output                                                                             |
+| ----- | ------------------------------------------------------------------------------------------- |
+| **A** | Complete architecture document with all mandatory sections                                  |
+| **B** | Impact scope, industry reference, schema/model/API changes, data flow, implementation waves |
+| **C** | Root cause analysis, fix design, affected files, verification plan                          |
+
+### 2.6 Self-Review Gate (MANDATORY)
+
+After completing any design or implementation, self-review before presenting work to the user.
+
+Self-review checklist:
+
+1. **Industry alignment**: For each design decision, is this what Stripe, AWS, or GitHub would do? If not, why is the deviation justified?
+2. **Pattern correctness**: Is the named pattern, such as Outbox, CQRS, or Repository, used correctly, or did the implementation invent a hybrid that violates the guarantee?
+3. **Scope creep**: Did the change add anything not requested? Did it miss anything requested?
+4. **Forbidden-pattern scan**: Grep every changed file against the forbidden-pattern tables. Zero tolerance.
+5. **Data-flow completeness**: For every new field, trace Source -> DTO -> Service -> Repository -> Entity -> VO -> Response.
+6. **Error-path coverage**: For every new code path, identify what happens on failure. It must not be silently swallowed.
+
+If any check fails, fix it before presenting. Do not present work with known issues.
+
+For Level A/B designs, use independent review only for relevant risks that deterministic checks cannot close. Select zero to three dimensions and at most two review-fix rounds unless new in-scope blocking evidence appears.
+
+### 2.7 Present Design for Approval
+
+Approval gate applies only to Level A designs.
+
+| Level | Approval behavior                                                                                                                |
+| ----- | -------------------------------------------------------------------------------------------------------------------------------- |
+| **A** | Present a concrete design; obtain approval for unapproved irreversible or business choices. Existing authorization remains valid |
+| **B** | Present design summary, then proceed to implementation. User can interrupt if needed                                             |
+| **C** | Implement directly and mention the fix rationale in the delivery message                                                         |
+
+---
+
+## Phase 3: Plan
+
+After design passes self-review, and after user approval for Level A, create the implementation plan.
+
+### 3.1 List All File Modifications
+
+For each file, state the exact path, function or section to change, and intended change.
+
+### 3.2 Map Dependencies
+
+Determine which changes depend on others. A change depends on another if it imports, references, or extends something defined by the other.
+
+### 3.3 Group Into Dependency Waves
+
+Group changes so each wave depends only on previous waves. Independent changes within one wave may be implemented in parallel.
+
+---
+
+## Phase 4: Implement
+
+### 4.1 Execute Wave by Wave
+
+For each wave:
+
+1. Implement all changes in the wave.
+2. Verify type consistency with previous waves.
+3. Proceed to the next wave only when the current wave is clean.
+
+### 4.2 Read Before Write
+
+Before modifying each file:
+
+1. Read its current content.
+2. Confirm the change is compatible with the actual file.
+3. Then apply the modification.
+
+### 4.3 Follow Existing Patterns
+
+When adding code to an existing file, match:
+
+- Naming conventions already used in that file.
+- Code style and formatting patterns.
+- Comment language and level of detail.
+- Import organization.
+
+---
+
+## Phase 5: Verify
+
+### 5.1 Build
+
+Run the subproject's build and type-check commands. All must pass.
+
+### 5.2 Design Conformance Check
+
+After build passes, verify the implementation matches the approved design. Every design item must be implemented. No silent omissions.
+
+### 5.3 Quantitative Verification
+
+Grep for expected outcomes with concrete numbers. "It compiles" is necessary but not sufficient. Count the things that should exist.
+
+### 5.4 Rule Conformance Check
+
+Re-validate actual implemented code against subproject forbidden-pattern tables. If any rule is violated, fix it before marking complete.
+
+### 5.5 Automated Review Loop for Level A/B
+
+For Level A and Level B deliveries:
+
+1. Select relevant architecture, rule or integration review dimensions that deterministic checks cannot close.
+2. Collect findings.
+3. Fix every finding.
+4. Re-run review.
+5. Complete at most two review-fix rounds unless new in-scope blocking evidence appears. Unresolved blocking findings prohibit completion.
+6. Only then present the final result.
+
+The user should receive a clean, reviewed deliverable, not a draft that depends on the user catching quality issues.
+
+---
+
+# Shared Rules
+
+Rules in this section apply to all subprojects regardless of language or framework.
+
+---
+
+## Forbidden Patterns — Shared (CRITICAL)
+
+Violation of any rule blocks commit. No exceptions.
+
+| ID    | Category      | Pattern                                                                                                                      | Fix                                                                                                                                                                                                        |
+| ----- | ------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SH-S1 | Security      | Hardcoded secrets in source                                                                                                  | Move to config/env                                                                                                                                                                                         |
+| SH-S3 | Security      | Sensitive data in logs                                                                                                       | Log IDs only; never log passwords, tokens, or PII                                                                                                                                                          |
+| SH-H2 | Hygiene       | Commented-out code                                                                                                           | Delete it; git has history                                                                                                                                                                                 |
+| SH-H5 | Hygiene       | Unused or speculative code                                                                                                   | Delete it; write only what is needed now                                                                                                                                                                   |
+| SH-I1 | Identifier    | Mixing public business numbers, business reference keys, idempotency keys, and third-party IDs in one field or naming scheme | Split identifier classes, use owner helpers, and put each semantic in the correct field                                                                                                                    |
+| SH-I2 | Identifier    | Runtime exact-match deduplication on a reference or idempotency field without a matching DB unique constraint                | Add a unique constraint on the exact lookup scope, or widen runtime lookup to the full owner scope                                                                                                         |
+| SH-D1 | Deferred      | `// TODO:` / `// 待后续` / `// 暂跳过` in committed code                                                                     | Implement completely or return an explicit error                                                                                                                                                           |
+| SH-D2 | Deferred      | Fallback branch for backward compatibility                                                                                   | Keep a single code path. Migrate data when format changes                                                                                                                                                  |
+| SH-D5 | Deferred      | Silent skip of an unsupported feature                                                                                        | Return a typed error for unsupported operations                                                                                                                                                            |
+| SH-D7 | Deferred      | `placeholder` / `stub` / `dummy` / `mock` in non-test code                                                                   | Allow only in test files. Production code must be complete                                                                                                                                                 |
+| SH-M1 | Migration     | Marking a migration complete from fresh empty-DB verification while imported databases still violate the current contract    | Audit existing imported data and ship a repair or clean re-import path before calling the migration complete                                                                                               |
+| SH-E1 | Enforcement   | Discovered violation deferred to "next time"                                                                                 | Fix it now. Rules have zero exceptions                                                                                                                                                                     |
+| SH-E2 | Enforcement   | Code delivered with known violations                                                                                         | Fix all violations before delivery                                                                                                                                                                         |
+| SH-E3 | Enforcement   | Fix applied as patch/workaround without proper design                                                                        | Make the fix architecturally sound                                                                                                                                                                         |
+| SH-E6 | Enum Registry | Cross-language enum metadata duplication, such as backend labels/colors/options plus frontend `constants/*.ts` copies        | The owning backend contract is the single source of truth for business enum metadata. Consume its declared API/generated types; pure UI variants stay local. Do not assume a platform enum endpoint exists |
+
+Additional forbidden patterns are defined in each subproject's `CLAUDE.md`. Identifier/reference boundaries are in `.claude/docs/security-lifecycle.md`.
+
+---
+
+## Delivery Discipline (CRITICAL)
+
+Every delivery must achieve zero violations against this spec.
+
+| Principle                          | Detail                                              |
+| ---------------------------------- | --------------------------------------------------- |
+| **Fix on discovery**               | Found a violation -> fix it now                     |
+| **No exemptions**                  | No pattern is too simple to follow the rules        |
+| **Design first**                   | Every fix must be designed properly, not patched    |
+| **No later**                       | "Handle later" means handle now                     |
+| **Delivery means zero violations** | Delivery with known violations is a failed delivery |
+
+---
+
+## Git History Safety (CRITICAL)
+
+- Read package.json and hook configuration. Run the installed setup command when present; never claim an absent hook script ran.
+- `git commit --amend`, branch history rewrites, rebase-based repair, and force push are forbidden. Use new normal commits only.
+- Push rejection must be resolved by fetch, inspect, merge, and new commit. Do not bypass installed hooks or claim an uninstalled gate enforces these rules.
+
+---
+
+## Deferred Code Policy (CRITICAL)
+
+Every committed line must be production-ready. There are zero exceptions.
+
+The principle: fail loudly, never silently skip. A production system that returns an error is safer than one that silently does nothing.
+
+---
+
+## Comments
+
+- Code comments: Chinese ONLY.
+- Style: explain why, not what. Skip self-explanatory code.
+- Never include ticket numbers or commented-out code.
+
+---
+
+## Reference
+
+| Doc                                     | Content                                                      |
+| --------------------------------------- | ------------------------------------------------------------ |
+| `.claude/docs/stack.md`                 | Apple delivery scopes, configuration and executable commands |
+| `.claude/docs/architecture.md`          | Types, owner boundaries and dependency direction             |
+| `.claude/docs/security-lifecycle.md`    | Trust, identity, secrets, async lifetime and recovery        |
+| `.claude/docs/verification.md`          | Full verification and delivery requirements                  |
+| `.claude/docs/architecture-template.md` | Complete Level A/B/C skeleton                                |
+
+## Project Skill Routing
+
+Use only skills available in the active environment. Read the selected entry and all applicable references before following its workflow. Explicit user scope takes precedence over generic length limits or unrelated release gates. This delivery workspace consumes the installed CLI and does not install runtime backend adapters.
+
+## Artifact Hygiene (CRITICAL)
+
+Durable standards belong in `.claude/docs/`; concrete designs and evidence belong in ordinary `docs/designs/`. Binding rules describe implemented structures and stable constraints. FORBIDDEN: conversation transcripts, repair narration, future-state assertions, dead links and invented commands.
+
+## Pre-commit Checklist
+
+- [ ] Read changed owners, nested rules, dependencies and direct consumers.
+- [ ] Contracts, enum authority, configuration and lifecycle are consistent.
+- [ ] Relevant success, validation, authorization and recovery behavior is verified.
+- [ ] Declared stack checks pass; unavailable checks are reported accurately.
+- [ ] No secrets, dead imports or deferred production code enter the diff.
+- [ ] CLAUDE.md and AGENTS.md contain the same complete standards body.
+- [ ] Normal commits preserve unrelated work and remote history.