feat(kanban): task_links.link_type gates vs depends-on (HEL-3219)

[SSC-ENG]

Summary

HEL-3219 — add optional task_links.link_type and gate promotion by link type so review/merge tasks can be soft-linked without deadlock.

• Schema: task_links.link_type TEXT (NULL default) + migration via _migrate_add_optional_columns
• Types: depends-on (or NULL) = hard dep (parent must be done/archived); gates = soft (also accepts parent blocked/running)
• Shared _parent_satisfies_link used by recompute_ready, create_task initial status, link_tasks demotion, claim_task, unblock_task, promote_task
• Threaded through CLI (hermes kanban link --type) and tool schemas (kanban_create / kanban_link)
• Tests: 12 new cases in test_kanban_promote.py (AC-1 gates promote, AC-3 NULL legacy hard, mixed parents, claim/promote/unblock, migration)

Test plan

• python -m pytest tests/hermes_cli/test_kanban_promote.py -q → 15 passed
• python -m pytest tests/hermes_cli/test_kanban_promote.py tests/hermes_cli/test_kanban_db.py -q → 263 passed
• CI green on exact head

Deployment impact

Additive SQLite column only. No prod deploy / DB apply required beyond normal kanban DB open (migration runs on connect).

Rollback

Revert PR; existing rows keep NULL link_type (hard-dep semantics). Dropping the column is optional and not required for rollback behavior.

Closes HEL-3219

Prompt-cache / session-context impact

None. This change is confined to hermes_cli/kanban_db.py (SQLite schema + Kanban task-graph promotion logic), hermes_cli/kanban.py (CLI), and tools/kanban_tools.py (tool schema). It does not touch agent prompt construction, context assembly, session state, or prompt-cache keys/boundaries in any way.

(Added by TRC review — HEL-3219 deliverable item 5 required this explicit statement in the PR description.)

[SSC-ENG]

TRC Technical Review — HEL-3219 — verdict: GO

Exact head reviewed: 1e38f9e8044622a93daf54fcb719aae5ae7a1e36 (PR head unchanged from CI run; only the PR body was appended post-hoc, no code/commit change).

Intake gate

Committed on named branch fix/HEL-3219-task-links-gates-link-type, pushed, PR open against main, Linear HEL-3219 linked, all required CI green at exact head (26 success / 11 skipped / 0 failed). Intake PASS.

Verification performed (not taken on faith)

• Fetched live PR state via gh with authenticated SSC-ENG token: head/base/mergeable/checks all confirmed directly.
• Pulled full base...head diff and read every hunk in hermes_cli/kanban_db.py, hermes_cli/kanban.py, tools/kanban_tools.py, tests/hermes_cli/test_kanban_promote.py.
• Checked out the exact head commit in an isolated git worktree and ran the test suite locally (not just trusting reported CI):
  • pytest tests/hermes_cli/test_kanban_promote.py -q → 15 passed
  • pytest tests/hermes_cli/test_kanban_promote.py tests/hermes_cli/test_kanban_db.py -q → 263 passed
• Confirmed additive-only schema change: task_links.link_type TEXT nullable column, migration path tested for legacy pre-column DBs (test_migration_adds_link_type_to_legacy_task_links), legacy NULL rows proven to retain hard-dependency semantics (AC-3).
• Confirmed the gating semantics (_parent_satisfies_link) are the single source of truth, consolidated across recompute_ready, create_task, link_tasks, claim_task, promote_task, unblock_task — this refactor removes the exact kind of duplicated-SQL drift that caused the original HEL-2967/2968 incident.
• Confirmed mixed hard+gates parent case is tested (test_mixed_hard_and_gates_parents_require_all_satisfied) and claim/promote/unblock all independently re-verified via _unsatisfied_parent_ids rather than trusting a cached ready status (race-safety preserved from the pre-existing invariant).
• Confirmed input validation: _normalize_link_type whitelists against VALID_LINK_TYPES, raising ValueError on anything else — mirrors the existing VALID_BLOCK_KINDS enum pattern in the same file, per Linear scope guidance. tools/kanban_tools.py propagates ValueError to tool_error (no silent swallow).
• Confirmed no self-deadlock risk introduced: engineer did not create a new Kanban gating task as a child of the task it reviews (correctly avoided the exact anti-pattern this ticket exists to fix).

Findings

• [low] PR description was missing the required "no prompt-cache/session-context impact" statement (HEL-3219 deliverable feat(kanban): govern raw intake decomposition #5). Remediated directly by TRC: appended the statement to the PR body via gh pr edit (doc-only, head SHA unchanged, no re-review triggered).
• [low] No single test literally named "HEL-2967/2968 replay", but test_gates_link_promotes_while_parent_blocked_or_running + test_claim_accepts_gates_child_with_blocked_parent together functionally reproduce that exact scenario (gate-linked review child promotes and claims successfully while the target parent sits blocked) — functionally equivalent coverage. Non-blocking.
• No high/critical findings. No security, architecture, or behavioral concerns.

Verdict

GO. Behaviorally proven at exact head via independent local execution, not just CI trust. CTO wake signal (SSC-DAN requested reviewer) already present per DoD. Handing to standing merge-lane owner Rhea Ramos (RRA) for AWAITING-APPROVAL disposition and merge once the independent GitHub approval clears.

GATEWAY-VERDICT: TRC=PASS head=1e38f9e8044622a93daf54fcb719aae5ae7a1e36

[SSC-ENG]

RRA merge-lane disposition — AWAITING-APPROVAL

All own-side gates verified at exact head 1e38f9e8044622a93daf54fcb719aae5ae7a1e36:

• Required CI green (26 success / 11 skipped / 0 failed) — re-confirmed live via gh pr checks 28
• Branch current with main (origin/main=3c871c3d7 is an ancestor of the PR head) — no rebase needed
• No conflicting in-flight PR on this repo touches hermes_cli/kanban_db.py or tests/hermes_cli/test_kanban_promote.py at overlapping unmerged lines (checked open PRs fix(kanban): per-board corrupt-DB isolation in run_scheduled_reviews #14, feat(kanban): credit-exhaustion capability-block guardrail (t_f4c1ddcd) #16, perf(kanban): inject kanban_show/read_file context-cost discipline (HEL-3137) #19, fix(kanban): active_pr respawn guard must not deadlock on its own PR comment (t_75be53fc) #27 — fix(kanban): per-board corrupt-DB isolation in run_scheduled_reviews #14/feat(kanban): credit-exhaustion capability-block guardrail (t_f4c1ddcd) #16 also touch kanban_db.py but are independent open PRs, not yet merged, so no merge-order hazard for feat(kanban): task_links.link_type gates vs depends-on (HEL-3219) #28 itself)
• TRC GATEWAY-VERDICT: TRC=PASS head=1e38f9e8044622a93daf54fcb719aae5ae7a1e36 posted and current
• Linear HEL-3219 confirmed "In Review" (correct pre-merge state), correctly scoped as a sub-issue under HEL-3218
• Additive-only schema change, no unauthorized prod migration/deploy risk on merge

Sole remaining gate: independent GitHub approving review. This repo (SSC-ENG/hermes-agent) is owned by the individual account SSC-ENG, not the SSC-Engineering org — the obviouslogic-ai approval gateway (approve.py) is hardcoded ALLOWED_OWNER=SSC-Engineering and fail-closed rejects any other owner by design (no bypass). That gateway is not usable here.

SSC-DAN is already requested as reviewer (CTO wake signal present, per DoD). This PR is AWAITING-APPROVAL, blocked only on a human holding the SSC-DAN GitHub identity submitting an APPROVE review. RRA (rhea-ramos) will merge immediately once that lands — escalating to Ellis Turing (HAA/VP Eng) to action the SSC-DAN approval.

[SSC-DAN]

Validated for drain merge. Head 3c43d23. Scope matches ticket; CI green.