feat(agentic-harness): dual-tracker sync (v0.8.0)

[MrBogomips]

Summary

Implements the approved v0.8.0 dual-tracker sync design (spec 1.1.0, decisions D1–D9 settled 2026-06-12). When a project runs both a repo-native tracker agents work (Beads, Backlog.md, git-bug, …) and a human-oriented SaaS tracker people watch (Jira, Linear, GitHub Issues), harness-setup can now generate a project-local sync that keeps the SaaS as a projection of the repo-native source of truth.

This is plugin-side work only: everything "generated" is authored as templates and protocol docs that harness-setup instantiates later in target projects.

The sync model (shared/tracker-sync-protocol.md, new)

• Three lanes: continuous one-way push (repo → SaaS, remote title/label edits overwritten + logged, never silently); one-time intake of human-created SaaS issues within a configured filter; remote state changes treated as proposals — logged, state push suspended per-item, adopted only on confirmation (D4). Full two-way merge stays out and documented against.
• State store .tracker-sync/ at repo root (D5): map.jsonl (canonical ordering for line-stable merges), cursor.json (intake watermark only, with defined loss recovery), conflicts.md, proposals.md, gitignored reports/.
• Idempotency: per-side fingerprints over normalized two-way-sensitive fields (push-only fields excluded — kills Jira ADF false positives); SaaS marker as pre-create duplicate guard; intake ordering that survives a failed marker write.
• Concurrency: designated sync branch, clean/up-to-date write preflight, commit + push with one rebase-retry, never force.
• Failure semantics: unmapped remote states no-op + log; failed Jira transitions skip + log; rate-limit stop-and-resume with a per-run item cap (default 50); orphans terminal, never auto-recreated.
• Credential posture: SaaS access only through the human-tracker role in tools.md; no tokens anywhere under .tracker-sync/; headless runs are read+report-only (D2), so absent headless auth degrades to a visible "role unavailable" report.
• Per-SaaS map for Jira / Linear / GitHub Issues (D1): access role, marker convention, intake-filter shape, rate-limit notes, state-table starters; the Jira table is elicited per project — MCP read with interview fallback, user-confirmed (D6).

Generation templates (harness-setup/references/tracker-sync-template.md, new)

The generated tracker-sync skill (three run modes: scoped for the orchestrator write-through, full for on-demand catch-up, report for read-only headless runs), the sync-config (mapping.md) template with elicitation guidance (state table, intake filter, backfill with new-from-now default, branch, cadence, cap), the single sync agent template, and the per-venue schedule-registration block (local scheduled agent or crontab claude -p "/tracker-sync report", default daily on workdays — D3/D8). Hooks remain rejected as a trigger.

Wiring

• harness-setup SKILL.md: the process-layers gate gains the sync sub-step, offered only when both tracker kinds are present/declared, with the sync preflight that validates both tracker entry points by actually calling them before generating (adversarial feat(agentic-harness): mandatory pre-write change-manifest approval (v0.3.0) #10-narrow, D7); Step 2b gains the register / unregister schedule manifest action kind, explicitly environment-level; Step 5 gains the placeholder-verification checklist over all generated artifacts — grep for unsubstituted {PLACEHOLDER} and ${CLAUDE_PLUGIN_ROOT} (adversarial devcontainer-generator: automatic host config and auth sharing for agentic coding tools #3, D7); matching deliverable-checklist items.
• orchestrator-template.md: addendum T4 (scoped tracker-sync write-through) spliced after T3, gated on the generated sync skill existing.
• detection-signatures.md: human-tracker usage signals (Jira keys in commits, linear.app links, configured Atlassian/Linear MCP, gh auth + ISSUE_TEMPLATE staying rule-5 weak) — all report-and-ask.
• harness-review: sync drift signals — cursor age vs cadence, unresolved conflicts, open-proposal backlog age, orphan counts, stale reports/.
• tracker-advisor: its sync boundary rows now point at harness-setup instead of "a planned future capability".
• README, plugin.json + marketplace.json → 0.8.0 (version-sync CI enforced).

Both cuts (Cut 1 sync core, Cut 2 intake + operations) ship in this single 0.8.0 release per D9.

Test plan

• bash tests/ci/run-structural-tests.sh — all 4 suites pass (plugin structure, connectors, reference paths, version sync at 0.8.0)
• claude plugin validate ./agentic-harness --strict — passes
• SKILL.md bodies within the ~500-line ceiling (largest: harness-setup at 389)
• Trigger-separation dry run on touched descriptions: "keep the trackers in sync / sync issues to Jira" → harness-setup only; "which tracker should we use" → tracker-advisor only; "review the harness" → harness-review only; no new overlap with spec-advisor, plugin-dev, claude-code-setup
• End-to-end generation dry run in a dual-tracker target project (Beads + GitHub Issues, the D1 Cut-1 validation path) — to do before community-marketplace resubmission

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.