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

Project Governance

Main Rule

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.
• 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.
• In sub-agent dispatch mode, curate implement.jsonl and check.jsonl with stable spec or research context only. In Codex inline mode they may contain no real entries because the main session reads specs directly.
• Give a concrete implementation plan before coding and wait for approval.
• Keep edits scoped to the current Trellis task.
• Commit in Chinese and include the Trellis task name or task ID.

Solo Developer Operating Mode

hyb-oa is developed and maintained by one primary developer. Optimize every feature, improvement and refactor for low error rate, fast review, clear rollback and future self-maintenance.

• Prefer small, independently verifiable slices over broad rewrites.
• Before adding a new capability, ask whether it is high-frequency for a domestic tech startup with fewer than 10 people; low-frequency capability should be deferred, hidden behind advanced/admin entry, or kept as a manual procedure unless the current Trellis task explicitly approves it.
• Prefer existing modules, shared components, scripts and runbooks over new abstractions. Add platform-like infrastructure only when it removes real repeated work or reduces operational risk.
• Every task should state the minimum useful validation command set before implementation; do not rely on manual memory for gates.
• Keep rollout and rollback obvious. For public-facing changes, record the exact commit, deployment command, public check and whether the user can test.
• Capture reusable lessons in docs/, .trellis/spec/ or the current task while they are fresh; do not depend on chat history for project rules.

Stop Conditions

• Production config, deployment, database reset, migration drift, real data writes, Enterprise WeChat writes, payment actions, or destructive cleanup need explicit approval.
• Permission model, status machine, workflow engine, migration or approval-rule changes require read-only reviewer review after implementation.

Current Local Commands

• python3 ./.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.

Scenario: Codex Inline Context Manifests

1. Scope / Trigger

• Trigger: creating, validating or finishing a Trellis task while .trellis/config.yaml sets codex.dispatch_mode: inline.

2. Signatures

• Config: codex.dispatch_mode: inline | sub-agent.
• Context files: <task>/implement.jsonl, <task>/check.jsonl.
• Gates: node scripts/qa/check-trellis-governance.mjs and python3 ./.trellis/scripts/task.py validate <task>.

3. Contracts

• Inline mode may keep both JSONL files at zero real entries; the seed _example row does not count as injected context.
• If an inline task contains real entries, each entry must still be valid JSON with non-empty file and reason; normal path and context warnings apply.
• Sub-agent mode requires at least one real entry in each manifest.
• Switching dispatch mode changes the validation policy, not historical task evidence and not the requirement to read specs before implementation.

4. Validation & Error Matrix

• Inline + zero real entries -> pass with *_inline_optional.
• Inline + malformed real entry -> fail.
• Sub-agent + zero real entries -> fail with *_empty.
• Either mode + non-spec/non-research context -> warning for review.

5. Good/Base/Bad Cases

• Good: inline task uses the seed-only files and the main agent reads specs.
• Base: inline task keeps curated entries for audit; they remain validated.
• Bad: governance fabricates placeholder entries only to satisfy a rule meant for sub-agent context injection.

6. Tests Required

• Fixture test for inline seed-only pass.
• Fixture test for sub-agent seed-only failure.
• Run both Trellis governance and task.py validate for the active task.

7. Wrong vs Correct

Wrong

dispatch_mode=inline -> require at least one injected JSONL entry

Correct

dispatch_mode=inline -> allow zero real entries; validate any real entries
dispatch_mode=sub-agent -> require curated real entries