trellis2-official-task-contract 采用官方 Trellis 执行合同

2026-05-26 10:08:06 +08:00
@@ -2,14 +2,14 @@

 ## Source Docs

-Read `docs/需求-统一审批中心规约.md` and the latest workflow-related Issue CSV
-before modifying approval behavior.
+Read `docs/需求-统一审批中心规约.md` and the current workflow-related Trellis
+task before modifying approval behavior.

 ## Rules

 - No self-approval.
- Do not use `admin` as a business approver unless the Issue explicitly defines
-  an administrative fallback.
+- Do not use `admin` as a business approver unless the current Trellis task
+  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
@@ -9,8 +9,8 @@ QA script patterns over new abstractions.

 - 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`.
+  focused regression listed in the current Trellis task.
+- Prisma migrations require rollback notes in the Trellis task design or PRD.
 - 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,
@@ -7,11 +7,11 @@ Start from `docs/文档索引.md` and `docs/文档事实源状态矩阵.md`.
 ## Rules

 - Prefer updating existing fact sources, module specs, manuals, evidence docs
-  or continuous Issue CSVs.
+  or the current Trellis task.
 - 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.
+  unless the current Trellis task explicitly calls for a legacy/export update.
 - For generated evidence, store report paths and conclusions, not raw secrets,
  raw payloads, full account identifiers, invoice originals or confidential
  business content.
@@ -1,25 +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/`
+development rules and point back to the current Trellis task 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.
+3. The current `.trellis/tasks/<task>/prd.md` and `docs/文档索引.md`.

 ## Domain Specs

 | Spec | Purpose |
 | --- | --- |
-| `project-governance.md` | Trellis-first flow, Issue CSV contract, approvals, commit rules |
+| `project-governance.md` | Official Trellis task 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 |
+| `docs-and-evidence.md` | Documentation reuse, evidence, Trellis task and status matrix |
 | `security-privacy.md` | Privacy, secret handling and sensitive-data exclusions |
@@ -2,17 +2,22 @@

 ## Main Rule

-Trellis is the development workflow coordinator. Issue CSV remains the execution
-contract and `docs/` remains the business fact source.
+Trellis task directories are the execution contract for new hyb-oa work.
+`docs/` remains the business fact source. Historical `issues/*.csv` files remain
+audit evidence and optional export material, but they are not mandatory for new
+tasks after TRELLIS2.

 ## 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.
+- Put goal, scope, out-of-scope, acceptance and test plan in `prd.md`.
+- Add `design.md` or `implement.md` for complex process, API, migration,
+  permission, deployment or workflow-governance changes.
+- Curate `implement.jsonl` and `check.jsonl` with stable spec or research
+  context only.
 - 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.
+- Keep edits scoped to the current Trellis task.
+- Commit in Chinese and include the Trellis task name or task ID.

 ## Stop Conditions

@@ -24,8 +29,13 @@ contract and `docs/` remains the business fact source.

 ## Current Local Commands

- `python3 <plan-skill>/scripts/validate_issues_csv.py <csv>`
- `node scripts/qa/check-process-contract.mjs --baseline --json`
+- `python3 ./.trellis/scripts/task.py validate <task>`
 - `node scripts/qa/check-trellis-governance.mjs`
 - `git diff --check`
 - `bash scripts/check-minimal.sh`
+
+## Legacy Issue CSV
+
+- Do not delete, bulk rewrite or move historical `issues/*.csv` files.
+- New work may mention an old Issue CSV for traceability, but must not require
+  a new CSV unless the user explicitly requests legacy/export evidence.
@@ -12,7 +12,7 @@ operating audit.
 - 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.
+  real users, or enable live trials without explicit approval and a Trellis task.
 - 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
@@ -0,0 +1,2 @@
+{"file":".trellis/spec/hyb-oa/index.md","reason":"Verify project-specific specs are discoverable."}
+{"file":".trellis/spec/hyb-oa/project-governance.md","reason":"Verify bootstrap remains compatible with current governance."}
@@ -0,0 +1,5 @@
+# Bootstrap Design
+
+This is the generated Trellis bootstrap task. hyb-oa keeps it as historical
+setup evidence, while project-specific rules live in `.trellis/spec/hyb-oa/`.
+TRELLIS2 supersedes the old Issue CSV binding requirement for new tasks.
@@ -0,0 +1,2 @@
+{"file":".trellis/spec/hyb-oa/index.md","reason":"Project-specific hyb-oa spec entry after bootstrap."}
+{"file":".trellis/spec/hyb-oa/project-governance.md","reason":"Project governance supersedes generated bootstrap placeholders."}
@@ -6,6 +6,32 @@
 `.trellis/spec/hyb-oa/`; the generated backend/frontend scaffolds remain
 secondary.

+## Goal
+
+Capture project-specific Trellis specs so future agents follow hyb-oa
+conventions instead of generic generated placeholders.
+
+## Scope
+
+- Bootstrap project-specific Trellis specs and confirm hyb-oa conventions.
+- Treat this task as historical setup evidence after TRELLIS2.
+
+## Out Of Scope
+
+- No OA business-code changes.
+- No deployment, database write, Enterprise WeChat write or public data write.
+
+## Acceptance
+
+- hyb-oa project specs exist under `.trellis/spec/hyb-oa/`.
+- Future work can use task PRDs and JSONL spec context instead of generic
+  agent memory.
+
+## Test Plan
+
+- `python3 ./.trellis/scripts/task.py validate 00-bootstrap-guidelines`
+- `node scripts/qa/check-trellis-governance.mjs`
+
 **You (the AI) are running this task. The developer does not read this file.**

 The developer just ran `trellis init` on this project for the first time.
@@ -0,0 +1,6 @@
+# TRELLIS1 Pilot Design
+
+TRELLIS1 proved Trellis could be introduced without changing OA business code.
+Its original design intentionally bound a Trellis task to Issue CSV evidence.
+TRELLIS2 supersedes that dual-track rule and keeps this task as historical
+migration evidence.
@@ -27,3 +27,8 @@ binding to Issue CSV and project documentation.
 - The task contains issue binding and redacted scope.
 - `implement.jsonl` and `check.jsonl` include real spec context entries.
 - Trellis governance check passes.
+
+## Test Plan
+
+- `python3 ./.trellis/scripts/task.py validate 05-26-trellis1-pilot`
+- `node scripts/qa/check-trellis-governance.mjs`
@@ -0,0 +1,3 @@
+{"file":".trellis/spec/hyb-oa/project-governance.md","reason":"Check that task-first governance supersedes mandatory Issue CSV binding."}
+{"file":".trellis/spec/hyb-oa/docs-and-evidence.md","reason":"Check documentation registration and evidence boundaries."}
+{"file":".trellis/spec/hyb-oa/security-privacy.md","reason":"Check sensitive-data exclusions in Trellis governance files."}
@@ -0,0 +1,21 @@
+# TRELLIS2 Design
+
+## Decision
+
+Use the official Trellis task directory as the single execution contract for
+new work. Issue CSV remains available as historical evidence or an optional
+export format when a tabular external audit packet is needed.
+
+## Contract Shape
+
+- `task.json`: metadata, status, scope, related files and optional commit/PR.
+- `prd.md`: goal, scope, out-of-scope, acceptance and test plan.
+- `design.md` or `implement.md`: required for complex process, API, migration,
+  permission, deployment or workflow-governance changes.
+- `implement.jsonl` / `check.jsonl`: stable spec or research context only.
+
+## Compatibility
+
+Existing Issue CSV files stay in place. Existing Trellis tasks can mention
+their old Issue CSV bindings as historical metadata, but new task validation
+must not require those bindings.
@@ -0,0 +1,3 @@
+{"file":".trellis/spec/hyb-oa/project-governance.md","reason":"Defines the hyb-oa development governance contract to update."}
+{"file":".trellis/spec/hyb-oa/docs-and-evidence.md","reason":"Defines docs fact-source and evidence registration rules."}
+{"file":".trellis/spec/hyb-oa/security-privacy.md","reason":"Defines redaction boundaries for Trellis tasks, docs and reports."}
@@ -0,0 +1,49 @@
+# TRELLIS2 Official Task Contract
+
+## Goal
+
+Adopt official Trellis task-first usage for hyb-oa development governance.
+Future non-trivial work starts from `.trellis/tasks/*`; the task directory
+holds the PRD, implementation context, verification context and finish record.
+
+## Scope
+
+- Make Trellis task the execution contract for new work.
+- Keep `docs/` as the business fact source.
+- Keep historical `issues/*.csv` files for audit and legacy lookup only.
+- Update AGENTS, Trellis workflow, project governance spec, governance check,
+  project documentation and the hyb-oa delivery skill.
+
+## Out Of Scope
+
+- No backend or frontend business-code changes.
+- No deployment or public OA verification.
+- No database, Enterprise WeChat, payment, production config or real-data write.
+- No deletion, migration or bulk rewrite of historical `issues/*.csv` files.
+
+## Acceptance
+
+- New governance text says non-trivial work requires a Trellis task, not an
+  Issue CSV.
+- `scripts/qa/check-trellis-governance.mjs` validates task contract quality
+  without requiring Issue CSV bindings.
+- Current active Trellis tasks have PRD/test/scope information sufficient for
+  the new check.
+- Documentation and the project skill agree on Trellis task-first operation.
+
+## Test Plan
+
+- `python3 ./.trellis/scripts/task.py validate 05-26-trellis2-official-task-contract`
+- `python3 ./.trellis/scripts/task.py list`
+- `node --check scripts/qa/check-trellis-governance.mjs`
+- `node scripts/qa/check-trellis-governance.mjs`
+- `node scripts/qa/audit-docs.mjs --check-registry`
+- `python3 /home/shunli/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/hyb-oa-delivery`
+- `git diff --check`
+- `bash scripts/check-minimal.sh`
+
+## Privacy
+
+Do not store passwords, token, Secret, real invoice originals, contract bodies,
+bank materials, full accounts, complete local paths or raw payloads in Trellis
+tasks, docs, reports or chat.
@@ -0,0 +1,38 @@
+{
+  "id": "trellis2-official-task-contract",
+  "name": "trellis2-official-task-contract",
+  "title": "TRELLIS2 official task contract",
+  "description": "Migrate hyb-oa development governance from Issue CSV binding to official Trellis task contracts.",
+  "status": "in_progress",
+  "dev_type": "docs",
+  "scope": "trellis-governance",
+  "package": "docs",
+  "priority": "P2",
+  "creator": "shunli",
+  "assignee": "shunli",
+  "createdAt": "2026-05-26",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [
+    "AGENTS.md",
+    ".trellis/workflow.md",
+    ".trellis/spec/hyb-oa/project-governance.md",
+    "scripts/qa/check-trellis-governance.mjs",
+    "docs/Agent开发交付实践.md",
+    "docs/文档索引.md",
+    "docs/文档事实源状态矩阵.md",
+    ".agents/skills/hyb-oa-delivery/SKILL.md"
+  ],
+  "notes": "No business code, no deployment, no public OA data writes. TRELLIS2 intentionally creates no Issue CSV.",
+  "meta": {
+    "contractMode": "trellis_task",
+    "supersedesPolicy": "TRELLIS1 dual-track Issue CSV binding"
+  }
+}
@@ -2,29 +2,32 @@

 ## hyb-oa Trellis-first Overlay

-hyb-oa uses Trellis as the primary development workflow from TRELLIS1 onward.
-Trellis organizes task context and execution, while Issue CSV remains the
-auditable contract and `docs/` remains the business fact source.
+hyb-oa uses official Trellis task directories as the development contract from
+TRELLIS2 onward. Trellis owns task context, planning, execution, verification
+and finish records; `docs/` remains the business fact source. Historical
+`issues/*.csv` files are audit evidence or optional export material, not a
+mandatory prerequisite for new work.

 Required project sequence for non-trivial work:

-1. Create or update a `.trellis/tasks/<task>/` task with a PRD and acceptance notes.
-2. Bind the task to an `issues/*.csv` file and Issue ID before implementation.
+1. Create or update a `.trellis/tasks/<task>/` task with `prd.md`, acceptance notes and test plan.
+2. Add `design.md` or `implement.md` for complex process, API, migration, permission, deployment or workflow-governance changes.
 3. Read the relevant `.trellis/spec/hyb-oa/` files and project docs referenced there.
-4. Implement only after the user has approved the plan and Issue CSV.
-5. Run the task's Test_Method plus the Trellis governance gate.
+4. Implement only after the user has approved the task plan.
+5. Run the task's test plan plus the Trellis governance gate.
 6. Update specs/docs only with stable, reusable lessons.
-7. Commit in Chinese and include the Issue ID.
+7. Commit in Chinese and include the Trellis task name or task ID.

 Hard boundaries:

- Do not let Trellis replace Issue CSV status, docs fact sources, or production
-  deployment gates.
+- Do not let Trellis replace docs fact sources or production deployment gates.
+- Do not create new Issue CSV files unless the user explicitly needs a tabular
+  external audit packet or legacy compatibility export.
 - Do not auto-commit Trellis workspace/session files; `session_auto_commit` is
  disabled in `.trellis/config.yaml`.
 - Do not write passwords, token, Secret, real invoice originals, contract bodies,
  bank materials, full accounts, complete local paths, or raw payloads into
-  `.trellis/`, docs, Issue CSV, reports, or chat.
+  `.trellis/`, docs, reports, or chat.
 - In Codex, this project defaults to inline dispatch. Sub-agents are optional and
  must receive an explicit active task path if used.