tl-next

/nacl:tl-next -- Graph-Aware Next Task Recommendation

Purpose

Graph-powered replacement for /nacl:tl-next. Queries Task and Wave nodes from Neo4j to recommend the optimal next task, enriched with UC entity names and form names from the SA layer. Falls back to .tl/status.json + master-plan.md when Neo4j is unavailable.

Critical difference from nacl-tl-next:

Aspect	nacl-tl-next	nacl-tl-next
Data source	.tl/status.json + master-plan.md	Neo4j Task/Wave nodes (primary)
Enrichment	Task title only	UC entity names, form names from SA layer
Scoring	File-based computation	tl_task_scoring Cypher query
Candidate list	Parsed from JSON	tl_actionable_tasks Cypher query
Fallback	None	.tl/status.json + master-plan.md

Shared references: ${CLAUDE_PLUGIN_ROOT}/nacl-core/SKILL.md

---

Your Role

• Query Neo4j for Task/Wave nodes, actionable candidates, and scoring
• Enrich recommendations with UC entity names, form names via tl_task_with_uc_context
• Identify the active wave via tl_active_wave query
• Analyze phase dependencies within each UC (BE -> review -> FE -> review -> sync -> stubs -> QA)
• Filter blocked tasks based on wave boundaries and cross-task dependencies
• Recommend a single action with phase-aware rationale and launch command
• Show parallel opportunities when multiple tasks are actionable
• Fall back to file-based mode if Neo4j is unreachable

Key Principle: Actionable Recommendation

CRITICAL: Always provide ONE clear recommendation with a launch command.

1. Single choice:    One task, not a list (unless --list flag)
2. Phase-aware:      Right phase for the UC lifecycle
3. Wave-aware:       Respect wave boundaries and parallelism
4. Unblocked:        No pending dependencies
5. Ready to start:   Immediate action command
6. Enriched:         UC entity/form context from SA layer

---

Neo4j Tools

Tool	Usage
mcp__neo4j__read-cypher	Read Task/Wave nodes, run scoring and actionable queries
mcp__neo4j__get-schema	Verify TL layer exists in graph

---

Invocation

/nacl:tl-next [flags]

Filtering Flags

/nacl:tl-next --be        # Only BE development tasks
/nacl:tl-next --fe        # Only FE development tasks
/nacl:tl-next --tech      # Only TECH tasks
/nacl:tl-next --review    # Only review tasks (BE or FE)
/nacl:tl-next --sync      # Only sync verification tasks
/nacl:tl-next --qa        # Only QA testing tasks
/nacl:tl-next --wave N    # Only tasks from wave N
/nacl:tl-next --list      # Show top 5 candidates with scores

---

Pre-Check Requirements

Before recommending, verify:

1. Neo4j reachable: Try mcp__neo4j__read-cypher with tl_active_wave query
2. TL layer exists: Task and Wave nodes present in graph
3. Tasks available: At least one actionable task exists

Decision: Graph or Fallback

Try Neo4j query (tl_active_wave)
  |
  +-- Success + results -> GRAPH MODE
  |
  +-- Connection error OR empty results -> FALLBACK MODE
      |
      +-- Check .tl/status.json exists
      |     +-- Yes -> file-based recommendation (same as nacl-tl-next)
      |     +-- No  -> error: "Project not initialized"

If falling back:

Note: Neo4j unavailable, using file-based fallback.
Recommendations based on .tl/status.json + master-plan.md.
Enrichment (entity/form names) unavailable in fallback mode.

Remote mode (multi-user shared graph): the FALLBACK path above is local mode only. When config.yaml graph.mode: remote (one shared graph, several developers), the .tl/status.json fallback is disabled — a per-clone cache cannot represent shared state. If Neo4j is unreachable, HALT with a clear message rather than recommend from stale local data. Additionally, in remote mode the recommendation is claim-first: first resolve the per-machine id with NACL_DEVELOPER_ID="$(node ${CLAUDE_PLUGIN_ROOT}/nacl-core/scripts/resolve-developer-id.mjs --project-root .)" (auto <git email|user>/<machine-key>, so one human on two machines never self-collides), then before presenting a task, claim it atomically with node ${CLAUDE_PLUGIN_ROOT}/nacl-core/scripts/claim-task.mjs claim --task <id> --dev "$NACL_DEVELOPER_ID" (run the emitted Cypher via mcp__neo4j__write-cypher). If the returned owner ≠ you, another developer holds it — skip to the next candidate. See ${CLAUDE_PLUGIN_ROOT}/nacl-tl-core/references/remote-mode-coordination.md.

---

Workflow -- Graph Mode

Step 1: Determine Active Wave

Run tl_active_wave from graph-infra/queries/tl-queries.cypher:

// tl_active_wave
MATCH (t:Task)-[:IN_WAVE]->(w:Wave)
WHERE t.status <> 'done'
RETURN w.number AS active_wave, count(t) AS remaining_tasks
ORDER BY w.number
LIMIT 1

If no results: all tasks are complete -- show completion message.

Step 2: Get Actionable Tasks

Run tl_actionable_tasks from graph-infra/queries/tl-queries.cypher:

// tl_actionable_tasks
MATCH (t:Task)
WHERE t.status IN ['todo', 'pending']
AND NOT EXISTS {
  MATCH (t)-[:DEPENDS_ON]->(dep:Task) WHERE dep.status <> 'done'
}
OPTIONAL MATCH (t)-[:IN_WAVE]->(w:Wave)
RETURN t.id AS task_id, t.title AS title, t.status AS status,
       w.number AS wave, t.priority AS priority
ORDER BY w.number, t.priority

Apply filter flags to the result set:

• --be: keep only tasks where t.type = 'be'
• --fe: keep only tasks where t.type = 'fe'
• --tech: keep only tasks where t.type = 'tech'
• --review: keep only tasks where phase is *-review-pending
• --sync: keep only tasks where phase is sync-pending
• --qa: keep only tasks where phase is qa-pending
• --wave N: keep only tasks in wave N

Step 3: Score and Rank Candidates

Run tl_task_scoring from graph-infra/queries/tl-queries.cypher:

// tl_task_scoring
MATCH (t:Task)-[:IN_WAVE]->(w:Wave)
WHERE t.status IN ['todo', 'pending']
AND NOT EXISTS {
  MATCH (t)-[:DEPENDS_ON]->(dep:Task) WHERE dep.status <> 'done'
}
WITH t, w,
     CASE t.priority
       WHEN 'critical' THEN 40
       WHEN 'high' THEN 30
       WHEN 'medium' THEN 20
       WHEN 'low' THEN 10
       ELSE 15
     END AS priority_score,
     CASE WHEN w.number = 0 THEN 20 ELSE 10.0 / w.number END AS wave_score
OPTIONAL MATCH (other:Task)-[:DEPENDS_ON]->(t) WHERE other.status <> 'done'
WITH t, w, priority_score, wave_score,
     count(other) AS blocks_count
RETURN t.id AS task_id, t.title AS title, w.number AS wave,
       t.priority AS priority,
       priority_score + wave_score + (blocks_count * 5) AS total_score
ORDER BY total_score DESC
LIMIT 5

Then apply the full composite scoring formula on the client side using the Cypher result plus additional phase information:

score = priority_weight
      + status_order_weight
      + wave_bonus
      + dependency_bonus
      + phase_completion_bonus
      - age_penalty

Component	Calculation	Description
priority_weight	critical=100, high=75, medium=50, low=25	Task-level priority
status_order_weight	QA=70, sync=60, review=50, stubs=45, fe=30, be=20, tech=10	Phases closer to done score higher
wave_bonus	+20 if in current active wave	Prefer current wave
dependency_bonus	blocks_count * 10	Tasks that unblock others
phase_completion_bonus	+15 if UC has 4+ phases complete	Finish what is started
age_penalty	min(days_since_created * 0.5, 10)	Slight preference for newer tasks

Step 4: Enrich Top Candidate with SA Context

For the highest-scoring task, run tl_task_with_uc_context from graph-infra/queries/tl-queries.cypher:

// tl_task_with_uc_context($taskId)
MATCH (t:Task {id: $taskId})
OPTIONAL MATCH (uc:UseCase)-[:GENERATES]->(t)
OPTIONAL MATCH (uc)-[:USES_FORM]->(f:Form)
OPTIONAL MATCH (uc)-[:HAS_STEP]->(as_step:ActivityStep)
OPTIONAL MATCH (f)-[:HAS_FIELD]->(ff:FormField)-[:MAPS_TO]->(da:DomainAttribute)<-[:HAS_ATTRIBUTE]-(de:DomainEntity)
RETURN t, uc,
       collect(DISTINCT f.name) AS form_names,
       collect(DISTINCT de.name) AS entity_names,
       count(DISTINCT as_step) AS step_count

This provides:

• form_names: UI forms the task touches (e.g., "OrderForm", "FilterPanel")
• entity_names: Domain entities involved (e.g., "Order", "OrderItem", "Customer")
• step_count: Number of activity steps (complexity indicator)

Step 5: Get Wave Progress Context

Run tl_progress_by_wave for the active wave and adjacent waves:

// tl_progress_by_wave
MATCH (t:Task)-[:IN_WAVE]->(w:Wave)
RETURN w.number AS wave,
       count(t) AS total,
       count(CASE WHEN t.status = 'done' THEN 1 END) AS done,
       count(CASE WHEN t.status = 'in_progress' THEN 1 END) AS in_progress,
       count(CASE WHEN t.status IN ['todo', 'pending'] THEN 1 END) AS pending,
       CASE WHEN count(t) > 0
         THEN round(100.0 * count(CASE WHEN t.status = 'done' THEN 1 END) / count(t))
         ELSE 0 END AS progress_pct
ORDER BY w.number

Step 6: Get Blocked Tasks for "Upcoming" Section

Run tl_blocked_tasks:

// tl_blocked_tasks
MATCH (t:Task)-[:DEPENDS_ON]->(dep:Task)
WHERE dep.status <> 'done'
RETURN t.id AS blocked_task, t.title AS blocked_title, t.status AS blocked_status,
       dep.id AS blocking_task, dep.title AS blocking_title, dep.status AS blocking_status

Step 7: Select and Present

Pick the single highest-scoring candidate. Present with full wave context, phase context, SA enrichment, parallel opportunities, and upcoming blockers.

---

Phase Action Priority Table

Priority	Phase	Condition	Command
0 (highest)	delivery pending	every relevant Task is status: done AND last-fix Status: is in PASS-family (PASS or operator-accepted BLOCKED)	/nacl:tl-deliver or /nacl:tl-conductor
1	QA pending	sync passed + stubs clean	/nacl:tl-qa UC###
2	sync pending	BE approved + FE approved	/nacl:tl-sync UC###
3	review-fe pending	FE dev complete	/nacl:tl-review UC### --fe
4	review-be pending	BE dev complete	/nacl:tl-review UC### --be
5	stubs pending	dev complete (any type)	/nacl:tl-stubs UC###
6	fe pending	BE approved + api-contract exists	/nacl:tl-dev-fe UC###
7	be pending	wave dependencies met	/nacl:tl-dev-be UC###
8	tech pending	wave dependencies met	/nacl:tl-dev TECH###

Priority 0 (/nacl:tl-deliver) recommendation rule

Recommend /nacl:tl-deliver ONLY when both conditions hold for every relevant Task:

1. Task.status == 'done', AND
2. The most recent fix/dev Status: line for that Task is PASS (or BLOCKED with a recorded operator acceptance).

Do NOT recommend /nacl:tl-deliver as a normal next step when any relevant Task is in any of these states — instead, surface a prominent warning block:

• verification_status == 'verified-pending'
• Task.status == 'blocked'
• last-fix Status: is UNVERIFIED, NO_INFRA, RUNNER_BROKEN, or REGRESSION

Warning block format:

[!! UNVERIFIED DELIVERY — NOT RECOMMENDED]

Task UC### has status `verified-pending` (or last fix Status: UNVERIFIED).

This task ships in unverified state — not recommended.

To unblock:
  - Run /nacl:tl-verify UC### or /nacl:tl-qa UC### to obtain PASS evidence, OR
  - Acknowledge unverified delivery via the explicit operator override on
    /nacl:tl-deliver itself (this skill will not recommend that path).

Suggested alternative next step: <next non-blocked Task from the priority
table>.

The warning block replaces the normal recommendation card; it does not appear alongside one. /nacl:tl-deliver is never silently recommended for unverified or blocked work.

---

Dependency Rules

TECH tasks (Wave 0):
  Must complete before Wave 1 tasks can start.

For each UC (within and across waves):
  BE dev -> BE review -> (api-contract must exist) -> FE dev
  FE dev -> FE review -> Sync check -> Stub scan -> QA test -> Done

Cross-UC:
  Tasks in the same wave can run in parallel.
  Tasks in later waves are blocked until previous wave completes.

Exception -- cross-wave phase unlock:
  If a UC's BE is approved and api-contract exists, the FE task
  for that UC CAN start even if it belongs to a later wave.
  Shown in "Also ready" section, not as primary recommendation.

---

UC Lifecycle Phases

Each UC goes through these phases in strict order:

Phase 1: BE Development     -> nacl-tl-dev-be UC###
Phase 2: BE Review          -> nacl-tl-review UC### --be
Phase 3: FE Development     -> nacl-tl-dev-fe UC### (requires BE approved + api-contract)
Phase 4: FE Review          -> nacl-tl-review UC### --fe
Phase 5: Sync Verification  -> nacl-tl-sync UC###   (requires BE + FE approved)
Phase 6: Stub Scan          -> nacl-tl-stubs UC###  (requires sync passed)
Phase 7: QA Testing         -> nacl-tl-qa UC###     (requires stubs clean)
Phase 8: Done

TECH Task Lifecycle

Phase 1: Development        -> nacl-tl-dev TECH###
Phase 2: Review             -> nacl-tl-review TECH### --be  (TECH reviewed as BE)
Phase 3: Done

---

Output Format

Standard Recommendation (Graph Mode)

===============================================================
                         NEXT TASK
===============================================================

  UC003: Delete Order -- Backend Development

Wave:        2 (Core Frontend + Next BE)
Phase:       BE Development
Priority:    high
Estimated:   2 hours

Entities:    Order, OrderItem, AuditLog
Forms:       DeleteConfirmationDialog
Steps:       6 activity steps

Description:
Implement backend API for order deletion with soft-delete
pattern and cascade handling.

Why this task:
  * Highest priority pending task in current wave
  * Unblocks UC003-FE in Wave 3
  * No dependencies (UC001-BE, UC002-BE already done)
  * Touches 3 domain entities (Order, OrderItem, AuditLog)

---------------------------------------------------------------

  Start now:
   /nacl:tl-dev-be UC003

---------------------------------------------------------------

Also ready (can run in parallel):
  * UC001-FE: Frontend development (/nacl:tl-dev-fe UC001)
    Wave 2, FE phase, BE already approved
    Forms: OrderForm, OrderListFilter

Upcoming (blocked):
  * UC002-FE: Waiting for current wave
  * UC001-SYNC: Waiting for UC001-FE completion

Wave Progress:
  Wave 0: [done]     100%  All TECH tasks done
  Wave 1: [done]     100%  All tasks done
  Wave 2: [active]    33%  2 of 6 done
  Wave 3: [blocked]    0%  Waiting for Wave 2

Source: Neo4j graph (Task/Wave nodes)
===============================================================

Enriched Sync Verification Ready

===============================================================
                         NEXT TASK
===============================================================

  UC001: Create Order -- Sync Verification

Both BE and FE are approved. Run sync check to verify
API contract compliance before QA.

Wave:      2       Phase:     Sync
Priority:  high    Reason:    Unblocks QA for UC001

Entities:  Order, Customer, OrderItem
Forms:     OrderForm (12 fields), CustomerSelect (3 fields)

  Start now: /nacl:tl-sync UC001

Source: Neo4j graph
===============================================================

Enriched QA Testing Ready

===============================================================
                         NEXT TASK
===============================================================

  UC001: Create Order -- QA Testing

All phases complete. Run E2E testing via Playwright.

Wave:      2       Phase:     QA
Priority:  critical (final validation)

Entities:  Order, Customer, OrderItem
Forms:     OrderForm, CustomerSelect
Steps:     8 activity steps (test scenarios)

  Start now: /nacl:tl-qa UC001

Source: Neo4j graph
===============================================================

List Mode (--list)

===============================================================
               TOP 5 TASK CANDIDATES
===============================================================

  Active Wave: 2
  Source: Neo4j graph (tl_task_scoring)

#  Score  Task                      Phase        Entities        Command
-- ------ ------------------------- ------------ --------------- ----------------------
1  135    UC003-BE Delete Order     BE Dev       Order,AuditLog  /nacl:tl-dev-be UC003
2  125    UC001-FE Create Order     FE Dev       Order,Customer  /nacl:tl-dev-fe UC001
3  110    UC002-FE Edit Order       FE Dev       Order,OrderItem /nacl:tl-dev-fe UC002
4   85    TECH-003 Error Handling   TECH Dev     --              /nacl:tl-dev TECH003
5   60    UC004-BE List Orders      BE Dev       Order           /nacl:tl-dev-be UC004

===============================================================

No Tasks Available

===============================================================
                  NO TASKS AVAILABLE
===============================================================

All tasks in the active wave are either:
  * Completed (done)
  * Blocked (waiting on dependencies)
  * In progress (being worked on)

Active wave: 2

Current blockers:
  * UC003-FE: Waiting for BE-UC003 review (in_review)
  * UC002-SYNC: Waiting for FE-UC002 completion (in_progress)

In progress:
  * BE-UC003: Backend review (/nacl:tl-review UC003 --be)
  * FE-UC002: Frontend development (/nacl:tl-dev-fe UC002)

Recommendations:
1. Complete in-progress tasks to unblock the wave
2. Run /nacl:tl-status for detailed progress view

Source: Neo4j graph
===============================================================

All Tasks Complete

===============================================================
                   ALL TASKS COMPLETE!
===============================================================

Summary:
  * UC tasks:     N (all phases: BE, FE, Sync, Review, QA)
  * TECH tasks:   M
  * Total phases: X completed
  * QA results:   N passed, 0 failed
  * Stubs:        0 critical, 0 warnings

The project development is complete!

Next steps:
  * Ship and deploy to staging:
    /nacl:tl-deliver                    (push + verify + deploy)
  * Or use conductor for managed delivery:
    /nacl:tl-conductor                  (full lifecycle including delivery)
  * Run /nacl:tl-status for the final project report
  * Review .tl/changelog.md for full history

Source: Neo4j graph
===============================================================

---

Workflow -- Fallback Mode

When Neo4j is unavailable, operate identically to nacl-tl-next:

Step 1: Read Current Status

Read .tl/master-plan.md and .tl/status.json. Extract:

• Wave definitions and task assignments per wave
• All tasks with their current phase status
• BE/FE pairing information per UC
• Cross-task and cross-wave dependencies
• Stub registry summary (from .tl/stub-registry.json if present)

Step 2: Determine Active Wave

For each wave (starting from Wave 0):
  If wave has any task NOT in done status -> this is the active wave
If all waves complete -> show completion message

Step 3: Build Candidate List

Apply the same phase action priority table and dependency rules as graph mode.

Step 4: Score and Rank

Apply the same composite scoring formula:

score = priority_weight
      + status_order_weight
      + wave_bonus
      + dependency_bonus
      + phase_completion_bonus
      - age_penalty

Step 5: Present

Same output format as graph mode, but without enrichment (entity/form names) and with a fallback notice:

Note: Neo4j unavailable, using file-based fallback.
Entity/form enrichment unavailable.

---

Pre-Check Error States

Situation	Mode	Message	Recovery
Neo4j unreachable	Graph	Neo4j unavailable, switching to fallback	Automatic fallback
No TL nodes in graph	Graph	No Task/Wave nodes in graph	/nacl:tl-plan
No .tl/ directory	Fallback	Project not initialized for TeamLead workflow	/nacl:tl-plan or /nacl:tl-plan
Missing master-plan.md	Fallback	Wave info unavailable, priority-only mode	/nacl:tl-plan
Corrupted status.json	Fallback	Warning: status.json is invalid	/nacl:tl-plan --refresh
Empty task list	Both	No tasks found	/nacl:tl-plan or /nacl:tl-plan
All tasks blocked	Both	Show blockers + in-progress	Complete blocking tasks first

---

Key Cypher Queries Reference

All queries are defined in graph-infra/queries/tl-queries.cypher:

Query Name	Purpose	Used In
tl_task_scoring	Composite scoring for ranking candidates	Step 3
tl_actionable_tasks	Tasks with all dependencies satisfied	Step 2
tl_active_wave	Lowest wave with incomplete tasks	Step 1
tl_task_with_uc_context	Task enriched with UC entities/forms	Step 4
tl_progress_by_wave	Per-wave progress stats	Step 5
tl_blocked_tasks	Tasks blocked by unsatisfied dependencies	Step 6

---

Reads / Writes

Reads (Neo4j -- via mcp__neo4j__read-cypher)

# TL layer nodes:
- Task (id, title, type, status, wave, priority, phase_*, created, agent)
- Wave (id, number, name, status)

# TL layer edges:
- (Task)-[:IN_WAVE]->(Wave)
- (Task)-[:DEPENDS_ON]->(Task)

# SA layer nodes (for enrichment):
- UseCase (id, name, description, priority)
- Form (id, name)
- FormField (id, name, label)
- ActivityStep (id, description, order)
- DomainEntity (id, name)
- DomainAttribute (id, name)

# SA layer edges (for enrichment):
- (UseCase)-[:GENERATES]->(Task)
- (UseCase)-[:USES_FORM]->(Form)
- (UseCase)-[:HAS_STEP]->(ActivityStep)
- (Form)-[:HAS_FIELD]->(FormField)
- (FormField)-[:MAPS_TO]->(DomainAttribute)
- (DomainEntity)-[:HAS_ATTRIBUTE]->(DomainAttribute)

# Key named queries (graph-infra/queries/tl-queries.cypher):
- tl_task_scoring
- tl_actionable_tasks
- tl_active_wave
- tl_task_with_uc_context
- tl_progress_by_wave
- tl_blocked_tasks

Reads (Filesystem -- fallback only)

- .tl/status.json        # Task states and wave assignments
- .tl/master-plan.md     # Wave definitions and dependency map
- .tl/stub-registry.json # Stub tracking (if present)

Writes

This skill is read-only. It does not modify the graph or the filesystem.

---

Reference Documents

Load these for detailed guidelines:

Context	Reference
Protocol and agent contracts	${CLAUDE_PLUGIN_ROOT}/nacl-tl-core/references/tl-protocol.md
Sync verification rules	${CLAUDE_PLUGIN_ROOT}/nacl-tl-core/references/sync-rules.md
Stub tracking rules	${CLAUDE_PLUGIN_ROOT}/nacl-tl-core/references/stub-tracking-rules.md
QA testing rules	${CLAUDE_PLUGIN_ROOT}/nacl-tl-core/references/qa-rules.md
API contract rules	${CLAUDE_PLUGIN_ROOT}/nacl-tl-core/references/api-contract-rules.md

---

Final Checklist

Before Recommending

• Neo4j queried (or fallback activated with notice)
• Active wave determined
• Task list is not empty
• At least one non-blocked task exists
• Scoring formula applied

Recommendation Content

• Single task selected (highest score)
• Wave context provided (current wave, wave status, progress %)
• Phase identified (BE dev, FE review, sync, QA, etc.)
• SA enrichment included (entity names, form names, step count)
• Priority rationale explained with bullet points
• Launch command provided and ready to copy
• Parallel opportunities listed in "Also ready" section
• Blocked tasks listed in "Upcoming" section
• Source noted (Neo4j graph vs file-based fallback)

After Recommending

• User knows exactly what to do next
• Command is ready to copy and paste
• Wave progress is visible
• Blockers are visible if relevant

---

Next Steps

After getting a recommendation:

• /nacl:tl-dev-be UC### -- Start backend development
• /nacl:tl-dev-fe UC### -- Start frontend development
• /nacl:tl-dev TECH### -- Start TECH task development
• /nacl:tl-review UC### --be -- Review backend code
• /nacl:tl-review UC### --fe -- Review frontend code
• /nacl:tl-sync UC### -- Run sync verification
• /nacl:tl-stubs UC### -- Run stub scan
• /nacl:tl-qa UC### -- Run E2E QA testing
• /nacl:tl-status -- View full project status with wave progress
• /nacl:tl-next --list -- View top 5 candidates with scores