From 1b5c7527b7cdc8c1252c6158b44ec62e87281c47 Mon Sep 17 00:00:00 2001 From: shunli Date: Tue, 26 May 2026 10:08:06 +0800 Subject: [PATCH] =?UTF-8?q?trellis2-official-task-contract=20=E9=87=87?= =?UTF-8?q?=E7=94=A8=E5=AE=98=E6=96=B9=20Trellis=20=E6=89=A7=E8=A1=8C?= =?UTF-8?q?=E5=90=88=E5=90=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/skills/hyb-oa-delivery/SKILL.md | 24 +-- .trellis/spec/hyb-oa/approval-workflow.md | 8 +- .../spec/hyb-oa/backend-fastify-prisma.md | 4 +- .trellis/spec/hyb-oa/docs-and-evidence.md | 4 +- .trellis/spec/hyb-oa/index.md | 8 +- .trellis/spec/hyb-oa/project-governance.md | 26 ++- .trellis/spec/hyb-oa/wecom-boundary.md | 2 +- .../tasks/00-bootstrap-guidelines/check.jsonl | 2 + .../tasks/00-bootstrap-guidelines/design.md | 5 + .../00-bootstrap-guidelines/implement.jsonl | 2 + .trellis/tasks/00-bootstrap-guidelines/prd.md | 26 +++ .trellis/tasks/05-26-trellis1-pilot/design.md | 6 + .trellis/tasks/05-26-trellis1-pilot/prd.md | 5 + .../check.jsonl | 3 + .../design.md | 21 +++ .../implement.jsonl | 3 + .../prd.md | 49 ++++++ .../task.json | 38 +++++ .trellis/workflow.md | 25 +-- AGENTS.md | 21 +-- docs/Agent开发交付实践.md | 34 ++-- docs/文档事实源状态矩阵.md | 21 +-- docs/文档索引.md | 33 ++-- scripts/qa/check-trellis-governance.mjs | 152 ++++++++++-------- 24 files changed, 361 insertions(+), 161 deletions(-) create mode 100644 .trellis/tasks/00-bootstrap-guidelines/check.jsonl create mode 100644 .trellis/tasks/00-bootstrap-guidelines/design.md create mode 100644 .trellis/tasks/00-bootstrap-guidelines/implement.jsonl create mode 100644 .trellis/tasks/05-26-trellis1-pilot/design.md create mode 100644 .trellis/tasks/05-26-trellis2-official-task-contract/check.jsonl create mode 100644 .trellis/tasks/05-26-trellis2-official-task-contract/design.md create mode 100644 .trellis/tasks/05-26-trellis2-official-task-contract/implement.jsonl create mode 100644 .trellis/tasks/05-26-trellis2-official-task-contract/prd.md create mode 100644 .trellis/tasks/05-26-trellis2-official-task-contract/task.json diff --git a/.agents/skills/hyb-oa-delivery/SKILL.md b/.agents/skills/hyb-oa-delivery/SKILL.md index e6cf2f3a..9b9d65b2 100644 --- a/.agents/skills/hyb-oa-delivery/SKILL.md +++ b/.agents/skills/hyb-oa-delivery/SKILL.md @@ -1,6 +1,6 @@ --- name: hyb-oa-delivery -description: "Use for hyb-oa project delivery tasks: natural-language triage, planning with Issue CSV, implementing Fastify/Prisma or React/Vite changes, refining PC/mobile/WeCom UI, reimbursement/invoice/OCR/attachment work, trial-run troubleshooting, automated/visual verification, and Chinese batch commits." +description: "Use for hyb-oa project delivery tasks: natural-language triage, Trellis task planning, implementing Fastify/Prisma or React/Vite changes, refining PC/mobile/WeCom UI, reimbursement/invoice/OCR/attachment work, trial-run troubleshooting, automated/visual verification, and Chinese batch commits." --- # hyb-oa Delivery @@ -11,11 +11,11 @@ Use this skill when working in `/home/shunli/Projects/hyb-oa` or when the user a Read only what is relevant: -- Always read `AGENTS.md`, `.trellis/workflow.md`, `.trellis/spec/hyb-oa/index.md`, and the newest relevant `issues/*.csv`. TRELLIS1 makes Trellis the primary development workflow: non-trivial work starts from `.trellis/tasks/`, but Issue CSV remains the auditable execution contract and `docs/` remains the business fact source. -- After R5, first check the main R5/R6 contract status before planning trial-run or follow-up work; R5 must remain the completed gate and R6 must have its own Issue CSV before expanding scope. +- Always read `AGENTS.md`, `.trellis/workflow.md`, `.trellis/spec/hyb-oa/index.md`, and the current `.trellis/tasks//prd.md` for non-trivial work. TRELLIS2 makes the Trellis task directory the execution contract; Issue CSV is historical audit or optional export material, while `docs/` remains the business fact source. +- After R5, first check the historical R5/R6 contract status before planning trial-run or follow-up work; R5 must remain the completed gate, and new expansion work should use a Trellis task after TRELLIS2. - For UI/page work, PC/mobile/WeCom experience, approval UX, or domestic OA benchmarking, read `docs/产品设计规则.md` and `references/visual-qa.md`. DG8 makes Feishu workbench/approval the single main UI/layout reference, with Hyinda branding and project rules taking priority. DG9 adds the A/B/C page layering and shared workbench/mobile samples; choose the DG9 sample before designing or coding a page. Other products are only function/process/control references. Mobile page work must treat `docs/产品设计规则.md` as the source of truth for the unified mobile shell, icon grid, card lists, deep Push pages, sticky actions, safe-area, and cross-viewport matrix. 移动页必须先对齐该设计事实源，再进入实现或验证。 - For approval workflow, roles, self-approval, notification, deeplink, reminder, or escalation work, read `docs/需求-统一审批中心规约.md`. -- For HR lifecycle, employee onboarding/offboarding, Enterprise WeChat directory sync, account disablement, or Enterprise WeChat API work, read `docs/需求-企业微信基础设施规约.md`, `docs/企微API能力目录.md`, `docs/管理员手册.md`, and the latest HCLT/HRWD/WAPI/WRRA Issue CSV evidence first. +- For HR lifecycle, employee onboarding/offboarding, Enterprise WeChat directory sync, account disablement, or Enterprise WeChat API work, read `docs/需求-企业微信基础设施规约.md`, `docs/企微API能力目录.md`, `docs/管理员手册.md`, the current Trellis task, and relevant historical HCLT/HRWD/WAPI/WRRA evidence first. - For any Enterprise WeChat capability, Secret, callback, approval, check-in, HR assistant, or contact-directory task, read `docs/企微API能力目录.md` before planning or coding. WAPI fixes the current Secret matrix: contacts use `WECOM_CONTACT_SECRET`; workbench/OAuth/messages/HR assistant/roster/check-in/approval use `WECOM_AGENT_SECRET`; `WECOM_CHECKIN_SECRET` is only an explicit check-in override; `WECOM_HR_ASSISTANT_SECRET` is historical compatibility and not a default. Do not write runtime code that tries multiple Secrets to guess the correct one. - For Enterprise WeChat-first HR/attendance runtime migration, read `docs/企微优先开发路线图.md` before planning or coding. WDRG makes the roadmap authoritative for stage order; WAPI adds the runtime-first stage before deep mirror work; WRRA states that WOUA `PASS_WITH_FINDINGS` does not clear deep mirror work; WOUA-FIX has now soft-archived the 7 OA active test accounts missing in WeCom, fixed the `T0000` seed reactivation behavior, transferred the `SMOKE201` test-manager side effects, and rerun WOUA with `oaActiveMissingInWecom=0`. WCPC has rerun the capability POC with an existing active test account and reached `GO_TO_HR_MASTER_SYNC`; WHMS/WHMSLIVE has implemented, deployed, and publicly verified `wecom_hr_master_sync_v1`, with the production flag restored to `force_off` and production real-employee batch apply not approved. WMSG1 proves real app-message delivery and Deeplink return only; WAPC1 fixes the approval configuration preparation checklist before mirror work; WAPC2 adds the leave/missed-punch approval template and low-risk `sp_no` read-only POC runner. WPROC1/WPROC2 fixed the engineering process gate; WEGOV1 is the route gate, and WACP3R has now rerun the compensation-pull POC by automatically discovering OA-POC leave/missed-punch template IDs from `SMOKE002` creator. Public report `/app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T115944Z/summary.json` is `PASS_WITH_FINDINGS`: compensation pull and detail read work, with finding that callback evidence files are not persisted across deploys. WREAD1/WREAD1F have now completed real-device readability confirmation for leave and missed-punch: public report `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` is `PASS_READABLE`; the user confirmed cards/lists/details are readable, reject has second confirmation, and approve is single-tap. WADM1 has completed the self-owned archive/mirror data-model design. WARCH1 has implemented and publicly verified the minimum leave/missed-punch archive slice: Prisma archive/callback/compensation/finding tables, callback DB persistence with non-200 retry on DB failure, compensation persistence behind `--persist-to-db` + `WECOM_ARCHIVE_WRITE=1`, and offline `npm run check:wecom-approval-archive`; public reports `/app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T160306Z/summary.json` and `/app/artifacts/qa-flow/wecom-approval-archive-20260519T160330Z/summary.json` are `PASS_WITH_FINDINGS`, with 2 archived histories readable and only a historical pre-WARCH1 callback gap finding. WARCH2 has now added the formal OA read-only archive API/page: `/api/wecom/approval-archive`, `/wecom-approval-archive`, and `/mobile/wecom-approval-archive` read OA DB only, do not call WeCom API or read WeCom Secrets, and enforce self/direct-report/HR-admin visibility with unmapped applicant records HR/admin-only. WROAD2+OPS is the controlled launch gate: use test accounts `SMOKE002 -> SMOKE101`, observe/admin-alert via employee_no `HYD000006` (the employee id for `wangshunli`), run daily checks for 3 days, allow only compensation archive writes to OA DB via `WECOM_ARCHIVE_WRITE=1`, and do not create WeCom templates/approvals, write WeCom, or expand real users. Day 0 public report `/app/artifacts/qa-flow/wroad2-ops-20260520-041941/summary.json` is `PASS_WITH_FINDINGS`: WeCom runtime, compensation archive persistence, offline archive read, and privacy smoke pass; findings are missing live-smoke login credentials/pending OCR subcheck and historical callback gap. It still does not implement full mirror, outing/overtime live, emergency mode, writeback, or RuleOps. WAUTO1 adds `scripts/qa/collect-wecom-controlled-trial-evidence.sh` for read-only controlled-trial evidence aggregation; it must not set `WECOM_ARCHIVE_WRITE=1`, `WECOM_CHECKIN_ARCHIVE_WRITE=1`, or `WECOM_APPROVAL_FIXTURE_WRITE=1`. WEXT1LD is the outing/overtime live-before dry-run gate and does not authorize live fixture creation. WFULLSMOKE1 adds `scripts/qa/run-three-day-full-goal-smoke.sh` as the three-day full-goal smoke controller; it may create only OA test business data marked `TEST-SMOKE-WFULL`, and must not write WeCom, create outing/overtime fixtures, enable real employees, make real payments, connect real payment providers, write ERP, or import bank statements. WTCLOSE2 adds the final test-account closeout and disables WFULLSMOKE1 public writes during that closeout. WPROC2 adds the executable `process gate`: before WAPC2F or other high-risk WeCom work, run `node scripts/qa/check-process-contract.mjs --baseline` and the issue-specific profile check to enforce DoR/DoD, fixed Secret source, non-self approval, live write switches, missing-config classification, and redaction boundaries. Do not start `wecom_attendance_approval_mirror_v1`, `oa_hr_emergency_mode_v1`, `wecom_recovery_writeback_v1`, or `wecom_ruleops_v1` without WROAD2-CLOSEOUT, WROAD2-BIZ1, WAPPR1, WRULE1, WAUTO1/WEXT1LD, WFULLSMOKE1 evidence, WTCLOSE2, WEXT1-FORMAL, WREAL1 question gates or explicit approval, and the next stage's own Issue CSV and acceptance gates. - WARCH3/WCHECK1/WEXT1 update the route after WROAD2 Day 0: WARCH3 adds `scripts/qa/run-warch3-ops-daily.sh`, `deploy/trialrun/install-warch3-ops-timer.sh`, and `npm run send:wecom-ops-alert` for 07:30 systemd巡检和脱敏企微告警；public report `/app/artifacts/qa-flow/warch3-ops-20260520-054841/summary.json` is `PASS_WITH_FINDINGS`, and WOPS1 now fixes alert noise: default recipient is `HYD000006` (the employee_no for `wangshunli`), repeated known findings are skipped via `artifacts/qa-flow/warch3-ops-alert-state.json`, and only blocked/failure/new-finding/status-worsening/force sends a message. WOPS1 public rerun `/app/artifacts/qa-flow/warch3-ops-20260520-070731/summary.json` is `PASS_WITH_FINDINGS`, and alert report `/app/artifacts/qa-flow/wecom-ops-alert-20260520T070740Z/summary.json` is `PASS_ALERT_SKIPPED_NO_FINDINGS` with `no_new_findings_or_status_worsening`. WCHECK1 adds `npm run check:wecom-checkin-summary-archive`, daily/monthly check-in summaries, and rule snapshots with `--persist-to-db` + `WECOM_CHECKIN_ARCHIVE_WRITE=1` as the only OA DB write gate; public reports `/app/artifacts/qa-flow/wecom-checkin-summary-archive-20260520T054907Z/summary.json` and `/app/artifacts/qa-flow/wecom-checkin-summary-archive-20260520T054926Z/summary.json` are `PASS_CHECKIN_ARCHIVE_READY` and `PASS_CHECKIN_ARCHIVE_OFFLINE_READY`. WEXT1 only extends approval fixtures for `--target=outing --target=overtime` dry-run; public report `/app/artifacts/qa-flow/wecom-approval-fixtures-20260520T054940Z/summary.json` is `PASS_FIXTURE_DRY_RUN_READY`. WAUTO1/WEXT1LD now add a read-only evidence aggregation script and a live-before dry-run contract; WFULLSMOKE1 adds full-domain main-path smoke orchestration across WeCom HR/attendance, OA-primary reimbursement/procurement/contract-project/payment-batch flows, mobile/WeCom entry, and ops checks. These do not create outing/overtime WeCom templates/approvals, expand real users, or implement full mirror/emergency/writeback/RuleOps. WEXT1-FORMAL needs WREMOTE1/WFULLSMOKE2 remote closeout, a new Issue CSV, and explicit approval for manual formal-template submission; WREAL1 real users are asked only after leave, missed punch, outing, and overtime test-account evidence plus approver-rule gate, WRULE1, WFULLSMOKE1, WTCLOSE2 and WEXT1-FORMAL are passable/explainable. @@ -34,8 +34,8 @@ Read only what is relevant: - OAFRONT6 is the current frontend maturity small-step lane after OAFRONT5: use `issues/2026-05-25_12-29-03-oa-frontend-maturity-small-step-v1.csv` for scoped design follow-ups only. Route-title cleanup, asset registry sectioning, mobile visual-matrix stability, contract registry form grouping, and long-number display compaction are implemented, deployed, and publicly rerun; report `artifacts/qa-flow/oafront3-pc-readonly-visual-20260525-202712/summary.json` is `PASS_PC_READONLY_VISUAL_READY` with `findingCount=0`. Portal observation remains later feedback-driven work. Do not treat OAFRONT6 as approval for a broad redesign, business logic changes, public writes, deployment, or final launch readiness; further implementation still needs `docs/产品设计规则.md`, focused Playwright/visual evidence, and OALAUNCH1 gates. - OAKISS1 is the current all-business-flow KISS review lane after OAFRONT6/OALAUNCH1: use `issues/2026-05-25_20-53-34-oa-business-flow-kiss-review-v1.csv` to record review evidence and suggestions across reimbursement/OCR, approval, procurement/expense, contracts/projects, payment/AP, invoice pool, assets, permissions, mobile/WeCom entry, and operations. It follows MAGI wording as an audit structure only: review first, run read-only evidence and record gaps second, then produce KISS keep/simplify/defer/manual-SOP recommendations. It must not create business data, execute payments, delete data, write WeCom, change production config, or replace OALAUNCH1 gates. Current evidence includes OAOPS1 daily `artifacts/qa-flow/oa-real-use-daily-20260525-205848/summary.json`, OALAUNCH1 `artifacts/qa-flow/oa-final-launch-readiness-20260525-211233/summary.json`, permission matrix `artifacts/qa-flow/oa-permission-matrix-20260525T130601Z/summary.json`, PC visual `artifacts/qa-flow/oafront3-pc-readonly-visual-20260525-210819/summary.json`, remote owner route `owner-application-approval-route-20260525-oakiss1`, and ASSET1D evidence. Treat the top remaining launch gates as real business closeout, 7-day stabilization, backup/restore drill, and data-governance/training acceptance. - PCDESIGN1 is the current PC all-page design review lane after OAKISS1: use `issues/2026-05-25_21-27-56-oa-pc-page-design-review-v1.csv` for PM/design-director review evidence and suggestions only. Current evidence includes key PC visual matrix `artifacts/qa-flow/pcdesign1-pc-readonly-visual-20260525-2128/summary.json` as `PASS_PC_READONLY_VISUAL_READY` for 7 roles/32 routes and all-static route scan `artifacts/qa-flow/pcdesign1-all-pc-static-20260525-2133/summary.json` as `PASS_PC_STATIC_ROUTE_SCAN_READY` for 45 static PC routes. Do not treat PCDESIGN1 as approval for broad redesign or code changes; the top suggested focus areas are HR/attendance OA-entry boundary cleanup, frozen-module entry labeling, high-density B/C page default-view simplification, and dynamic detail page sample evidence. -- TRELLIS1 is the current development-process migration lane after PCDESIGN1: use `issues/2026-05-26_09-02-34-trellis-primary-development-workflow-v1.csv` for Trellis-first workflow adoption. Trellis task/spec/workflow is now the default development entry, while Issue CSV remains the audit contract, docs remain business facts, `session_auto_commit=false`, `.trellis/workspace/` is local-only by default, and `node scripts/qa/check-trellis-governance.mjs` must pass before commit. This does not change business code, deploy public OA, write public data, or authorize production/WeCom writes. -- OMAT1 is the current maturity-gap review goal after OALAUNCH1: use `issues/2026-05-23_17-20-00-oa-maturity-gap-review-v1.csv` as the reviewable ledger for every problem or suggestion. It includes domestic benchmark sources, a domain capability comparison matrix, manual decision Q&A checklist, review decision packet, status audit, and MAGI round reviews in the manual trial-run report, the small-team rule that maturity means controlled operation before feature breadth, explicit adopt/defer/reject decision回填, and a need for a concise evidence view. Follow the MAGI cycle wording as audit structure only: review/evaluate first, record or solve bounded evidence gaps second, then prioritize direction. Do not implement OMAT1 suggestions until the user chooses adopt/defer/reject and a proper Issue CSV exists for the adopted work. +- TRELLIS2 is the current development-process migration lane after TRELLIS1: use `.trellis/tasks/05-26-trellis2-official-task-contract/` as the execution contract. Trellis task/spec/workflow is now the default development entry; Issue CSV remains historical audit or optional export material, docs remain business facts, `session_auto_commit=false`, `.trellis/workspace/` is local-only by default, and `node scripts/qa/check-trellis-governance.mjs` must pass before commit. This does not change business code, deploy public OA, write public data, or authorize production/WeCom writes. +- OMAT1 is the current maturity-gap review goal after OALAUNCH1: use `issues/2026-05-23_17-20-00-oa-maturity-gap-review-v1.csv` as historical review ledger for every problem or suggestion. It includes domestic benchmark sources, a domain capability comparison matrix, manual decision Q&A checklist, review decision packet, status audit, and MAGI round reviews in the manual trial-run report, the small-team rule that maturity means controlled operation before feature breadth, explicit adopt/defer/reject decision回填, and a need for a concise evidence view. Follow the MAGI cycle wording as audit structure only: review/evaluate first, record or solve bounded evidence gaps second, then prioritize direction. Do not implement OMAT1 suggestions until the user chooses adopt/defer/reject and a Trellis task exists for the adopted work. - WEGOV1 changes the current WeCom route to "Enterprise WeChat owns mature HR/attendance flows; OA stores self-owned history, audit, entry, messages, and emergency fallback." Treat four domains explicitly: WeCom-owned domain is check-in, leave, missed punch, outing, overtime, leave balance, and HR assistant; OA-owned domain remains reimbursement, procurement, contracts, projects, payments, invoices, bank receipts, sensitive attachments, and operating audit; OA archive domain stores WeCom business history, full external keys, and necessary snapshots; OA emergency domain is manually enabled only when WeCom is unavailable. Do not assume a full isolated WeCom sandbox; use the controlled test domain `SMOKE002 -> SMOKE101`, `OA-POC` templates, low-risk approvals, synthetic tests, public live runners, and limited real-device confirmation. WARCH1 now supplies the minimum leave/missed-punch archive implementation, WARCH2 supplies the formal read-only history query surface, and WROAD2 supplies controlled ops daily checks. Do not start deep mirror until WROAD2-CLOSEOUT, WROAD2-BIZ1, WAPPR1, WRULE1, WAUTO1/WEXT1LD, WFULLSMOKE1, WTCLOSE2, WEXT1-FORMAL, WREAL1 question gates or explicit approval, and the mirror stage's own contract are complete. - For reimbursement, invoice, OCR, duplicate invoice, or attachment work, read `docs/报销发票附件规则.md` and `references/reimbursement.md`. - For local/WeCom/public trial-run, OCR runtime, Caddy, or DB drift work, read `docs/试运行与自动化验证手册.md` and `references/trialrun.md`. @@ -50,13 +50,13 @@ Default behavior: 1. Extract intent, target surface, constraints, approval state, and next action. 2. Check existing assets before declaring a blocker: `issues/`, `docs/`, `artifacts/`, `output/`, scripts, Playwright tests, runbooks, and prior trial-run evidence. 3. Ask only when required by `AGENTS.md` or safety: missing approval for non-trivial coding, destructive data work, production config, secrets/accounts, conflicting goals, or unclear high-risk acceptance. -4. Treat a plain "确认" as approval for the immediately preceding explicit plan or Issue CSV, unless multiple candidates exist. +4. Treat a plain "确认" as approval for the immediately preceding explicit plan or Trellis task, unless multiple candidates exist. 5. If the user asks whether a problem is real, verify first with automation, code inspection, public checks, or visual evidence before proposing broad changes. ## Delivery Loop 1. Check `git status --short`; do not revert unrelated user changes. -2. Identify the current active continuous Issue CSV before non-trivial work. Same-type trial-run feedback, real-device feedback, single-surface defects, and small follow-up fixes must append rows or update Notes in the active flow instead of creating one-off CSVs. Create a new CSV only when no active same-type flow exists, the current flow is closed, the change crosses risk/business domains, or the user explicitly asks for a new contract; if creating one, state why the active flows cannot carry it. After R5, distinguish R6 preparation from actual trial-run execution. +2. Identify or create the current Trellis task before non-trivial work. Same-type trial-run feedback, real-device feedback, single-surface defects, and small follow-up fixes should update the active task or create a child task instead of reintroducing one-off CSVs. Create a new Issue CSV only when the user explicitly needs a legacy/export audit packet. 3. State the implementation approach before editing code; if already approved, proceed. 4. Keep changes scoped to the current Issue. 5. Prefer existing project patterns, official SDKs, and the main UI/layout hierarchy in `docs/产品设计规则.md`; for page work, classify the page into DG9 A/B/C layering and reuse the matching workbench/mobile sample before adding local layout code. Do not mix multiple competitor visual systems or copy competitor flows/text directly. @@ -64,8 +64,8 @@ Default behavior: 7. Use Playwright screenshots or visual metrics for PC/mobile/WeCom UI changes. New or changed mobile pages must join the unified responsive system and the 320/360/375/390/393/414/430px 统一视觉矩阵 rather than adding page-specific layout fixes. 8. Dedicated `/mobile` pages must use the shared mobile slot/card/list/sticky-action system from `docs/产品设计规则.md`: fixed icon/avatar/status slots, `minmax(0, 1fr)` copy slots, `mobile-card`/mobile list cards, `mobile-field-row`, mobile tokens, and no desktop `card-std p-4/p-5/p-6` as a mobile main container. 9. Mobile homepage, approval, notification, and business cards must follow the display dedupe rules in `docs/产品设计规则.md`: one pending/progress summary per page, notifications as event stream with direct target links, bottom badges as counts only, and one visible business identifier/status per card or row. -10. Update Issue CSV statuses only after the stated `Test_Method` passes. -11. Commit in Chinese batches with Issue IDs. +10. Update Trellis task notes/status only after the stated task test plan passes. +11. Commit in Chinese batches with the Trellis task name or task ID. 12. 面向用户可测试的改动，最终必须明确“是否已部署”。只有部署与公网检查通过后，才能告知用户可以去企业微信或公网试运行环境测试。 ## Default Verification Matrix @@ -121,7 +121,7 @@ Final responses should include: ## R6 and Trial-Run Defaults -- R6 can start only from a new Issue CSV that fixes users, roles, time window, rollback contact, issue log, and daily closeout rhythm. +- R6 historical expansion required a dedicated contract; after TRELLIS2, equivalent expansion work must start from a Trellis task that fixes users, roles, time window, rollback contact, issue log, and daily closeout rhythm. - R6 scope defaults to reimbursement, leave, procurement, approval, Enterprise WeChat entry/notification, finance payment/export. - Do not expand to budget, ERP, AI, full travel, or complex BPM during R6; record those as follow-up Issues. - Enterprise WeChat personal app message is the formal approval notification channel after R5; mock and group bots are not acceptance evidence for R6 business notification. @@ -132,7 +132,7 @@ Final responses should include: - WAPC2 has added the WeCom approval template/detail read-only POC runner for leave and missed punch. Use `npm run check:wecom-approval-poc`; pass template IDs with `--template=leave:` / `--template=missed_punch:` and low-risk test approval numbers with `--sp-no=leave:` / `--sp-no=missed_punch:`. The runner must use only `WECOM_AGENT_SECRET`, redact full template IDs and `sp_no`, and never output form values, attachments, comments, full userid, token, Secret, or raw payload. - WPROC1 fixes the WeCom approval engineering process. Future WeCom work must satisfy route gate, capability gate, and implementation gate; use automatic runners before asking the user to do manual work. WPROC2 makes this executable through `node scripts/qa/check-process-contract.mjs --baseline` plus issue-specific profiles such as `--profile wecom-approval-fixture`; run it before WAPC2F and later high-risk WeCom contracts. Manual work is limited to write approval, secrets/callback config, WeCom backend settings that cannot be API-driven, real-device confirmation, and risk decisions. High-risk stages require POC before implementation: callback signature/decryption/idempotency, compensation pull, mirror data model, then mirror implementation. - WAPC2F has added the WeCom approval fixture dry-run runner. Use `npm run check:wecom-approval-fixtures`; it defaults to applicant `SMOKE002`, approver `SMOKE101`, fixed `WECOM_AGENT_SECRET`, minimal generic OA-POC leave/missed-punch template payloads, and no write token or WeCom writes. Real fixture creation requires `--live --create-templates --submit-test-approvals` plus one-process `WECOM_APPROVAL_FIXTURE_WRITE=1` and explicit user approval. The public dry-run report is `/app/artifacts/qa-flow/wecom-approval-fixtures-20260519T045001Z/summary.json` with `PASS_FIXTURE_DRY_RUN_READY`. -- WAPC2FLIVE has executed that approved live path once after fixing the template payload shape; current public evidence is `/app/artifacts/qa-flow/wecom-approval-fixtures-20260519T053400Z/summary.json`, `PASS_FIXTURE_CREATED`, `checks.autoRerun.status=OK`, and `PASS_APPROVAL_POC`. Do not create more approval fixtures without a new Issue CSV and explicit approval. +- WAPC2FLIVE has executed that approved live path once after fixing the template payload shape; current public evidence is `/app/artifacts/qa-flow/wecom-approval-fixtures-20260519T053400Z/summary.json`, `PASS_FIXTURE_CREATED`, `checks.autoRerun.status=OK`, and `PASS_APPROVAL_POC`. Do not create more approval fixtures without a Trellis task and explicit approval. - WCBK1 has implemented and verified the WeCom approval callback read-only POC path. Use `npm run check:wecom-approval-callback-poc`; default synthetic mode verifies local encrypted callback samples, while `--live` checks the configured public callback URL and redacted event evidence. The route uses only `WECOM_APPROVAL_CALLBACK_URL`, `WECOM_CALLBACK_TOKEN`, `WECOM_CALLBACK_ENCODING_AES_KEY`, and `WECOM_CORP_ID`; do not use contact Secret or legacy callback env names. Current public status is `PASS_CALLBACK_EVENT_CONFIRMED`: URL verification passed, and one existing OA-POC missed-punch approval handled by `SMOKE101` produced a redacted approval-status event. Do not store raw XML, ciphertext, full `sp_no`, full userid, Token, EncodingAESKey, form values, attachments, comments, or raw payload. - Approval-chain correctness can be proven by PC or automation, while Enterprise WeChat validates entry, binding,免登录, notification, deeplink, and mobile layout. - If real-device mobile validation is paused after automation passes, record the gate as `PAUSED`; do not close RS6/UI6/R6 mobile blockers until representative real-device confirmation is recorded. diff --git a/.trellis/spec/hyb-oa/approval-workflow.md b/.trellis/spec/hyb-oa/approval-workflow.md index 04eb5807..2d02f20d 100644 --- a/.trellis/spec/hyb-oa/approval-workflow.md +++ b/.trellis/spec/hyb-oa/approval-workflow.md @@ -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 diff --git a/.trellis/spec/hyb-oa/backend-fastify-prisma.md b/.trellis/spec/hyb-oa/backend-fastify-prisma.md index 8ca3d6ff..2f0d3494 100644 --- a/.trellis/spec/hyb-oa/backend-fastify-prisma.md +++ b/.trellis/spec/hyb-oa/backend-fastify-prisma.md @@ -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, diff --git a/.trellis/spec/hyb-oa/docs-and-evidence.md b/.trellis/spec/hyb-oa/docs-and-evidence.md index e1394587..ea4c25ee 100644 --- a/.trellis/spec/hyb-oa/docs-and-evidence.md +++ b/.trellis/spec/hyb-oa/docs-and-evidence.md @@ -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. diff --git a/.trellis/spec/hyb-oa/index.md b/.trellis/spec/hyb-oa/index.md index b9fcbecb..6f71bd45 100644 --- a/.trellis/spec/hyb-oa/index.md +++ b/.trellis/spec/hyb-oa/index.md @@ -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//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 | diff --git a/.trellis/spec/hyb-oa/project-governance.md b/.trellis/spec/hyb-oa/project-governance.md index 1548b5f5..5e60ed41 100644 --- a/.trellis/spec/hyb-oa/project-governance.md +++ b/.trellis/spec/hyb-oa/project-governance.md @@ -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 /scripts/validate_issues_csv.py ` -- `node scripts/qa/check-process-contract.mjs --baseline --json` +- `python3 ./.trellis/scripts/task.py validate ` - `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. diff --git a/.trellis/spec/hyb-oa/wecom-boundary.md b/.trellis/spec/hyb-oa/wecom-boundary.md index c9c907b5..7c02c0aa 100644 --- a/.trellis/spec/hyb-oa/wecom-boundary.md +++ b/.trellis/spec/hyb-oa/wecom-boundary.md @@ -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 diff --git a/.trellis/tasks/00-bootstrap-guidelines/check.jsonl b/.trellis/tasks/00-bootstrap-guidelines/check.jsonl new file mode 100644 index 00000000..599991f3 --- /dev/null +++ b/.trellis/tasks/00-bootstrap-guidelines/check.jsonl @@ -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."} diff --git a/.trellis/tasks/00-bootstrap-guidelines/design.md b/.trellis/tasks/00-bootstrap-guidelines/design.md new file mode 100644 index 00000000..102daf31 --- /dev/null +++ b/.trellis/tasks/00-bootstrap-guidelines/design.md @@ -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. diff --git a/.trellis/tasks/00-bootstrap-guidelines/implement.jsonl b/.trellis/tasks/00-bootstrap-guidelines/implement.jsonl new file mode 100644 index 00000000..b263b345 --- /dev/null +++ b/.trellis/tasks/00-bootstrap-guidelines/implement.jsonl @@ -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."} diff --git a/.trellis/tasks/00-bootstrap-guidelines/prd.md b/.trellis/tasks/00-bootstrap-guidelines/prd.md index 5cc057a1..46226eb4 100644 --- a/.trellis/tasks/00-bootstrap-guidelines/prd.md +++ b/.trellis/tasks/00-bootstrap-guidelines/prd.md @@ -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. diff --git a/.trellis/tasks/05-26-trellis1-pilot/design.md b/.trellis/tasks/05-26-trellis1-pilot/design.md new file mode 100644 index 00000000..740325a1 --- /dev/null +++ b/.trellis/tasks/05-26-trellis1-pilot/design.md @@ -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. diff --git a/.trellis/tasks/05-26-trellis1-pilot/prd.md b/.trellis/tasks/05-26-trellis1-pilot/prd.md index e5daa9c9..8d13df94 100644 --- a/.trellis/tasks/05-26-trellis1-pilot/prd.md +++ b/.trellis/tasks/05-26-trellis1-pilot/prd.md @@ -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` diff --git a/.trellis/tasks/05-26-trellis2-official-task-contract/check.jsonl b/.trellis/tasks/05-26-trellis2-official-task-contract/check.jsonl new file mode 100644 index 00000000..fca812b3 --- /dev/null +++ b/.trellis/tasks/05-26-trellis2-official-task-contract/check.jsonl @@ -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."} diff --git a/.trellis/tasks/05-26-trellis2-official-task-contract/design.md b/.trellis/tasks/05-26-trellis2-official-task-contract/design.md new file mode 100644 index 00000000..11d85d0e --- /dev/null +++ b/.trellis/tasks/05-26-trellis2-official-task-contract/design.md @@ -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. diff --git a/.trellis/tasks/05-26-trellis2-official-task-contract/implement.jsonl b/.trellis/tasks/05-26-trellis2-official-task-contract/implement.jsonl new file mode 100644 index 00000000..6135432a --- /dev/null +++ b/.trellis/tasks/05-26-trellis2-official-task-contract/implement.jsonl @@ -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."} diff --git a/.trellis/tasks/05-26-trellis2-official-task-contract/prd.md b/.trellis/tasks/05-26-trellis2-official-task-contract/prd.md new file mode 100644 index 00000000..8a2140fa --- /dev/null +++ b/.trellis/tasks/05-26-trellis2-official-task-contract/prd.md @@ -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. diff --git a/.trellis/tasks/05-26-trellis2-official-task-contract/task.json b/.trellis/tasks/05-26-trellis2-official-task-contract/task.json new file mode 100644 index 00000000..bedf9447 --- /dev/null +++ b/.trellis/tasks/05-26-trellis2-official-task-contract/task.json @@ -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" + } +} \ No newline at end of file diff --git a/.trellis/workflow.md b/.trellis/workflow.md index 9a1e7cec..03bf6cab 100644 --- a/.trellis/workflow.md +++ b/.trellis/workflow.md @@ -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 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 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. diff --git a/AGENTS.md b/AGENTS.md index 6e6311c1..e63e4c2f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,23 +1,24 @@ # AGENTS -> Purpose: 以 Trellis 为主流程，保留 Issue CSV 审计合同和 hyb-oa 业务事实源。 +> Purpose: 以官方 Trellis task 为执行合同，驱动 hyb-oa 后续开发、验证和复盘。 ## Trellis-first 入口 - 开始任何非微小开发、审查、测试或文档治理任务前，先读 `.trellis/workflow.md`。 -- Trellis task 是后续需求拆解、上下文组织、执行复盘的主入口；每个 task 必须绑定 `issues/*.csv` 中的 Issue ID。 -- `issues/*.csv` 仍是可审计执行合同；Trellis 不替代 Issue CSV 状态、验收、回滚和 commit 追踪。 -- `docs/` 仍是业务事实源；Trellis spec 只沉淀开发流程和高频工程规则。 +- Trellis task 是后续需求拆解、执行、验证和复盘的执行合同；新任务不再强制绑定 `issues/*.csv`。 +- `prd.md` 是任务需求和验收入口；复杂任务补 `design.md` 或 `implement.md`；`implement.jsonl` / `check.jsonl` 只登记稳定 spec 或 research 上下文。 +- `issues/*.csv` 保留为历史审计材料或特殊外部交付导出格式，不再作为新开发的默认前置合同。 +- `docs/` 仍是业务事实源；Trellis spec 沉淀开发流程和高频工程规则。 ## 不可违反约束 - 编码前先方案：非微小改动必须先给实现方案并等待批准。 -- 先有 Issue CSV 再开发：非微小改动必须先落 `issues/*.csv`。 +- 先有 Trellis task 再开发：非微小改动必须先创建或更新 `.trellis/tasks//`。 - 计划工具约束：使用 Codex 原生 `update_plan` 做执行清单，不用外部自定义 plan 替代。 - 项目 Skill 优先：hyb-oa 交付、试运行、视觉复核、报销/OCR/附件、企业微信或部署类任务继续使用 `.agents/skills/hyb-oa-delivery`，再按 Trellis task/spec 组织上下文。 -- 中文沟通；commit message 使用中文并引用 Issue ID。 +- 中文沟通；commit message 使用中文并引用 Trellis task 名称或任务 ID。 - 不泄露密码、token、Secret、真实票据、合同正文、银行资料、完整账号、完整本地路径或原始 payload。 -- 不轻易新建文档；优先更新现有事实源、模块规约、操作手册、证据文档或连续 Issue CSV。 +- 不轻易新建文档；优先更新现有事实源、模块规约、操作手册、证据文档或当前 Trellis task。 - 页面调整必须参考 `docs/产品设计规则.md`，并对齐公司主页 `www.hyinda.com` 的品牌风格。 - 面向用户可测试的改动，只有部署与公网检查通过后才能告知用户可以测试。 @@ -42,14 +43,14 @@ ## Trellis 使用边界 -- `.trellis/workspace/` 为本地个人日志，默认不提交；需要沉淀的经验应脱敏后写入 `.trellis/spec/`、`docs/` 或 Issue CSV。 +- `.trellis/workspace/` 为本地个人日志，默认不提交；需要沉淀的经验应脱敏后写入 `.trellis/spec/`、`docs/` 或当前 Trellis task。 - `.trellis/config.yaml` 固定 `session_auto_commit: false`；Trellis 不得自动提交。 - 当前仅启用 Codex 适配；不把 Cursor/Claude/其他平台迁移作为本轮默认范围。 - Codex hooks 文件可以存在，但只有用户级配置和 `/hooks` 审核启用后才生效；本项目不把 hook 自动注入作为验收前提。 ## 编排规则 -- 默认按 Trellis workflow 执行：task/prd -> Issue CSV -> implement -> check -> spec/docs update -> commit -> finish。 +- 默认按 Trellis workflow 执行：task/prd -> design/implement notes（按需） -> implement -> check -> spec/docs update -> commit -> finish。 - 涉及权限模型、状态机、workflow、数据迁移、审批规则时，实施后必须启动只读 review，不让 reviewer 改代码。 - 公网部署、生产配置、真实数据写入、数据库重置、企业微信写入和真实付款必须另行获得明确批准。 -- 若 Trellis 规则与业务文档冲突：最新 Issue CSV > 当前模块规约/PRD > `docs/产品设计规则.md` 和业务规约 > Trellis spec > 历史证据。 +- 若 Trellis 规则与业务文档冲突：当前 Trellis task PRD/设计 > 当前模块规约 > `docs/产品设计规则.md` 和业务规约 > Trellis spec > 历史证据；历史 Issue CSV 只用于追溯。 diff --git a/docs/Agent开发交付实践.md b/docs/Agent开发交付实践.md index 6c07c302..af14958a 100644 --- a/docs/Agent开发交付实践.md +++ b/docs/Agent开发交付实践.md @@ -16,19 +16,19 @@ ## 本项目采用的原则 -### 0. TRELLIS1 后以 Trellis 为主流程 +### 0. TRELLIS2 后以官方 Trellis task 为执行合同 -TRELLIS1 起，hyb-oa 的后续非微小开发默认从 `.trellis/tasks/` 进入，由 `.trellis/workflow.md` 组织计划、实施、检查和复盘。 +TRELLIS2 起，hyb-oa 的后续非微小开发默认从 `.trellis/tasks/` 进入，由 task 目录本身承载需求、计划、实施、检查和复盘。 -Trellis 的定位是“开发流程和上下文组织层”，不是业务事实源替代品： +Trellis 的定位是“开发执行合同和上下文组织层”，不是业务事实源替代品： -- Trellis task：承载本轮需求 PRD、上下文和复盘。 +- Trellis task：承载本轮需求 PRD、范围边界、验收、测试计划、上下文和复盘。 - Trellis spec：沉淀稳定开发规则和高频工程边界。 -- Issue CSV：仍是执行合同、验收、状态和回滚审计台账。 +- Issue CSV：保留为历史审计材料或特殊外部交付导出格式，不再作为新任务默认前置合同。 - `docs/`：仍是业务事实源、产品规则、操作手册和证据入口。 - `AGENTS.md`：只保留 Trellis-first 入口和不可违反硬约束。 -每个 Trellis task 必须绑定 Issue CSV 和 Issue ID；`.trellis/workspace/` 默认作为本地个人日志，不提交。提交前必须运行 `node scripts/qa/check-trellis-governance.mjs`。 +每个非微小 Trellis task 必须有 `prd.md`；复杂流程、API、迁移、权限、部署或治理变更补 `design.md` 或 `implement.md`；`.trellis/workspace/` 默认作为本地个人日志，不提交。提交前必须运行 `node scripts/qa/check-trellis-governance.mjs`。 ### 1. 先简单、后编排 @@ -36,15 +36,17 @@ Trellis 的定位是“开发流程和上下文组织层”，不是业务事实 不为了“多 agent”而多 agent。复杂编排的收益必须超过上下文丢失、沟通成本和合并风险。 -### 2. Issue CSV 是执行合同 +### 2. Trellis task 是执行合同 -所有非微小改动先进入 `issues/*.csv`，再实施。Issue 必须写清： +所有非微小改动先进入 `.trellis/tasks//`，再实施。task 必须写清： - 业务流程级影响，不只写文件路径。 - 验收标准，不只写“完成开发”。 - 可执行验证命令或可复现手工步骤。 - 数据迁移、权限、状态机、审批规则的回滚策略。 +历史 `issues/*.csv` 不删除、不批量回写；需要表格化审计时，可以从 Trellis task 摘要导出，而不是重新维护一套并行合同。 + ### 3. Skill 只沉淀操作流程 Skill 用于减少重复沟通和降低遗漏风险，适合沉淀： @@ -124,7 +126,7 @@ DG9 之后，页面任务必须先按 `docs/产品设计规则.md` 的 A/B/C 页 - 当前事实源、操作手册和用户可读文档默认使用中文文件名；技术生态或脚本强引用的英文名可以保留，但必须在索引中说明。 - 已确认不用的历史文档从当前树物理删除，不放 `docs/archive/`；需要时通过 git 历史恢复。 - 不回写旧 Issue CSV 快照；旧 Issue 中的历史路径保留审计语义。 -- 历史矩阵、旧 runbook 或旧 trialrun 记录若与最新 Issue CSV、当前 PRD 或模块规约冲突，以最新 Issue CSV 和当前模块规约为准。 +- 历史矩阵、旧 runbook 或旧 trialrun 记录若与当前 Trellis task、当前 PRD 或模块规约冲突，以当前 Trellis task 和当前模块规约为准。 - R7/OPS7/DOC7 草案不代表真实 R7 已启动；MIF7/MIF7T 已收口，后续移动体验问题应进入新的 UX8 或专项 Issue。 ### 7. 提交要小批次、中文、可回滚 @@ -136,7 +138,7 @@ DG9 之后，页面任务必须先按 `docs/产品设计规则.md` 的 A/B/C 页 - 前端体验。 - 测试和视觉验证。 -commit message 使用中文并引用 Issue ID，例如 `R121/A1-A3 沉淀交付事实源`。 +commit message 使用中文并引用 Trellis task 名称或任务 ID，例如 `trellis2-official-task-contract 采用官方 Trellis 执行合同`。 ### 8. 自然语言派工是默认入口 @@ -145,9 +147,9 @@ commit message 使用中文并引用 Issue ID，例如 `R121/A1-A3 沉淀交付 - 意图：缺陷、需求、验收反馈、计划、审查、测试、部署、设计或产品流程优化。 - 对象：页面、接口、业务流程、数据、部署环境、文档或自动化。 - 约束：是否要求先规划、是否已授权实施、是否涉及公网、企业微信、真实账号或真实数据。 -- 下一步：核查、建 Issue CSV、给方案等确认、实施、验证、提交、部署。 +- 下一步：核查、建 Trellis task、给方案等确认、实施、验证、提交、部署。 -当用户说“确认”时，默认表示批准上一条明确方案或 Issue CSV 进入下一阶段。若上下文中存在多个候选方案，agent 才需要反问确认对象。 +当用户说“确认”时，默认表示批准上一条明确方案或 Trellis task 进入下一阶段。若上下文中存在多个候选方案，agent 才需要反问确认对象。 ### 9. 少反问，先查已有资产 @@ -164,7 +166,7 @@ agent 在声明 blocker 前，必须先查项目内已有资产： 以下情况必须暂停确认： -- 非微小代码改动还没有方案批准，或没有 Issue CSV 执行合同。 +- 非微小代码改动还没有方案批准，或没有 Trellis task 执行合同。 - 需要删除或重置数据、处理迁移漂移、修改生产配置、重启远程服务。 - 需要使用、重置或暴露真实账号密码、密钥、令牌、客户数据。 - 用户目标互相冲突，且无法通过现有文档和代码推断优先级。 @@ -176,7 +178,7 @@ agent 在声明 blocker 前，必须先查项目内已有资产： 同一个 agent 可以按任务临时切换工作视角，但输出必须落到可审计交付物： -- 产品经理：把一段话拆成业务流程、优先级、Issue CSV、验收标准和下一步建议。 +- 产品经理：把一段话拆成业务流程、优先级、Trellis task、验收标准和下一步建议。 - 需求分析：补齐边界条件、角色权限、异常状态、国内同类系统常见处理方式。 - 开发：按 Issue 实施后端、前端、脚本或文档变更，并执行对应验证。 - 审查：默认先报风险、行为回归、权限泄漏、状态机问题和漏测项。 @@ -204,7 +206,7 @@ agent 在声明 blocker 前，必须先查项目内已有资产： 适合自动化或半自动化固化的任务： -- 每轮 Issue CSV 校验、状态回填检查和未完成项扫描。 +- 每轮 Trellis task 合同校验、上下文检查和未完成项扫描。 - 后端 syntax、Prisma validate、核心回归脚本。 - 前端 typecheck、build、关键页面 Playwright 和视觉截图。 - 公网 `/ready`、企业微信配置、资源版本、核心文案和 live smoke。 @@ -217,7 +219,7 @@ agent 在声明 blocker 前，必须先查项目内已有资产： 开发类任务完成时，agent 必须说明： -- 改了什么，关联哪些 Issue ID。 +- 改了什么，关联哪个 Trellis task。 - 验证了什么，哪些命令或路径通过。 - 是否提交 commit，commit hash 是什么。 - 面向用户可测试的改动是否已经部署；未部署时不能说“可以去企业微信测试”。 diff --git a/docs/文档事实源状态矩阵.md b/docs/文档事实源状态矩阵.md index de039dc9..fb13b72d 100644 --- a/docs/文档事实源状态矩阵.md +++ b/docs/文档事实源状态矩阵.md @@ -5,12 +5,12 @@ **适用时间**：DCL7 之后。 **关联 Issue**：`GOV8`。 **最近审计**：2026-05-18。 -**不得误读**：本文登记文档权威性和状态，不替代具体 PRD、模块规约、测试规约或 Issue CSV。 +**不得误读**：本文登记文档权威性和状态，不替代具体 Trellis task、PRD、模块规约或测试规约。 **治理口径**：中文优先，物理精简，优先复用已有文档。历史资料不建 `docs/archive/`，已确认不用的文档从当前树移除，通过 git 历史恢复。 ## 冲突优先级 -最新 Issue CSV > 当前 PRD/模块规约 > 产品和设计规则 > 当前操作手册 > 技术参考 > 历史证据 > git 历史。 +当前 Trellis task PRD/设计 > 当前 PRD/模块规约 > 产品和设计规则 > 当前操作手册 > 技术参考 > 历史证据 > git 历史。 ## 台账状态值 @@ -118,17 +118,18 @@ | `OAFRONT6` | `issues/2026-05-25_12-29-03-oa-frontend-maturity-small-step-v1.csv` | `CURRENT` | 当前前端成熟化小步收口合同：承接 OAFRONT5 部署后 PC 硬问题清零和设计审计；路由标题修复、资产台账详情分区、移动视觉矩阵稳定等待、合同台账表单分组和长编号压缩均已实施部署，公网 PC 只读视觉矩阵复测 `PASS_PC_READONLY_VISUAL_READY` 且 `findingCount=0`；Portal 观察继续后置；本合同不写公网业务数据，不替代 OALAUNCH1 真实业务、备份恢复、7 天稳定化或 Go/No-Go | | `OAKISS1` | `issues/2026-05-25_20-53-34-oa-business-flow-kiss-review-v1.csv` | `CURRENT` | 当前全业务流程 KISS 审查合同：按 MAGI 审视/执行/提升轮次，对报销/OCR、审批、采购/费用、合同/项目、付款/AP、票据池、资产、权限、移动/企微入口逐项做自动化和人工步骤审查；输出 KISS 建议台账，不直接改业务代码；OALAUNCH1 真实业务闭环、备份恢复、7 天稳定化和 Go/No-Go 仍是正式启用前硬门禁 | | `PCDESIGN1` | `issues/2026-05-25_21-27-56-oa-pc-page-design-review-v1.csv` | `CURRENT` | 当前 PC 全页面设计审查合同：按 MAGI 审视/执行/提升轮次，以项目经理和设计总监视角盘点 45 条静态 PC 路由、A/B/C 页面分层、关键视觉矩阵和 KISS 建议；关键 PC 矩阵 `PASS_PC_READONLY_VISUAL_READY`，全静态路由扫描 `PASS_PC_STATIC_ROUTE_SCAN_READY`；建议优先收敛 HR/考勤边界、冻结模块入口、高密度 B/C 页默认视图和动态详情页证据，不直接改业务代码 | -| `TRELLIS1` | `issues/2026-05-26_09-02-34-trellis-primary-development-workflow-v1.csv` | `CURRENT` | 当前 Trellis 主导开发流程迁移合同：后续非微小开发默认从 `.trellis/tasks/` 进入；`.trellis/workflow.md` 组织计划、实施、检查和复盘；Issue CSV 仍是审计合同，`docs/` 仍是业务事实源；本轮不改业务代码、不部署、不写公网数据 | +| `TRELLIS1` | `issues/2026-05-26_09-02-34-trellis-primary-development-workflow-v1.csv` | `EVIDENCE` | Trellis-first 初始迁移历史合同：已由 TRELLIS2 官方 task 执行合同口径替代 | +| `TRELLIS2` | `.trellis/tasks/05-26-trellis2-official-task-contract/` | `CURRENT` | 当前开发流程合同：官方 Trellis task 作为新任务执行合同；Issue CSV 降级为历史审计或可选导出格式；本轮不改业务代码、不部署、不写公网数据 | | `WREAL1-PREP` | `issues/2026-05-20_14-35-42-wecom-real-trial-prep-v1.csv` | `CURRENT` | 真实小范围试用准备合同：只固化候选员工、非自审审批人、回滚联系人、允许流程、暂停条件和验收标准；当前不启用真实员工，真实试用必须等请假/补卡/外出/加班四类测试号证据、WAPPR1 审批规则门禁和 WFULLSMOKE1 全域主路径可解释通过后再问 | -旧 Issue CSV 保留为历史审计证据：不删除、不批量回写、不移动到 `docs/archive/` 或其他归档目录。新连续合同如替代旧合同，只在新合同 `Notes` 或文档索引中说明 supersedes。 +旧 Issue CSV 保留为历史审计证据：不删除、不批量回写、不移动到 `docs/archive/` 或其他归档目录。新治理流如替代旧合同，只在新 Trellis task、文档索引或事实源矩阵中说明 supersedes。 ## 文档台账 | Doc_ID | Path | Category | Authority | Status | Owner | Related_Issues | Evidence | Supersedes | Last_Audited | Audit_Method | Risk | Notes | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| `IDX` | `docs/文档索引.md` | 入口索引 | 最高文档入口 | `CURRENT` | product/dev | `GOV8,QAOPS9,P2D,P2-ORG,P2-FIN-DECISION,P2-FIN-V1,P2-OCR-SAMPLE,P2Q,P2AUTO,P2AF,P2-FIN-LIVE-DECISION,P2-FIN-LIVE,PRELAUNCH,CASHIER-VOUCHER-V1,LAUNCH-DEPLOY-FINANCE,FIN-PROD-ENABLE,ACCOUNTING-HANDOFF-V1,SYSTEM-COMPLETE-GATE,LAUNCH-OPS-V1,REQ-COMPLETE-AUDIT,ATTV1,LAUNCH-AUTO-OPS-V1,AUTO-REMAINING-CLOSEOUT,HR-WECOM-DIRECTORY-V1,WFOC,DBWFOC,WFDG,WDRG,WCP1,WCPC,WHMS,WHMSLIVE,WOUA,WAPI,WRRA,WOUAFIX,WRV1,WRA1,WMSG1,WAPC1,WAPC2,WPROC1,WPROC2,WAPC2F,WAPC2FLIVE,WCBK1,WEGOV1,WARCH1,WARCH2,WROAD2,WARCH3,WCHECK1,WEXT1,WOPS1,WROAD2C,WROAD2B,WAPPR1,WRULE1,WAUTO1,WEXT1LD,WFULLSMOKE1,WTCLOSE2,WREAL1P,OAOPS1,ASSET1,OSMOKE1,OALAUNCH1,OMAT1,OPOLICY1,OAFLOW1,OAFRONT6,OAKISS1,PCDESIGN1` | `rg` | none | 2026-05-25 | `node scripts/qa/audit-docs.mjs --check-registry` | medium | 判断当前该读什么；OAOPS1/ASSET1/OSMOKE1 后优先读取 OALAUNCH1 最终启用门禁、OMAT1 成熟度缺口、OPOLICY1 制度与 OA 对齐、OAFLOW1 负责人本人报销兜底、OAFRONT6 前端成熟化规划、OAKISS1 全业务 KISS 审查、PCDESIGN1 PC 全页面设计审查、小团队 V1、每日巡检、备份恢复和 P2 冻结口径 | -| `REG` | `docs/文档事实源状态矩阵.md` | 文档台账 | 文档分类和状态事实源 | `CURRENT` | product/dev | `GOV8,QAOPS9,P2D,P2-ORG,P2-FIN-DECISION,P2-FIN-V1,P2-OCR-SAMPLE,P2Q,P2AUTO,P2AF,P2-FIN-LIVE-DECISION,P2-FIN-LIVE,PRELAUNCH,CASHIER-VOUCHER-V1,LAUNCH-DEPLOY-FINANCE,FIN-PROD-ENABLE,ACCOUNTING-HANDOFF-V1,SYSTEM-COMPLETE-GATE,LAUNCH-OPS-V1,REQ-COMPLETE-AUDIT,ATTV1,LAUNCH-AUTO-OPS-V1,AUTO-REMAINING-CLOSEOUT,HR-WECOM-DIRECTORY-V1,WFOC,DBWFOC,WFDG,WDRG,WCP1,WCPC,WHMS,WHMSLIVE,WOUA,WAPI,WRRA,WOUAFIX,WRV1,WRA1,WMSG1,WAPC1,WAPC2,WPROC1,WPROC2,WAPC2F,WAPC2FLIVE,WCBK1,WEGOV1,WARCH1,WARCH2,WROAD2,WARCH3,WCHECK1,WEXT1,WOPS1,WROAD2C,WROAD2B,WAPPR1,WRULE1,WAUTO1,WEXT1LD,WFULLSMOKE1,WTCLOSE2,WREAL1P,OAOPS1,ASSET1,OSMOKE1,OALAUNCH1,OMAT1,OPOLICY1,OAFLOW1,OAFRONT6,OAKISS1,PCDESIGN1` | `audit-docs` | none | 2026-05-25 | `audit-docs --check-registry` | medium | 判断文档权威性；登记当前 OALAUNCH1 最终启用 Go/No-Go、OMAT1 成熟度缺口、OPOLICY1 制度与 OA 对齐、OAFLOW1 负责人本人报销兜底、OAFRONT6 前端成熟化规划、OAKISS1 全业务 KISS 审查、PCDESIGN1 PC 全页面设计审查、OAOPS1、ASSET1、OSMOKE1、每日巡检、阻断即修和冻结项事实 | +| `IDX` | `docs/文档索引.md` | 入口索引 | 最高文档入口 | `CURRENT` | product/dev | `GOV8,QAOPS9,P2D,P2-ORG,P2-FIN-DECISION,P2-FIN-V1,P2-OCR-SAMPLE,P2Q,P2AUTO,P2AF,P2-FIN-LIVE-DECISION,P2-FIN-LIVE,PRELAUNCH,CASHIER-VOUCHER-V1,LAUNCH-DEPLOY-FINANCE,FIN-PROD-ENABLE,ACCOUNTING-HANDOFF-V1,SYSTEM-COMPLETE-GATE,LAUNCH-OPS-V1,REQ-COMPLETE-AUDIT,ATTV1,LAUNCH-AUTO-OPS-V1,AUTO-REMAINING-CLOSEOUT,HR-WECOM-DIRECTORY-V1,WFOC,DBWFOC,WFDG,WDRG,WCP1,WCPC,WHMS,WHMSLIVE,WOUA,WAPI,WRRA,WOUAFIX,WRV1,WRA1,WMSG1,WAPC1,WAPC2,WPROC1,WPROC2,WAPC2F,WAPC2FLIVE,WCBK1,WEGOV1,WARCH1,WARCH2,WROAD2,WARCH3,WCHECK1,WEXT1,WOPS1,WROAD2C,WROAD2B,WAPPR1,WRULE1,WAUTO1,WEXT1LD,WFULLSMOKE1,WTCLOSE2,WREAL1P,OAOPS1,ASSET1,OSMOKE1,OALAUNCH1,OMAT1,OPOLICY1,OAFLOW1,OAFRONT6,OAKISS1,PCDESIGN1,TRELLIS2` | `rg` | none | 2026-05-26 | `node scripts/qa/audit-docs.mjs --check-registry` | medium | 判断当前该读什么；TRELLIS2 后新开发先读当前 Trellis task，旧 Issue CSV 只追溯；仍优先读取 OALAUNCH1、OMAT1、OPOLICY1、OAFLOW1、OAFRONT6、OAKISS1、PCDESIGN1 等业务事实源 | +| `REG` | `docs/文档事实源状态矩阵.md` | 文档台账 | 文档分类和状态事实源 | `CURRENT` | product/dev | `GOV8,QAOPS9,P2D,P2-ORG,P2-FIN-DECISION,P2-FIN-V1,P2-OCR-SAMPLE,P2Q,P2AUTO,P2AF,P2-FIN-LIVE-DECISION,P2-FIN-LIVE,PRELAUNCH,CASHIER-VOUCHER-V1,LAUNCH-DEPLOY-FINANCE,FIN-PROD-ENABLE,ACCOUNTING-HANDOFF-V1,SYSTEM-COMPLETE-GATE,LAUNCH-OPS-V1,REQ-COMPLETE-AUDIT,ATTV1,LAUNCH-AUTO-OPS-V1,AUTO-REMAINING-CLOSEOUT,HR-WECOM-DIRECTORY-V1,WFOC,DBWFOC,WFDG,WDRG,WCP1,WCPC,WHMS,WHMSLIVE,WOUA,WAPI,WRRA,WOUAFIX,WRV1,WRA1,WMSG1,WAPC1,WAPC2,WPROC1,WPROC2,WAPC2F,WAPC2FLIVE,WCBK1,WEGOV1,WARCH1,WARCH2,WROAD2,WARCH3,WCHECK1,WEXT1,WOPS1,WROAD2C,WROAD2B,WAPPR1,WRULE1,WAUTO1,WEXT1LD,WFULLSMOKE1,WTCLOSE2,WREAL1P,OAOPS1,ASSET1,OSMOKE1,OALAUNCH1,OMAT1,OPOLICY1,OAFLOW1,OAFRONT6,OAKISS1,PCDESIGN1,TRELLIS2` | `audit-docs` | none | 2026-05-26 | `audit-docs --check-registry` | medium | 判断文档权威性；登记 TRELLIS2 官方 task-first 口径，以及当前 OALAUNCH1、OMAT1、OPOLICY1、OAFLOW1、OAFRONT6、OAKISS1、PCDESIGN1、OAOPS1、ASSET1、OSMOKE1、每日巡检、阻断即修和冻结项事实 | | `PRD-MVP` | `docs/海音达OA-MVP需求规格说明书.md` | 需求事实源 | PRD 主事实源 | `CURRENT` | product | `REQ8,P2T,GOV8,HR-WECOM-DIRECTORY-V1,WFOC,DBWFOC,WFDG,WDRG,WCP1,WCPC,WHMS,WHMSLIVE,WOUA,WAPI,WRRA,WAPC1,WAPC2,WAPC2FLIVE,WCBK1,WEGOV1,WACP3,WACP3R,WARCH1,WARCH2,WROAD2,WARCH3,WCHECK1,WEXT1` | Issue CSV | `docs/requirements-specification.md` | 2026-05-20 | `rg` | high | WARCH3/WCHECK1/WEXT1/WOPS1 后定义 HR/考勤企微主办、OA 自建留存、受控测试域、只读历史查询、自动巡检、打卡摘要、外出/加班 dry-run、WEXT1-FORMAL、WREAL1 前置和深度镜像边界；ERP 未来不接入 OA | | `PRODUCT-SCOPE` | `docs/产品口径.md` | 需求事实源 | 产品边界事实源 | `CURRENT` | product | `REQ8,P2T,WFDG,WDRG,WCP1,WCPC,WHMS,WHMSLIVE,WOUA,WAPI,WRRA,WAPC1,WAPC2FLIVE,WCBK1,WEGOV1` | `rg` | none | 2026-05-19 | `rg` | high | 记录已拍板产品边界、企微/OA 设计门禁、开发路线图、WCBK1 真实回调事件证据、WEGOV1 混合主办边界和 OA 自建留存策略 | | `DESIGN-UI` | `docs/产品设计规则.md` | 设计事实源 | PC/移动/企业微信设计事实源 | `CURRENT` | design/frontend | `MIA7,MIF7,GOV8,DG8,DG9,WFDG` | Playwright/视觉审查/DG8/DG9/WFDG | none | 2026-05-18 | `rg` | high | 页面改动必须读取；DG8 后飞书为主 UI/布局参考；DG9 后按页面分层和样板选型；WFDG 后区分 OA 主办、企微镜像和 OA 应急接管 | @@ -136,10 +137,10 @@ | `WECOM-API-CATALOG` | `docs/企微API能力目录.md` | 集成事实源 | 企微 API 能力目录和 Secret 矩阵事实源 | `CURRENT` | product/backend/qa | `WAPI,WRRA,WAPC1,WAPC2,WPROC1,WPROC2,WAPC2F,WAPC2FLIVE,WCBK1,WEGOV1,WACP3,WACP3R,WREAD1,WADM1,WARCH1,WARCH2,WROAD2,WARCH3,WCHECK1,WEXT1,WAPPR1,WTCLOSE1,WRULE1,WTCLOSE2` | 官方企业微信开发者中心链接/Issue CSV | none | 2026-05-22 | `rg` | high | 企微开发先读；只保存摘要、链接和项目决策，不保存 Secret、token、完整 userid、手机号、邮箱或原始 payload；记录审批补偿、打卡摘要、巡检只写 OA 留存、不写企业微信、企微原生审批规则不可只读 API 化、需人工门禁，以及 WRULE1/WTCLOSE2 只读审批链校验和最终收口边界 | | `DELIVERY` | `docs/开发交付与变更管理规约.md` | 开发治理 | 开发交付事实源 | `CURRENT` | dev/qa | `GOV8,WDRG,WRRA,WAPC1,WPROC1,WPROC2,WCBK1,WEGOV1,WOPS1,WROAD2C,WROAD2B,WAPPR1,WAUTO1,WEXT1LD,WFULLSMOKE1` | `rg` | none | 2026-05-20 | `rg` | high | Issue、review、commit、交付规则；WFULLSMOKE1 后固定 WAUTO1、WEXT1LD、全域最终目标测试和 WEXT1-FORMAL/WREAL1 前置门禁 | | `QA-GATE` | `docs/测试规约与回归门禁.md` | 测试验收 | 测试和回归门禁事实源 | `CURRENT` | qa | `QAF8,GOV8,WPROC1,WPROC2,WAPC2FLIVE,WCBK1,WEGOV1` | 回归脚本/Playwright | none | 2026-05-19 | `rg` | high | 测试计划、DONE 门禁、企微三层门禁、自动化优先、非自审、无完整 sandbox 假设、WREAD1 真机可读性和 WARCH1 留存验收门禁 | -| `AGENT-PRACTICE` | `docs/Agent开发交付实践.md` | Agent 治理 | Agent 协作事实源 | `CURRENT` | dev | `GOV8,DG8` | Skill 校验 | none | 2026-05-13 | `rg` | medium | Agent 协作开发实践和设计主参考层级 | +| `AGENT-PRACTICE` | `docs/Agent开发交付实践.md` | Agent 治理 | Agent 协作事实源 | `CURRENT` | dev | `GOV8,DG8,TRELLIS2` | Skill 校验 | none | 2026-05-26 | `rg` | medium | Agent 协作开发实践、设计主参考层级和 TRELLIS2 官方 task-first 执行合同口径 | | `AGENTS` | `AGENTS.md` | 执行硬约束 | 项目硬规则 | `CURRENT` | lead | `GOV8` | 人工核对 | none | 2026-05-13 | `rg` | high | 不可违反约束 | -| `SKILL-HYB` | `.agents/skills/hyb-oa-delivery/SKILL.md` | Skill | 项目交付 Skill | `CURRENT` | dev | `GOV8,DG8,WFDG,WDRG,WCP1,WCPC,WHMS,WHMSLIVE,WOUA,WAPI,WRRA,WRV1,WRA1,WMSG1,WAPC1,WAPC2,WPROC1,WPROC2,WAPC2F,WAPC2FLIVE,WCBK1,WEGOV1,WACP3,WACP3R,WREAD1,WREAD1F,WADM1,WARCH1,WARCH2,WROAD2,WARCH3,WCHECK1,WEXT1,WOPS1,WROAD2C,WROAD2B,WAPPR1,WRULE1,WAUTO1,WEXT1LD,WFULLSMOKE1,WROUTE2,WTCLOSE1,WTCLOSE2,WREAL1P,OAOPS1,ASSET1,OSMOKE1,OALAUNCH1,OMAT1,OPOLICY1,OAFLOW1,OAFRONT6` | quick_validate | none | 2026-05-25 | `quick_validate.py` | medium | 每轮交付操作入口；企微/OA 后续先读 API 能力目录、Secret 矩阵、路线图、ASSET1 资产边界、OSMOKE1 OA-only smoke 账号治理、OALAUNCH1 最终启用门禁、OPOLICY1 小团队 V1 制度对齐、OAFLOW1 负责人本人报销兜底和 OAFRONT6 前端成熟化规划；不得绕过真实业务闭环、权限矩阵、备份恢复、制度签收、Day 7 Go/No-Go 或后续独立合同直接宣布最终启用完成 | -| `TRELLIS-WORKFLOW` | `.trellis/workflow.md` | Trellis | 开发主流程入口 | `CURRENT` | dev | `TRELLIS1` | `check-trellis-governance` | `AGENTS.md,.trellis/spec/hyb-oa/` | 2026-05-26 | `node scripts/qa/check-trellis-governance.mjs` | medium | TRELLIS1 后后续非微小开发默认从 Trellis task 进入；Issue CSV 和 docs 仍是审计/业务事实源 | +| `SKILL-HYB` | `.agents/skills/hyb-oa-delivery/SKILL.md` | Skill | 项目交付 Skill | `CURRENT` | dev | `GOV8,DG8,WFDG,WDRG,WCP1,WCPC,WHMS,WHMSLIVE,WOUA,WAPI,WRRA,WRV1,WRA1,WMSG1,WAPC1,WAPC2,WPROC1,WPROC2,WAPC2F,WAPC2FLIVE,WCBK1,WEGOV1,WACP3,WACP3R,WREAD1,WREAD1F,WADM1,WARCH1,WARCH2,WROAD2,WARCH3,WCHECK1,WEXT1,WOPS1,WROAD2C,WROAD2B,WAPPR1,WRULE1,WAUTO1,WEXT1LD,WFULLSMOKE1,WROUTE2,WTCLOSE1,WTCLOSE2,WREAL1P,OAOPS1,ASSET1,OSMOKE1,OALAUNCH1,OMAT1,OPOLICY1,OAFLOW1,OAFRONT6,TRELLIS2` | quick_validate | none | 2026-05-26 | `quick_validate.py` | medium | 每轮交付操作入口；TRELLIS2 后非微小工作先读当前 Trellis task；企微/OA 后续先读 API 能力目录、Secret 矩阵、路线图、ASSET1 资产边界、OSMOKE1、OALAUNCH1、OPOLICY1、OAFLOW1 和 OAFRONT6；不得绕过真实业务闭环、权限矩阵、备份恢复、制度签收、Day 7 Go/No-Go 或后续独立合同直接宣布最终启用完成 | +| `TRELLIS-WORKFLOW` | `.trellis/workflow.md` | Trellis | 开发主流程入口 | `CURRENT` | dev | `TRELLIS2` | `check-trellis-governance` | `AGENTS.md,.trellis/spec/hyb-oa/` | 2026-05-26 | `node scripts/qa/check-trellis-governance.mjs` | medium | TRELLIS2 后后续非微小开发默认从官方 Trellis task 进入；Issue CSV 只作历史审计或可选导出格式，docs 仍是业务事实源 | | `REQ-WF` | `docs/需求-统一审批中心规约.md` | 需求事实源 | 审批模块规约 | `CURRENT` | product/backend | `AP6,WF8,WFOC,DBWFOC,WFDG,WOUA,WAPI,WRRA,WRV1,WRA1,WMSG1,WAPC1,WAPC2,WPROC1,WPROC2,WAPC2F,WAPC2FLIVE,WCBK1,WEGOV1,WACP3,WACP3R,WREAD1,WREAD1F,WADM1,WARCH1,WAPPR1,WAUTO1,WEXT1LD,WFULLSMOKE1,WTCLOSE1,WRULE1,WTCLOSE2,OAFLOW1` | workflow 回归 | none | 2026-05-24 | `rg` | high | OA 主办审批、企微主办 HR/考勤审批、OA 自建留存、真实回调事件证据、WACP3R 补偿拉取 findings、WREAD1 请假/补卡真机可读性结论、WARCH1 最小历史留存、WAPPR1 审批规则规范化和 API 不支持读取规则边界、WTCLOSE1 小团队一层审批 + 管理员兜底目标 A、WRULE1 理论审批人与实际审批链校验、WTCLOSE2 测试号最终收口、OAFLOW1 负责人本人报销兜底、WAUTO1/WEXT1LD/WFULLSMOKE1 前置和 OA 应急接管边界 | | `REQ-OCR` | `docs/需求-报销发票OCR规约.md` | 需求事实源 | OCR 模块规约 | `CURRENT` | product/backend | `RI6,OCR8,BIZ8` | OCR 回归 | none | 2026-05-13 | `rg` | high | OCR 和发票边界 | | `RULE-REIMB` | `docs/报销发票附件规则.md` | 需求事实源 | 报销发票附件规则 | `CURRENT` | product/finance | `RI6,BIZ8` | 报销回归 | none | 2026-05-13 | `rg` | high | 报销、发票、附件细则 | @@ -176,7 +177,7 @@ | `docs/需求-项目轻管理规约.md` | 当前事实源 | 项目轻管理 | | `docs/需求-资产管理规约.md` | 当前事实源 | 统一资产台账、电子资产安全边界和资产编号族 | | `docs/测试规约与回归门禁.md` | 当前事实源 | 测试和回归门禁 | -| `docs/开发交付与变更管理规约.md` | 当前事实源 | Issue CSV、review、提交和交付 | +| `docs/开发交付与变更管理规约.md` | 当前事实源 | Trellis task、review、提交和交付 | | `docs/Agent开发交付实践.md` | 当前事实源 | Agent 协作开发实践 | | `AGENTS.md` | 当前事实源 | 项目硬约束 | | `.agents/skills/hyb-oa-delivery/SKILL.md` | 当前事实源 | 项目交付 Skill | diff --git a/docs/文档索引.md b/docs/文档索引.md index 685e4bf8..8fa74081 100644 --- a/docs/文档索引.md +++ b/docs/文档索引.md @@ -10,17 +10,17 @@ ## 读取规则 -- 判断当前需求、开发、验收：读最新 Issue CSV、当前 PRD、模块规约和本索引。 +- 判断当前需求、开发、验收：读当前 Trellis task、当前 PRD、模块规约和本索引。 - 判断历史证据：读轻量历史索引，必要时用 `git show :` 恢复旧文档。 -- 判断冲突：最新 Issue CSV > 当前 PRD/模块规约 > 设计和产品规则 > 当前操作手册 > 技术参考 > 历史证据。 +- 判断冲突：当前 Trellis task PRD/设计 > 当前 PRD/模块规约 > 设计和产品规则 > 当前操作手册 > 技术参考 > 历史证据。 - 英文文件名只在技术生态或脚本强引用时保留，例如 `docs/mcp-tools.md`。 -- 判断当前可执行任务：只读当前活跃治理流和对应连续型 Issue CSV；旧 Issue CSV 默认是历史审计证据。 -- 新需求或试运行反馈：优先进入当前同类型连续治理流；只有跨业务域、跨风险等级或阶段收口后，才新建下一版 CSV。 -- 新增说明、方案、审计或证据：优先补充现有事实源、模块规约、操作手册、证据文档或当前连续 Issue CSV；只有现有文档无法承载、需要独立审计证据或用户明确要求时，才新建文档并登记本索引和事实源矩阵。 +- 判断当前可执行任务：先读当前 Trellis task；旧 Issue CSV 默认是历史审计证据。 +- 新需求或试运行反馈：优先创建或更新当前同类型 Trellis task；只有跨业务域、跨风险等级或阶段收口后，才新建下一版 task。 +- 新增说明、方案、审计或证据：优先补充现有事实源、模块规约、操作手册、证据文档或当前 Trellis task；只有现有文档无法承载、需要独立审计证据或用户明确要求时，才新建文档并登记本索引和事实源矩阵。 ## 最近事实源链 -R6 -> PC6 -> PA6 -> FL6 -> AP6 -> RI6 -> LP6 -> ME6/QG6 -> DG7/MRF7 -> MIA7 -> MIF7/MIF7T(公网部署与带凭据公网复检已收口) -> DG8 -> DG9 -> R7E -> FBA -> QAOPS9/P2D -> P2-ORG -> P2-FIN-DECISION -> P2-FIN-V1 -> P2-OCR-SAMPLE -> P2Q -> P2AUTO -> P2AF -> P2-FIN-LIVE-DECISION -> P2-FIN-LIVE -> PRELAUNCH -> CASHIER-VOUCHER-V1 -> LAUNCH-DEPLOY-FINANCE -> FIN-PROD-ENABLE -> ACCOUNTING-HANDOFF-V1 -> SYSTEM-COMPLETE-GATE -> LAUNCH-OPS-V1 -> REQ-COMPLETE-AUDIT -> ATTV1 -> LAUNCH-AUTO-OPS-V1 -> AUTO-REMAINING-CLOSEOUT -> HR-WECOM-DIRECTORY-V1 -> HRWD-CONTACT-LIVE-TEST -> WCFB -> WFOC -> DBWFOC -> WFDG -> WDRG -> WCP1 -> WCPC -> WHMS -> WHMSLIVE -> WOUA -> WAPI -> WRRA -> WOUA-FIX -> WRV1 -> WRA1 -> WMSG1 -> WAPC1 -> WAPC2 -> WPROC1 -> WPROC2 -> WAPC2F dry-run -> WAPC2FLIVE -> WCBK1 -> WEGOV1 -> WACP3/WACP3R -> WREAD1 自动汇总 -> WREAD1F 新样例 -> WREAD1 真机确认 -> WADM1 自建留存模型设计 -> WARCH1 最小审批历史留存 -> WARCH2 正式只读历史查询 -> WROAD2+OPS 受控上线与每日巡检 -> WARCH3 归档稳定化自动巡检 -> WCHECK1 打卡摘要留存 -> WEXT1 外出/加班 dry-run -> WOPS1 巡检告警降噪 -> WROAD2-CLOSEOUT 三天验收 -> WROAD2-BIZ1 三天业务冒烟 -> WAPPR1 审批规则规范化 -> WRULE1 审批链校验器 POC -> WAUTO1 自动证据汇总 -> WEXT1LD live 前 dry-run -> WFULLSMOKE1 三天全域最终目标测试 -> WROUTE2 测试号收口到最小镜像路线锁定 -> WTCLOSE1 小团队自动审批规则与测试号全域收口 dry-run -> WTCLOSE2 测试号最终收口与证据复核 -> WTCLOSE2F 远端可信 IP 执行口径修正 -> WREMOTE1 远端可信 IP 收口 -> WFULLSMOKE2 全域 smoke -> WEXT1-FORMAL/WEXT1F 正式模板外出/加班测试 -> OAOPS1 小团队全员真实使用稳定化 -> ASSET1 电子资产与固定资产统一台账 -> OSMOKE1 OA-only smoke 账号治理与公网自动化恢复 -> OALAUNCH1 最终启用前收口与 Go/No-Go 门禁 -> OMAT1 成熟度缺口审查 -> OPOLICY1 制度与 OA 对齐 -> OAFRONT6 前端成熟化小步收口（标题/资产/移动/合同/长编号已部署并公网复测通过）-> OAKISS1 全业务流程 KISS 审查 -> PCDESIGN1 PC 全页面设计审查 -> TRELLIS1 Trellis 主导开发流程迁移 -> 后续再按需问答 WREAL1/最小镜像。 +R6 -> PC6 -> PA6 -> FL6 -> AP6 -> RI6 -> LP6 -> ME6/QG6 -> DG7/MRF7 -> MIA7 -> MIF7/MIF7T(公网部署与带凭据公网复检已收口) -> DG8 -> DG9 -> R7E -> FBA -> QAOPS9/P2D -> P2-ORG -> P2-FIN-DECISION -> P2-FIN-V1 -> P2-OCR-SAMPLE -> P2Q -> P2AUTO -> P2AF -> P2-FIN-LIVE-DECISION -> P2-FIN-LIVE -> PRELAUNCH -> CASHIER-VOUCHER-V1 -> LAUNCH-DEPLOY-FINANCE -> FIN-PROD-ENABLE -> ACCOUNTING-HANDOFF-V1 -> SYSTEM-COMPLETE-GATE -> LAUNCH-OPS-V1 -> REQ-COMPLETE-AUDIT -> ATTV1 -> LAUNCH-AUTO-OPS-V1 -> AUTO-REMAINING-CLOSEOUT -> HR-WECOM-DIRECTORY-V1 -> HRWD-CONTACT-LIVE-TEST -> WCFB -> WFOC -> DBWFOC -> WFDG -> WDRG -> WCP1 -> WCPC -> WHMS -> WHMSLIVE -> WOUA -> WAPI -> WRRA -> WOUA-FIX -> WRV1 -> WRA1 -> WMSG1 -> WAPC1 -> WAPC2 -> WPROC1 -> WPROC2 -> WAPC2F dry-run -> WAPC2FLIVE -> WCBK1 -> WEGOV1 -> WACP3/WACP3R -> WREAD1 自动汇总 -> WREAD1F 新样例 -> WREAD1 真机确认 -> WADM1 自建留存模型设计 -> WARCH1 最小审批历史留存 -> WARCH2 正式只读历史查询 -> WROAD2+OPS 受控上线与每日巡检 -> WARCH3 归档稳定化自动巡检 -> WCHECK1 打卡摘要留存 -> WEXT1 外出/加班 dry-run -> WOPS1 巡检告警降噪 -> WROAD2-CLOSEOUT 三天验收 -> WROAD2-BIZ1 三天业务冒烟 -> WAPPR1 审批规则规范化 -> WRULE1 审批链校验器 POC -> WAUTO1 自动证据汇总 -> WEXT1LD live 前 dry-run -> WFULLSMOKE1 三天全域最终目标测试 -> WROUTE2 测试号收口到最小镜像路线锁定 -> WTCLOSE1 小团队自动审批规则与测试号全域收口 dry-run -> WTCLOSE2 测试号最终收口与证据复核 -> WTCLOSE2F 远端可信 IP 执行口径修正 -> WREMOTE1 远端可信 IP 收口 -> WFULLSMOKE2 全域 smoke -> WEXT1-FORMAL/WEXT1F 正式模板外出/加班测试 -> OAOPS1 小团队全员真实使用稳定化 -> ASSET1 电子资产与固定资产统一台账 -> OSMOKE1 OA-only smoke 账号治理与公网自动化恢复 -> OALAUNCH1 最终启用前收口与 Go/No-Go 门禁 -> OMAT1 成熟度缺口审查 -> OPOLICY1 制度与 OA 对齐 -> OAFRONT6 前端成熟化小步收口（标题/资产/移动/合同/长编号已部署并公网复测通过）-> OAKISS1 全业务流程 KISS 审查 -> PCDESIGN1 PC 全页面设计审查 -> TRELLIS1 Trellis 主导开发流程迁移 -> TRELLIS2 官方 Trellis task 执行合同 -> 后续再按需问答 WREAL1/最小镜像。 - R6、PC6、PA6、FL6、AP6、RI6、LP6 已完成并部署。 - ME6 自动化、公网视觉矩阵和 `ME6-3` 代表性企业微信真机门禁已完成。 @@ -84,7 +84,7 @@ R6 -> PC6 -> PA6 -> FL6 -> AP6 -> RI6 -> LP6 -> ME6/QG6 -> DG7/MRF7 -> MIA7 -> M ## 当前活跃治理流 -后续不再为每次聊天、小反馈或单点修正单独创建 Issue CSV。同类型、同目标、同风险域的任务优先进入同一个连续型 Issue CSV，直到该治理流完成明确阶段。 +后续不再为每次聊天、小反馈或单点修正单独创建 Issue CSV。同类型、同目标、同风险域的任务优先进入同一个 Trellis task 或子任务，直到该治理流完成明确阶段。 | 治理流 | 当前合同 | 当前状态 | 范围 | 不做 | | --- | --- | --- | --- | --- | @@ -178,21 +178,22 @@ R6 -> PC6 -> PA6 -> FL6 -> AP6 -> RI6 -> LP6 -> ME6/QG6 -> DG7/MRF7 -> MIA7 -> M | `OAFRONT6` | `issues/2026-05-25_12-29-03-oa-frontend-maturity-small-step-v1.csv` | 当前前端成熟化小步收口：承接 OAFRONT5 部署后 PC 硬问题清零和设计审计；审批规则路由标题、资产台账详情分区、移动视觉矩阵稳定等待、合同台账表单分组和长编号压缩均已实施部署，公网 PC 只读视觉矩阵复测 `PASS_PC_READONLY_VISUAL_READY` 且 `findingCount=0`；Portal 继续后置观察 | 页面改动继续读取 `docs/产品设计规则.md` 和 OALAUNCH1 启用门禁；后续 Portal 仍需按真实使用反馈推进 | 不写公网业务数据；不替代真实业务闭环、备份恢复、7 天稳定化或 Day 7 Go/No-Go | | `OAKISS1` | `issues/2026-05-25_20-53-34-oa-business-flow-kiss-review-v1.csv` | 当前全业务流程 KISS 审查台账：按 MAGI 审视/执行/提升轮次，对报销/OCR、审批、采购/费用、合同/项目、付款/AP、票据池、资产、权限、移动/企微入口逐项做自动化和人工步骤审查 | 已形成 OAOPS1、OALAUNCH1、权限矩阵、PC 视觉、负责人审批链、资产试录和 OCR 辅助证据；建议保留 P0 主流程、简化 TEST/SMOKE 噪声和高密度后台页、后置 P2 复杂能力 | 本台账只做审查和建议，不直接改业务代码；真实业务闭环、备份恢复和 Day 7 Go/No-Go 仍按 OALAUNCH1 人工门禁执行 | | `PCDESIGN1` | `issues/2026-05-25_21-27-56-oa-pc-page-design-review-v1.csv` | 当前 PC 全页面设计审查台账：以项目经理和设计总监视角按 MAGI 审视/执行/提升轮次盘点 PC 路由、页面分层、交互、内容和 KISS 建议 | 已复跑关键 PC 视觉矩阵 `PASS_PC_READONLY_VISUAL_READY`，并补全 45 条静态 PC 路由扫描 `PASS_PC_STATIC_ROUTE_SCAN_READY`；建议优先收敛 HR/考勤边界、冻结模块入口、高密度 B/C 页默认视图和动态详情页证据 | 本台账只做审查和建议，不直接改业务代码；采纳后必须另建前端实施 Issue CSV | -| `TRELLIS1` | `issues/2026-05-26_09-02-34-trellis-primary-development-workflow-v1.csv` | 当前 Trellis 主导开发流程迁移合同：后续非微小开发默认从 `.trellis/tasks/` 进入，以 `.trellis/workflow.md` 组织计划、实施、检查和复盘 | Trellis 只做开发流程和上下文组织；Issue CSV 仍是执行合同，`docs/` 仍是业务事实源；`.trellis/workspace/` 默认不提交 | 本合同不改业务代码、不部署、不写公网数据；提交前必须通过 `node scripts/qa/check-trellis-governance.mjs` | +| `TRELLIS1` | `issues/2026-05-26_09-02-34-trellis-primary-development-workflow-v1.csv` | 历史迁移合同：完成 Trellis-first 初始接入 | Trellis task/spec/workflow 成为开发入口的第一步，旧口径仍保留 Issue CSV 绑定 | 历史审计；已由 TRELLIS2 官方 task 合同口径替代 | +| `TRELLIS2` | `.trellis/tasks/05-26-trellis2-official-task-contract/` | 当前开发流程合同：采用官方 Trellis task 作为新任务执行合同 | `prd.md` 承载需求/验收/测试，复杂任务补 `design.md` 或 `implement.md`，Issue CSV 降级为历史审计或可选导出格式 | 不改业务代码、不部署、不写公网数据；提交前必须通过 `node scripts/qa/check-trellis-governance.mjs` | | `WREAL1-PREP` | `issues/2026-05-20_14-35-42-wecom-real-trial-prep-v1.csv` | 当前真实试用准备：不启用真实员工 | 固化候选员工、非自审审批人、回滚联系人、允许流程、暂停条件和验收标准；真实试用必须等请假、补卡、外出、加班四类测试号证据、WAPPR1 和 WFULLSMOKE1 通过后再问 | 当前不创建外出/加班 live 样件；真实员工名单不写入 Issue 或文档，后续通过问答确认 | -旧 Issue CSV 不删除、不批量回写、不移动到归档目录。若新治理流替代旧合同，只在新 CSV 的 `Notes` 或本索引说明 supersedes，旧文件保留历史审计语义。 +旧 Issue CSV 不删除、不批量回写、不移动到归档目录。若新治理流替代旧合同，只在新 Trellis task、文档索引或事实源矩阵中说明 supersedes，旧文件保留历史审计语义。 ## 按开发阶段阅读 | 阶段 | 必读入口 | 目的 | | --- | --- | --- | -| 需求阶段 | 最新同类型连续 Issue CSV、[海音达OA-MVP需求规格说明书](./海音达OA-MVP需求规格说明书.md)、对应 `需求-*.md`、[产品口径](./产品口径.md) | 判断做什么、不做什么、验收什么 | +| 需求阶段 | 当前 Trellis task、[海音达OA-MVP需求规格说明书](./海音达OA-MVP需求规格说明书.md)、对应 `需求-*.md`、[产品口径](./产品口径.md) | 判断做什么、不做什么、验收什么 | | 设计阶段 | 最新设计治理合同、[产品设计规则](./产品设计规则.md)、[架构概览](./架构概览.md)、[集成边界](./集成边界.md)、`docs/ops/*.md`、必要 ADR | 判断页面、权限、状态流、集成和非功能边界 | -| 开发阶段 | 当前连续 Issue CSV、[开发交付与变更管理规约](./开发交付与变更管理规约.md)、`AGENTS.md` | 判断文件范围、依赖、方案批准和交接物 | -| 测试阶段 | [测试规约与回归门禁](./测试规约与回归门禁.md)、[试运行与自动化验证手册](./试运行与自动化验证手册.md)、当前 Issue 的 `Test_Method` | 判断怎么测、何时可回填 DONE | +| 开发阶段 | 当前 Trellis task、[开发交付与变更管理规约](./开发交付与变更管理规约.md)、`AGENTS.md` | 判断文件范围、依赖、方案批准和交接物 | +| 测试阶段 | [测试规约与回归门禁](./测试规约与回归门禁.md)、[试运行与自动化验证手册](./试运行与自动化验证手册.md)、当前 Trellis task 的 Test Plan | 判断怎么测、何时可收口 | | 发布阶段 | [发布试运行准备清单](./trialrun/发布试运行准备清单.md)、[公网 Live Smoke 准备清单](./trialrun/公网LiveSmoke准备清单.md)、[OPS7 运维交接 Runbook](./trialrun/OPS7运维交接Runbook.md) | 判断公网、企业微信、真实 OCR 和回滚条件 | -| 审计阶段 | [文档事实源状态矩阵](./文档事实源状态矩阵.md)、[人工试运行报告](./trialrun/人工试运行报告.md)、当前连续 Issue CSV、git 历史 | 判断当前事实、历史证据和冲突处理 | +| 审计阶段 | [文档事实源状态矩阵](./文档事实源状态矩阵.md)、[人工试运行报告](./trialrun/人工试运行报告.md)、当前 Trellis task、git 历史 | 判断当前事实、历史证据和冲突处理 | | 历史追溯 | [历史功能状态矩阵](./历史功能状态矩阵.md)、旧 Issue CSV、git 历史 | 只追溯，不直接派工 | ## 当前事实源 @@ -215,10 +216,10 @@ R6 -> PC6 -> PA6 -> FL6 -> AP6 -> RI6 -> LP6 -> ME6/QG6 -> DG7/MRF7 -> MIA7 -> M | [需求 - 项目轻管理规约](./需求-项目轻管理规约.md) | 项目轻管理边界 | | [需求 - 资产管理规约](./需求-资产管理规约.md) | 统一资产台账、编号族、电子资产安全边界和离职交接口径 | | [测试规约与回归门禁](./测试规约与回归门禁.md) | 自动化、视觉、真机、状态回填 | -| [开发交付与变更管理规约](./开发交付与变更管理规约.md) | Issue CSV、review、提交、交付和企微阶段门禁顺序 | +| [开发交付与变更管理规约](./开发交付与变更管理规约.md) | Trellis task、review、提交、交付和企微阶段门禁顺序 | | [Agent开发交付实践](./Agent开发交付实践.md) | Agent 协作和交付实践 | | [AGENTS 项目规则](../AGENTS.md) | 执行硬约束 | -| [Trellis Workflow](../.trellis/workflow.md) | TRELLIS1 后开发主流程入口 | +| [Trellis Workflow](../.trellis/workflow.md) | TRELLIS2 后官方 Trellis task 开发主流程入口 | ## 当前操作手册 @@ -288,7 +289,7 @@ R6 -> PC6 -> PA6 -> FL6 -> AP6 -> RI6 -> LP6 -> ME6/QG6 -> DG7/MRF7 -> MIA7 -> M ## 阅读顺序 -1. 新需求：PRD + 对应模块规约 + 最新 Issue CSV。 +1. 新需求：当前 Trellis task PRD + 对应模块规约。 2. 页面体验：产品设计规则；DG8 后先按主 UI/布局参考层级判断。 3. 报销/发票：报销发票附件规则 + 报销 OCR 规约。 4. 试运行/部署/真机：试运行手册 + 发布清单 + 真机清单。 diff --git a/scripts/qa/check-trellis-governance.mjs b/scripts/qa/check-trellis-governance.mjs index 19ec7a8e..bdf65fa1 100644 --- a/scripts/qa/check-trellis-governance.mjs +++ b/scripts/qa/check-trellis-governance.mjs @@ -25,7 +25,17 @@ const requiredDocMentions = [ ".agents/skills/hyb-oa-delivery/SKILL.md", ]; -const issueIdPattern = /^TRELLIS\d+-\d+$/; +const validTaskStatuses = new Set(["planning", "in_progress", "review", "completed"]); +const requiredPrdSections = [ + { code: "goal", pattern: /(^|\n)#{1,4}\s*(Goal|目标)\b/i }, + { code: "scope", pattern: /(^|\n)#{1,4}\s*(Scope|范围)\b/i }, + { code: "out_of_scope", pattern: /(^|\n)#{1,4}\s*(Out Of Scope|Out of Scope|不做|范围外|边界)\b/i }, + { code: "acceptance", pattern: /(^|\n)#{1,4}\s*(Acceptance|验收|完成口径)\b/i }, + { code: "test_plan", pattern: /(^|\n)#{1,4}\s*(Test Plan|测试计划|验证|Test Method)\b/i }, +]; + +const complexTaskPattern = + /\b(api|schema|migration|prisma|permission|role|deployment|production|database|remote|wecom|payment)\b|权限|状态机|审批|部署|公网|数据库|数据迁移|企业微信|付款|流程治理|workflow-governance/i; function readText(relativePath) { return fs.readFileSync(path.join(repoRoot, relativePath), "utf8"); @@ -60,46 +70,54 @@ function listTaskDirs() { .map((entry) => `.trellis/tasks/${entry.name}`); } -function parseCsvLine(line) { - const cells = []; - let current = ""; - let quoted = false; - for (let index = 0; index < line.length; index += 1) { - const char = line[index]; - const next = line[index + 1]; - if (quoted && char === "\"" && next === "\"") { - current += "\""; - index += 1; - continue; - } - if (char === "\"") { - quoted = !quoted; - continue; - } - if (!quoted && char === ",") { - cells.push(current); - current = ""; - continue; - } - current += char; - } - cells.push(current); - return cells; -} - -function issueIdsFromCsv(relativePath) { +function parseJsonl(relativePath) { const text = readText(relativePath); - const lines = text.split(/\r?\n/).filter((line) => line.trim()); - if (lines.length < 2) return new Set(); - const header = parseCsvLine(lines[0]); - const idIndex = header.indexOf("ID"); - if (idIndex < 0) return new Set(); - return new Set(lines.slice(1).map((line) => parseCsvLine(line)[idIndex]).filter(Boolean)); + return text + .split(/\r?\n/) + .map((line) => line.trim()) + .filter(Boolean) + .map((line, index) => { + try { + return { value: JSON.parse(line), line: index + 1 }; + } catch (error) { + throw new Error(`${relativePath}:${index + 1} invalid JSONL: ${error.message}`); + } + }); } -function normalizeIssueCsv(value) { - if (typeof value !== "string") return ""; - return value.trim().replace(/^\.?\//, ""); +function checkContextManifest(result, taskDir, action) { + const relativePath = `${taskDir}/${action}.jsonl`; + if (!exists(relativePath)) { + fail(result, `task.${action}_missing`, `${taskDir} missing ${action}.jsonl`); + return; + } + const entries = parseJsonl(relativePath); + let realEntryCount = 0; + for (const { value, line } of entries) { + if (value._example) { + fail(result, `task.${action}_seed`, `${relativePath}:${line} still contains seed _example row`); + continue; + } + if (typeof value.file !== "string" || !value.file.trim()) { + fail(result, `task.${action}_file`, `${relativePath}:${line} missing file`); + continue; + } + if (typeof value.reason !== "string" || !value.reason.trim()) { + fail(result, `task.${action}_reason`, `${relativePath}:${line} missing reason`); + continue; + } + if (!exists(value.file)) { + fail(result, `task.${action}_file_missing`, `${relativePath}:${line} references missing ${value.file}`); + continue; + } + if (!value.file.startsWith(".trellis/spec/") && !value.file.includes("/research/")) { + warn(result, `task.${action}_non_spec_context`, `${relativePath}:${line} should usually reference .trellis/spec/ or task research`); + } + realEntryCount += 1; + } + if (realEntryCount === 0) { + fail(result, `task.${action}_empty`, `${relativePath} must contain at least one real context entry`); + } } function createResult() { @@ -143,6 +161,9 @@ function checkCoreFiles(result) { } else { pass(result, "agents.workflow_pointer", "AGENTS.md points to Trellis workflow"); } + if (/每个 task 必须绑定|先有 Issue CSV 再开发/.test(agents)) { + fail(result, "agents.legacy_issue_required", "AGENTS.md still requires Issue CSV before development"); + } } if (exists(".trellis/config.yaml")) { @@ -158,7 +179,7 @@ function checkCoreFiles(result) { } } -function checkTaskBindings(result) { +function checkTaskContracts(result) { const taskDirs = listTaskDirs(); if (taskDirs.length === 0) { fail(result, "tasks.none", "no .trellis/tasks/* directories found"); @@ -173,36 +194,37 @@ function checkTaskBindings(result) { continue; } const task = JSON.parse(readText(taskJsonPath)); - const issueCsv = normalizeIssueCsv(task.meta?.issueCsv); - const issueIds = Array.isArray(task.meta?.issueIds) ? task.meta.issueIds : []; const prdText = exists(prdPath) ? readText(prdPath) : ""; - const csvFromPrd = prdText.match(/issues\/[A-Za-z0-9_.-]+\.csv/)?.[0] ?? ""; - const boundCsv = issueCsv || csvFromPrd; - if (!boundCsv) { - fail(result, "task.issue_csv", `${dir} must bind an Issue CSV in task.json meta or prd.md`); + if (!task.id || !task.name || !task.title) { + fail(result, "task.identity", `${dir} task.json must include id, name and title`); + } + if (!validTaskStatuses.has(task.status)) { + fail(result, "task.status", `${dir} has invalid status ${task.status}`); + } + if (typeof task.description !== "string" || !task.description.trim()) { + fail(result, "task.description", `${dir} task.json must include description`); + } + if (!exists(prdPath)) { + fail(result, "task.prd_missing", `${dir} missing prd.md`); continue; } - if (!exists(boundCsv)) { - fail(result, "task.issue_csv_missing", `${dir} references missing ${boundCsv}`); - continue; - } - - const ids = issueIds.length > 0 ? issueIds : [...prdText.matchAll(/TRELLIS\d+-\d+/g)].map((match) => match[0]); - if (ids.length === 0) { - fail(result, "task.issue_ids", `${dir} must bind at least one TRELLIS Issue ID`); - continue; - } - const csvIds = issueIdsFromCsv(boundCsv); - for (const id of ids) { - if (!issueIdPattern.test(id)) { - fail(result, "task.issue_id_format", `${dir} has invalid Issue ID ${id}`); - } else if (!csvIds.has(id)) { - fail(result, "task.issue_id_missing", `${dir} references ${id}, not found in ${boundCsv}`); + for (const section of requiredPrdSections) { + if (!section.pattern.test(prdText)) { + fail(result, `task.prd_${section.code}`, `${prdPath} missing ${section.code} section`); } } + if (!task.scope && (!Array.isArray(task.relatedFiles) || task.relatedFiles.length === 0)) { + fail(result, "task.scope", `${dir} must declare scope or relatedFiles in task.json`); + } + const complexText = [task.title, task.description, task.scope, task.notes, prdText].filter(Boolean).join("\n"); + if (complexTaskPattern.test(complexText) && !exists(`${dir}/design.md`) && !exists(`${dir}/implement.md`)) { + fail(result, "task.complex_design", `${dir} complex task must include design.md or implement.md`); + } + checkContextManifest(result, dir, "implement"); + checkContextManifest(result, dir, "check"); } - if (result.status === "PASS") pass(result, "task_bindings", `${taskDirs.length} task directories are bound`); + if (result.status === "PASS") pass(result, "task_contracts", `${taskDirs.length} task directories have Trellis contracts`); } function checkDocsRegistration(result) { @@ -212,9 +234,9 @@ function checkDocsRegistration(result) { continue; } const text = readText(file); - const hasTrellis = text.includes("TRELLIS1") || text.includes(".trellis") || text.includes("Trellis"); + const hasTrellis = text.includes("TRELLIS2") || text.includes(".trellis") || text.includes("Trellis"); if (!hasTrellis) { - fail(result, "docs.trellis_registration", `${file} must mention Trellis/TRELLIS1`); + fail(result, "docs.trellis_registration", `${file} must mention Trellis/TRELLIS2`); } } if (result.status === "PASS") pass(result, "docs_registration", `${requiredDocMentions.length} fact sources mention Trellis`); @@ -246,7 +268,7 @@ function checkSensitiveData(result) { const result = createResult(); try { checkCoreFiles(result); - checkTaskBindings(result); + checkTaskContracts(result); checkDocsRegistration(result); checkSensitiveData(result); } catch (error) {