feat(processes): establish scm:* task namespace — agent-safe, platform-abstract, JSON-native SCM operations

[visionik]

Summary

Directive currently uses gh CLI commands directly in skills and tasks — GitHub-specific, agent-hostile (pager issues, noisy output, poor polling), and not abstracted for other platforms. Establish a scm:* task namespace that encodes agent best practices once and supports platform swapping via conditional includes.

Current problems

1. GitHub lock-in
Skills (deft-review-cycle, deft-swarm) and task operations call gh directly. Companies on GitLab, Linear, or Azure DevOps cannot use these skills without forking. As the practices/processes split (#878) positions directive as general-purpose, this coupling increasingly undercuts that goal.

2. Pager issues
gh pr view, gh issue view, and similar commands open a pager by default. Agents see truncated output or hang. This must be suppressed (e.g. GH_PAGER=cat) on every call. Currently this is done inconsistently or not at all.

3. Noisy output
Human-readable gh output (table headers, color codes, status icons, separators) is not agent-consumable. Agents fail to parse it or waste tokens processing decoration.

4. Suboptimal polling
Directive skills use sleep 30; gh pr view style polling. This is the worst-case pattern. Better options exist:

• gh pr checks --watch — built-in watching for CI checks (Level 1)
• ETag-based conditional API requests — only fetches when data changes (Level 2, shown in deftai/bridge PR#53 pr:reviews task)
• Webhook callbacks — GitHub pushes to agent (Level 3, future)

5. Not using JSON output
gh supports --json field1,field2 for most commands, eliminating noise, pager triggers, and token waste. Agent-facing calls should always use this.

Proposed: scm:* task namespace

Establish a scm: namespace in directive's Taskfile that:

1. Encodes agent best practices once — every scm:* task uses GH_PAGER=cat, --json output, ETag polling where applicable, and ghx (brunoborges/ghx) as the caching proxy
2. Provides a clean interface — calling agent does task scm:pr:view PR=42 and gets structured JSON with no paging, no noise
3. Enables platform swapping — via go-task conditional includes (or wrapper scripts pending upstream support), swap tasks/scm-github.yml for tasks/scm-gitlab.yml based on SCM_PLATFORM env var

Proposed command set (v1)

Task	Purpose
scm:issue:list	List open issues
scm:issue:view	Read a single issue (JSON)
scm:issue:create	Create an issue
scm:issue:close	Close with comment
scm:pr:list	List open PRs
scm:pr:view	Read a PR (JSON)
scm:pr:create	Open a PR
scm:pr:checks	Get CI check status
scm:pr:reviews	Poll for review comments (ETag-based, Level 2)
scm:pr:watch	Watch PR checks until complete
scm:pr:merge	Merge/squash a PR

Task design rules for scm:*

• ! All tasks MUST use --json output or emit a JSON envelope
• ! All tasks MUST suppress pager (GH_PAGER=cat or equivalent)
• ! Polling tasks MUST use at minimum Level 1 (--watch) or Level 2 (ETag) patterns -- never sleep N; gh ...
• ! audience: agent when go-task supports it (chore(vbrief): complete #845 triage v1 lifecycle housekeeping #880)
• ~ Tasks SHOULD use ghx instead of gh when available for caching/singleflight

Reference implementation

deftai/bridge PR#53 (task pr:watch, task pr:view, task pr:reviews) demonstrates the patterns this namespace should standardize. The ETag-based pr:reviews task is the reference for Level 2 polling.

Migration

• deft-review-cycle currently polls at Level 0 -- should be upgraded to use task scm:pr:reviews
• deft-swarm PR monitoring similarly should be upgraded
• Existing direct gh calls in skills can be migrated incrementally

Related

• deftai/bridge PR#53 (pr:watch, pr:view, pr:reviews patterns)
• brunoborges/ghx (caching proxy that slots into this namespace)
• feat(meta): RFC: restructure directive into practices/ and processes/ top-level directories #878 (practices/processes split -- scm:* tasks belong in processes/)
• chore(vbrief): complete #845 triage v1 lifecycle housekeeping #880 (go-task improvements for agent-facing tasks)
• feat(triage,cache,refinement): pre-ingest triage workflow with sidecar issue cache (refs #583 #788 #789 #815 #522) #845 (triage workflow -- uses gh commands that should go through scm: namespace)
• docs/valuable-go-task-improvements.md -- item 5 (conditional includes for platform swapping)

[visionik]

Two gaps identified during #845 / #883 design work:

1. scm:issue:comment missing from namespace

The triage needs-AC action (#845) posts a comment on an issue requesting acceptance criteria from the author. This operation isn't in the proposed command set. Suggest adding:

Task	Purpose
scm:issue:comment	Post a comment on an issue

Usage: task scm:issue:comment N=42 --body "Please add acceptance criteria before this can be triaged."

2. scm:issue:view --etag support needed

The deft-cache design (#883) relies on ETag-based conditional refresh: when an existing cache entry has a stored ETag, cache:refresh should pass it to scm:issue:view as a conditional request header. If upstream returns 304, the entry TTL is extended without re-fetching or re-scanning.

This requires scm:issue:view to accept an optional --etag parameter and forward it as If-None-Match: <etag> in the API request, returning a structured result that distinguishes 304 (not modified) from 200 (new content).