升级Trellis并精简项目知识（09-05-trellis-upgrade-rule-cleanup）
更新Trellis适配、任务归属与归档失败恢复，精简技能入口和知识读取规则。 保留权限、证据、事务及独立复核合同；纳入对应任务及已完成复核记录。 仅本地提交，不启用新平台适配，不推送或部署。
这个提交包含在：
@@ -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
|
||||
|
||||
在新工单中引用
屏蔽一个用户