TRELLIS1 迁移 Trellis 主导开发流程

.trellis/spec/backend/database-guidelines.md

@@ -0,0 +1,51 @@
+# Database Guidelines
+
+> Database patterns and conventions for this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's database conventions here.
+
+Questions to answer:
+- What ORM/query library do you use?
+- How are migrations managed?
+- What are the naming conventions for tables/columns?
+- How do you handle transactions?
+-->
+
+(To be filled by the team)
+
+---
+
+## Query Patterns
+
+<!-- How should queries be written? Batch operations? -->
+
+(To be filled by the team)
+
+---
+
+## Migrations
+
+<!-- How to create and run migrations -->
+
+(To be filled by the team)
+
+---
+
+## Naming Conventions
+
+<!-- Table names, column names, index names -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- Database-related mistakes your team has made -->
+
+(To be filled by the team)

.trellis/spec/backend/directory-structure.md

@@ -0,0 +1,54 @@
+# Directory Structure
+
+> How backend code is organized in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's backend directory structure here.
+
+Questions to answer:
+- How are modules/packages organized?
+- Where does business logic live?
+- Where are API endpoints defined?
+- How are utilities and helpers organized?
+-->
+
+(To be filled by the team)
+
+---
+
+## Directory Layout
+
+```
+<!-- Replace with your actual structure -->
+src/
+├── ...
+└── ...
+```
+
+---
+
+## Module Organization
+
+<!-- How should new features/modules be organized? -->
+
+(To be filled by the team)
+
+---
+
+## Naming Conventions
+
+<!-- File and folder naming rules -->
+
+(To be filled by the team)
+
+---
+
+## Examples
+
+<!-- Link to well-organized modules as examples -->
+
+(To be filled by the team)

.trellis/spec/backend/error-handling.md

@@ -0,0 +1,51 @@
+# Error Handling
+
+> How errors are handled in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's error handling conventions here.
+
+Questions to answer:
+- What error types do you define?
+- How are errors propagated?
+- How are errors logged?
+- How are errors returned to clients?
+-->
+
+(To be filled by the team)
+
+---
+
+## Error Types
+
+<!-- Custom error classes/types -->
+
+(To be filled by the team)
+
+---
+
+## Error Handling Patterns
+
+<!-- Try-catch patterns, error propagation -->
+
+(To be filled by the team)
+
+---
+
+## API Error Responses
+
+<!-- Standard error response format -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- Error handling mistakes your team has made -->
+
+(To be filled by the team)

.trellis/spec/backend/index.md

@@ -0,0 +1,30 @@
+# Backend Development Guidelines
+
+---
+
+## Overview
+
+hyb-oa backend work uses Fastify, Prisma and PostgreSQL under `server/`.
+The project-specific backend rules live in `../hyb-oa/backend-fastify-prisma.md`;
+the files in this directory are Trellis default scaffolding and may be expanded
+only when a later task needs deeper backend conventions.
+
+---
+
+## Guidelines Index
+
+| Guide | Description | Status |
+|-------|-------------|--------|
+| [hyb-oa Backend Rules](../hyb-oa/backend-fastify-prisma.md) | Current project backend rules | Current |
+| [Directory Structure](./directory-structure.md) | Module organization and file layout | Scaffold |
+| [Database Guidelines](./database-guidelines.md) | ORM patterns, queries, migrations | Scaffold |
+| [Error Handling](./error-handling.md) | Error types, handling strategies | Scaffold |
+| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | Scaffold |
+| [Logging Guidelines](./logging-guidelines.md) | Structured logging, log levels | Scaffold |
+
+---
+
+## Language
+
+Project rules are Chinese-first where they are user-facing. Short English files
+generated by Trellis may remain when they are tool-facing scaffolding.

.trellis/spec/backend/logging-guidelines.md

@@ -0,0 +1,51 @@
+# Logging Guidelines
+
+> How logging is done in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's logging conventions here.
+
+Questions to answer:
+- What logging library do you use?
+- What are the log levels and when to use each?
+- What should be logged?
+- What should NOT be logged (PII, secrets)?
+-->
+
+(To be filled by the team)
+
+---
+
+## Log Levels
+
+<!-- When to use each level: debug, info, warn, error -->
+
+(To be filled by the team)
+
+---
+
+## Structured Logging
+
+<!-- Log format, required fields -->
+
+(To be filled by the team)
+
+---
+
+## What to Log
+
+<!-- Important events to log -->
+
+(To be filled by the team)
+
+---
+
+## What NOT to Log
+
+<!-- Sensitive data, PII, secrets -->
+
+(To be filled by the team)

.trellis/spec/backend/quality-guidelines.md

@@ -0,0 +1,51 @@
+# Quality Guidelines
+
+> Code quality standards for backend development.
+
+---
+
+## Overview
+
+<!--
+Document your project's quality standards here.
+
+Questions to answer:
+- What patterns are forbidden?
+- What linting rules do you enforce?
+- What are your testing requirements?
+- What code review standards apply?
+-->
+
+(To be filled by the team)
+
+---
+
+## Forbidden Patterns
+
+<!-- Patterns that should never be used and why -->
+
+(To be filled by the team)
+
+---
+
+## Required Patterns
+
+<!-- Patterns that must always be used -->
+
+(To be filled by the team)
+
+---
+
+## Testing Requirements
+
+<!-- What level of testing is expected -->
+
+(To be filled by the team)
+
+---
+
+## Code Review Checklist
+
+<!-- What reviewers should check -->
+
+(To be filled by the team)

.trellis/spec/frontend/component-guidelines.md

@@ -0,0 +1,59 @@
+# Component Guidelines
+
+> How components are built in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's component conventions here.
+
+Questions to answer:
+- What component patterns do you use?
+- How are props defined?
+- How do you handle composition?
+- What accessibility standards apply?
+-->
+
+(To be filled by the team)
+
+---
+
+## Component Structure
+
+<!-- Standard structure of a component file -->
+
+(To be filled by the team)
+
+---
+
+## Props Conventions
+
+<!-- How props should be defined and typed -->
+
+(To be filled by the team)
+
+---
+
+## Styling Patterns
+
+<!-- How styles are applied (CSS modules, styled-components, Tailwind, etc.) -->
+
+(To be filled by the team)
+
+---
+
+## Accessibility
+
+<!-- A11y requirements and patterns -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- Component-related mistakes your team has made -->
+
+(To be filled by the team)

.trellis/spec/frontend/directory-structure.md

@@ -0,0 +1,54 @@
+# Directory Structure
+
+> How frontend code is organized in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's frontend directory structure here.
+
+Questions to answer:
+- Where do components live?
+- How are features/modules organized?
+- Where are shared utilities?
+- How are assets organized?
+-->
+
+(To be filled by the team)
+
+---
+
+## Directory Layout
+
+```
+<!-- Replace with your actual structure -->
+src/
+├── ...
+└── ...
+```
+
+---
+
+## Module Organization
+
+<!-- How should new features be organized? -->
+
+(To be filled by the team)
+
+---
+
+## Naming Conventions
+
+<!-- File and folder naming rules -->
+
+(To be filled by the team)
+
+---
+
+## Examples
+
+<!-- Link to well-organized modules as examples -->
+
+(To be filled by the team)

.trellis/spec/frontend/hook-guidelines.md

@@ -0,0 +1,51 @@
+# Hook Guidelines
+
+> How hooks are used in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's hook conventions here.
+
+Questions to answer:
+- What custom hooks do you have?
+- How do you handle data fetching?
+- What are the naming conventions?
+- How do you share stateful logic?
+-->
+
+(To be filled by the team)
+
+---
+
+## Custom Hook Patterns
+
+<!-- How to create and structure custom hooks -->
+
+(To be filled by the team)
+
+---
+
+## Data Fetching
+
+<!-- How data fetching is handled (React Query, SWR, etc.) -->
+
+(To be filled by the team)
+
+---
+
+## Naming Conventions
+
+<!-- Hook naming rules (use*, etc.) -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- Hook-related mistakes your team has made -->
+
+(To be filled by the team)

.trellis/spec/frontend/index.md

@@ -0,0 +1,31 @@
+# Frontend Development Guidelines
+
+---
+
+## Overview
+
+hyb-oa frontend work uses React, TypeScript, Vite and Tailwind under `client/`.
+The project-specific frontend/design rules live in
+`../hyb-oa/frontend-react-vite-design.md`; detailed visual facts remain in
+`docs/产品设计规则.md`.
+
+---
+
+## Guidelines Index
+
+| Guide | Description | Status |
+|-------|-------------|--------|
+| [hyb-oa Frontend Rules](../hyb-oa/frontend-react-vite-design.md) | Current project frontend/design rules | Current |
+| [Directory Structure](./directory-structure.md) | Module organization and file layout | Scaffold |
+| [Component Guidelines](./component-guidelines.md) | Component patterns, props, composition | Scaffold |
+| [Hook Guidelines](./hook-guidelines.md) | Custom hooks, data fetching patterns | Scaffold |
+| [State Management](./state-management.md) | Local state, global state, server state | Scaffold |
+| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | Scaffold |
+| [Type Safety](./type-safety.md) | Type patterns, validation | Scaffold |
+
+---
+
+## Language
+
+Project rules are Chinese-first where they are user-facing. Short English files
+generated by Trellis may remain when they are tool-facing scaffolding.

.trellis/spec/frontend/quality-guidelines.md

@@ -0,0 +1,51 @@
+# Quality Guidelines
+
+> Code quality standards for frontend development.
+
+---
+
+## Overview
+
+<!--
+Document your project's quality standards here.
+
+Questions to answer:
+- What patterns are forbidden?
+- What linting rules do you enforce?
+- What are your testing requirements?
+- What code review standards apply?
+-->
+
+(To be filled by the team)
+
+---
+
+## Forbidden Patterns
+
+<!-- Patterns that should never be used and why -->
+
+(To be filled by the team)
+
+---
+
+## Required Patterns
+
+<!-- Patterns that must always be used -->
+
+(To be filled by the team)
+
+---
+
+## Testing Requirements
+
+<!-- What level of testing is expected -->
+
+(To be filled by the team)
+
+---
+
+## Code Review Checklist
+
+<!-- What reviewers should check -->
+
+(To be filled by the team)

.trellis/spec/frontend/state-management.md

@@ -0,0 +1,51 @@
+# State Management
+
+> How state is managed in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's state management conventions here.
+
+Questions to answer:
+- What state management solution do you use?
+- How is local vs global state decided?
+- How do you handle server state?
+- What are the patterns for derived state?
+-->
+
+(To be filled by the team)
+
+---
+
+## State Categories
+
+<!-- Local state, global state, server state, URL state -->
+
+(To be filled by the team)
+
+---
+
+## When to Use Global State
+
+<!-- Criteria for promoting state to global -->
+
+(To be filled by the team)
+
+---
+
+## Server State
+
+<!-- How server data is cached and synchronized -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- State management mistakes your team has made -->
+
+(To be filled by the team)

.trellis/spec/frontend/type-safety.md

@@ -0,0 +1,51 @@
+# Type Safety
+
+> Type safety patterns in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's type safety conventions here.
+
+Questions to answer:
+- What type system do you use?
+- How are types organized?
+- What validation library do you use?
+- How do you handle type inference?
+-->
+
+(To be filled by the team)
+
+---
+
+## Type Organization
+
+<!-- Where types are defined, shared types vs local types -->
+
+(To be filled by the team)
+
+---
+
+## Validation
+
+<!-- Runtime validation patterns (Zod, Yup, io-ts, etc.) -->
+
+(To be filled by the team)
+
+---
+
+## Common Patterns
+
+<!-- Type utilities, generics, type guards -->
+
+(To be filled by the team)
+
+---
+
+## Forbidden Patterns
+
+<!-- any, type assertions, etc. -->
+
+(To be filled by the team)

.trellis/spec/guides/code-reuse-thinking-guide.md

@@ -0,0 +1,105 @@
+# Code Reuse Thinking Guide
+
+> **Purpose**: Stop and think before creating new code - does it already exist?
+
+---
+
+## The Problem
+
+**Duplicated code is the #1 source of inconsistency bugs.**
+
+When you copy-paste or rewrite existing logic:
+- Bug fixes don't propagate
+- Behavior diverges over time
+- Codebase becomes harder to understand
+
+---
+
+## Before Writing New Code
+
+### Step 1: Search First
+
+```bash
+# Search for similar function names
+grep -r "functionName" .
+
+# Search for similar logic
+grep -r "keyword" .
+```
+
+### Step 2: Ask These Questions
+
+| Question | If Yes... |
+|----------|-----------|
+| Does a similar function exist? | Use or extend it |
+| Is this pattern used elsewhere? | Follow the existing pattern |
+| Could this be a shared utility? | Create it in the right place |
+| Am I copying code from another file? | **STOP** - extract to shared |
+
+---
+
+## Common Duplication Patterns
+
+### Pattern 1: Copy-Paste Functions
+
+**Bad**: Copying a validation function to another file
+
+**Good**: Extract to shared utilities, import where needed
+
+### Pattern 2: Similar Components
+
+**Bad**: Creating a new component that's 80% similar to existing
+
+**Good**: Extend existing component with props/variants
+
+### Pattern 3: Repeated Constants
+
+**Bad**: Defining the same constant in multiple files
+
+**Good**: Single source of truth, import everywhere
+
+---
+
+## When to Abstract
+
+**Abstract when**:
+- Same code appears 3+ times
+- Logic is complex enough to have bugs
+- Multiple people might need this
+
+**Don't abstract when**:
+- Only used once
+- Trivial one-liner
+- Abstraction would be more complex than duplication
+
+---
+
+## After Batch Modifications
+
+When you've made similar changes to multiple files:
+
+1. **Review**: Did you catch all instances?
+2. **Search**: Run grep to find any missed
+3. **Consider**: Should this be abstracted?
+
+---
+
+## Gotcha: Asymmetric Mechanisms Producing Same Output
+
+**Problem**: When two different mechanisms must produce the same file set (e.g., recursive directory copy for init vs. manual `files.set()` for update), structural changes (renaming, moving, adding subdirectories) only propagate through the automatic mechanism. The manual one silently drifts.
+
+**Symptom**: Init works perfectly, but update creates files at wrong paths or misses files entirely.
+
+**Prevention checklist**:
+- [ ] When migrating directory structures, search for ALL code paths that reference the old structure
+- [ ] If one path is auto-derived (glob/copy) and another is manually listed, the manual one needs updating
+- [ ] Add a regression test that compares outputs from both mechanisms
+
+---
+
+## Checklist Before Commit
+
+- [ ] Searched for existing similar code
+- [ ] No copy-pasted logic that should be shared
+- [ ] Constants defined in one place
+- [ ] Similar patterns follow same structure

.trellis/spec/guides/cross-layer-thinking-guide.md

@@ -0,0 +1,162 @@
+# Cross-Layer Thinking Guide
+
+> **Purpose**: Think through data flow across layers before implementing.
+
+---
+
+## The Problem
+
+**Most bugs happen at layer boundaries**, not within layers.
+
+Common cross-layer bugs:
+- API returns format A, frontend expects format B
+- Database stores X, service transforms to Y, but loses data
+- Multiple layers implement the same logic differently
+
+---
+
+## Before Implementing Cross-Layer Features
+
+### Step 1: Map the Data Flow
+
+Draw out how data moves:
+
+```
+Source → Transform → Store → Retrieve → Transform → Display
+```
+
+For each arrow, ask:
+- What format is the data in?
+- What could go wrong?
+- Who is responsible for validation?
+
+### Step 2: Identify Boundaries
+
+| Boundary | Common Issues |
+|----------|---------------|
+| API ↔ Service | Type mismatches, missing fields |
+| Service ↔ Database | Format conversions, null handling |
+| Backend ↔ Frontend | Serialization, date formats |
+| Component ↔ Component | Props shape changes |
+
+### Step 3: Define Contracts
+
+For each boundary:
+- What is the exact input format?
+- What is the exact output format?
+- What errors can occur?
+
+---
+
+## Common Cross-Layer Mistakes
+
+### Mistake 1: Implicit Format Assumptions
+
+**Bad**: Assuming date format without checking
+
+**Good**: Explicit format conversion at boundaries
+
+### Mistake 2: Scattered Validation
+
+**Bad**: Validating the same thing in multiple layers
+
+**Good**: Validate once at the entry point
+
+### Mistake 3: Leaky Abstractions
+
+**Bad**: Component knows about database schema
+
+**Good**: Each layer only knows its neighbors
+
+---
+
+## Checklist for Cross-Layer Features
+
+Before implementation:
+- [ ] Mapped the complete data flow
+- [ ] Identified all layer boundaries
+- [ ] Defined format at each boundary
+- [ ] Decided where validation happens
+
+After implementation:
+- [ ] Tested with edge cases (null, empty, invalid)
+- [ ] Verified error handling at each boundary
+- [ ] Checked data survives round-trip
+
+---
+
+## Cross-Platform Template Consistency
+
+In Trellis, command templates (e.g., `record-session.md`) exist in **multiple platforms** with identical or near-identical content. This is a cross-layer boundary.
+
+### Checklist: After Modifying Any Command Template
+
+- [ ] Find all platforms with the same command: `find src/templates/*/commands/trellis/ -name "<command>.*"`
+- [ ] Update all platform copies (Markdown `.md` and TOML `.toml`)
+- [ ] For Gemini TOML: adapt line continuations (`\\` vs `\`) and triple-quoted strings
+- [ ] Run `/trellis:check-cross-layer` to verify nothing was missed
+
+**Real-world example**: Updated `record-session.md` in Claude to use `--mode record`, but forgot iFlow, Kilo, OpenCode, and Gemini — caught by cross-layer check.
+
+---
+
+## Generated Runtime Template Upgrade Consistency
+
+Some generated files are both documentation and runtime input. In Trellis,
+`.trellis/workflow.md` is parsed by `get_context.py`, `workflow_phase.py`,
+SessionStart filters, and per-turn hooks. Template changes must be validated
+against both fresh init and upgrade paths.
+
+### Checklist: After Modifying A Runtime-Parsed Template
+
+- [ ] Identify every runtime parser that reads the template, not just the file
+  writer that installs it
+- [ ] Check whether relevant syntax lives outside obvious managed regions
+  such as tag blocks
+- [ ] Verify fresh `init` output and a versioned `update` scenario that writes
+  the older `.trellis/.version`
+- [ ] Add an upgrade regression using an older pristine template fixture, then
+  assert the installed file reaches the current packaged shape
+- [ ] Update the backend spec that owns the runtime contract
+
+**Real-world example**: Codex inline mode changed workflow platform markers from
+`[Codex]` / `[Kilo, Antigravity, Windsurf]` to `[codex-sub-agent]` /
+`[codex-inline, Kilo, Antigravity, Windsurf]`. Fresh init was correct, but
+`trellis update` only merged `[workflow-state:*]` blocks and preserved stale
+markers outside those blocks. Result: upgraded projects got new hook scripts
+but old workflow routing, so `get_context.py --mode phase --platform codex`
+could return empty Phase 2.1 detail.
+
+---
+
+## Mode-Detection Probe Checklist
+
+When a CLI auto-detects a mode by probing a remote resource (e.g., checking if `index.json` exists to decide marketplace vs direct download):
+
+### Before implementing:
+- [ ] Probe runs in **ALL** code paths that use the result (interactive, `-y`, `--flag` combos)
+- [ ] 404 vs transient error are distinguished — don't treat both as "not found"
+- [ ] Transient errors **abort or retry**, never silently switch modes
+- [ ] Shared state (caches, prefetched data) is **reset** when context changes (e.g., user switches source)
+- [ ] **Shortcut paths** (e.g., `--template` skipping picker) must have the same error-handling quality as the probed path — check that downstream functions don't call catch-all wrappers
+
+### After implementing:
+- [ ] Trace every path from probe result to the mode-decision branch — no fallthrough
+- [ ] External format contracts (giget URI, raw URLs) are tested or at least documented as comments
+- [ ] Metadata reads consume a complete response or use a streaming parser — never parse a fixed-size prefix as full JSON
+- [ ] When reconstructing a composite identifier from parsed parts, verify **all** fields are included and in the **correct position** (e.g., `provider:repo/path#ref` not `provider:repo#ref/path`)
+- [ ] Verify that **action functions** called after a shortcut don't internally use the old catch-all fetch — they must use the probe-quality variant when error distinction matters
+
+**Real-world example**: Custom registry flow had 8 bugs across 3 review rounds: (1) probe only ran in interactive mode, (2) transient errors fell through to wrong mode, (3) giget URI had `#ref` in wrong position, (4) prefetched templates leaked across source switches, (5) `--template` shortcut bypassed probe but `downloadTemplateById` internally used catch-all `fetchTemplateIndex`, turning timeouts into "Template not found".
+
+**Real-world example**: Agent-session update hints fetched npm `latest` metadata with `response.read(4096)` and then parsed it as complete JSON. The `@mindfoldhq/trellis` package metadata exceeded 4 KB, so the JSON was truncated, parse failed silently, and the first session injection showed no update hint. Fix: read the complete response before parsing, and add a regression where `version` is followed by an 8 KB metadata tail.
+
+---
+
+## When to Create Flow Documentation
+
+Create detailed flow docs when:
+- Feature spans 3+ layers
+- Multiple teams are involved
+- Data format is complex
+- Feature has caused bugs before

.trellis/spec/guides/index.md

@@ -0,0 +1,79 @@
+# Thinking Guides
+
+> **Purpose**: Expand your thinking to catch things you might not have considered.
+
+---
+
+## Why Thinking Guides?
+
+**Most bugs and tech debt come from "didn't think of that"**, not from lack of skill:
+
+- Didn't think about what happens at layer boundaries → cross-layer bugs
+- Didn't think about code patterns repeating → duplicated code everywhere
+- Didn't think about edge cases → runtime errors
+- Didn't think about future maintainers → unreadable code
+
+These guides help you **ask the right questions before coding**.
+
+---
+
+## Available Guides
+
+| Guide | Purpose | When to Use |
+|-------|---------|-------------|
+| [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md) | Identify patterns and reduce duplication | When you notice repeated patterns |
+| [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md) | Think through data flow across layers | Features spanning multiple layers |
+
+---
+
+## Quick Reference: Thinking Triggers
+
+### When to Think About Cross-Layer Issues
+
+- [ ] Feature touches 3+ layers (API, Service, Component, Database)
+- [ ] Data format changes between layers
+- [ ] Multiple consumers need the same data
+- [ ] You're not sure where to put some logic
+
+→ Read [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md)
+
+### When to Think About Code Reuse
+
+- [ ] You're writing similar code to something that exists
+- [ ] You see the same pattern repeated 3+ times
+- [ ] You're adding a new field to multiple places
+- [ ] **You're modifying any constant or config**
+- [ ] **You're creating a new utility/helper function** ← Search first!
+
+→ Read [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md)
+
+---
+
+## Pre-Modification Rule (CRITICAL)
+
+> **Before changing ANY value, ALWAYS search first!**
+
+```bash
+# Search for the value you're about to change
+grep -r "value_to_change" .
+```
+
+This single habit prevents most "forgot to update X" bugs.
+
+---
+
+## How to Use This Directory
+
+1. **Before coding**: Skim the relevant thinking guide
+2. **During coding**: If something feels repetitive or complex, check the guides
+3. **After bugs**: Add new insights to the relevant guide (learn from mistakes)
+
+---
+
+## Contributing
+
+Found a new "didn't think of that" moment? Add it to the relevant guide.
+
+---
+
+**Core Principle**: 30 minutes of thinking saves 3 hours of debugging.

.trellis/spec/hyb-oa/approval-workflow.md

@@ -0,0 +1,18 @@
+# Approval And Workflow
+
+## Source Docs
+
+Read `docs/需求-统一审批中心规约.md` and the latest workflow-related Issue CSV
+before modifying approval behavior.
+
+## Rules
+
+- No self-approval.
+- Do not use `admin` as a business approver unless the Issue explicitly defines
+  an administrative fallback.
+- Approval precheck, submission, workflow snapshot and task advancement must use
+  consistent rule semantics.
+- Existing workflow snapshots are historical facts; approval advancement should
+  not drift because rules changed later.
+- Reviewer review is required after changes touching workflow, status machine,
+  approval rules, permissions or migrations.

.trellis/spec/hyb-oa/backend-fastify-prisma.md

@@ -0,0 +1,24 @@
+# Backend Fastify / Prisma
+
+## Scope
+
+Server work lives under `server/`. Prefer existing route, service, utility and
+QA script patterns over new abstractions.
+
+## Rules
+
+- Validate Prisma changes with `cd server && npm run prisma:validate`.
+- For route/service edits, run `node --check` on the touched files and the
+  focused regression listed in the Issue CSV.
+- Prisma migrations require rollback notes in Issue `Notes`.
+- Do not resolve migration drift, reset databases, or rewrite migration history
+  without explicit approval.
+- Workflow, approval and permission behavior must be verified at process level,
+  not only syntax level.
+
+## Common Checks
+
+- `cd server && node --check src/routes/reimbursements.js`
+- `cd server && node --check src/routes/workflow.js`
+- `cd server && ./scripts/regression-workflow-actions.sh`
+- `cd server && ./scripts/regression-all.sh`

.trellis/spec/hyb-oa/deployment-trialrun.md

@@ -0,0 +1,17 @@
+# Deployment / Trial Run
+
+## Public OA Boundary
+
+Public OA is quasi-production. Deployments, remote config changes and live data
+operations require explicit approval and evidence.
+
+## Rules
+
+- Use `SYNC_ENV=0 bash deploy/trialrun/deploy.sh` only when deployment is
+  approved; do not overwrite remote `.env`.
+- After deployment, report commit hash, `/ready`, public smoke results and
+  whether the user can test.
+- Real business writes are manual unless an Issue explicitly authorizes a
+  controlled test write.
+- Do not execute real payments, import bank statements, connect payment
+  providers or write ERP without a separate approved Issue.

.trellis/spec/hyb-oa/docs-and-evidence.md

@@ -0,0 +1,17 @@
+# Docs And Evidence
+
+## Source Docs
+
+Start from `docs/文档索引.md` and `docs/文档事实源状态矩阵.md`.
+
+## Rules
+
+- Prefer updating existing fact sources, module specs, manuals, evidence docs
+  or continuous Issue CSVs.
+- New documents need a reason and must be registered in both the index and
+  status matrix.
+- Old Issue CSV files are historical audit evidence and should not be rewritten
+  unless the current Issue explicitly says so.
+- For generated evidence, store report paths and conclusions, not raw secrets,
+  raw payloads, full account identifiers, invoice originals or confidential
+  business content.

.trellis/spec/hyb-oa/frontend-react-vite-design.md

@@ -0,0 +1,23 @@
+# Frontend React / Vite / Design
+
+## Source Of Truth
+
+UI work must read `docs/产品设计规则.md` first and align with the Hyinda brand
+style. For PC/mobile/WeCom pages, add Playwright or visual verification when
+reasonable.
+
+## Rules
+
+- Use existing React/Vite/Tailwind patterns and shared components before adding
+  page-local UI systems.
+- PC pages should keep dense but orderly OA layouts: clear header, filters,
+  table/list, status, details and predictable actions.
+- Mobile pages must use the unified mobile shell, card/list rows, safe-area and
+  sticky action patterns from the design rules.
+- Do not add decorative landing-page styling to operational OA pages.
+- Run `cd client && npm run typecheck && npm run build` for frontend changes.
+
+## Frozen / Boundary Items
+
+Frozen modules and Enterprise WeChat-owned HR/attendance entries must be labeled
+or hidden according to the active Issue; do not silently re-enable them.

.trellis/spec/hyb-oa/index.md

@@ -0,0 +1,25 @@
+# hyb-oa Project Specs
+
+These specs are the Trellis entry point for hyb-oa. They summarize stable
+development rules and point back to the authoritative Issue CSV and `docs/`
+fact sources.
+
+## Read Order
+
+1. `project-governance.md`
+2. The domain file matching the task.
+3. `docs/文档索引.md` and the latest relevant Issue CSV.
+
+## Domain Specs
+
+| Spec | Purpose |
+| --- | --- |
+| `project-governance.md` | Trellis-first flow, Issue CSV contract, approvals, commit rules |
+| `backend-fastify-prisma.md` | Server implementation and migration boundaries |
+| `frontend-react-vite-design.md` | React/Vite UI and design-source rules |
+| `approval-workflow.md` | OA approval/workflow/self-approval boundaries |
+| `reimbursement-invoice-ocr.md` | Reimbursement, invoice, OCR and attachment rules |
+| `wecom-boundary.md` | Enterprise WeChat ownership and API/write gates |
+| `deployment-trialrun.md` | Public deployment, smoke, live-readiness and rollback gates |
+| `docs-and-evidence.md` | Documentation reuse, evidence, Issue CSV and status matrix |
+| `security-privacy.md` | Privacy, secret handling and sensitive-data exclusions |

.trellis/spec/hyb-oa/project-governance.md

@@ -0,0 +1,31 @@
+# Project Governance
+
+## Main Rule
+
+Trellis is the development workflow coordinator. Issue CSV remains the execution
+contract and `docs/` remains the business fact source.
+
+## Required Flow
+
+- Start non-trivial work from a Trellis task with a PRD.
+- Bind the task to an Issue CSV path and Issue ID before implementation.
+- Give a concrete implementation plan before coding and wait for approval.
+- Keep edits scoped to the current Issue.
+- Update Issue statuses only after the stated Test_Method passes.
+- Commit in Chinese and include the Issue ID.
+
+## Stop Conditions
+
+- Production config, deployment, database reset, migration drift, real data
+  writes, Enterprise WeChat writes, payment actions, or destructive cleanup need
+  explicit approval.
+- Permission model, status machine, workflow engine, migration or approval-rule
+  changes require read-only reviewer review after implementation.
+
+## Current Local Commands
+
+- `python3 <plan-skill>/scripts/validate_issues_csv.py <csv>`
+- `node scripts/qa/check-process-contract.mjs --baseline --json`
+- `node scripts/qa/check-trellis-governance.mjs`
+- `git diff --check`
+- `bash scripts/check-minimal.sh`

.trellis/spec/hyb-oa/reimbursement-invoice-ocr.md

@@ -0,0 +1,16 @@
+# Reimbursement / Invoice / OCR
+
+## Source Docs
+
+Read `docs/报销发票附件规则.md` before changing reimbursement, invoice, OCR,
+duplicate detection or attachment behavior.
+
+## Rules
+
+- PDF invoice OCR is the maintained main path.
+- Image OCR remains frozen unless a later Issue explicitly reopens it.
+- Do not write raw invoice images, sensitive form values or full OCR payloads to
+  repo docs, Issue CSV, Trellis task files or chat.
+- Reimbursement flow tests should cover upload/OCR, duplicate handling,
+  submission, approval, payment batch, receipt attachment and AP export when the
+  Issue scope touches those areas.

.trellis/spec/hyb-oa/security-privacy.md

@@ -0,0 +1,19 @@
+# Security And Privacy
+
+## Never Store In Repo / Trellis / Chat
+
+- Passwords, token, Secret, private keys, EncodingAESKey.
+- Full personal accounts, full phone numbers, full email addresses where not
+  required for local config.
+- Raw invoice images, contract bodies, bank statement originals, payment
+  credentials, sensitive quotes, cost details.
+- Complete local paths to confidential company directories.
+- Enterprise WeChat raw payloads, full `sp_no`, full template IDs, full userid,
+  form values, attachments or comments.
+
+## Trellis-Specific Rules
+
+- `.trellis/workspace/` is local-only by default.
+- `.trellis/tasks/` may contain PRD and acceptance context, but only in
+  redacted form.
+- `scripts/qa/check-trellis-governance.mjs` must pass before commit.

.trellis/spec/hyb-oa/wecom-boundary.md

@@ -0,0 +1,19 @@
+# Enterprise WeChat Boundary
+
+## Ownership
+
+Enterprise WeChat owns mature HR/attendance actions: check-in, leave, missed
+punch, outing, overtime and related mobile entry. OA owns reimbursement,
+procurement, contracts, projects, payments, invoices, sensitive attachments and
+operating audit.
+
+## Rules
+
+- Enterprise WeChat API checks that need trusted IP must run from the deployment
+  server, not local.
+- Do not write Enterprise WeChat, create templates, create approvals, expand
+  real users, or enable live trials without explicit approval and an Issue CSV.
+- Approval-rule configuration cannot be fully read through official APIs; keep
+  manual backend/real-device gates where specified.
+- Messages to Enterprise WeChat must be dehydrated and link back to OA; do not
+  send sensitive attachments or business documents into native WeCom approvals.