升级Trellis并精简项目知识（09-05-trellis-upgrade-rule-cleanup）
更新Trellis适配、任务归属与归档失败恢复，精简技能入口和知识读取规则。 保留权限、证据、事务及独立复核合同；纳入对应任务及已完成复核记录。 仅本地提交，不启用新平台适配，不推送或部署。
这个提交包含在：
@@ -5,11 +5,9 @@ description: "Load the task and affected-layer guidelines before implementation
|
||||
|
||||
# Before Development
|
||||
|
||||
1. Read the current PRD and applicable design/implementation notes if not already current in context.
|
||||
2. Identify the smallest behavior gap, affected files, exclusions and validation commands. Reuse the approved plan rather than writing another checklist.
|
||||
3. Discover package indexes only when the affected layer is unknown. Read its relevant coding and quality contracts; follow references needed for this change.
|
||||
4. Read cross-layer or reuse guides only when shared contracts, multiple layers, shared constants or new abstractions are involved.
|
||||
5. Once the plan is approved, continue through implementation and relevant validation. Ask again only for material changes to scope, risk or acceptance, or separately protected operations.
|
||||
6. Keep unrelated dirty files and pre-existing failures out of scope. A local refactor requires evidence that behavior stays unchanged.
|
||||
1. Reuse the current PRD and approved plan; load missing design/implementation context. Identify the behavior gap, affected files, exclusions and meaningful checks.
|
||||
2. Locate affected-layer contracts through the package index. For large specs use `rg -n '^#{1,3} ' <file>`, then read general rules, complete relevant sections and required references. Expand for shared/cross-layer contracts; a search excerpt is not full coverage. Reuse unchanged context.
|
||||
3. Continue approved implementation and validation. Ask again only for material changes to scope, risk or acceptance, or separately protected operations.
|
||||
4. Preserve unrelated dirty files and pre-existing failures. Verify behavior for local refactors; choose checks for this change, not full business testing for rule-only edits.
|
||||
|
||||
Do not force full document reads, repeat unchanged context, require unavailable tools, or turn a rule-only task into full business testing. Preserve privacy, production and independent-review boundaries from AGENTS.md.
|
||||
Keep privacy, production and independent-review boundaries from AGENTS.md. Use supported fallbacks for unavailable optional tools.
|
||||
|
||||
@@ -1,200 +1,21 @@
|
||||
---
|
||||
name: trellis-brainstorm
|
||||
description: "Guides collaborative requirements discovery before implementation. Creates task directory, seeds PRD, asks high-value questions one at a time, researches technical choices, and converges on MVP scope. Use when requirements are unclear, there are multiple valid approaches, or the user describes a new feature or complex task."
|
||||
description: "Resolve unclear requirements and consequential design choices before implementation; produce or update the owning Trellis plan."
|
||||
---
|
||||
|
||||
# Trellis Brainstorm
|
||||
# Plan The Requested Change
|
||||
|
||||
## Non-Negotiable Planning Contract
|
||||
Use the project's workflow and task contract. Reuse a suitable task; create one only when needed and authorized. Task creation alone is not implementation approval. Keep unrelated tasks and historical evidence intact.
|
||||
|
||||
A request to build, implement, fix, refactor, or "go ahead" is not approval to leave planning. Task-creation consent is also not implementation approval.
|
||||
Inspect relevant code, tests and fact sources before asking questions. Separate observed behavior from intended behavior: existing code is evidence, not authority to redefine the user's goal. Search past dialogue only when a necessary decision is missing from current context and task records.
|
||||
|
||||
For non-trivial work, present the plan and obtain approval before implementation. Approval of the same plan in prior turns remains valid; clerical backfill, unchanged artifacts or repeated planning breadcrumbs do not restart the approval gate. Once decisions and required artifacts are complete, start and execute the approved scope.
|
||||
Resolve routine implementation choices within the user's authorized scope. Ask about consequential product, compatibility, UX, risk or acceptance decisions that remain unclear; state the recommendation and trade-off. A blocking answer is required before dependent work, while independent evidence gathering may continue. Do not invent questions or treat silence as approval.
|
||||
|
||||
While any user-owned product, scope, UX, compatibility, risk, or acceptance decision remains unresolved, end the turn with exactly one highest-value question. Do not edit product code, dispatch implementation, or run `task.py start`.
|
||||
Record the smallest plan that makes the work reviewable:
|
||||
- `prd.md`: goal, relevant facts, scope/exclusions, observable acceptance, test plan and unresolved decisions.
|
||||
- Complex work also needs `design.md` for contracts, trade-offs and rollout/rollback, plus `implement.md` for ordered work and checks. Lightweight tasks may be PRD-only.
|
||||
- Context manifests contain stable spec/research only. Sub-agent mode requires curated real entries; empty/legacy seed-only manifests do not qualify. Inline mode reads context directly and permits empty manifests.
|
||||
|
||||
## Non-Negotiable Evidence Rule
|
||||
Before requesting a new plan's approval, resolve blocking questions and consolidate temporary notes into the owning sections. Preserve requirement IDs, evidence anchors, decisions and acceptance mappings; do not rewrite an already clear PRD merely to satisfy a template. Defer technical unknowns explicitly only when doing so does not silently change required behavior.
|
||||
|
||||
If a question can be answered by exploring the codebase, explore the codebase instead.
|
||||
|
||||
This is mandatory. Before asking the user a question, first check whether the answer is already available in code, tests, configs, docs, existing specs, or task history.
|
||||
|
||||
Do not ask the user to confirm facts that the repository can answer. Ask only for product intent, preference, scope, risk tolerance, acceptance behavior, or decisions that remain ambiguous after inspection.
|
||||
|
||||
Repository evidence establishes current behavior and technical constraints. The user's intended behavior, feature scope boundaries, and UX preferences are never answerable by repository evidence alone, even when an existing pattern exists; existing patterns are options and recommendation evidence, not decisions.
|
||||
|
||||
---
|
||||
|
||||
Use this skill during Phase 1 planning to turn the user's request into clear requirements and planning artifacts.
|
||||
|
||||
## Preconditions
|
||||
|
||||
Use this skill only after task-creation consent has been given and the user is ready to enter Trellis planning.
|
||||
|
||||
If no task exists yet, create one:
|
||||
|
||||
```bash
|
||||
TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<short task title>" --description "<one-line summary>" --slug <slug>)
|
||||
```
|
||||
|
||||
Use a concise title from the user's request. Both the title and `--description` must be non-empty — `create` rejects blanks, and a record with either one empty is refused at archive. Use a slug without a date prefix. `task.py create` adds the `MM-DD-` directory prefix automatically.
|
||||
|
||||
`task.py create` creates the default `prd.md`. Update that file with the current understanding before asking follow-up questions.
|
||||
|
||||
## Planning Flow
|
||||
|
||||
1. Capture the user's request and initial known facts in `prd.md`.
|
||||
2. Inspect available evidence before asking questions:
|
||||
- code, tests, fixtures, and configs
|
||||
- README files, docs, existing specs, and domain notes
|
||||
- related Trellis tasks, research files, and session history when present
|
||||
3. Separate what you found into:
|
||||
- confirmed facts
|
||||
- product intent still needed from the user
|
||||
- scope or risk decisions still needed from the user
|
||||
- likely out-of-scope items
|
||||
4. If a user-owned decision remains, ask the single highest-value question, include your recommendation and trade-off, then stop. Do not perform implementation work in the same turn.
|
||||
5. After each user answer, update `prd.md`, recompute the decision inventory, and repeat from step 2.
|
||||
6. When no user-owned decision remains, create or update `design.md` and `implement.md` for complex tasks.
|
||||
7. Run the requirement convergence gate, then the PRD convergence pass.
|
||||
8. If this plan has not yet been approved, present its final summary and wait. If the same scope has already been approved, do not ask again.
|
||||
9. With recorded approval and complete artifacts, run `task.py start` and implement. Repeat review only for a material scope, risk or acceptance change.
|
||||
|
||||
Do not invent a project-specific product/spec hierarchy. If the repository already has product, domain, or spec docs, use them. If it does not, proceed with the evidence that exists.
|
||||
|
||||
## Question Rules
|
||||
|
||||
Ask only one question per message.
|
||||
|
||||
Each question must include:
|
||||
|
||||
- the decision needed
|
||||
- why the answer matters
|
||||
- your recommended answer
|
||||
- the trade-off if the user chooses differently
|
||||
|
||||
Do not ask process questions such as whether to search, inspect files, or continue brainstorming. Do the evidence work directly. Ask the user only when the remaining issue is a product decision, preference, scope boundary, or risk tolerance choice.
|
||||
|
||||
Recommendations are not default selections. Never choose a recommended product decision on the user's behalf merely because the user asked for implementation.
|
||||
|
||||
Do not manufacture clarification questions. Present a new plan for approval when needed; if the same plan is already approved and artifacts are complete, start implementation.
|
||||
|
||||
Final review is required for a new or materially changed plan, not for reformatting an already approved plan. Task-creation consent alone is not implementation approval.
|
||||
|
||||
## Thinking Framework: First Principles Analysis
|
||||
|
||||
When requirements are vague, solutions feel over-engineered, or you're about to add complexity "because everyone does" — decompose to fundamental truths before reasoning upward.
|
||||
|
||||
### Step 1: Restate the Problem
|
||||
|
||||
Strip away implementation details to one sentence.
|
||||
|
||||
> Bad: "We need to add Redis caching to the user profile endpoint"
|
||||
> Good: "User profile data takes too long to load"
|
||||
|
||||
### Step 2: List Fundamental Truths
|
||||
|
||||
What is absolutely true (not opinion or convention)?
|
||||
|
||||
| Category | Examples |
|
||||
|----------|----------|
|
||||
| **Physical constraints** | Network latency ≥ 0, disk I/O has limits |
|
||||
| **Business rules** | "Users must see their own data" |
|
||||
| **Technical invariants** | "Data must be consistent" |
|
||||
| **User needs** | "The user wants X within Y seconds" |
|
||||
|
||||
### Step 3: Challenge Assumptions
|
||||
|
||||
For each component of the current plan:
|
||||
|
||||
- **Fact or convention?** "We always use REST" — why?
|
||||
- **What if we removed this?** If nothing breaks, it's unnecessary.
|
||||
- **Solving the actual problem or a symptom?** Trace the causal chain.
|
||||
- **Who benefits from this complexity?** If "nobody", simplify.
|
||||
|
||||
### Step 4: Build Up from Truths
|
||||
|
||||
1. Start with the minimum viable mechanism satisfying all truths
|
||||
2. Add complexity only when a specific truth demands it
|
||||
3. Each addition must answer: "Which truth requires this?"
|
||||
|
||||
### Step 5: Validate
|
||||
|
||||
- Does the solution solve the original problem?
|
||||
- What assumptions need verification?
|
||||
- What's the simplest experiment to test this?
|
||||
|
||||
## Requirement Convergence Gate
|
||||
|
||||
Before final review, verify all of the following:
|
||||
|
||||
- the user outcome and product value are explicit
|
||||
- in-scope and out-of-scope behavior are explicit
|
||||
- acceptance criteria describe observable outcomes
|
||||
- user-owned product, scope, UX, compatibility, and risk decisions are resolved
|
||||
- blocking open questions are empty
|
||||
- technical unknowns are researched or explicitly deferred without changing MVP behavior
|
||||
|
||||
Lightweight tasks may omit `design.md` and `implement.md`; they may not skip evidence inspection, requirement convergence, final review, or fresh implementation approval.
|
||||
|
||||
The final planning summary must show Goal, In Scope, Out of Scope, Acceptance Criteria, Key Decisions, relevant Risks or Deferred Items, and artifact status.
|
||||
|
||||
## Artifact Rules
|
||||
|
||||
`prd.md` records requirements and acceptance:
|
||||
|
||||
- goal and user value
|
||||
- confirmed facts
|
||||
- requirements
|
||||
- acceptance criteria
|
||||
- out of scope
|
||||
- open questions that still block planning
|
||||
|
||||
`design.md` records technical design for complex tasks:
|
||||
|
||||
- architecture and boundaries
|
||||
- data flow and contracts
|
||||
- compatibility and migration notes
|
||||
- important trade-offs
|
||||
- operational or rollback considerations
|
||||
|
||||
`implement.md` records execution planning for complex tasks:
|
||||
|
||||
- ordered implementation checklist
|
||||
- validation commands
|
||||
- risky files or rollback points
|
||||
- follow-up checks before `task.py start`
|
||||
|
||||
Lightweight tasks may have only `prd.md`. Complex tasks must have `prd.md`, `design.md`, and `implement.md` before `task.py start`.
|
||||
|
||||
`implement.md` is not a replacement for `implement.jsonl`. On sub-agent-dispatch workflows, `implement.jsonl` and `check.jsonl` must each contain at least one real spec/research entry before `task.py start`; an empty manifest, or one holding only a legacy `_example` placeholder row, does not count. Inline workflows skip this JSONL gate because Phase 2 loads context through `trellis-before-dev`.
|
||||
|
||||
## PRD Convergence Pass
|
||||
|
||||
Before declaring planning ready or running `task.py start`, rewrite `prd.md` once against the final structure described in the artifact rules above. This is not optional cleanup; it is the final planning gate.
|
||||
|
||||
The pass must be lossless:
|
||||
|
||||
- Collapse repeated facts into one authoritative section.
|
||||
- Fold temporary brainstorm sections such as `What I already know`, `Assumptions`, and resolved `Open Questions` into Goal, Background, Requirements, Technical Notes, or Acceptance Criteria.
|
||||
- Remove resolved open questions instead of leaving empty or already-answered sections.
|
||||
- Merge parallel bug and requirement lists when they describe the same work; keep each defect's severity, evidence, and file:line anchors on the owning requirement.
|
||||
- Preserve every file:line anchor, decision, constraint, requirement ID, and acceptance-criteria mapping.
|
||||
- Do not proceed to final review while any blocking open question remains.
|
||||
|
||||
After the pass, read `prd.md` top to bottom and verify that no fact is repeated across sections unless the repetition adds new information.
|
||||
|
||||
## Quality Bar
|
||||
|
||||
Before declaring planning ready:
|
||||
|
||||
- `prd.md` contains testable acceptance criteria.
|
||||
- `prd.md` has passed the PRD convergence pass: no unresolved temporary brainstorm sections, no duplicate facts across sections, and no lost anchors, decisions, or acceptance mappings.
|
||||
- Repository-answerable questions have already been answered through inspection.
|
||||
- Blocking open questions are empty.
|
||||
- Complex tasks have `design.md` and `implement.md`.
|
||||
- Sub-agent-dispatch tasks have real curated entries in both `implement.jsonl` and `check.jsonl`; seed-only manifests are not ready.
|
||||
- The latest final planning summary has been presented to the user.
|
||||
- The user explicitly approved this scope for implementation; unchanged restatements and clerical backfill do not invalidate that approval.
|
||||
|
||||
Do not start implementation merely because the user originally asked for implementation.
|
||||
Present a concise plan with material risks and completion criteria. A recorded approval or explicit delegation covering this scope remains valid; clerical updates do not restart approval. Once required artifacts and decisions are complete, run the official `task.py start` command and continue approved implementation and checks. Reconfirm only material scope, risk or acceptance changes and separately protected operations.
|
||||
|
||||
@@ -1,188 +1,18 @@
|
||||
---
|
||||
name: trellis-break-loop
|
||||
description: "Deep bug analysis to break the fix-forget-repeat cycle. Analyzes root cause category, why fixes failed, prevention mechanisms, and captures knowledge into specs. Use after fixing a bug to prevent the same class of bugs."
|
||||
description: "Analyze recurring bugs or failed fixes to identify a supported cause and targeted prevention; use for a requested debugging retrospective."
|
||||
---
|
||||
|
||||
# Break the Loop - Deep Bug Analysis
|
||||
# Learn From A Debugging Loop
|
||||
|
||||
When debug is complete, use this for deep analysis to break the "fix bug -> forget -> repeat" cycle.
|
||||
Use the current task's evidence and existing analysis. An ordinary fix with adequate regression coverage does not automatically need a separate retrospective or new spec section.
|
||||
|
||||
---
|
||||
Distinguish the observed failure, supported cause and remaining hypotheses. Explain earlier failed fixes only when they change the diagnosis. Consider missing contracts, cross-layer mismatch, missed consumers, inadequate coverage or an implicit assumption; these are prompts, not mandatory categories.
|
||||
|
||||
## Analysis Framework
|
||||
When causes compete, choose a small check whose outcome distinguishes them. Preserve counterevidence, input/environment differences and failed runs. Do not invent numerical priors or confidence thresholds, or call a plausible explanation proven. Stop expanding the investigation when the authorized problem and meaningful regression are covered; new risks become scoped follow-up work.
|
||||
|
||||
Analyze the bug you just fixed from these 5 dimensions:
|
||||
Choose the smallest useful prevention: correct the shared contract, add a behavioral regression, enforce an invariant or improve a specific diagnostic. Reuse existing protections. Similar symptoms warrant a targeted consumer check, not automatic repository-wide cleanup or a new abstraction.
|
||||
|
||||
### 1. Root Cause Category
|
||||
Keep run chronology and unresolved hypotheses in the current task. Use `trellis-update-spec` only for a new, reusable lesson, updating its existing owner rather than duplicating it across spec and guides. Summarize cause, evidence, prevention and remaining limitations at the depth the problem needs.
|
||||
|
||||
Which category does this bug belong to?
|
||||
|
||||
| Category | Characteristics | Example |
|
||||
|----------|-----------------|---------|
|
||||
| **A. Missing Spec** | No documentation on how to do it | New feature without checklist |
|
||||
| **B. Cross-Layer Contract** | Interface between layers unclear | API returns different format than expected |
|
||||
| **C. Change Propagation Failure** | Changed one place, missed others | Changed function signature, missed call sites |
|
||||
| **D. Test Coverage Gap** | Unit test passes, integration fails | Works alone, breaks when combined |
|
||||
| **E. Implicit Assumption** | Code relies on undocumented assumption | Timestamp seconds vs milliseconds |
|
||||
|
||||
### 2. Why Fixes Failed (if applicable)
|
||||
|
||||
If you tried multiple fixes before succeeding, analyze each failure:
|
||||
|
||||
- **Surface Fix**: Fixed symptom, not root cause
|
||||
- **Incomplete Scope**: Found root cause, didn't cover all cases
|
||||
- **Tool Limitation**: grep missed it, type check wasn't strict
|
||||
- **Mental Model**: Kept looking in same layer, didn't think cross-layer
|
||||
|
||||
### 3. Prevention Mechanisms
|
||||
|
||||
What mechanisms would prevent this from happening again?
|
||||
|
||||
| Type | Description | Example |
|
||||
|------|-------------|---------|
|
||||
| **Documentation** | Write it down so people know | Update thinking guide |
|
||||
| **Architecture** | Make the error impossible structurally | Type-safe wrappers |
|
||||
| **Compile-time** | Strict type checking, no escape hatches | Signature change causes compile error |
|
||||
| **Runtime** | Monitoring, alerts, scans | Detect orphan entities |
|
||||
| **Test Coverage** | E2E tests, integration tests | Verify full flow |
|
||||
| **Code Review** | Checklist, PR template | "Did you check X?" |
|
||||
|
||||
### 4. Systematic Expansion
|
||||
|
||||
What broader problems does this bug reveal?
|
||||
|
||||
- **Similar Issues**: Where else might this problem exist?
|
||||
- **Design Flaw**: Is there a fundamental architecture issue?
|
||||
- **Process Flaw**: Is there a development process improvement?
|
||||
- **Knowledge Gap**: Is the team missing some understanding?
|
||||
|
||||
### 5. Knowledge Capture
|
||||
|
||||
Solidify insights into the system:
|
||||
|
||||
- [ ] Update `.trellis/spec/guides/` thinking guides
|
||||
- [ ] Update relevant `.trellis/spec/` docs
|
||||
- [ ] Create issue record (if applicable)
|
||||
- [ ] Create feature ticket for root fix
|
||||
- [ ] Update check guidelines if needed
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
Please output analysis in this format:
|
||||
|
||||
```markdown
|
||||
## Bug Analysis: [Short Description]
|
||||
|
||||
### 1. Root Cause Category
|
||||
- **Category**: [A/B/C/D/E] - [Category Name]
|
||||
- **Specific Cause**: [Detailed description]
|
||||
|
||||
### 2. Why Fixes Failed (if applicable)
|
||||
1. [First attempt]: [Why it failed]
|
||||
2. [Second attempt]: [Why it failed]
|
||||
...
|
||||
|
||||
### 3. Prevention Mechanisms
|
||||
| Priority | Mechanism | Specific Action | Status |
|
||||
|----------|-----------|-----------------|--------|
|
||||
| P0 | ... | ... | TODO/DONE |
|
||||
|
||||
### 4. Systematic Expansion
|
||||
- **Similar Issues**: [List places with similar problems]
|
||||
- **Design Improvement**: [Architecture-level suggestions]
|
||||
- **Process Improvement**: [Development process suggestions]
|
||||
|
||||
### 5. Knowledge Capture
|
||||
- [ ] [Documents to update / tickets to create]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
> **The value of debugging is not in fixing the bug, but in making this class of bugs never happen again.**
|
||||
|
||||
Three levels of insight:
|
||||
1. **Tactical**: How to fix THIS bug
|
||||
2. **Strategic**: How to prevent THIS CLASS of bugs
|
||||
3. **Philosophical**: How to expand thinking patterns
|
||||
|
||||
30 minutes of analysis saves 30 hours of future debugging.
|
||||
|
||||
## Thinking Framework: Bayesian Reasoning
|
||||
|
||||
When multiple root causes are plausible and evidence is incomplete, update your beliefs proportionally to new evidence rather than clinging to initial assumptions.
|
||||
|
||||
### Step 1: Establish Priors
|
||||
|
||||
Before investigating, state what you believe and why:
|
||||
|
||||
| Hypothesis | Prior | Reasoning |
|
||||
|------------|-------|-----------|
|
||||
| H1: [cause A] | 40% | Most common for this pattern |
|
||||
| H2: [cause B] | 30% | Plausible given environment |
|
||||
| H3: [other] | 30% | Catch-all |
|
||||
|
||||
Priors must sum to 100%. If you can't assign probabilities, investigate first.
|
||||
|
||||
### Step 2: Observe Evidence
|
||||
|
||||
Document what you found — be specific about reliability:
|
||||
|
||||
- What exactly did you observe?
|
||||
- How reliable? (test output > log message > user report > hunch)
|
||||
- Could multiple hypotheses explain this?
|
||||
|
||||
### Step 3: Update Beliefs
|
||||
|
||||
For each hypothesis, ask: **How likely is this evidence if this hypothesis were true?**
|
||||
|
||||
Direction of update matters more than calculation:
|
||||
- Evidence strongly predicted by H1 → H1 probability increases
|
||||
- Evidence contradicts H2 → H2 probability decreases
|
||||
- Evidence equally likely under all → no update
|
||||
|
||||
### Step 4: Seek Discriminating Evidence
|
||||
|
||||
Don't gather more of the same. Find evidence that **differs strongly** between top hypotheses.
|
||||
|
||||
> If H1 and H3 are close: "What would I see if H1 is true but not if H3 is true?" Then check for that.
|
||||
|
||||
### Step 5: State Confidence
|
||||
|
||||
| Confidence | Action |
|
||||
|------------|--------|
|
||||
| 90%+ | Proceed with fix, monitor |
|
||||
| 70-90% | Proceed, add fallback check |
|
||||
| 50-70% | Test hypothesis before committing |
|
||||
| <50% | Need more evidence, don't guess |
|
||||
|
||||
Never express binary certainty when evidence is incomplete. Use "most likely", "plausible but unlikely", "worth investigating".
|
||||
|
||||
### Common Fallacies
|
||||
|
||||
| Fallacy | Example | Correction |
|
||||
|---------|---------|------------|
|
||||
| **Base rate neglect** | "Test failed → code is broken" | How often do tests fail for other reasons? |
|
||||
| **Confirmation bias** | "Must be a race condition, let me find race evidence" | Actively seek evidence AGAINST your top hypothesis |
|
||||
| **Anchoring** | "Last time it was caching, probably caching again" | Establish priors from current context, not yesterday's bug |
|
||||
|
||||
---
|
||||
|
||||
## After Analysis: Immediate Actions
|
||||
|
||||
**IMPORTANT**: After completing the analysis above, you MUST immediately:
|
||||
|
||||
1. **Update spec/guides** - Don't just list TODOs, actually update the relevant files:
|
||||
- If it's a cross-platform issue → update `cross-platform-thinking-guide.md`
|
||||
- If it's a cross-layer issue → update `cross-layer-thinking-guide.md`
|
||||
- If it's a code reuse issue → update `code-reuse-thinking-guide.md`
|
||||
- If it's domain-specific → update `backend/*.md` or `frontend/*.md`
|
||||
|
||||
2. **Sync templates** - After updating `.trellis/spec/`, sync to `src/templates/markdown/spec/`
|
||||
|
||||
3. **Commit the spec updates** - This is the primary output, not just the analysis text
|
||||
|
||||
> **The analysis is worthless if it stays in chat. The value is in the updated specs.**
|
||||
Retrospective work does not authorize commits, archival, deployment, real-data operations or edits to an upstream template repository. Preserve project approval and independent-review requirements.
|
||||
|
||||
@@ -1,61 +1,12 @@
|
||||
---
|
||||
name: trellis-continue
|
||||
description: "Resume work on the current task. Loads the workflow Phase Index, figures out which phase/step to pick up at, then pulls the step-level detail via get_context.py --mode phase. Use when coming back to an in-progress task and you need to know what to do next."
|
||||
description: "Resume an existing Trellis task after a pause or handoff; locate its current phase and next unfinished step."
|
||||
---
|
||||
|
||||
# Continue Current Task
|
||||
|
||||
Resume work on the current task — pick up at the right phase/step in `.trellis/workflow.md`.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Load Current Context
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py
|
||||
```
|
||||
|
||||
Confirms: current task, git state, recent commits.
|
||||
|
||||
## Step 2: Load the Phase Index
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode phase
|
||||
```
|
||||
|
||||
Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping.
|
||||
|
||||
## Step 3: Decide Where You Are
|
||||
|
||||
`get_context.py` shows the active task's `status` field. Route by `status` + artifact presence. This command replaces the user needing to remember the Trellis flow; it does not itself approve implementation.
|
||||
|
||||
- `status=planning` + no `prd.md` → **1.1** (load `trellis-brainstorm`)
|
||||
- `status=planning` + `prd.md` only → decide whether the task is lightweight or complex. Lightweight can move to **1.4** review; complex returns to **1.1** to add `design.md` + `implement.md`.
|
||||
- `status=planning` + complex artifacts complete + sub-agent jsonl not curated (empty, or only a legacy `_example` placeholder row) → **1.3**
|
||||
- `status=planning` + required artifacts complete + required jsonl curated or inline mode → **1.4** (ask for start review; only run `task.py start` after user confirms)
|
||||
- `status=in_progress` + implementation not started → **2.1**
|
||||
- `status=in_progress` + implementation done, not yet checked → **2.2**
|
||||
- `status=in_progress` + check passed → **3.3** (spec update) → **3.4** (commit)
|
||||
- `status=completed` (rare; usually archived immediately) → archive flow
|
||||
|
||||
Phase rules (full detail in `.trellis/workflow.md`):
|
||||
|
||||
1. Run steps **in order** within a phase — `[required]` steps must not be skipped
|
||||
2. `[once]` steps are already done if the required output exists. `prd.md` alone can be enough only for lightweight tasks; complex tasks also need `design.md` and `implement.md`.
|
||||
3. You may go back to an earlier phase if discoveries require it
|
||||
|
||||
## Step 4: Load the Specific Step
|
||||
|
||||
Once you know which step to resume at:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode phase --step <X.X> --platform codex
|
||||
```
|
||||
|
||||
Follow the loaded instructions. After each `[required]` step completes, move to the next.
|
||||
|
||||
---
|
||||
|
||||
## Reference
|
||||
|
||||
Full workflow and detailed phase steps live in `.trellis/workflow.md`. This command is only an entry point — the canonical guidance is there.
|
||||
1. Reuse fresh task context; otherwise run `python3 .trellis/scripts/task.py current --source` and read that task's `task.json`. If the pointer is missing, inspect directly related tasks before creating anything. Never infer another session's ownership. Use full `get_context.py` only for a broader session-state question.
|
||||
2. Read the current PRD and the latest status/unfinished steps in `implement.md`; read the applicable design decisions when needed. Preserve constraints and approvals from the handoff. Do not reload unchanged history, unrelated journals or every spec.
|
||||
3. Load the Phase Index only when routing is unclear: `python3 .trellis/scripts/get_context.py --mode phase`. Load the next step with `--mode phase --step <X.X> --platform codex`; the workflow owns phase rules, so do not maintain a duplicate routing table here.
|
||||
4. Complete missing planning decisions before implementation. An existing PRD is not approval; recorded approval for unchanged scope permits `task.py start` and continued execution without another confirmation. Complex tasks need PRD, design and implementation notes; inline mode permits empty context manifests.
|
||||
5. Use `trellis-before-dev` for implementation and `trellis-check` for verification. Continue through the approved scope and relevant checks; leave independent review explicitly pending if unavailable. Commit, push, archive, deployment and real-data operations retain their separate authorization boundaries.
|
||||
|
||||
@@ -11,7 +11,7 @@ It is intentionally a **capability skill, not a workflow**. There is no fixed ou
|
||||
|
||||
## What `trellis mem` is
|
||||
|
||||
A local CLI that indexes the user's past Claude Code, Codex, Pi Agent, and ZCode conversation logs and lets you list, search, slice by Trellis task boundaries, and dump cleaned dialogue from them. Claude and Codex use `~/.claude/projects/` and `~/.codex/sessions/`. Pi uses its default or environment-configured session root, global `~/.pi/agent/settings.json`, and the scoped project's `.pi/settings.json`; relative `sessionDir` values resolve from the settings file directory. Project-local Pi settings require project-scoped lookup through the current cwd or `--cwd`. ZCode uses `~/.zcode/cli/db/db.sqlite`. OpenCode logs are not yet indexable (provider adapter pending) — when an OpenCode session is the obvious target, surface that limitation rather than guessing.
|
||||
A local CLI that indexes the user's past Claude Code, Codex, Devin CLI, Grok, OpenCode, Pi Agent, and ZCode conversation logs and lets you list, search, slice by Trellis task boundaries, and dump cleaned dialogue from them. Claude and Codex use `~/.claude/projects/` and `~/.codex/sessions/`. Devin CLI (Cognition terminal agent, not `trellis init --devin` Desktop) uses `~/.local/share/devin/cli/sessions.db`. Grok uses `~/.grok/sessions/`. OpenCode uses `~/.local/share/opencode/opencode.db` (zero-dependency SQLite reader). Pi uses its default or environment-configured session root, global `~/.pi/agent/settings.json`, and the scoped project's `.pi/settings.json`; relative `sessionDir` values resolve from the settings file directory. Project-local Pi settings require project-scoped lookup through the current cwd or `--cwd`. ZCode uses `~/.zcode/cli/db/db.sqlite`.
|
||||
|
||||
Nothing in `mem` is uploaded. All reads are local.
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ Full flag reference for the five subcommands. Pin this as the authoritative sour
|
||||
|
||||
| Flag | Subcommands | Meaning |
|
||||
| --------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `--platform claude\|codex\|opencode\|pi\|all` | all | Default `all`. OpenCode adapter is currently a stub on `0.6.0-beta.*` — see "Caveats" below. |
|
||||
| `--platform claude\|codex\|devin\|grok\|opencode\|pi\|zcode\|all` | all | Default `all`. `devin` is Cognition Devin CLI (`sessions.db`), not `trellis init --devin` (Desktop). |
|
||||
| `--since YYYY-MM-DD` | list / search | Inclusive lower date bound. |
|
||||
| `--until YYYY-MM-DD` | list / search | Inclusive upper date bound. |
|
||||
| `--global` | list / search | Include sessions from every project on this machine. Default is the current project `cwd`. |
|
||||
@@ -56,6 +56,7 @@ trellis mem projects
|
||||
## Caveats
|
||||
|
||||
- **OpenCode adapter is a stub on `0.6.0-beta.*`.** When `--platform` resolves to OpenCode (or `all` and OpenCode would be included), `mem` prints a one-line "reader unavailable" notice and continues with the other platforms. Don't promise OpenCode coverage in your reply until the adapter ships.
|
||||
- **`--platform devin` is Cognition Devin CLI** (`~/.local/share/devin/cli/sessions.db`). It is not `trellis init --devin` (Devin Desktop / Cascade) and not Factory Droid.
|
||||
- **`--phase` slicing depends on `task.py create` / `task.py start` invocations appearing in the recorded bash calls of the session.** Sessions where the user ran `task.py` from a different terminal — outside the recorded AI loop — will not have phase boundaries. `--phase all` is the safe fallback.
|
||||
- **`mem` indexes platform JSONL files directly.** If the user has cleared their Claude / Codex / Pi session storage, `mem` cannot recover what is no longer on disk.
|
||||
- **`mem` is read-only.** No remote sync, no edits to platform JSONL. Any write you do based on `mem` findings is your own follow-up call into the editing tools available to you.
|
||||
|
||||
@@ -5,10 +5,10 @@ description: "Initialize or resume non-trivial work in this Trellis project. Ski
|
||||
|
||||
# Start Session
|
||||
|
||||
1. Classify the request before loading context. Pure consultation and small isolated edits do not need a task or a task-creation question. Preserve risk boundaries in AGENTS.md.
|
||||
2. For tracked work, obtain current task and status from already supplied context, or run get_context.py when missing or stale. Do not enumerate unrelated journals and historical tasks.
|
||||
3. Read the workflow Phase Index and current step on demand. Read the current PRD, then design and implementation notes if needed. Reuse unchanged material already loaded in this session.
|
||||
4. With no task, obtain task-creation consent for non-trivial work unless already authorized. With a planning task, complete missing decisions; once its plan is approved, start and execute without asking again. An existing PRD alone is not proof of approval.
|
||||
5. For implementation load trellis-before-dev; for verification load trellis-check. Load spec indexes only for affected layers and follow relevant links, not every guideline.
|
||||
1. Classify the request. Pure consultation and small isolated edits need no task unless requested; preserve AGENTS.md risk boundaries.
|
||||
2. Reuse fresh task context; otherwise run `python3 .trellis/scripts/task.py current --source` and read its status. If no pointer exists, inspect directly related tasks before creating one. Use full `get_context.py` only for broader session state.
|
||||
3. Load the workflow Phase Index/current step and task PRD as needed, then relevant design/implementation notes. Reuse unchanged material.
|
||||
4. Obtain creation/plan approval only when missing. A PRD alone is not approval; an approved unchanged plan permits start and execution without asking again.
|
||||
5. Load `trellis-before-dev` for implementation and `trellis-check` for verification. Follow affected-layer references, not every guide. Missing optional tools use supported fallbacks, not repeated permission requests.
|
||||
|
||||
The project workflow and task status are authoritative over legacy user-level Trellis skills. Missing optional tools require a supported fallback or a precise limitation report, not repeated permission requests.
|
||||
Project workflow and task status take precedence over legacy user-level Trellis skills.
|
||||
|
||||
@@ -1,356 +1,21 @@
|
||||
---
|
||||
name: trellis-update-spec
|
||||
description: "Captures executable contracts and coding conventions into .trellis/spec/ documents. Use when learning something valuable from debugging, implementing, or discussion that should be preserved for future sessions."
|
||||
description: "Maintain an existing spec when a verified change reveals a reusable contract, convention or pitfall; exclude routine status and run logs."
|
||||
---
|
||||
|
||||
# Update Code-Spec - Capture Executable Contracts
|
||||
# Maintain Reusable Contracts
|
||||
|
||||
When you learn something valuable (from debugging, implementing, or discussion), use this to update the relevant code-spec documents.
|
||||
First decide whether there is a new, supported lesson worth retaining. No spec edit is needed when the contract is already documented, evidence is inconclusive or the fact belongs only to this run. Model upgrades alone are not evidence that a business safeguard is obsolete.
|
||||
|
||||
**Timing**: After completing a task, fixing a bug, or discovering a new pattern
|
||||
Use the package index and heading search to locate the owning section. Read its applicable contract and references before editing. Update or consolidate that section; create a new one only for a distinct concept. Keep business facts in the existing docs owner, executable development rules in spec, and thinking prompts in guides that point to those rules. Do not replicate the same contract in each layer.
|
||||
|
||||
---
|
||||
Preserve concrete depth when commands/APIs, schemas, infrastructure or cross-layer behavior change:
|
||||
- Applicable scope and the actual signature, fields/types, storage or configuration keys.
|
||||
- Required invariants, validation/authorization boundaries, failure behavior and compatibility or migration constraints.
|
||||
- The observable assertions and relevant test commands that distinguish correct behavior from the failure.
|
||||
|
||||
## Code-Spec First Rule (CRITICAL)
|
||||
Use the shortest clear structure: a paragraph, table or focused example is often enough. A good/bad example helps when it explains a subtle distinction; it is not required for every lesson. Follow any explicitly required task/delivery format, but do not impose seven sections, a code sample or a new document on every change.
|
||||
|
||||
In this project, "spec" for implementation work means **code-spec**:
|
||||
- Executable contracts (not principle-only text)
|
||||
- Concrete signatures, payload fields, env keys, and boundary behavior
|
||||
- Testable validation/error behavior
|
||||
Before removing material, inspect its callers/references and preserve unique conditions, exceptions, evidence links and requirement IDs. Retire stale instructions only after confirming the current owner and scope. Historical findings, run counts, timestamps, candidate hashes, approvals and original receipts remain in task/evidence; a new result must not rewrite their past state.
|
||||
|
||||
If the change touches infra or cross-layer contracts, code-spec depth is mandatory.
|
||||
|
||||
### Mandatory Triggers
|
||||
|
||||
Apply code-spec depth when the change includes any of:
|
||||
- New/changed command or API signature
|
||||
- Cross-layer request/response contract change
|
||||
- Database schema/migration change
|
||||
- Infra integration (storage, queue, cache, secrets, env wiring)
|
||||
|
||||
### Mandatory Output (7 Sections)
|
||||
|
||||
For triggered tasks, include all sections below:
|
||||
1. Scope / Trigger
|
||||
2. Signatures (command/API/DB)
|
||||
3. Contracts (request/response/env)
|
||||
4. Validation & Error Matrix
|
||||
5. Good/Base/Bad Cases
|
||||
6. Tests Required (with assertion points)
|
||||
7. Wrong vs Correct (at least one pair)
|
||||
|
||||
---
|
||||
|
||||
## When to Update Code-Specs
|
||||
|
||||
| Trigger | Example | Target Spec |
|
||||
|---------|---------|-------------|
|
||||
| **Implemented a feature** | Added a new integration or module | Relevant spec file |
|
||||
| **Made a design decision** | Chose extensibility pattern over simplicity | Relevant spec + "Design Decisions" section |
|
||||
| **Fixed a bug** | Found a subtle issue with error handling | Relevant spec (e.g., error-handling docs) |
|
||||
| **Discovered a pattern** | Found a better way to structure code | Relevant spec file |
|
||||
| **Hit a gotcha** | Learned that X must be done before Y | Relevant spec + "Common Mistakes" section |
|
||||
| **Established a convention** | Team agreed on naming pattern | Quality guidelines |
|
||||
| **New thinking trigger** | "Don't forget to check X before doing Y" | `guides/*.md` (as a checklist item) |
|
||||
|
||||
**Key Insight**: Code-spec updates are NOT just for problems. Every feature implementation contains design decisions and contracts that future AI/developers need to execute safely.
|
||||
|
||||
---
|
||||
|
||||
## Spec Structure Overview
|
||||
|
||||
```
|
||||
.trellis/spec/
|
||||
├── <layer>/ # Per-layer coding standards (e.g., backend/, frontend/, api/)
|
||||
│ ├── index.md # Overview and links
|
||||
│ └── *.md # Topic-specific guidelines
|
||||
└── guides/ # Thinking checklists (NOT coding specs!)
|
||||
├── index.md # Guide index
|
||||
└── *.md # Topic-specific guides
|
||||
```
|
||||
|
||||
### CRITICAL: Code-Spec vs Guide - Know the Difference
|
||||
|
||||
| Type | Location | Purpose | Content Style |
|
||||
|------|----------|---------|---------------|
|
||||
| **Code-Spec** | `<layer>/*.md` | Tell AI "how to implement safely" | Signatures, contracts, matrices, cases, test points |
|
||||
| **Guide** | `guides/*.md` | Help AI "what to think about" | Checklists, questions, pointers to specs |
|
||||
|
||||
**Decision Rule**: Ask yourself:
|
||||
|
||||
- "This is **how to write** the code" → Put in a spec layer directory
|
||||
- "This is **what to consider** before writing" → Put in `guides/`
|
||||
|
||||
**Example**:
|
||||
|
||||
| Learning | Wrong Location | Correct Location |
|
||||
|----------|----------------|------------------|
|
||||
| "Use API X not API Y for this task" | ❌ `guides/` (too specific for a thinking guide) | ✅ Relevant spec file (concrete convention) |
|
||||
| "Remember to check X when doing Y" | ❌ Spec file (too abstract for a spec) | ✅ `guides/` (thinking checklist) |
|
||||
|
||||
**Guides should be short checklists that point to specs**, not duplicate the detailed rules.
|
||||
|
||||
---
|
||||
|
||||
## Update Process
|
||||
|
||||
### Step 1: Identify What You Learned
|
||||
|
||||
Answer these questions:
|
||||
|
||||
1. **What did you learn?** (Be specific)
|
||||
2. **Why is it important?** (What problem does it prevent?)
|
||||
3. **Where does it belong?** (Which spec file?)
|
||||
|
||||
### Step 2: Classify the Update Type
|
||||
|
||||
| Type | Description | Action |
|
||||
|------|-------------|--------|
|
||||
| **Design Decision** | Why we chose approach X over Y | Add to "Design Decisions" section |
|
||||
| **Project Convention** | How we do X in this project | Add to relevant section with examples |
|
||||
| **New Pattern** | A reusable approach discovered | Add to "Patterns" section |
|
||||
| **Forbidden Pattern** | Something that causes problems | Add to "Anti-patterns" or "Don't" section |
|
||||
| **Common Mistake** | Easy-to-make error | Add to "Common Mistakes" section |
|
||||
| **Convention** | Agreed-upon standard | Add to relevant section |
|
||||
| **Gotcha** | Non-obvious behavior | Add warning callout |
|
||||
|
||||
### Step 3: Read the Target Code-Spec
|
||||
|
||||
Before editing, read the current code-spec to:
|
||||
- Understand existing structure
|
||||
- Avoid duplicating content
|
||||
- Find the right section for your update
|
||||
|
||||
```bash
|
||||
cat .trellis/spec/<category>/<file>.md
|
||||
```
|
||||
|
||||
### Step 4: Make the Update
|
||||
|
||||
Follow these principles:
|
||||
|
||||
1. **Be Specific**: Include concrete examples, not just abstract rules
|
||||
2. **Explain Why**: State the problem this prevents
|
||||
3. **Show Contracts**: Add signatures, payload fields, and error behavior
|
||||
4. **Show Code**: Add code snippets for key patterns
|
||||
5. **Keep it Short**: One concept per section
|
||||
|
||||
### Step 5: Update the Index (if needed)
|
||||
|
||||
If you added a new section or the code-spec status changed, update the category's `index.md`.
|
||||
|
||||
---
|
||||
|
||||
## Update Templates
|
||||
|
||||
### Mandatory Template for Infra/Cross-Layer Work
|
||||
|
||||
```markdown
|
||||
## Scenario: <name>
|
||||
|
||||
### 1. Scope / Trigger
|
||||
- Trigger: <why this requires code-spec depth>
|
||||
|
||||
### 2. Signatures
|
||||
- Backend command/API/DB signature(s)
|
||||
|
||||
### 3. Contracts
|
||||
- Request fields (name, type, constraints)
|
||||
- Response fields (name, type, constraints)
|
||||
- Environment keys (required/optional)
|
||||
|
||||
### 4. Validation & Error Matrix
|
||||
- <condition> -> <error>
|
||||
|
||||
### 5. Good/Base/Bad Cases
|
||||
- Good: ...
|
||||
- Base: ...
|
||||
- Bad: ...
|
||||
|
||||
### 6. Tests Required
|
||||
- Unit/Integration/E2E with assertion points
|
||||
|
||||
### 7. Wrong vs Correct
|
||||
#### Wrong
|
||||
...
|
||||
#### Correct
|
||||
...
|
||||
```
|
||||
|
||||
### Adding a Design Decision
|
||||
|
||||
```markdown
|
||||
### Design Decision: [Decision Name]
|
||||
|
||||
**Context**: What problem were we solving?
|
||||
|
||||
**Options Considered**:
|
||||
1. Option A - brief description
|
||||
2. Option B - brief description
|
||||
|
||||
**Decision**: We chose Option X because...
|
||||
|
||||
**Example**:
|
||||
\`\`\`typescript
|
||||
// How it's implemented
|
||||
code example
|
||||
\`\`\`
|
||||
|
||||
**Extensibility**: How to extend this in the future...
|
||||
```
|
||||
|
||||
### Adding a Project Convention
|
||||
|
||||
```markdown
|
||||
### Convention: [Convention Name]
|
||||
|
||||
**What**: Brief description of the convention.
|
||||
|
||||
**Why**: Why we do it this way in this project.
|
||||
|
||||
**Example**:
|
||||
\`\`\`typescript
|
||||
// How to follow this convention
|
||||
code example
|
||||
\`\`\`
|
||||
|
||||
**Related**: Links to related conventions or specs.
|
||||
```
|
||||
|
||||
### Adding a New Pattern
|
||||
|
||||
```markdown
|
||||
### Pattern Name
|
||||
|
||||
**Problem**: What problem does this solve?
|
||||
|
||||
**Solution**: Brief description of the approach.
|
||||
|
||||
**Example**:
|
||||
\`\`\`
|
||||
// Good
|
||||
code example
|
||||
|
||||
// Bad
|
||||
code example
|
||||
\`\`\`
|
||||
|
||||
**Why**: Explanation of why this works better.
|
||||
```
|
||||
|
||||
### Adding a Forbidden Pattern
|
||||
|
||||
```markdown
|
||||
### Don't: Pattern Name
|
||||
|
||||
**Problem**:
|
||||
\`\`\`
|
||||
// Don't do this
|
||||
bad code example
|
||||
\`\`\`
|
||||
|
||||
**Why it's bad**: Explanation of the issue.
|
||||
|
||||
**Instead**:
|
||||
\`\`\`
|
||||
// Do this instead
|
||||
good code example
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Adding a Common Mistake
|
||||
|
||||
```markdown
|
||||
### Common Mistake: Description
|
||||
|
||||
**Symptom**: What goes wrong
|
||||
|
||||
**Cause**: Why this happens
|
||||
|
||||
**Fix**: How to correct it
|
||||
|
||||
**Prevention**: How to avoid it in the future
|
||||
```
|
||||
|
||||
### Adding a Gotcha
|
||||
|
||||
```markdown
|
||||
> **Warning**: Brief description of the non-obvious behavior.
|
||||
>
|
||||
> Details about when this happens and how to handle it.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Interactive Mode
|
||||
|
||||
If you're unsure what to update, answer these prompts:
|
||||
|
||||
1. **What did you just finish?**
|
||||
- [ ] Fixed a bug
|
||||
- [ ] Implemented a feature
|
||||
- [ ] Refactored code
|
||||
- [ ] Had a discussion about approach
|
||||
|
||||
2. **What did you learn or decide?**
|
||||
- Design decision (why X over Y)
|
||||
- Project convention (how we do X)
|
||||
- Non-obvious behavior (gotcha)
|
||||
- Better approach (pattern)
|
||||
|
||||
3. **Would future AI/developers need to know this?**
|
||||
- To understand how the code works → Yes, update spec
|
||||
- To maintain or extend the feature → Yes, update spec
|
||||
- To avoid repeating mistakes → Yes, update spec
|
||||
- Purely one-off implementation detail → Maybe skip
|
||||
|
||||
4. **Which area does it relate to?**
|
||||
- [ ] Backend code
|
||||
- [ ] Frontend code
|
||||
- [ ] Cross-layer data flow
|
||||
- [ ] Code organization/reuse
|
||||
- [ ] Quality/testing
|
||||
|
||||
---
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before finishing your code-spec update:
|
||||
|
||||
- [ ] Is the content specific and actionable?
|
||||
- [ ] Did you include a code example?
|
||||
- [ ] Did you explain WHY, not just WHAT?
|
||||
- [ ] Did you include executable signatures/contracts?
|
||||
- [ ] Did you include validation and error matrix?
|
||||
- [ ] Did you include Good/Base/Bad cases?
|
||||
- [ ] Did you include required tests with assertion points?
|
||||
- [ ] Is it in the right code-spec file?
|
||||
- [ ] Does it duplicate existing content?
|
||||
- [ ] Would a new team member understand it?
|
||||
|
||||
---
|
||||
|
||||
## Relationship to Other Commands
|
||||
|
||||
```
|
||||
Development Flow:
|
||||
Learn something → `update-spec` (Trellis command) → Knowledge captured
|
||||
↑ ↓
|
||||
`break-loop` (Trellis command) ←──────────────────── Future sessions benefit
|
||||
(deep bug analysis)
|
||||
```
|
||||
|
||||
- ``break-loop` (Trellis command)` - Analyzes bugs deeply, often reveals spec updates needed
|
||||
- ``update-spec` (Trellis command)` - Actually makes the updates
|
||||
- ``finish-work` (Trellis command)` - Reminds you to check if specs need updates
|
||||
|
||||
---
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
> **Code-specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the implementation contract clearer.**
|
||||
|
||||
The goal is **institutional memory**:
|
||||
- What one person learns, everyone benefits from
|
||||
- What AI learns in one session, persists to future sessions
|
||||
- Mistakes become documented guardrails
|
||||
Check links and affected process/doc contracts. Reuse unchanged test results; rerun relevant checks when behavior or inputs changed. Update an index only if discovery or ownership changed. Report the actual maintenance scope and limitations. Do not auto-commit, archive, alter runtime templates/hashes, or modify upstream/global files as a side effect.
|
||||
|
||||
@@ -1122,7 +1122,11 @@ def main():
|
||||
sys.exit(0)
|
||||
|
||||
# Get current task directory (research doesn't require it)
|
||||
task_dir = get_current_task(repo_root, input_data)
|
||||
task_dir = get_current_task(
|
||||
repo_root,
|
||||
input_data,
|
||||
allow_single_session_fallback=True,
|
||||
)
|
||||
|
||||
# implement/check need task directory
|
||||
if subagent_type in AGENTS_REQUIRE_TASK:
|
||||
|
||||
@@ -42,7 +42,7 @@
|
||||
".trellis/scripts/__init__.py": "1242be5b972094c2e141aecbe81a4efd478f6534e3d5e28306374e6a18fcf46c",
|
||||
".trellis/scripts/add_session.py": "f61a452ec5f7eece8d7e0f0dd56ce5851166cbc83ca4822e30acbb36eeb5896f",
|
||||
".trellis/scripts/common/__init__.py": "f258cd873681dc5a4d71db0dd71d10fd78656de55bec96418d6702503c16e87d",
|
||||
".trellis/scripts/common/active_task.py": "f52715bbcc0677607055903e799674d7d50d6fcbab413a8f453c4e4efc954726",
|
||||
".trellis/scripts/common/active_task.py": "63d5bc308ac4939fde8923775ced2a76125a4dbbd868b23b6c2857bfbace3bbf",
|
||||
".trellis/scripts/common/cli_adapter.py": "5d6bd9d6f5c631e7e792db7dd343351317f9643bc87b73a9a98abd51cefb4307",
|
||||
".trellis/scripts/common/config.py": "9a042d6f0e25a33a567510760e87c1e389af14a41faf1daeb1190a00f3df7f5e",
|
||||
".trellis/scripts/common/developer.py": "a0f61bb58063e2f4cb357bcb2c22fd5a6f1241286398beaa7130b2a8994a4afa",
|
||||
@@ -56,7 +56,7 @@
|
||||
".trellis/scripts/common/session_context.py": "3379ef1766e4e5ca77cbb7c040dbba3883fcca2548580299e3b38dbf22f4f7d5",
|
||||
".trellis/scripts/common/task_context.py": "51301e180ce702c6a5b1a2dd1b155a6eed1bf2b05cb2ac1e51081212628b11d4",
|
||||
".trellis/scripts/common/task_queue.py": "0be61f713462b1fe4574927c82fc4704e678afe72dcb9813543aedf2f9e9e0c5",
|
||||
".trellis/scripts/common/task_store.py": "5712b0405e1fd0c2b7be5e5fbd420fa6eec2c49c8e4cf2b8fc69b7d2e4aeb016",
|
||||
".trellis/scripts/common/task_store.py": "e0c08cb52789233d2774275c4632f68b1811ade25c2a211b56ef5fc6095e1605",
|
||||
".trellis/scripts/common/task_utils.py": "35f544317a95e98d05fe089794071482175739e8c1f3b3b0228dae48602ffe90",
|
||||
".trellis/scripts/common/tasks.py": "87aca6b73ec4524450cfff8e2ae561b1f2e53bd62a185f036a7a2d484d90c8a2",
|
||||
".trellis/scripts/common/trellis_config.py": "f1fc705ec463b0b9c163672dc9e50f10d29da967775a1900429205f7c4fcb51c",
|
||||
@@ -78,15 +78,15 @@
|
||||
".agents/skills/trellis-channel/SKILL.md": "ff84801c511a736da018b4b1149348ebc9a16b7fc18d905ec10cfa7acbf269a3",
|
||||
".agents/skills/trellis-meta/references/local-architecture/bundled-skills.md": "aa6a0bf83060205ee4ea621c467fb900a7db06b4476a4ad472cc4e248c887389",
|
||||
".agents/skills/trellis-meta/references/local-architecture/multi-agent-channel.md": "56e5070474aeca872e2d70c46feea5aaafecd3d3ec052c3f7b1877358dca62e9",
|
||||
".agents/skills/trellis-session-insight/references/cli-quick-reference.md": "c520353fe3fc00b9702ed4f780647c8fbd6d342e66527a03647f533a9fe09779",
|
||||
".agents/skills/trellis-session-insight/references/cli-quick-reference.md": "3f2dd664868f4b7f90b4800868bb34eaf8ed81246d1adaf5f4da34d1387765e3",
|
||||
".agents/skills/trellis-session-insight/references/triggering-patterns.md": "121ecd23be83d1567e8ce15c366a81073d7a2b1d3ad616fce235c07ca1f1cc20",
|
||||
".agents/skills/trellis-session-insight/SKILL.md": "d20f1d20c6946e26ba6f848b9a016d9a16c803d87501462e5b11a2ced6f56643",
|
||||
".agents/skills/trellis-session-insight/SKILL.md": "c9e58477f71987750f025ee967ca6663ccbbede8a352506bc2f4232a356deb12",
|
||||
".agents/skills/trellis-spec-bootstrap/references/mcp-setup.md": "df542fc8f279edd38046d26a7c8151804b708f57b24d4aa2733cea587a88c65e",
|
||||
".agents/skills/trellis-spec-bootstrap/references/repository-analysis.md": "0dae98d774f6e34559b9f3442888ac43e3a8af110c37cbefc49ce256986858b6",
|
||||
".agents/skills/trellis-spec-bootstrap/references/spec-task-planning.md": "ef493d028c3b0807a8a534bb71fb92a68129f273db763ad27ceb464a522e799d",
|
||||
".agents/skills/trellis-spec-bootstrap/references/spec-writing.md": "e9800fe9ed4a4cd87062ea1829cf2caa8d170ec15e141678a6a30e74c497f47d",
|
||||
".agents/skills/trellis-spec-bootstrap/SKILL.md": "97bfa68c06cebb558eb4464bc1b81f7d2d56040d75baa8de1ee5ad90cca0196a",
|
||||
".codex/hooks/inject-subagent-context.py": "9b68be8d08f85e824e39d901a29f14d38346dbeeda15880e4cba03076f2a8caa",
|
||||
"AGENTS.md": "064873e2aba815f74e973de77269e3b2ae072b69d1486af54c355e66e10251c6"
|
||||
".codex/hooks/inject-subagent-context.py": "022d41a9b6f5dba45bc284a466206fbefedf93f2504a6fe30141ec91c3fbc1ae",
|
||||
"AGENTS.md": "7d9449f8ff2b337062213d2d6c3201bfdc148072387b4dfddcf0ff405acbbaae"
|
||||
}
|
||||
}
|
||||
+1
-1
@@ -1 +1 @@
|
||||
0.6.16
|
||||
0.6.17
|
||||
@@ -648,17 +648,15 @@ def resolve_active_task(
|
||||
platform_input: dict[str, Any] | None = None,
|
||||
platform: str | None = None,
|
||||
*,
|
||||
allow_single_session_fallback: bool = True,
|
||||
allow_single_session_fallback: bool = False,
|
||||
allow_environment_context: bool = True,
|
||||
) -> ActiveTask:
|
||||
"""Resolve the active task from session runtime state only.
|
||||
|
||||
A stale session task is returned as stale. Missing context identity or a
|
||||
missing/empty session context falls back to single-session inference: if
|
||||
exactly one session file exists in the runtime, return its task with
|
||||
source_type="session-fallback" — covers pull-based platform sub-agents
|
||||
(copilot, gemini, qoder) that don't inherit the parent's session id. ≥2
|
||||
files or 0 files yield ActiveTask(None) — refuses to guess across windows.
|
||||
Missing or unmatched session identity does not infer ownership from the
|
||||
number of session files. Pull-based child-agent callers that cannot inherit
|
||||
a parent identity must opt into the compatibility fallback explicitly.
|
||||
"""
|
||||
context_key = resolve_context_key(
|
||||
platform_input,
|
||||
|
||||
@@ -196,6 +196,40 @@ def _report_write_failure(path: Path) -> None:
|
||||
)
|
||||
|
||||
|
||||
def _restore_child_links(unlinked: dict[Path, str | None]) -> None:
|
||||
"""Put back the parent links this archive attempt already removed.
|
||||
|
||||
The unlink loop below walks a parent's children one at a time, so a
|
||||
failure part-way through leaves the earlier children carrying
|
||||
``parent: null`` while their parent is still in the active tree. That is
|
||||
the mirror image of the dangling reference the same loop already refuses
|
||||
to create, and nothing repairs it later either, so undo it before the
|
||||
failure is reported.
|
||||
|
||||
Restoring is best-effort: if a child cannot be written back, name it so
|
||||
the caller can re-link it by hand instead of guessing which one broke.
|
||||
"""
|
||||
broken: list[str] = []
|
||||
for child_json, original_parent in unlinked.items():
|
||||
child_data, _ = read_json_checked(child_json)
|
||||
if child_data is None:
|
||||
broken.append(child_json.parent.name)
|
||||
continue
|
||||
child_data["parent"] = original_parent
|
||||
if not write_json(child_json, child_data):
|
||||
broken.append(child_json.parent.name)
|
||||
if broken:
|
||||
print(
|
||||
colored(
|
||||
f"Warning: could not restore the parent link on: {', '.join(broken)}. "
|
||||
"Re-link each one with `python3 .trellis/scripts/task.py "
|
||||
"add-subtask <parent> <child>`.",
|
||||
Colors.RED,
|
||||
),
|
||||
file=sys.stderr,
|
||||
)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Sub-agent platform detection + JSONL context files
|
||||
# =============================================================================
|
||||
@@ -1332,7 +1366,13 @@ def cmd_archive(args: argparse.Namespace) -> int:
|
||||
# missing from the active set are treated as completed.
|
||||
task_children = data.get("children", [])
|
||||
|
||||
# If this is a parent, clear parent field in all children
|
||||
# If this is a parent, clear parent field in all children.
|
||||
# Remember each link removed so a later failure in this loop can
|
||||
# put it back (see _restore_child_links). Keyed by the child's
|
||||
# task.json: a `children` list that names the same child twice
|
||||
# would otherwise record a second, already-cleared snapshot and
|
||||
# the restore would write that `null` back over the real parent.
|
||||
unlinked_children: dict[Path, str | None] = {}
|
||||
if task_children:
|
||||
for child_name in task_children:
|
||||
child_dir_path = find_task_by_name(child_name, tasks_dir)
|
||||
@@ -1351,13 +1391,29 @@ def cmd_archive(args: argparse.Namespace) -> int:
|
||||
file=sys.stderr,
|
||||
)
|
||||
continue
|
||||
# Only the first visit to a child records its original
|
||||
# parent: a `children` list naming the same child twice
|
||||
# would otherwise snapshot the already-cleared value and
|
||||
# the restore would write that `null` back over the link.
|
||||
first_visit = child_json not in unlinked_children
|
||||
original_parent = child_data.get("parent")
|
||||
if first_visit:
|
||||
unlinked_children[child_json] = original_parent
|
||||
child_data["parent"] = None
|
||||
if not write_json(child_json, child_data):
|
||||
# Stop before the move: a child pointing at a
|
||||
# parent that has left .trellis/tasks/ is a
|
||||
# dangling reference nothing repairs later.
|
||||
# Put back the children already unlinked above —
|
||||
# their parent is staying, so losing the link the
|
||||
# other way round is just as unrecoverable.
|
||||
# Retrying is safe — every step so far is
|
||||
# idempotent.
|
||||
if first_visit:
|
||||
# The link never came off, so there is nothing
|
||||
# to put back for this child.
|
||||
del unlinked_children[child_json]
|
||||
_restore_child_links(unlinked_children)
|
||||
_report_write_failure(child_json)
|
||||
print(
|
||||
f"Not archived: {_repo_relative_path(task_dir, repo_root)} is "
|
||||
|
||||
@@ -1,105 +1,21 @@
|
||||
# Code Reuse Thinking Guide
|
||||
|
||||
> **Purpose**: Stop and think before creating new code - does it already exist?
|
||||
Consult when adding a helper/component or changing behavior shared by multiple
|
||||
consumers. Search the relevant source and tests with `rg` before creating a
|
||||
second implementation; widen the search when ownership is uncertain.
|
||||
|
||||
---
|
||||
## Decide From The Contract
|
||||
|
||||
## The Problem
|
||||
- Compare responsibilities, inputs, failure behavior, permissions and lifecycle, not only similar syntax or visual shape.
|
||||
- Reuse or extend an existing owner when the semantics agree. Keep distinct rules separate when combining them creates flags, coupling or misleading names.
|
||||
- Share constants only when they represent the same business fact. A fixed repetition count or similarity percentage does not justify an abstraction.
|
||||
- For a shared change, identify callers and assert the affected behaviors, including exceptions. After a batch edit, check for missed consumers and accidental out-of-scope changes.
|
||||
|
||||
**Duplicated code is the #1 source of inconsistency bugs.**
|
||||
## Asymmetric Producers
|
||||
|
||||
When you copy-paste or rewrite existing logic:
|
||||
- Bug fixes don't propagate
|
||||
- Behavior diverges over time
|
||||
- Codebase becomes harder to understand
|
||||
|
||||
---
|
||||
|
||||
## Before Writing New Code
|
||||
|
||||
### Step 1: Search First
|
||||
|
||||
```bash
|
||||
# Search for similar function names
|
||||
grep -r "functionName" .
|
||||
|
||||
# Search for similar logic
|
||||
grep -r "keyword" .
|
||||
```
|
||||
|
||||
### Step 2: Ask These Questions
|
||||
|
||||
| Question | If Yes... |
|
||||
|----------|-----------|
|
||||
| Does a similar function exist? | Use or extend it |
|
||||
| Is this pattern used elsewhere? | Follow the existing pattern |
|
||||
| Could this be a shared utility? | Create it in the right place |
|
||||
| Am I copying code from another file? | **STOP** - extract to shared |
|
||||
|
||||
---
|
||||
|
||||
## Common Duplication Patterns
|
||||
|
||||
### Pattern 1: Copy-Paste Functions
|
||||
|
||||
**Bad**: Copying a validation function to another file
|
||||
|
||||
**Good**: Extract to shared utilities, import where needed
|
||||
|
||||
### Pattern 2: Similar Components
|
||||
|
||||
**Bad**: Creating a new component that's 80% similar to existing
|
||||
|
||||
**Good**: Extend existing component with props/variants
|
||||
|
||||
### Pattern 3: Repeated Constants
|
||||
|
||||
**Bad**: Defining the same constant in multiple files
|
||||
|
||||
**Good**: Single source of truth, import everywhere
|
||||
|
||||
---
|
||||
|
||||
## When to Abstract
|
||||
|
||||
**Abstract when**:
|
||||
- Same code appears 3+ times
|
||||
- Logic is complex enough to have bugs
|
||||
- Multiple people might need this
|
||||
|
||||
**Don't abstract when**:
|
||||
- Only used once
|
||||
- Trivial one-liner
|
||||
- Abstraction would be more complex than duplication
|
||||
|
||||
---
|
||||
|
||||
## After Batch Modifications
|
||||
|
||||
When you've made similar changes to multiple files:
|
||||
|
||||
1. **Review**: Did you catch all instances?
|
||||
2. **Search**: Run grep to find any missed
|
||||
3. **Consider**: Should this be abstracted?
|
||||
|
||||
---
|
||||
|
||||
## Gotcha: Asymmetric Mechanisms Producing Same Output
|
||||
|
||||
**Problem**: When two different mechanisms must produce the same file set (e.g., recursive directory copy for init vs. manual `files.set()` for update), structural changes (renaming, moving, adding subdirectories) only propagate through the automatic mechanism. The manual one silently drifts.
|
||||
|
||||
**Symptom**: Init works perfectly, but update creates files at wrong paths or misses files entirely.
|
||||
|
||||
**Prevention checklist**:
|
||||
- [ ] When migrating directory structures, search for ALL code paths that reference the old structure
|
||||
- [ ] If one path is auto-derived (glob/copy) and another is manually listed, the manual one needs updating
|
||||
- [ ] Add a regression test that compares outputs from both mechanisms
|
||||
|
||||
---
|
||||
|
||||
## Checklist Before Commit
|
||||
|
||||
- [ ] Searched for existing similar code
|
||||
- [ ] No copy-pasted logic that should be shared
|
||||
- [ ] Constants defined in one place
|
||||
- [ ] Similar patterns follow same structure
|
||||
When automatic discovery/copy and a manually listed producer promise the same
|
||||
output (for example init/update, screen/export or live/snapshot inputs), a
|
||||
rename or added field can update only one side. Inspect both producers and
|
||||
compare their observable output contract. Prefer a focused parity regression
|
||||
over another copied list; do not assume generated output proves every producer
|
||||
was exercised.
|
||||
|
||||
@@ -1,162 +1,46 @@
|
||||
# Cross-Layer Thinking Guide
|
||||
|
||||
> **Purpose**: Think through data flow across layers before implementing.
|
||||
Use for changes crossing data, authority or state boundaries. Trace the affected
|
||||
path from input through transformation/storage to display or export. Identify
|
||||
consumers and the format, ownership, errors and invariants at each boundary.
|
||||
Do not require a diagram or new document when a short task note suffices.
|
||||
|
||||
---
|
||||
## Validation And Round Trips
|
||||
|
||||
## The Problem
|
||||
Client validation helps the user; the server still enforces authentication,
|
||||
authorization and untrusted input. Mutable business facts may need rechecking
|
||||
under the transaction/lock that protects the write. Reuse pure validation rules
|
||||
where semantics agree, but never remove a trust-boundary check merely because
|
||||
another layer validated earlier.
|
||||
|
||||
**Most bugs happen at layer boundaries**, not within layers.
|
||||
Check null/omitted/empty distinctions, dates/time zones, precision, serialization
|
||||
and error handling on affected consumers. Verify meaningful round trips and
|
||||
negative cases; test depth follows the changed contract, not a fixed layer count.
|
||||
The owning domain spec defines exact business behavior.
|
||||
|
||||
Common cross-layer bugs:
|
||||
- API returns format A, frontend expects format B
|
||||
- Database stores X, service transforms to Y, but loses data
|
||||
- Multiple layers implement the same logic differently
|
||||
## Generated Runtime Inputs
|
||||
|
||||
---
|
||||
For generated files that are also parsed at runtime, identify readers as well
|
||||
as writers. Workflow tag/platform markers outside a managed block may affect
|
||||
phase routing even when the block itself updates correctly.
|
||||
|
||||
## Before Implementing Cross-Layer Features
|
||||
In this installed project, use the pinned target CLI, preserve overlays and
|
||||
exercise the actual context/hook parsers; see
|
||||
[upgrade compatibility](../hyb-oa/project-governance.md#scenario-trellis-project-upgrade-compatibility).
|
||||
Only an authorized upstream-template task should modify other platform copies
|
||||
or test upstream init/update generation with older pristine fixtures. Do not
|
||||
assume this repository contains `src/templates` or enable other platforms.
|
||||
|
||||
### Step 1: Map the Data Flow
|
||||
## Probe-Dependent Modes
|
||||
|
||||
Draw out how data moves:
|
||||
When a mode depends on an external probe, check normal, non-interactive and
|
||||
shortcut paths. Distinguish missing resources from transient failures; fail
|
||||
clearly or retry within the authorized budget, never silently switch modes
|
||||
after a timeout or transport error. Preserve that error
|
||||
quality in downstream helpers and reset cached state when the source changes.
|
||||
|
||||
```
|
||||
Source → Transform → Store → Retrieve → Transform → Display
|
||||
```
|
||||
|
||||
For each arrow, ask:
|
||||
- What format is the data in?
|
||||
- What could go wrong?
|
||||
- Who is responsible for validation?
|
||||
|
||||
### Step 2: Identify Boundaries
|
||||
|
||||
| Boundary | Common Issues |
|
||||
|----------|---------------|
|
||||
| API ↔ Service | Type mismatches, missing fields |
|
||||
| Service ↔ Database | Format conversions, null handling |
|
||||
| Backend ↔ Frontend | Serialization, date formats |
|
||||
| Component ↔ Component | Props shape changes |
|
||||
|
||||
### Step 3: Define Contracts
|
||||
|
||||
For each boundary:
|
||||
- What is the exact input format?
|
||||
- What is the exact output format?
|
||||
- What errors can occur?
|
||||
|
||||
---
|
||||
|
||||
## Common Cross-Layer Mistakes
|
||||
|
||||
### Mistake 1: Implicit Format Assumptions
|
||||
|
||||
**Bad**: Assuming date format without checking
|
||||
|
||||
**Good**: Explicit format conversion at boundaries
|
||||
|
||||
### Mistake 2: Scattered Validation
|
||||
|
||||
**Bad**: Validating the same thing in multiple layers
|
||||
|
||||
**Good**: Validate once at the entry point
|
||||
|
||||
### Mistake 3: Leaky Abstractions
|
||||
|
||||
**Bad**: Component knows about database schema
|
||||
|
||||
**Good**: Each layer only knows its neighbors
|
||||
|
||||
---
|
||||
|
||||
## Checklist for Cross-Layer Features
|
||||
|
||||
Before implementation:
|
||||
- [ ] Mapped the complete data flow
|
||||
- [ ] Identified all layer boundaries
|
||||
- [ ] Defined format at each boundary
|
||||
- [ ] Decided where validation happens
|
||||
|
||||
After implementation:
|
||||
- [ ] Tested with edge cases (null, empty, invalid)
|
||||
- [ ] Verified error handling at each boundary
|
||||
- [ ] Checked data survives round-trip
|
||||
|
||||
---
|
||||
|
||||
## Cross-Platform Template Consistency
|
||||
|
||||
In Trellis, command templates (e.g., `record-session.md`) exist in **multiple platforms** with identical or near-identical content. This is a cross-layer boundary.
|
||||
|
||||
### Checklist: After Modifying Any Command Template
|
||||
|
||||
- [ ] Find all platforms with the same command: `find src/templates/*/commands/trellis/ -name "<command>.*"`
|
||||
- [ ] Update all platform copies (Markdown `.md` and TOML `.toml`)
|
||||
- [ ] For Gemini TOML: adapt line continuations (`\\` vs `\`) and triple-quoted strings
|
||||
- [ ] Run `/trellis:check-cross-layer` to verify nothing was missed
|
||||
|
||||
**Real-world example**: Updated `record-session.md` in Claude to use `--mode record`, but forgot iFlow, Kilo, OpenCode, and Gemini — caught by cross-layer check.
|
||||
|
||||
---
|
||||
|
||||
## Generated Runtime Template Upgrade Consistency
|
||||
|
||||
Some generated files are both documentation and runtime input. In Trellis,
|
||||
`.trellis/workflow.md` is parsed by `get_context.py`, `workflow_phase.py`,
|
||||
SessionStart filters, and per-turn hooks. Template changes must be validated
|
||||
against both fresh init and upgrade paths.
|
||||
|
||||
### Checklist: After Modifying A Runtime-Parsed Template
|
||||
|
||||
- [ ] Identify every runtime parser that reads the template, not just the file
|
||||
writer that installs it
|
||||
- [ ] Check whether relevant syntax lives outside obvious managed regions
|
||||
such as tag blocks
|
||||
- [ ] Verify fresh `init` output and a versioned `update` scenario that writes
|
||||
the older `.trellis/.version`
|
||||
- [ ] Add an upgrade regression using an older pristine template fixture, then
|
||||
assert the installed file reaches the current packaged shape
|
||||
- [ ] Update the backend spec that owns the runtime contract
|
||||
|
||||
**Real-world example**: Codex inline mode changed workflow platform markers from
|
||||
`[Codex]` / `[Kilo, Antigravity, Windsurf]` to `[codex-sub-agent]` /
|
||||
`[codex-inline, Kilo, Antigravity, Windsurf]`. Fresh init was correct, but
|
||||
`trellis update` only merged `[workflow-state:*]` blocks and preserved stale
|
||||
markers outside those blocks. Result: upgraded projects got new hook scripts
|
||||
but old workflow routing, so `get_context.py --mode phase --platform codex`
|
||||
could return empty Phase 2.1 detail.
|
||||
|
||||
---
|
||||
|
||||
## Mode-Detection Probe Checklist
|
||||
|
||||
When a CLI auto-detects a mode by probing a remote resource (e.g., checking if `index.json` exists to decide marketplace vs direct download):
|
||||
|
||||
### Before implementing:
|
||||
- [ ] Probe runs in **ALL** code paths that use the result (interactive, `-y`, `--flag` combos)
|
||||
- [ ] 404 vs transient error are distinguished — don't treat both as "not found"
|
||||
- [ ] Transient errors **abort or retry**, never silently switch modes
|
||||
- [ ] Shared state (caches, prefetched data) is **reset** when context changes (e.g., user switches source)
|
||||
- [ ] **Shortcut paths** (e.g., `--template` skipping picker) must have the same error-handling quality as the probed path — check that downstream functions don't call catch-all wrappers
|
||||
|
||||
### After implementing:
|
||||
- [ ] Trace every path from probe result to the mode-decision branch — no fallthrough
|
||||
- [ ] External format contracts (giget URI, raw URLs) are tested or at least documented as comments
|
||||
- [ ] Metadata reads consume a complete response or use a streaming parser — never parse a fixed-size prefix as full JSON
|
||||
- [ ] When reconstructing a composite identifier from parsed parts, verify **all** fields are included and in the **correct position** (e.g., `provider:repo/path#ref` not `provider:repo#ref/path`)
|
||||
- [ ] Verify that **action functions** called after a shortcut don't internally use the old catch-all fetch — they must use the probe-quality variant when error distinction matters
|
||||
|
||||
**Real-world example**: Custom registry flow had 8 bugs across 3 review rounds: (1) probe only ran in interactive mode, (2) transient errors fell through to wrong mode, (3) giget URI had `#ref` in wrong position, (4) prefetched templates leaked across source switches, (5) `--template` shortcut bypassed probe but `downloadTemplateById` internally used catch-all `fetchTemplateIndex`, turning timeouts into "Template not found".
|
||||
|
||||
**Real-world example**: Agent-session update hints fetched npm `latest` metadata with `response.read(4096)` and then parsed it as complete JSON. The `@mindfoldhq/trellis` package metadata exceeded 4 KB, so the JSON was truncated, parse failed silently, and the first session injection showed no update hint. Fix: read the complete response before parsing, and add a regression where `version` is followed by an 8 KB metadata tail.
|
||||
|
||||
---
|
||||
|
||||
## When to Create Flow Documentation
|
||||
|
||||
Create detailed flow docs when:
|
||||
- Feature spans 3+ layers
|
||||
- Multiple teams are involved
|
||||
- Data format is complex
|
||||
- Feature has caused bugs before
|
||||
Parse complete metadata or use a real streaming parser; a fixed-length prefix
|
||||
is not a complete JSON document. For reconstructed identifiers, preserve all
|
||||
fields and their ordering (such as path before fragment). Exercise a large
|
||||
metadata response and failure/shortcut cases only when those mechanisms are
|
||||
part of the change. Do not contact real external systems merely to read this guide.
|
||||
|
||||
+10
-68
@@ -1,72 +1,14 @@
|
||||
# Thinking Guides
|
||||
|
||||
> **Purpose**: Expand your thinking to catch things you might not have considered.
|
||||
Use a guide only when its trigger applies and its relevant context is not
|
||||
already loaded. Stable implementation contracts remain in the domain specs;
|
||||
these guides help locate the questions that matter.
|
||||
|
||||
---
|
||||
| Guide | Trigger |
|
||||
| --- | --- |
|
||||
| [Code reuse](./code-reuse-thinking-guide.md) | A new helper/component, repeated behavior, or a shared constant/contract change |
|
||||
| [Cross-layer behavior](./cross-layer-thinking-guide.md) | Data, authority or state crosses a boundary; multiple consumers depend on a change |
|
||||
|
||||
## Why Thinking Guides?
|
||||
|
||||
**Most bugs and tech debt come from "didn't think of that"**, not from lack of skill:
|
||||
|
||||
- Didn't think about what happens at layer boundaries → cross-layer bugs
|
||||
- Didn't think about code patterns repeating → duplicated code everywhere
|
||||
- Didn't think about edge cases → runtime errors
|
||||
- Didn't think about future maintainers → unreadable code
|
||||
|
||||
These guides help you **ask the right questions before coding**.
|
||||
|
||||
---
|
||||
|
||||
## Available Guides
|
||||
|
||||
| Guide | Purpose | When to Use |
|
||||
|-------|---------|-------------|
|
||||
| [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md) | Identify patterns and reduce duplication | When you notice repeated patterns |
|
||||
| [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md) | Think through data flow across layers | Features spanning multiple layers |
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Thinking Triggers
|
||||
|
||||
### When to Think About Cross-Layer Issues
|
||||
|
||||
- [ ] Feature touches 3+ layers (API, Service, Component, Database)
|
||||
- [ ] Data format changes between layers
|
||||
- [ ] Multiple consumers need the same data
|
||||
- [ ] You're not sure where to put some logic
|
||||
|
||||
→ Read [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md)
|
||||
|
||||
### When to Think About Code Reuse
|
||||
|
||||
- [ ] You're writing similar code to something that exists
|
||||
- [ ] You see the same pattern repeated 3+ times
|
||||
- [ ] You're adding a new field to multiple places
|
||||
- [ ] You are changing a shared constant or configuration contract
|
||||
- [ ] **You're creating a new utility/helper function** ← Search first!
|
||||
|
||||
→ Read [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md)
|
||||
|
||||
---
|
||||
|
||||
## Reference Checks By Risk
|
||||
|
||||
Before changing shared contracts, cross-layer constants or configuration, inspect their consumers. A local literal or wording correction does not require a repository-wide search. Read these guides only when the task matches their triggers; do not repeat an unchanged checklist every turn.
|
||||
|
||||
---
|
||||
|
||||
## How to Use This Directory
|
||||
|
||||
1. **Before coding**: Skim the relevant thinking guide
|
||||
2. **During coding**: If something feels repetitive or complex, check the guides
|
||||
3. **After bugs**: Add new insights to the relevant guide (learn from mistakes)
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
Found a new "didn't think of that" moment? Add it to the relevant guide.
|
||||
|
||||
---
|
||||
|
||||
**Core Principle**: 30 minutes of thinking saves 3 hours of debugging.
|
||||
Search affected consumers for a shared-contract change. A local wording or
|
||||
literal correction does not require a full-repository search. Add a reusable
|
||||
insight at its existing owner; keep one-off findings in the task.
|
||||
|
||||
@@ -2,276 +2,187 @@
|
||||
|
||||
## Source Docs
|
||||
|
||||
Start from `docs/文档索引.md` and `docs/文档事实源状态矩阵.md`.
|
||||
Use `docs/文档索引.md` and `docs/文档事实源状态矩阵.md` to locate the current fact owner.
|
||||
|
||||
## Rules
|
||||
|
||||
- Prefer updating existing fact sources, module specs, manuals, evidence docs
|
||||
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 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.
|
||||
- Update the existing fact source, module spec, manual or task. A new document needs a distinct purpose and registration in both the docs index and status matrix.
|
||||
- Keep a verified reusable rule in its owning section; keep run chronology, counts, candidate hashes and unresolved hypotheses in task/evidence. Consolidate repetition without losing unique conditions, exceptions or references. If there is no new reusable lesson, no spec edit is needed; a fixed seven-section layout is not required unless the task/delivery contract requires it.
|
||||
- Preserve historical Issue CSVs, findings and original receipts. New evidence adds a dated/sourced delta; it does not rewrite the old result. A matching selected-code digest does not establish whole-tree or publication coverage.
|
||||
- Record relative report references and safe conclusions, not raw payloads, secrets, full accounts, invoice originals or confidential business content. Static validation, runtime behavior, independent review and public/real-data verification remain distinct.
|
||||
|
||||
## Scenario: Registered Local Evidence Integrity
|
||||
|
||||
### 1. Scope / Trigger
|
||||
|
||||
Protect the 14 historical screenshots registered in the archived 07-18
|
||||
small-team internal-readiness evidence table. Not being an automated snapshot
|
||||
baseline does not make human-reviewed, digest-registered evidence disposable.
|
||||
small-team internal-readiness evidence table. Human-reviewed digest-registered
|
||||
artifacts remain evidence even when automated snapshot tests do not read them.
|
||||
|
||||
### 2. Signatures
|
||||
|
||||
`node scripts/qa/check-trellis-governance.mjs` calls `validateRegisteredEvidence`.
|
||||
The code-owned registry supplies document, artifact directory and expected count;
|
||||
the document's `截图 | SHA-256` table supplies filenames and approved hashes.
|
||||
Its code-owned registry defines document, artifact directory and expected count;
|
||||
the document's `截图 | SHA-256` table defines filenames and approved hashes.
|
||||
|
||||
### 3. Contracts
|
||||
|
||||
Validate regular local files without following symlink artifacts or ancestor
|
||||
redirects. Preserve original documents/hashes. Before restoring an accidentally
|
||||
overwritten artifact, preserve the new runtime copy and its digest separately.
|
||||
Do not remove registered evidence from the index merely because tests never read it.
|
||||
Historical private restore-runner candidate hashes without a public repository
|
||||
file mapping are not local-file checks; do not fetch private/production inputs
|
||||
or claim universal verification of every SHA literal in Trellis documents.
|
||||
Require regular local files, without artifact symlinks or ancestor redirects.
|
||||
Preserve the registered documents/hashes. Before restoring an overwritten file,
|
||||
save the runtime copy and its digest separately. Do not unregister evidence to
|
||||
make a check pass. Private restore-candidate hashes without a public repository
|
||||
file mapping are outside this local check; do not fetch private/production inputs
|
||||
or claim every historical SHA was verified.
|
||||
|
||||
### 4. Validation / Error Matrix
|
||||
|
||||
Missing document/table/file, changed digest, invalid row/path, duplicate entry,
|
||||
symlink or reduced registered count is a governance error. A matching table
|
||||
reports the exact number verified; no silent table-shrink acceptance is allowed.
|
||||
symlink or reduced registered count fails governance. A match reports the exact
|
||||
verified count; silently shrinking the table is not an acceptable repair.
|
||||
|
||||
### 5. Good / Base / Bad
|
||||
|
||||
Good: verify 14/14 archived hashes while new screenshots go to isolated run roots.
|
||||
Base: local governance verifies registered public artifacts, with scope explicit.
|
||||
Bad: ignore all output paths, silently replace archived hashes, or call unverifiable
|
||||
private historical candidates locally verified.
|
||||
Verify the registered 14/14 separately from new isolated screenshots. Never
|
||||
replace approved hashes with runtime outputs or claim unmapped private evidence
|
||||
was locally checked.
|
||||
|
||||
### 6. Tests Required
|
||||
|
||||
`node --test scripts/qa/tests/registered-evidence.test.mjs` covers intact evidence,
|
||||
overwrites, missing files/tables/rows, duplicate rows, unsafe paths and symlinks.
|
||||
Visual path and full-repository snapshot tests separately prevent the producer
|
||||
from overwriting history and detect tracked mutations even when already dirty.
|
||||
`node --test scripts/qa/tests/registered-evidence.test.mjs`: intact evidence,
|
||||
overwrite/missing document/table/file/row, duplicate rows, unsafe paths and
|
||||
symlinks. Visual-output isolation and repository snapshot tests separately check
|
||||
the producer and tracked mutations, including an already dirty checkout.
|
||||
|
||||
### 7. Wrong / Correct
|
||||
|
||||
Wrong: selected source digest unchanged, therefore the worktree is unchanged.
|
||||
Correct: report selected-source and repository/index facts separately; tracked
|
||||
output remains subject to the same whole-repository integrity requirements.
|
||||
Report selected-source, whole-repository and index integrity separately; an
|
||||
unchanged selected-source digest does not prove the worktree is unchanged.
|
||||
|
||||
## Scenario: Finding Lifecycle And Audit Closeout
|
||||
|
||||
### 1. Scope / Trigger
|
||||
|
||||
- Trigger: a review, audit or trial-run task records findings and later code,
|
||||
deployment or external evidence changes their current state.
|
||||
- Applies to Trellis PRDs, review reports, finding ledgers and management
|
||||
summaries.
|
||||
Use when later code, deployment or external evidence changes a recorded review,
|
||||
audit or trial-run finding's current disposition.
|
||||
|
||||
### 2. Signatures
|
||||
|
||||
- Canonical ledger fields: `findingId`, `dimension`, `discoverySeverity`,
|
||||
`confidence`, `discoveryStatus`, `remediationStatus`, `deploymentStatus`,
|
||||
`externalVerificationStatus`, `evidenceRef`, `businessImpact`,
|
||||
`controlObjective`, `safeVerification`, `followUpWorkPackage`.
|
||||
- Delta fields: `discoveryCommit`, `reviewedCommit`, changed-commit list,
|
||||
validation command, result and explicit environment boundary.
|
||||
Canonical ledger fields: `findingId`, `dimension`, `discoverySeverity`,
|
||||
`confidence`, `discoveryStatus`, `remediationStatus`, `deploymentStatus`,
|
||||
`externalVerificationStatus`, `evidenceRef`, `businessImpact`, `controlObjective`,
|
||||
`safeVerification`, `followUpWorkPackage`. A delta records `discoveryCommit`,
|
||||
`reviewedCommit`, changed commits, command/result and environment boundary.
|
||||
|
||||
### 3. Contracts
|
||||
|
||||
- Preserve the discovery baseline, discovery severity and discovery status.
|
||||
Later remediation must add a delta; it must not rewrite history as if the
|
||||
finding never existed.
|
||||
- Record remediation, deployment and external-behavior verification as three
|
||||
independent states. A local test pass does not prove deployment, and a
|
||||
deployed build marker does not prove role-specific or real-device behavior.
|
||||
- A closeout task must have one canonical finding ledger. Component reports
|
||||
may retain their original wording, but duplicate IDs and reclassified items
|
||||
must point to the canonical ledger.
|
||||
- When HEAD moves after discovery, record the exact old and new commits,
|
||||
classify the delta and rerun the closeout gates. Do not relabel an old report
|
||||
as evidence for the new HEAD.
|
||||
- Use repo-relative evidence references and synthetic fixtures. Unknown or
|
||||
unauthorized deployment, public, production-data and real-device checks stay
|
||||
explicit as pending or externally gated.
|
||||
Preserve discovery baseline/severity/status. Maintain one canonical finding
|
||||
ledger per closeout; duplicate or reclassified component findings retain source
|
||||
references and map to exactly one canonical entry. Record remediation,
|
||||
deployment and external behavior independently: local PASS does not establish
|
||||
deployment, and a build marker does not establish role/device behavior.
|
||||
|
||||
When HEAD changes, identify old/new commits, classify the delta and rerun the
|
||||
applicable closeout gates; never relabel old reports as evidence for new inputs.
|
||||
Use relative evidence refs and synthetic fixtures. Unknown or unauthorized
|
||||
production/public/real-device checks remain explicitly pending or externally gated.
|
||||
|
||||
### 4. Validation & Error Matrix
|
||||
|
||||
- Local fix tested, not deployed -> remediation may pass; deployment remains
|
||||
pending and external behavior remains pending when applicable.
|
||||
- Finding open with no fix artifact -> deployment is `NO_FIX_TO_DEPLOY`, not
|
||||
`DEPLOYMENT_PENDING`.
|
||||
- Static/tooling-only finding -> deployment may be `NOT_APPLICABLE`; the
|
||||
remediation state still records whether the contract itself is fixed.
|
||||
- Duplicate component finding -> preserve its source reference and map it to
|
||||
exactly one canonical ledger entry.
|
||||
| Condition | Recorded state |
|
||||
| --- | --- |
|
||||
| Local fix verified, not deployed | Remediation may pass; deployment and applicable external behavior remain pending |
|
||||
| Open finding with no fix artifact | `NO_FIX_TO_DEPLOY`, not `DEPLOYMENT_PENDING` |
|
||||
| Static/tooling-only finding | Deployment may be `NOT_APPLICABLE`; record remediation independently |
|
||||
| External verification not required | `NOT_REQUIRED` only where that verification is inapplicable |
|
||||
| Duplicate component finding | Source retained; exactly one canonical ledger mapping |
|
||||
|
||||
### 5. Good/Base/Bad Cases
|
||||
|
||||
- Good: a historical P0 remains P0/confirmed while local remediation passes,
|
||||
deployment is pending and external behavior is pending.
|
||||
- Base: an open local-only QA finding uses `NO_FIX_TO_DEPLOY`,
|
||||
`NOT_APPLICABLE` deployment or `NOT_REQUIRED` external verification as
|
||||
appropriate.
|
||||
- Bad: rename the discovery status to `RESOLVED` and omit whether the fix was
|
||||
deployed or observed externally.
|
||||
A confirmed historical P0 stays P0/confirmed after local remediation. Do not
|
||||
replace discovery status with `RESOLVED` or a single `resolved` field that hides
|
||||
deployment or observation.
|
||||
|
||||
### 6. Tests Required
|
||||
|
||||
- Task validation and Trellis governance.
|
||||
- Sensitive-content scan and document registry audit.
|
||||
- `git diff --check` plus a manual check that the recorded HEAD matches the
|
||||
evidence-producing checkout.
|
||||
Task validation, Trellis governance/sensitive scan, document registry audit and
|
||||
`git diff --check`; verify that the recorded HEAD identifies the evidence-producing
|
||||
checkout. Select additional checks from the changed contract.
|
||||
|
||||
### 7. Wrong vs Correct
|
||||
|
||||
#### Wrong
|
||||
|
||||
```json
|
||||
{"findingId":"F-001","status":"resolved"}
|
||||
```
|
||||
`{"findingId":"F-001","status":"resolved"}` loses the discovery and verification states.
|
||||
|
||||
#### Correct
|
||||
|
||||
```json
|
||||
{
|
||||
"findingId": "F-001",
|
||||
"discoverySeverity": "P0",
|
||||
"discoveryStatus": "CONFIRMED",
|
||||
"remediationStatus": "LOCAL_FIX_VERIFIED",
|
||||
"deploymentStatus": "DEPLOYMENT_PENDING",
|
||||
"externalVerificationStatus": "EXTERNAL_BEHAVIOR_PENDING"
|
||||
}
|
||||
```
|
||||
Keep `discoverySeverity=P0`, `discoveryStatus=CONFIRMED`,
|
||||
`remediationStatus=LOCAL_FIX_VERIFIED`, `deploymentStatus=DEPLOYMENT_PENDING`,
|
||||
`externalVerificationStatus=EXTERNAL_BEHAVIOR_PENDING` when those facts apply.
|
||||
|
||||
## Scenario: QA Readiness Report Summaries
|
||||
|
||||
### 1. Scope / Trigger
|
||||
|
||||
- Trigger: QA shell runners aggregate child reports for launch, patrol,
|
||||
smoke or readiness gates.
|
||||
- Applies to generated `summary.json`, step JSON and privacy findings under
|
||||
`artifacts/qa-flow/` or Trellis task research directories.
|
||||
Shell runners aggregating child launch/patrol/smoke/readiness reports into
|
||||
`summary.json`, step JSON or privacy findings under `artifacts/qa-flow/` or task research.
|
||||
|
||||
### 2. Signatures
|
||||
|
||||
- Parent shell runner writes `summary.json`.
|
||||
- Child runner summary input: `<child-report-dir>/summary.json`.
|
||||
- Step summary input/output: `<step-name>.step.json`.
|
||||
Parent output: `summary.json`; child input: `<child-report-dir>/summary.json`;
|
||||
step input/output: `<step-name>.step.json`.
|
||||
|
||||
### 3. Contracts
|
||||
|
||||
- Use repo-relative `reportRef` / `logRef` when a path is inside the repo.
|
||||
- Do not write absolute local workspace paths into `summary.json`.
|
||||
- Parent summaries must include child report status and child finding counts.
|
||||
- Live-readiness summaries must distinguish the local `sourceCommit` from the
|
||||
public `observedBuildSha`; a missing or mismatched public build marker cannot
|
||||
produce a clean pass.
|
||||
- Parent `findingCount` must become non-zero when any child summary reports
|
||||
`PASS_WITH_FINDINGS`, `SKIP`, `PARTIAL`, `PAUSED`, `MISSING`, blocker-like
|
||||
status or child `findingCount > 0`.
|
||||
- Machine-readable reports may include status, count, mode, conclusion,
|
||||
boolean operational flags and relative report refs.
|
||||
- Machine-readable reports must not include amounts, prices, costs, balances,
|
||||
bank details, invoice values, full accounts, tokens, secrets, raw payloads,
|
||||
raw form values or full local paths.
|
||||
- Credential/readiness presence reports must use safe business labels, not raw
|
||||
env key names. For example, emit `adminCredentialReady: true` instead of a
|
||||
field named after a credential-value environment variable.
|
||||
- `check-pending-ocr.mjs` must reuse the adapter-backed Prisma client factory
|
||||
and close both Prisma and its external PostgreSQL pool.
|
||||
Use repo-relative `reportRef`/`logRef` for repository paths. Include each child's
|
||||
status and finding count; any child finding or non-clean status makes parent
|
||||
`findingCount` non-zero. Live readiness records local `sourceCommit` separately
|
||||
from public `observedBuildSha`; absent/mismatched public identity cannot yield
|
||||
a clean pass attributed to local HEAD.
|
||||
|
||||
Allow status/count/mode/conclusion, operational booleans and relative refs.
|
||||
Exclude amounts/prices/costs/balances, bank/invoice details, full accounts,
|
||||
tokens/secrets, raw payload/form values and absolute local paths. Presence
|
||||
reports use safe labels such as `adminCredentialReady`, never secret-like raw
|
||||
environment-key field names, even with boolean values.
|
||||
|
||||
`check-pending-ocr.mjs` reuses the adapter-backed Prisma client factory and
|
||||
closes both Prisma and its external PostgreSQL pool.
|
||||
|
||||
### 4. Validation & Error Matrix
|
||||
|
||||
- Child `PASS` + `findingCount=0` -> parent may stay pass.
|
||||
- Child `PASS_WITH_FINDINGS` -> parent records a finding.
|
||||
- Child `SKIP` / `PARTIAL` / `PAUSED` / `MISSING` -> parent records
|
||||
`manual_or_config`.
|
||||
- Child `FAIL` / `BLOCKED` / `ERROR` -> parent records a finding or blocker
|
||||
according to whether the parent step is required.
|
||||
- Privacy smoke match -> write redacted finding metadata and make final
|
||||
summary reflect the failure.
|
||||
- Secret-like field names in generated reports -> privacy finding, even when
|
||||
the value is only a boolean presence flag.
|
||||
- Public `/ready` has no usable build SHA -> `manual_or_config` finding.
|
||||
- Expected and observed public SHA differ -> `manual_or_config` finding or a
|
||||
deployment blocker; never a clean pass attributed to local HEAD.
|
||||
| Child/observation | Parent behavior |
|
||||
| --- | --- |
|
||||
| `PASS` and `findingCount=0` | May remain pass |
|
||||
| `PASS_WITH_FINDINGS` or any child `findingCount>0` | Record a finding |
|
||||
| `SKIP`, `PARTIAL`, `PAUSED`, `MISSING` | Record `manual_or_config` |
|
||||
| `FAIL`, `BLOCKED`, `ERROR` or blocker-like status | Record finding/blocker according to whether the step is required |
|
||||
| Privacy smoke match or secret-like report field | Redacted finding metadata; final summary reflects failure |
|
||||
| Missing/unusable public `/ready` build SHA | `manual_or_config` finding |
|
||||
| Expected/observed public SHA mismatch | `manual_or_config` or deployment blocker, never clean pass |
|
||||
|
||||
### 5. Good/Base/Bad Cases
|
||||
|
||||
- Good: `summary.json` contains `reportRef`, `childReports.<name>.status`,
|
||||
`childReports.<name>.findingCount`, `sourceCommit`, `observedBuildSha` and no
|
||||
absolute local path.
|
||||
- Base: Missing runtime credentials produce `PASS_WITH_FINDINGS` or
|
||||
`manual_or_config`, not a clean pass.
|
||||
- Bad: Parent command exits 0 for a child `PASS_WITH_FINDINGS` and the parent
|
||||
summary still says clean pass.
|
||||
A parent report exposes child status/count and separate source/public identities.
|
||||
Missing credentials produce `PASS_WITH_FINDINGS` or `manual_or_config`/blocking,
|
||||
not clean readiness; exit 0 alone cannot erase a child's findings.
|
||||
|
||||
### 6. Tests Required
|
||||
|
||||
- `bash -n <runner>.sh`
|
||||
- Run the parent runner in a missing-credential scenario and assert:
|
||||
- parent status is `PASS_WITH_FINDINGS` or blocked, not clean pass;
|
||||
- child finding count is visible in parent summary;
|
||||
- privacy step is present in parent summary;
|
||||
- `summary.json` has no full workspace path or business amount fields.
|
||||
- For live/readiness env reports, assert the JSON contains safe readiness
|
||||
labels and does not contain raw secret-like env key names.
|
||||
- Run the matching launch/readiness aggregator when it consumes the report.
|
||||
- Build a synthetic 40-character SHA and assert the public bundle contains only
|
||||
its 12-character marker; use a local HTTP stub to assert readiness records and
|
||||
matches the observed marker.
|
||||
- `bash -n <runner>.sh`; exercise the parent/consuming aggregator with missing credentials. Assert parent `PASS_WITH_FINDINGS` or blocked, visible child count and privacy step, and absence of full paths/business amount fields.
|
||||
- Assert safe readiness labels and no raw secret-like environment-key fields.
|
||||
- Use a synthetic 40-character SHA to assert the public bundle exposes only its 12-character marker; a local HTTP stub verifies readiness reads and compares that marker.
|
||||
|
||||
### 7. Wrong vs Correct
|
||||
|
||||
#### Wrong
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "PASS_OA_REAL_USE_DAILY_READY",
|
||||
"reportDir": "/home/user/project/artifacts/qa-flow/run",
|
||||
"childReports": {}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"liveSmoke": {
|
||||
"RAW_CREDENTIAL_ENV_KEY": true
|
||||
}
|
||||
}
|
||||
```
|
||||
A clean parent status with an empty `childReports` hides a child's findings;
|
||||
a raw credential environment-key name remains unsuitable even with value `true`.
|
||||
|
||||
#### Correct
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "PASS_WITH_FINDINGS",
|
||||
"sourceCommit": "abcdef1234567890",
|
||||
"observedBuildSha": "abcdef123456",
|
||||
"buildShaMatches": true,
|
||||
"reportRef": "artifacts/qa-flow/run",
|
||||
"childReports": {
|
||||
"oaOnlySmokeReadiness": {
|
||||
"status": "PASS_WITH_FINDINGS",
|
||||
"reportRef": "artifacts/qa-flow/run/oa-only-smoke-readiness/summary.json",
|
||||
"findingCount": 7
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"liveSmoke": {
|
||||
"adminCredentialReady": true
|
||||
}
|
||||
}
|
||||
```
|
||||
A `PASS_WITH_FINDINGS` summary records `sourceCommit`, `observedBuildSha`,
|
||||
`buildShaMatches`, relative `reportRef`, and `childReports.<name>` with its
|
||||
`status`, relative `reportRef` and `findingCount`. Credential presence uses
|
||||
`liveSmoke.adminCredentialReady`, not a raw credential key.
|
||||
|
||||
+26
-16
@@ -1,25 +1,35 @@
|
||||
# hyb-oa Project Specs
|
||||
|
||||
These specs are the Trellis entry point for hyb-oa. They summarize stable
|
||||
development rules and point back to the current Trellis task and `docs/`
|
||||
fact sources.
|
||||
Stable development contracts live here; current requirements and status live in
|
||||
the Trellis task, while `docs/` remains the business fact source.
|
||||
|
||||
## Read Order
|
||||
|
||||
1. `project-governance.md`
|
||||
2. The domain file matching the task.
|
||||
3. The current `.trellis/tasks/<task>/prd.md` and `docs/文档索引.md`.
|
||||
1. Start with the current PRD and latest implementation status. Resolve a stale/missing pointer with `task.py current --source`; inspect related tasks before creating one.
|
||||
2. Reuse governance already loaded from AGENTS/workflow; consult `project-governance.md` for the relevant operation.
|
||||
3. Select the affected domain below. Use `docs/文档索引.md` only to locate unresolved business facts.
|
||||
|
||||
## Domain Specs
|
||||
|
||||
| Spec | Purpose |
|
||||
| Spec | Read when touching |
|
||||
| --- | --- |
|
||||
| `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, Trellis task and status matrix |
|
||||
| `security-privacy.md` | Privacy, secret handling and sensitive-data exclusions |
|
||||
| `project-governance.md` | Task/approval rules; Trellis Project Upgrade Compatibility; Codex Inline Context Manifests |
|
||||
| `backend-fastify-prisma.md` | Server APIs, transactions, migrations and data contracts |
|
||||
| `frontend-react-vite-design.md` | React behavior, page permissions and design-source rules |
|
||||
| `approval-workflow.md` | Approval states, self-approval and payment handoffs |
|
||||
| `reimbursement-invoice-ocr.md` | Reimbursement, invoice, OCR and attachment handling |
|
||||
| `wecom-boundary.md` | Enterprise WeChat ownership, APIs and write gates |
|
||||
| `deployment-trialrun.md` | The specific candidate gate, deployment or recovery operation |
|
||||
| `docs-and-evidence.md` | Evidence integrity, reporting and closeout |
|
||||
| `security-privacy.md` | Authentication, sensitive-data access and privacy boundaries |
|
||||
|
||||
## Large Specs And Reusable Lessons
|
||||
|
||||
Locate sections with `rg -n '^#{1,3} ' .trellis/spec/hyb-oa/<file>.md`, then read
|
||||
general rules, complete applicable scenarios and required references. Expand
|
||||
for shared/cross-layer contracts; no search hit does not prove no rule applies.
|
||||
Reuse unchanged sections already loaded instead of reading all domains.
|
||||
|
||||
For maintaining lessons and distinguishing evidence states, use
|
||||
[Docs And Evidence rules](./docs-and-evidence.md#rules). A model upgrade does
|
||||
not waive authorization, privacy, validation or independent review.
|
||||
|
||||
@@ -29,6 +29,13 @@ tasks after TRELLIS2.
|
||||
acceptance decisions require approval, not every intermediate action.
|
||||
- Read the current phase and affected-layer contracts on demand. Reuse
|
||||
unchanged context; do not require every document or thinking guide per turn.
|
||||
- Resolve task identity with `task.py current --source` before broad session
|
||||
dumps. A missing pointer does not authorize guessing another session's task
|
||||
or creating a duplicate; inspect directly related task contracts.
|
||||
- Use the package index and heading search for large specs, then read the
|
||||
applicable general rules and complete scenarios. Do not treat a truncated
|
||||
search excerpt as full contract coverage. Keep skills as small entry points,
|
||||
with one owner for phase routing and reusable lessons.
|
||||
- Prefer an available native plan tool. If unavailable, keep the checklist
|
||||
in the current task implementation notes rather than stopping or creating
|
||||
another planning system.
|
||||
@@ -226,7 +233,8 @@ records the adopted scope and first reversible navigation reduction.
|
||||
- Compile every Python file under `.trellis/scripts` and `.codex/hooks`.
|
||||
- Exercise task validate/current/list and run Trellis governance.
|
||||
- Archive the final active task and assert Trellis governance still passes with
|
||||
zero active task directories.
|
||||
zero active task directories in a disposable synthetic project only. This
|
||||
runtime check does not authorize archiving a real task.
|
||||
- Record pre-existing backup directory names before update; confirm no `.new`,
|
||||
newly generated backup, bytecode or out-of-scope platform assets are tracked
|
||||
or left for the sensitive scanner. Do not interpret a historical backup as
|
||||
|
||||
@@ -1,5 +1,64 @@
|
||||
# 升级与规则治理设计
|
||||
|
||||
## 自主经验精简设计（2026-09-19，最新）
|
||||
|
||||
用户授权主会话自主决定本轮维护。沿用项目合同，先记录本方案再执行，不为纯文本编辑重启同范围审批。
|
||||
|
||||
### 已核问题及处置
|
||||
|
||||
| 位置 | 已核问题 | 处理 |
|
||||
| --- | --- | --- |
|
||||
| trellis-update-spec | 10109 字节，强制七段输出和多份示例，容易把一次性事实扩为永久规约 | 改为短入口：先判断稳定/复用价值，再在原章节增改；infra/API/schema 的具体字段、边界、失败和断言深度保持，版式不固定 |
|
||||
| trellis-break-loop | 6963 字节，要求猜先验并合计100%、强制概率阈值、立即提交及同步不存在的上游模板目录 | 保留根因、失败原因、区分性证据和最小预防；去掉伪精确概率、擅自提交和跨项目模板写入 |
|
||||
| trellis-brainstorm | 10645 字节，重复规划/提问/汇总清单，已有充分信息也容易停顿 | 保留真实用户决策和批准门禁；自主授权范围内的常规选择直接处理，问题只阻塞依赖部分；复用已有任务 |
|
||||
| spec/guides | 通用教程、固定重复次数阈值、多平台源码模板路径与本项目不符；“入口校验一次”误导跨信任边界 | 只保留按风险触发的消费者/数据流检查；明确前端校验不替代服务端权限与事务重验，生成模板检查按本地实际适用 |
|
||||
| docs-and-evidence | 三类场景的正反例/正文重复 | 保留既有章节标题和可执行合同，缩短重复示例；补原章节维护稳定经验、任务保存本轮事实的规则 |
|
||||
|
||||
本轮不拆分或移动大型业务 spec、不删历史经验/截图/回执、不改四个官方 bundled skills，不为减少提示字符停用技能。不修改 AGENTS、runtime、workflow、用户级技能/配置或产品。
|
||||
|
||||
### 验证与回退
|
||||
|
||||
证据根 artifacts/qa-governance/knowledge-pruning-20260919；before/ 保存允许改动的12个路径，protected-before.json 保存3070条整树基线，working-before.diff 保留既有差异。本轮逐文件对照，不以 HEAD 混入旧修改。
|
||||
|
||||
先核保留契约映射及引用，再运行 skill-creator quick_validate、已有隔离 app-server 的技能发现（扩展核对本轮三技能）、task/process/docs/governance/diff 和保护检查。无 runtime/业务修改，不重跑50个未变 runtime用例或4437/372全量。只读主会话检查不冒充独立模型行为评估；新规划/复盘指令的独立审阅单列，旧升级 PASS 仍仅覆盖原增量。
|
||||
|
||||
失败时从本轮 before/ 逐文件恢复，不重置整树。修订覆盖“证据先行、授权边界、合同深度、最小防回归、引用与历史保护”；不以压缩百分比决定删除条款。
|
||||
|
||||
## 0.6.17 续办设计（2026-09-19）
|
||||
|
||||
### 本轮审查结论
|
||||
|
||||
- 已落实：三份项目入口技能共 5411 → 3981 字节（减少 26.4%）；其中 continue 为 2685 → 1640 字节（减少 38.9%），移除重复阶段表。当前任务查询实测输出由完整会话的 5320 字节缩为 123 字节，但只覆盖任务身份，仍须另读任务合同，不能把它当作等价上下文或 token 节省比例。
|
||||
- 大规约：10 份 spec 标题盘点未发现重复二级标题；大文件主要由各场景合同累计形成。本轮增加定位指引，不凭文件大小删除场景或迁移历史链接。新增指引使部分文档略增，目录总大小没有作为优化目标。
|
||||
- AGENTS：6072 字节，现有核心条款已经覆盖按需读取、同范围不重复确认及风险验证。本轮保持原件，不增加 GPT-6 专属长规则，也不降低安全/审批要求。
|
||||
- Skills：盘点 12 个项目技能。5 个既有精简入口保留，其中 start/before-dev 进一步压缩；continue 补齐。官方 bundled meta/session-insight 的描述仍偏长（525/552 字符），保持上游来源，不把业务定制塞入公共目录。channel 等未触发时不加载正文；不因当前 inline 删除可选能力及其他工具可能依赖的全局技能。
|
||||
- 经验沉淀：采用“原章节维护稳定规则、task/evidence 保存当次事实”的方式；不再复制阶段路由或当次结果。既有 22 个未登记文档提示和旧 CSV 工具缺项不扩大为本轮清理。
|
||||
- 新会话：尝试新进程 skills/list 时 Codex CLI 不在 PATH，记 NOT_RUN；静态 frontmatter/引用/入口合同可验，但本会话目录缓存、实际选技和 token 用量未测。未安装新 CLI 或修改全局配置来弥补该缺项。
|
||||
- 独立复核：本轮上游 runtime/workflow 增量仍需独立只读 review；当前 inline 未派 implement/check 代理，记 PENDING。不能把历史 0.6.16 独立 PASS 移用于 0.6.17。
|
||||
|
||||
### 来源与现状
|
||||
|
||||
- npm latest/本机 CLI=0.6.17，项目=0.6.16；beta=0.7.0-beta.4，不纳入本轮。
|
||||
- 官方 v0.6.17 migration manifest：breaking=false、recommendMigrate=false、migrations=[]。修复缺少当前 session id 时误认其他会话任务、archive 中断时恢复子任务 parent；另更新 mem 与子代理上下文入口。无文件迁移。
|
||||
- 官方指南：https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra 、https://developers.openai.com/codex/skills/ 、https://developers.openai.com/codex/guides/agents-md/ 。已实际抓取正文。要点是精确触发、渐进读取、给出完成边界并避免重复确认，不据模型更强删除项目安全约束。
|
||||
- 基线：342 项 Git 状态条目；10 份 hyb-oa spec 共 679071 字节，workflow 42074 字节，AGENTS 6072 字节；46 份项目技能 Markdown 共 235792 字节。技能目录总大小并非默认注入量。
|
||||
- 既有归档升级经验已沉淀于 project-governance；本轮上下文足够，不读取无关原始会话或真实配置。
|
||||
|
||||
### 最小批次
|
||||
|
||||
1. 官方 update：只自动更新预览列出的 active_task.py、task_store.py、session-insight 的 SKILL/CLI reference、Codex inject-subagent-context.py。11 个本地冲突先生成 .new，再对照本轮备份/上游内容逐项处理；保留现有 task.py/task_context.py 的 inline 与 seed 合同、config、gitignore、workflow 和精简技能。不手改模板哈希，不 force。
|
||||
2. 读取入口：trellis-start 先查官方 current/source，trellis-continue 移除默认全量 get_context 和重复路由说明；before-dev 明确先定位章节再读完整相关合同。保留 PRD/计划批准、检查、独立 review 与提交授权边界。
|
||||
3. 经验整理：spec index 提供主题路由与大文档章节检索方式；project-governance 和 Agent 开发交付实践只补稳定读取/沉淀规则。workflow 的 no_task 口径与已有“复用/已授权”规则对齐；inline breadcrumb 明示相关章节和授权边界。保留阶段号和上游多平台参考，不做大规模拆分或搬迁历史经验。
|
||||
4. 本轮不改公共 bundled skills 的业务规则，不新建一套 GPT-6 专用技能，不改模型/推理强度/全局 Codex 设置。审查的全局技能仅限本会话已提供的元数据及任务相关正文；不宣称已审全部全局专业资源。
|
||||
|
||||
### 验证与回退
|
||||
|
||||
本轮证据根为 artifacts/qa-governance/trellis-0617-context-20260919；before/ 保存允许更新的原文件，protected-before.json/working-before.diff 保存 3070 路径状态及旧差异。执行官方 update 前已备份，dry-run 的潜在写入也纳入对照。
|
||||
|
||||
只运行 Trellis/规则定向回归与流程文档门禁，不因治理升级重跑 4437 后端、372 浏览器或恢复演练。session 绑定和 archive 回滚用临时合成任务验证，不归档真实任务。后置 dry-run 应无新自动更新，已明确的本地定制可以保留；清点本轮 .new/备份并收口，不删除旧证据。
|
||||
|
||||
失败时按 before/ 逐文件恢复本轮改动，必要时用固定 CLI 0.6.16 配套旧模板；不整树 reset/stash。高风险运行时变更的独立只读复核在当前 inline 限制下保留 PENDING，主会话测试不代替。
|
||||
|
||||
## 基线和证据
|
||||
|
||||
2026-09-05：全局 CLI 与项目模板均为 0.6.12；npm latest 为 0.6.16，beta 为 0.7.0-beta.3。Node.js 22.22.2 满足目标包要求，CLI 软链接目标与 npm 全局 prefix 一致。
|
||||
|
||||
@@ -1,5 +1,69 @@
|
||||
# 执行清单
|
||||
|
||||
## 知识精简独立静态复核接收（2026-09-19，最新）
|
||||
|
||||
- 已读取用户交回的 Claude 原报告 `artifacts/qa-governance/knowledge-pruning-claude-review-20260919T023533Z.txt`：本轮知识精简 **PASS，无必修项**。比较基线为本轮 before/ 与 incremental-review.diff，独立于 0.6.17 升级批次；仅覆盖指令与静态合同。
|
||||
- Reviewer 无 shell，以逐行内容比对核对12份输入，未运行命令或重算 SHA。接收前主会话另行重算 final-inputs.json 所列12份输入，全部匹配；这是主会话的输入完整性检查，不归为 reviewer 实测。本次接收仅追加 implement.md 和 task.json 的结果记录，不改受审技能、指南或 spec。
|
||||
- 唯一非必修建议按观察项保留：基础设施类示例若在实际执行中因缺失造成理解偏差，再评估收紧；当前没有该问题证据，不恢复强制模板。当前客户端刷新、真实用户配置下发现、模型实际选技及 token 节省仍未验证，原22份未登记文档提示保持。
|
||||
- 知识精简批次的独立指令/静态复核门禁已通过；原 final-inputs/final-checks 中的 PENDING 是交审时点记录，保留原件，以新增 review-reception-20260919 证据为后续状态。业务补审 b1rubx7qf 仍在外部进行，本结论不覆盖业务候选或其发布资格。
|
||||
- task 保持 review；历史 G1–G10 用户级复核欠项单列。不提交、推送、归档、部署或扩大精简范围。
|
||||
|
||||
## 自主经验维护批次（2026-09-19，最新）
|
||||
|
||||
用户已授权自主优化经验、skills 和 specs；范围/设计见同 task 顶部。原0.6.17独立PASS保持，本增量不冒用该结论。
|
||||
|
||||
- [x] 核对官方 current、技能/规约正文和实际调用者，保存12文件副本及3070路径保护基线。
|
||||
- [x] 精简三份技能，去掉固定教学模板、伪概率及未经授权提交/上游写入要求。
|
||||
- [x] 精简三份思考指南，修正重复即抽象/只校验一次等泛化规则。
|
||||
- [x] 合并证据规约重复示例，保留字段、状态、错误、测试与隐私合同。
|
||||
- [x] 完成契约保留核对、skill validator/引用/真实隔离发现、task/process/docs/governance/diff与保护检查。
|
||||
- [x] 记录增量、实际字节变化及独立行为复核限制；无提交、部署、全局配置或业务修改。
|
||||
|
||||
本轮完成情况：
|
||||
|
||||
- 三技能 brainstorm/break-loop/update-spec 共27717→6712字节（-75.8%）；三指南11892→4564（-61.6%）；证据规约/索引12879→11123（-13.6%）；8份文本合计52488→22399（-57.3%）。这些是文件字节，非实际token节省；本轮PRD/design/结果记录另计。
|
||||
- 将已授权范围自主推进写入当前规划语义，仍保留真实用户决策/批准和独立复核边界；删除机械七段式、泛化抽象阈值、概率表、擅自提交及跨项目模板写入要求。新经验应在原归属章节维护，不为每次修复增加长模板。
|
||||
- 12项主会话契约保留核对通过；docs-and-evidence的31个标题全部保留，无内部锚点破坏。三个skill-creator quick_validate均通过；引用/锚点、task/process/docs/Trellis敏感扫描/diff通过，22份既有未登记文档提示保留。
|
||||
- 现有Codex0.125.0在空白用户目录/禁网/项目只读隔离中真实skills/list(forceReload=true)：12个项目技能、0错误，本轮3个技能来源/描述/启用匹配。未读真实用户配置/密钥、未改HOME/CODEX_HOME、未启动模型turn；不证明真实客户端刷新、模型实际选技或独立行为评估。
|
||||
- 模板预览无自动待更新，14个本地定制提示符合预期（新增break-loop/update-spec，brainstorm原已定制）；模板哈希未改。此次只改变指令/规约，不重跑输入未变的50个runtime或4437/372业务全量。
|
||||
- 3070路径保护核验仅12个本轮允许文件变化；1076个r6业务输入及11个原始证据SHA保持，HEAD/index、runtime、workflow、AGENTS、全局/官方bundled skills不变。
|
||||
- 证据根artifacts/qa-governance/knowledge-pruning-20260919：size-comparison、contract-preservation-review、validation、isolated-skill-discovery、protection-check、incremental-review.diff及final-inputs。增量基线为本轮before/，旧交审包保持。主会话审阅/静态检查/真实发现分列，本轮新指令的独立行为复核未执行，旧Trellis独立PASS不抵扣；task保留review，不归档。
|
||||
|
||||
## 2026-09-19 Claude 复核接收与技能发现纠正（最新）
|
||||
|
||||
用户提供 Claude 独立只读报告：本轮 18 个受审路径全部覆盖，Trellis 升级/精简 PASS；其另跑既有回归 50/50 和上游探针 7/7。按用户提供的外部复核结果登记，未取得其 scratchpad 原始日志，不冒称主会话新跑或覆盖原证据。接收前主会话重新核对原 final-inputs.json，18 项均一致；以下仅补任务记录，不改受审 runtime/skills/spec。
|
||||
|
||||
- Claude 会话 current=none 是正确的会话隔离行为；本会话 current=本 task 不应被当作跨会话保证。
|
||||
- 更正原“找不到 Codex CLI”判断：npm 全局 prefix 下已有 0.125.0，仅不在当前 PATH。主会话已通过实际 --version、app-server 协议 schema 核实；该版本支持 skills/list 和 forceReload。Claude 对 mcp-server 调用返回 method not found，不能证明 app-server 不支持，不据此升级 CLI。
|
||||
- 已用现有 CLI 完成真正的新进程 app-server initialize/skills/list(forceReload=true)：12 个项目技能、0 个加载错误，start/continue/before-dev 来源和描述匹配。采用 bubblewrap 空白 Codex 用户目录、禁网、项目只读；HOME/CODEX_HOME 环境值未改，真实用户配置/凭据被挂载隔离，未修改全局文件或启动模型 turn。
|
||||
- 本项结论为 PASS_ISOLATED_HOME；真实用户配置下的发现、当前客户端刷新/选技、token 节省仍未验证。Claude 报告的全局 config 类型错误记外部观察，主会话未读取该文件，不直接采纳改全局配置/升级 CLI 的建议。
|
||||
- 本轮 Trellis 独立复核门禁可关；历史 G1–G10 全局技能完整复核及真实客户端限制继续单列，task 保持 review，不提交或归档。
|
||||
|
||||
新增证据：artifacts/qa-governance/trellis-0617-review-followup-20260919。原 final-checks、fresh-skill-discovery 的 NOT_RUN、交审 diff 和回执均保留，它们描述原检查时点；当前实际结果以新增证据为准。
|
||||
|
||||
## 当前批次：0.6.17 与上下文精简（2026-09-19）
|
||||
|
||||
按用户本轮升级和审查要求，续办既有稳定版升级、保留本地定制、按需加载与规则精简方案；最新具体边界见 PRD/设计顶部。历史独立提交/合入授权不用于本轮。
|
||||
|
||||
- [x] 官方 current/source、CLI/npm/项目版本、上游迁移清单及官方 GPT-6 指南核对。
|
||||
- [x] 核对既有治理任务、经验和技能入口，保存受管文件及旧差异保护基线；目标版 dry-run 完成。
|
||||
- [x] 官方保守更新并逐项处理 .new；保持 inline、关闭自动提交及 seed 加固。
|
||||
- [x] 收紧当前任务/规约读取入口，补主题路由与可复用经验的精简原则。
|
||||
- [x] 实际 Python 兼容、既有 Trellis 定向回归及新增上游行为的合成探针。
|
||||
- [x] task/context/hook、process/docs/governance/sensitive/diff、后置 dry-run 与任务外保护核验。
|
||||
- [x] 记录字节度量、实际覆盖、独立 review 和新会话限制，交付增量审查包。
|
||||
|
||||
本轮结果：
|
||||
|
||||
- CLI 和项目 0.6.17；5 个上游文件更新，11 个冲突保留定制，全部 .new 原件和官方自动备份移入本轮证据目录保存。后置 dry-run 无自动待更新项，12 个提示均为保留的本地定制（比升级前新增 continue 定制），模板哈希再次预览后未变。
|
||||
- Python 3.9.2 对 31 个 runtime/hook 文件实际编译通过；既有两文件回归 50/50 PASS。新增临时合成检查 7/7 PASS；同探针对升级前备份 4 FAIL / 3 PASS，保留负向日志。合成归档检查只证明子任务 parent 链恢复，上游失败时父任务仍标 completed 且留原处，不夸大为整项回滚。
|
||||
- task validate/current/list、phase、真实 hook 路由（既有回归）、process/docs/Trellis（含敏感扫描）及 diff 检查通过。文档登记仍有既有 22 项提示；历史 CSV 校验未运行，本轮未改 CSV。
|
||||
- 3070 路径保护基线仅 18 个本轮允许路径变化；业务代码、旧任务、HEAD/index 保持。r6 的 1076 个代码输入及 11 个已有原始证据文件 SHA 复核保持；当前新增治理/spec/文档变化不被旧发布回执覆盖，deploymentEligible=false。
|
||||
- 字节度量见 size-review.json；来源、冲突、升级日志、探针及旧证据核验均在本轮证据根。incremental-review.diff 以本轮 before/ 为基线，不使用 HEAD 混入 342 项旧差异。
|
||||
- 本地实施与可执行检查完成，任务回到 review。独立复核 PENDING；新进程技能发现 NOT_RUN（缺少 Codex CLI），当前客户端实际刷新/选技未验证。未提交、推送、归档、部署、启用编号或更新其他工作树。
|
||||
|
||||
当前无业务实施、提交、推送、归档、部署或生产操作。原官方 current 为 09-06-release-gate-integrity，原任务及回执状态保留，治理续办用本 task。
|
||||
|
||||
## 授权与阶段
|
||||
|
||||
用户已审阅落盘方案并批准 CLI 升级与项目只读预览，随后于 2026-09-05 批准本文件第二阶段四个补丁批次。任务为 in_progress，按该范围实施并验证，不重复申请同一授权；提交、归档、部署与业务修改仍未授权。
|
||||
|
||||
@@ -1,5 +1,37 @@
|
||||
# Trellis 升级与规则精简
|
||||
|
||||
## 经验维护自主优化授权（2026-09-19，最新）
|
||||
|
||||
用户明确授权主会话自主决定经验、skill、spec 的优化改进或精简。本轮在既有治理任务中维护项目技能/思考指南/经验规则，无需逐份文本再次确认；不扩展为业务变更、验收降级、全局配置修改、提交部署或旧证据删除。
|
||||
|
||||
- M1：压缩 brainstorm/break-loop/update-spec 的重复教程与机械模板，保留规划批准、证据与明确的不变量；消除未经授权提交、修改上游模板、强制猜概率等错误指令。
|
||||
- M2：精简项目思考指南，按共享契约风险决定复用和跨层验证；保留服务端信任边界与事务内必要重验，避免“只校验一次”等泛化误导。
|
||||
- M3：经验沉淀按事实归属更新已有章节，不默认新增七段式案例；精简证据说明的重复示例，保留历史证据和全部可执行门禁。
|
||||
- M4：提供本轮增量、字节变化、技能真实发现和治理检查；静态/加载验证不冒充模型行为评估或独立审阅。原升级独立 PASS 不覆盖本轮新技能修改。
|
||||
|
||||
本轮验收：
|
||||
|
||||
- [x] 三份技能与三份指南精简完成，关键契约有保留映射。
|
||||
- [x] 证据规约重复说明压缩，原状态、错误和验证边界保持。
|
||||
- [x] skill frontmatter/引用、真实隔离发现、task/process/docs/governance/diff 与任务外保护核验通过。
|
||||
- [x] 当前结果、外部复核范围、未验证部分如实交接；未修改业务代码、全局配置或原回执。
|
||||
|
||||
## 本轮续办（2026-09-19）
|
||||
|
||||
用户要求现在升级 Trellis、按官方指南更新相关文件，并审查既有经验和 skills，结合 GPT-6 减少上下文消耗。本轮复用该任务的稳定版升级、保留定制、按需读取与规则精简范围；下文 0.6.16 和历史提交授权只说明历史，不沿用为本轮提交授权。
|
||||
|
||||
- R5：CLI 已为 npm latest 0.6.17，将执行树的 0.6.16 模板保守升级到 0.6.17；不选 beta，不重装已匹配 CLI。
|
||||
- R6：以官方 GPT-6 Astra 和 Codex skills 文档为依据，审查重复入口、过宽触发及大文档读取；改进项目内的读取路由，保留既有合同与历史经验。
|
||||
- R7：量化文档/入口字节和读取路径变化；静态字节不是模型实际 token 节省，不虚报新会话行为。
|
||||
- 边界：仅指定执行树。保留所有业务差异、冻结包、回执及旧失败；不读真实配置/密钥/备份，不改用户级技能或其他工作树，不提交、推送、归档、部署或启用生产编号。历史全局技能独立复核欠项保持。
|
||||
|
||||
本轮验收：
|
||||
|
||||
- [x] A17：项目和 CLI 均为 0.6.17，官方迁移清单/更新预览/冲突处理留证，定制与 inline/禁止自动提交保持。
|
||||
- [x] A18：续办/开发入口按需读当前任务与相关章节，经验原文和引用可用；未将模型能力当作权限或验收豁免。
|
||||
- [x] A19：Python 实际运行时、Trellis 定向回归、task/context/hook、process/docs/governance/diff 检查及任务外保护核验完成。
|
||||
- [x] A20：精简收益、未实施建议、独立复核和新会话验证状态分别记录；不复用旧业务回执证明新整树发布资格。
|
||||
|
||||
## Goal
|
||||
|
||||
先完成全局 Trellis CLI 稳定版升级与当前项目只读更新预览，再提出按来源、任务和风险分层的规则精简方案。全局只做一轮，项目分别处理，不因模型升级直接删除必要保障。
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
"id": "trellis-upgrade-rule-cleanup",
|
||||
"name": "trellis-upgrade-rule-cleanup",
|
||||
"title": "Trellis 升级与规则精简",
|
||||
"description": "全局 CLI 与项目模板升级至 0.6.16，适配 inline 并精简已批准的项目及用户级规则，不涉及业务代码。",
|
||||
"description": "续办 Trellis 0.6.17 项目升级与上下文精简，保留 0.6.16 历史结果和未完独立复核。",
|
||||
"status": "review",
|
||||
"dev_type": null,
|
||||
"scope": "workflow-governance",
|
||||
@@ -22,5 +22,66 @@
|
||||
"parent": null,
|
||||
"relatedFiles": [],
|
||||
"notes": "2026-09-06 原项目升级及 seed 增量均经用户独立复核 PASS；TR-01 是遗留宽松的后续加固，不是升级回归。独立重现 50/50 绿与旧判定 9 红/41 绿，确认增量 6 变/42 不变；main 历史 138 行 seed 全为纯 marker。已补 hook/validator 不对称及诊断差异规约，用户明确授权本次项目升级独立提交并合入 main，执行结果以 Git 历史为准。不 push、归档或部署；保留 review 和空 completedAt，不将未覆盖的 G1–G10 用户级全量独立复核算作通过。",
|
||||
"meta": {}
|
||||
"meta": {
|
||||
"upgrade0617": {
|
||||
"status": "local_complete_independent_review_pass",
|
||||
"scope": "execution-tree-only",
|
||||
"cliVersion": "0.6.17",
|
||||
"originalProjectVersion": "0.6.16",
|
||||
"independentReview": "PASS_USER_PROVIDED_CLAUDE_REPORT",
|
||||
"commitAuthorized": false,
|
||||
"deploymentAuthorized": false,
|
||||
"projectVersion": "0.6.17",
|
||||
"runtimeTests": {
|
||||
"passed": 50
|
||||
},
|
||||
"syntheticProbes": {
|
||||
"passed": 7,
|
||||
"priorVersionExpectedFailures": 4
|
||||
},
|
||||
"freshSkillDiscovery": "PASS_ISOLATED_HOME",
|
||||
"currentClientReloadVerified": false,
|
||||
"entryBytes": {
|
||||
"before": 5411,
|
||||
"after": 3981
|
||||
},
|
||||
"evidence": "artifacts/qa-governance/trellis-0617-context-20260919",
|
||||
"deploymentEligible": false,
|
||||
"reviewerRawLogsObtained": false,
|
||||
"realUserConfigDiscoveryVerified": false,
|
||||
"followupEvidence": "artifacts/qa-governance/trellis-0617-review-followup-20260919"
|
||||
},
|
||||
"knowledgePruning20260919": {
|
||||
"authorization": "user_explicit_autonomous_knowledge_maintenance",
|
||||
"status": "local_complete_independent_static_review_pass",
|
||||
"evidence": "artifacts/qa-governance/knowledge-pruning-20260919",
|
||||
"independentReview": "PASS_CLAUDE_STATIC_CONTENT_REVIEW",
|
||||
"independentReviewReport": "artifacts/qa-governance/knowledge-pruning-claude-review-20260919T023533Z.txt",
|
||||
"independentReviewReportSha256": "141a2fe798e6461e962ae8af9b23be309e1e19eabf90b6010d464e8b2e60b192",
|
||||
"reviewerCommandsRun": false,
|
||||
"reviewerShaRecomputed": false,
|
||||
"reviewerInputVerification": "12 files compared by content",
|
||||
"mainSessionPreReceptionInputShaMatches": 12,
|
||||
"mandatoryReviewFindings": 0,
|
||||
"reviewFollowupEvidence": "artifacts/qa-governance/knowledge-pruning-20260919/review-reception-20260919",
|
||||
"optionalObservation": "Reassess infrastructure example requirements only if actual use shows missing examples cause misunderstanding; no instruction change now.",
|
||||
"businessChangesAuthorized": false,
|
||||
"mainSessionContractReview": "PASS",
|
||||
"staticValidation": "PASS",
|
||||
"isolatedSkillDiscovery": "PASS",
|
||||
"skillBytes": {
|
||||
"before": 27717,
|
||||
"after": 6712
|
||||
},
|
||||
"eightDocumentBytes": {
|
||||
"before": 52488,
|
||||
"after": 22399
|
||||
},
|
||||
"tokenSavingsMeasured": false,
|
||||
"currentClientRefreshVerified": false,
|
||||
"realUserConfigDiscoveryVerified": false,
|
||||
"modelSkillSelectionVerified": false,
|
||||
"historicalEvidencePreserved": true
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
+4
-4
@@ -203,9 +203,9 @@ Create new children with `task.py create "<title>" --slug <name> --parent <paren
|
||||
<!-- Per-turn breadcrumb: shown when there is no active task (before Phase 1) -->
|
||||
|
||||
[workflow-state:no_task]
|
||||
No active task. First classify the current turn and ask for task-creation consent before creating any Trellis task.
|
||||
No active task pointer. First classify the turn and inspect directly related tasks; a missing pointer does not mean no suitable task exists.
|
||||
Pure consultation or a small isolated edit: respond or execute within scope without asking to create a task.
|
||||
Complex task: ask the user if you can create a Trellis task and enter the planning phase. If the user says no, explain, clarify scope, or suggest a smaller split.
|
||||
Reuse a suitable task and activate already approved work with the official task command. New scope still needs review; ask for task creation only when no suitable owner exists and creation is not already authorized.
|
||||
[/workflow-state:no_task]
|
||||
|
||||
<!-- Per-turn breadcrumb: shown when the active task record cannot be read. -->
|
||||
@@ -272,9 +272,9 @@ Dispatch prompt starts with `Active task: <task path from task.py current>`. Rea
|
||||
instead of dispatching sub-agents. -->
|
||||
|
||||
[workflow-state:in_progress-inline]
|
||||
Flow: `trellis-before-dev` -> edit -> `trellis-check` -> validation -> `trellis-update-spec` -> commit (Phase 3.4) -> `/trellis:finish-work`.
|
||||
Flow: `trellis-before-dev` -> edit -> `trellis-check` -> validation -> reusable spec update when needed -> authorized commit (Phase 3.4) -> requested finish-work.
|
||||
Do not dispatch implement/check sub-agents in inline mode.
|
||||
Read context: `prd.md` -> `design.md if present` -> `implement.md if present`, plus relevant spec/research loaded by skills.
|
||||
Read the current PRD, applicable design decisions and latest implementation status; load relevant spec sections and reuse unchanged context. Continue approved work through its checks. Independent review remains a separate gate; commit, push, archive and production actions require their existing explicit authorization.
|
||||
[/workflow-state:in_progress-inline]
|
||||
|
||||
### Phase 3: Finish
|
||||
|
||||
@@ -7,6 +7,7 @@
|
||||
- OpenAI How OpenAI uses Codex: https://openai.com/business/guides-and-resources/how-openai-uses-codex/
|
||||
- OpenAI Codex AGENTS.md: https://developers.openai.com/codex/guides/agents-md
|
||||
- OpenAI Codex Skills: https://developers.openai.com/codex/skills/
|
||||
- OpenAI GPT-6 Astra skills/prompt 精简指南：https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra
|
||||
- OpenAI Codex Automations: https://openai.com/academy/codex-automations/
|
||||
- OpenAI Agents 文档: https://platform.openai.com/docs/guides/agents
|
||||
- OpenAI Evals 文档: https://platform.openai.com/docs/guides/evals
|
||||
@@ -16,6 +17,16 @@
|
||||
|
||||
## 本项目采用的原则
|
||||
|
||||
### 上下文使用（2026-09-19）
|
||||
|
||||
当前采用 GPT-6 时，仍以项目合同决定权限和完成标准；模型能力提升不代替业务验收或独立复核。按官方指南采用渐进读取：技能描述只说明准确触发范围，正文作为短入口，详细步骤和经验按需查阅。
|
||||
|
||||
- 当前任务不明时先用 `task.py current --source`，需要更广会话状态才运行完整 `get_context.py`。续办先读当前要求、最新状态与未完项；不默认加载全部历史任务或原始会话。
|
||||
- 大 spec 先查目录/标题，再读通用规则、相关完整场景和必要引用；跨层时扩展。已加载且未变化的内容不重复读取。入口见 `.trellis/spec/hyb-oa/index.md`。
|
||||
- 稳定经验更新原归属章节；当次测试数量、时间、候选资格及失败记录留在任务/证据。避免每次复盘追加一份同义模板，不为精简删除历史原件。
|
||||
- 已批准范围连续实施到约定验证完成；变更范围、风险或验收才重新确认。按变更选择测试，未变输入可复用已有结果；生产操作和提交/归档继续单独授权。
|
||||
- 技能目录总字节不等于默认注入量，文本缩短不等于已测 token 节省。新会话加载、模型实际选技和端到端表现需分别验证；不据静态检查宣称已生效。
|
||||
|
||||
### 0. TRELLIS2 后以官方 Trellis task 为执行合同
|
||||
|
||||
TRELLIS2 起，hyb-oa 的后续非微小开发默认从 `.trellis/tasks/` 进入，由 task 目录本身承载需求、计划、实施、检查和复盘。
|
||||
|
||||
在新工单中引用
屏蔽一个用户