refactor(team): add fast-advance notification and knowledge transfer protocol

- team-worker: add fast_advance message bus log after spawning successor,
  closing coordinator state blind spot during fast-advance
- team-worker: add Knowledge Transfer section with upstream loading,
  downstream publishing, and context_accumulator conventions
- role-spec-template: add Knowledge Transfer Protocol with Transfer
  Channels table and shared-memory.json namespaced write convention
- monitor.md (v2+v5): add fast-advance reconciliation step reading
  fast_advance messages, add State Sync section for coordinator wake
- lifecycle-v5 SKILL.md: update cadence diagram with fast_advance log
This commit is contained in:
catlog22
2026-02-28 22:53:56 +08:00
parent 67b2129f3c
commit e42597b1bc
4 changed files with 101 additions and 2 deletions

View File

@@ -404,6 +404,48 @@ Write discoveries to corresponding wisdom files:
--- ---
## Knowledge Transfer
### Upstream Context Loading (Phase 2)
When executing Phase 2 of a role-spec, the worker MUST load available cross-role context:
| Source | Path | Load Method |
|--------|------|-------------|
| Upstream artifacts | `<session>/artifacts/*.md` | Read files listed in task description or dependency chain |
| Shared memory | `<session>/shared-memory.json` | Read and parse JSON |
| Wisdom | `<session>/wisdom/*.md` | Read all wisdom files |
| Exploration cache | `<session>/explorations/cache-index.json` | Check before new explorations |
### Downstream Context Publishing (Phase 4)
After Phase 4 verification, the worker MUST publish its contributions:
1. **Artifact**: Write deliverable to `<session>/artifacts/<prefix>-<task-id>-<name>.md`
2. **shared-memory.json**: Read-merge-write under role namespace
```json
{ "<role>": { "key_findings": [...], "decisions": [...], "files_modified": [...] } }
```
3. **Wisdom**: Append new patterns to `learnings.md`, decisions to `decisions.md`, issues to `issues.md`
### Inner Loop Context Accumulator
For `inner_loop: true` roles, `context_accumulator` is maintained in-memory:
```
context_accumulator.append({
task: "<task-id>",
artifact: "<output-path>",
key_decisions: [...],
summary: "<brief>",
files_modified: [...]
})
```
Pass the full accumulator to each subsequent task's Phase 3 subagent as `## Prior Context`.
---
## Message Bus Protocol ## Message Bus Protocol
Always use `mcp__ccw-tools__team_msg` for logging. Parameters: Always use `mcp__ccw-tools__team_msg` for logging. Parameters:

View File

@@ -134,3 +134,46 @@ Coordinator MAY reference these patterns when composing Phase 2-4 content for a
- Phase 2: Detect test framework + identify changed files from upstream - Phase 2: Detect test framework + identify changed files from upstream
- Phase 3: Run test-fix cycle — iteration count and strategy determined by task - Phase 3: Run test-fix cycle — iteration count and strategy determined by task
- Phase 4: Verify pass rate + coverage (Behavioral Traits) + update shared-memory - Phase 4: Verify pass rate + coverage (Behavioral Traits) + update shared-memory
---
## Knowledge Transfer Protocol
How context flows between roles. Coordinator MUST reference this when composing Phase 2 of any role-spec.
### Transfer Channels
| Channel | Scope | Mechanism | When to Use |
|---------|-------|-----------|-------------|
| **Artifacts** | Producer -> Consumer | Write to `<session>/artifacts/<name>.md`, consumer reads in Phase 2 | Structured deliverables (reports, plans, specs) |
| **shared-memory.json** | Cross-role | Read-merge-write `<session>/shared-memory.json` | Key findings, decisions, metadata (small, structured data) |
| **Wisdom** | Cross-task | Append to `<session>/wisdom/{learnings,decisions,conventions,issues}.md` | Patterns, conventions, risks discovered during execution |
| **context_accumulator** | Intra-role (inner loop) | In-memory array, passed to each subsequent task in same-prefix loop | Prior task summaries within same role's inner loop |
| **Exploration cache** | Cross-role | `<session>/explorations/cache-index.json` + per-angle JSON | Codebase discovery results, prevents duplicate exploration |
### Phase 2 Context Loading (role-spec must specify)
Every generated role-spec Phase 2 MUST declare which upstream sources to load:
```
1. Extract session path from task description
2. Read upstream artifacts: <list which artifacts from which upstream role>
3. Read shared-memory.json for cross-role decisions
4. Load wisdom files for accumulated knowledge
5. For inner_loop roles: load context_accumulator from prior tasks
6. Check exploration cache before running new explorations
```
### shared-memory.json Usage Convention
- **Read-merge-write**: Read current content -> merge new keys -> write back (NOT overwrite)
- **Namespaced keys**: Each role writes under its own namespace: `{ "<role_name>": { ... } }`
- **Small data only**: Key findings, decision summaries, metadata. NOT full documents
- **Example**:
```json
{
"researcher": { "key_findings": [...], "scope": "..." },
"writer": { "documents_created": [...], "style_decisions": [...] },
"developer": { "files_changed": [...], "patterns_used": [...] }
}
```

View File

@@ -192,7 +192,9 @@ Beat Cycle (single beat)
Fast-Advance (skips coordinator for simple linear successors) Fast-Advance (skips coordinator for simple linear successors)
====================================================================== ======================================================================
[Worker A] Phase 5 complete [Worker A] Phase 5 complete
+- 1 ready task? simple successor? --> spawn team-worker B directly +- 1 ready task? simple successor?
| --> spawn team-worker B directly
| --> log fast_advance to message bus (coordinator syncs on next wake)
+- complex case? --> SendMessage to coordinator +- complex case? --> SendMessage to coordinator
====================================================================== ======================================================================
``` ```

View File

@@ -59,7 +59,12 @@ Receive callback from [<role>]
+- None completed -> STOP +- None completed -> STOP
``` ```
**Fast-advance awareness**: Check if next task is already `in_progress` (fast-advanced by worker). If yes -> skip spawning, update active_workers. **Fast-advance reconciliation**: When processing any callback or resume:
1. Read recent `fast_advance` messages from team_msg (type="fast_advance")
2. For each: add spawned successor to `active_workers` if not already present
3. Check if expected next task is already `in_progress` (fast-advanced)
4. If yes -> skip spawning (already running)
5. If no -> normal handleSpawnNext
--- ---
@@ -205,6 +210,13 @@ Detect orphaned in_progress task (no active_worker):
+- Reset to pending -> handleSpawnNext +- Reset to pending -> handleSpawnNext
``` ```
### Fast-Advance State Sync
On every coordinator wake (handleCallback, handleResume, handleCheck):
1. Read team_msg entries with `type="fast_advance"` since last coordinator wake
2. For each entry: sync `active_workers` with the spawned successor
3. This ensures coordinator's state reflects fast-advance decisions even before the successor's callback arrives
### Consensus-Blocked Handling ### Consensus-Blocked Handling
``` ```