coilyco-flight-deck/ward

Fork 0

Choose an out-of-band issue tracker source before public release #827

New issue

Closed

opened 2026-07-09 17:45:03 +00:00 by coilyco-ops · 3 comments

coilyco-ops commented

2026-07-09 17:45:03 +00:00

Member

Ward needs a real out-of-band issue tracker source before public release.

Current state:

Forgejo is canonical for source and internal work, but its tracker is embedded in the Git platform.
GitHub is the public front door and mirror surface, but relying on GitHub Issues would make the fallback tracker another Git platform surface.
The release needs a tracker source outside both Git platforms so ward can coordinate work when Git hosting or mirror state is the thing being tested.
Kai already uses Trello, but Trello may be too board-shaped for ward's issue lifecycle.
Shortcut, Linear, and Jira should be evaluated. Shortcut has extra leverage because Kai already uses it at Kapwing and ward will need Shortcut support soon anyway.

Decision pressure:

Public release needs a tracker with a stable API, webhooks, durable IDs, and enough workflow structure for ward issue refs.
Ward needs a small integration surface first: create, read, comment, state transition, search, and link back to Forgejo/GitHub refs.
The tracker must be usable as the source of truth for release-blocking work, not just as a mirror of Git issues.
Writes are externally visible and should use explicit gates, audit rows, and least-privilege tokens.

Evaluate:

Shortcut as likely first pick because it is already operationally relevant to Kai and has a straightforward REST API.
Linear as a strong product fit with GraphQL, webhooks, and agent-oriented workflows.
Jira as the enterprise-compatible option, with higher setup and workflow overhead.
Trello as the existing personal tool, but likely weaker for pressure-tested issue lifecycle semantics.

Acceptance:

A recommendation names the tracker ward should support first for public release readiness.
The recommendation includes a minimum viable command surface for ward.
The recommendation identifies auth, webhook, ID mapping, and failure-mode requirements.
Follow-up implementation issues are filed for the first integration slice.

Ward needs a real out-of-band issue tracker source before public release. Current state: * Forgejo is canonical for source and internal work, but its tracker is embedded in the Git platform. * GitHub is the public front door and mirror surface, but relying on GitHub Issues would make the fallback tracker another Git platform surface. * The release needs a tracker source outside both Git platforms so ward can coordinate work when Git hosting or mirror state is the thing being tested. * Kai already uses Trello, but Trello may be too board-shaped for ward's issue lifecycle. * Shortcut, Linear, and Jira should be evaluated. Shortcut has extra leverage because Kai already uses it at Kapwing and ward will need Shortcut support soon anyway. Decision pressure: * Public release needs a tracker with a stable API, webhooks, durable IDs, and enough workflow structure for ward issue refs. * Ward needs a small integration surface first: create, read, comment, state transition, search, and link back to Forgejo/GitHub refs. * The tracker must be usable as the source of truth for release-blocking work, not just as a mirror of Git issues. * Writes are externally visible and should use explicit gates, audit rows, and least-privilege tokens. Evaluate: * Shortcut as likely first pick because it is already operationally relevant to Kai and has a straightforward REST API. * Linear as a strong product fit with GraphQL, webhooks, and agent-oriented workflows. * Jira as the enterprise-compatible option, with higher setup and workflow overhead. * Trello as the existing personal tool, but likely weaker for pressure-tested issue lifecycle semantics. Acceptance: * A recommendation names the tracker ward should support first for public release readiness. * The recommendation includes a minimum viable command surface for ward. * The recommendation identifies auth, webhook, ID mapping, and failure-mode requirements. * Follow-up implementation issues are filed for the first integration slice.

coilyco-ops commented

2026-07-09 17:47:52 +00:00

Author

Member

Pressure-test point: avoid making every tracker equally authoritative. The adapter contract should define create/read/comment/transition/search/link semantics, then personal flow can run Forgejo + Shortcut for each item to catch drift. GitHub -> Shortcut probably does not need to be in Kai's personal flow at first because that is mainly the Kapwing path. Keep GitHub -> Shortcut as a separate integration slice or fixture-backed contract test until there is a real need to run it day to day.

Additional design angle from Kai: use personal work as a high-coverage many-to-many tracker testbed. Likely shape: every personal work item exercises both the Forgejo tracker adapter and the Shortcut tracker adapter, with one source of truth and the other operating as a mirror/shadow target. This would give broad real-world coverage without waiting for public users. Pressure-test point: avoid making every tracker equally authoritative. The adapter contract should define create/read/comment/transition/search/link semantics, then personal flow can run Forgejo + Shortcut for each item to catch drift. GitHub -> Shortcut probably does not need to be in Kai's personal flow at first because that is mainly the Kapwing path. Keep GitHub -> Shortcut as a separate integration slice or fixture-backed contract test until there is a real need to run it day to day.

coilyco-ops commented

2026-07-09 17:48:58 +00:00

Author

Member

🔎 ward agent advisor

ward agent advisor --harness codex ran a one-shot standard research pass on this question:

Read the issue title, body, and comment thread below as the research brief. Identify the decisions, options, open questions, and risks, then give a clear advisory recommendation that can be posted back on the issue.

Recommendation

Support Shortcut first for public release readiness, with Linear as the planned second integration.

That is not because Shortcut is the strongest product overall. It is because it is the best first shipping fit for ward as it exists today:

ward already treats the tracker thread as a durable automation surface, and its current host abstraction is small: get, thread read, create, comment, close/reopen, optional lock fallback in cmd/ward/forge.go.
ward already ships a spec-driven ward-kdl path for REST/OpenAPI surfaces, and already vendors a third-party tracker surface for Trello. Shortcut is a straightforward REST API with webhook docs and stable workflow-state semantics, so it matches the existing architecture better than Linear's GraphQL-first surface.
Shortcut is already operationally relevant to Kai, which lowers adoption friction.
Trello is technically close because ward already vendors its spec, but it is the weakest fit semantically for "source of truth" issue lifecycle.
Jira is viable but heavy. It solves the wrong problem first.

Important caveat: if the deciding constraint is strictly "least-privilege auth before all else," then Linear is the better platform. Its current docs support OAuth2, scoped permissions, app-actor installs, signed webhooks, and explicitly agent-oriented workflows. Shortcut's public API docs, by contrast, document token auth only, and say those tokens provide complete account access. So the call here is:

First ship: Shortcut
Best long-term target: Linear

Why Shortcut wins the first slice

1. It fits ward's current integration shape

Ward's existing cross-forge issue surface is deliberately narrow. The current issueForge contract only needs read/create/comment/state-change plus optional conversation lock fallback. Shortcut can satisfy that with REST endpoints and workflow-state transitions without forcing a new generator or a hand-rolled GraphQL client layer.

Relevant repo context:

issueForge host abstraction in cmd/ward/forge.go
GitHub implementation mirrors that surface in cmd/ward/github_ops.go
ward-kdl is explicitly the build-time generator for spec-driven ops surfaces in docs/ward-kdl.md

2. The Shortcut API has the minimum needed product semantics

As of July 9, 2026, Shortcut's official docs show:

REST API v3 marked current, with backwards-compatible changes promised: Shortcut REST API v3
token auth via Shortcut-Token header
rate limiting documented at 200 requests/minute
story comments via POST /stories/{story-public-id}/comments
search via GET /search
workflows and workflow states via GET /workflows
story history and state update surfaces
external-link lookup via GET /external-link/stories
outgoing webhooks with HMAC-SHA-256 signatures via Payload-Signature: Shortcut Webhook API v1

That covers the small integration surface this issue asks for without inventing workflow semantics on top of a board tool.

3. It is better than Trello for source-of-truth work

Trello is already present in ward's ward-kdl docs, which means it is the cheapest technical path. But the product model is still card/board/list, not issue/workflow/thread.

Repo evidence:

ward already vendors a Trello surface: docs/ward-kdl/ward-kdl.trello.guardfile.md
that surface exposes board/list/card/comment operations, but not the stronger issue-lifecycle semantics ward wants from a release-blocking source of truth.

Official Trello docs also reinforce the mismatch:

auth is API key + token, or OAuth-style delegated token flow: Trello authorization
webhooks are token-scoped to watched models and require callback URL validation: Trello webhooks

Useful, but still board-shaped.

Option assessment

Shortcut

Strengths

REST surface matches ward's current generator and ops style.
Workflow states map cleanly to "open / in-progress / done" semantics.
Search, comments, history, and webhook support are already documented.
External-link lookup is unusually useful for mapping Forgejo/GitHub refs back to tracker items.
Operational leverage is immediate because Kai already uses it.

Weaknesses

Official auth docs show only token auth, and explicitly warn the token has complete account access. That is a real least-privilege weakness.
Public docs do not show the same app-install / scoped OAuth posture that Linear does.
If ward wants per-workspace service identities with narrow write scopes, Shortcut is weaker today.

Verdict

Best first implementation target
Not the strongest long-term auth story

Linear

Strengths

Strongest product fit after Shortcut, arguably the strongest overall.
Official docs support personal API keys and OAuth2: Linear GraphQL getting started, Linear OAuth2
OAuth scopes are narrow and relevant, including issues:create and comments:create.
App-actor installation is explicitly documented for agents: Linear agents
Webhooks are signed with Linear-Signature and include replay guidance using webhookTimestamp: Linear webhooks
Issue attachments are designed for integrations and can be queried by URL, which is excellent for linkback/idempotency: Linear attachments
Linear is now explicitly documenting agent interaction patterns and issue-thread context surfaces, which aligns with ward's direction.

Weaknesses

GraphQL is the main blocker. It does not fit ward's current OpenAPI/specverb path.
A good Linear integration likely wants a dedicated client layer, typed mutation/query wrappers, or a new generator path.
That makes the first slice materially larger than Shortcut even though the platform is excellent.

Verdict

Best second integration
Could become the default public recommendation later

Jira

Strengths

Enterprise-compatible and extremely durable as a backlog source.
Rich issue, comment, transition, search, remote-link, and webhook surfaces are all present in current docs.
Remote links are first-class, which helps Forgejo/GitHub linkage: Jira remote issue links
Search and workflow transition APIs are mature: Jira issue search, Jira issues API
Webhooks support HMAC signing: Jira webhooks

Weaknesses

Highest setup and workflow overhead.
The product model is powerful, but that power becomes config burden for ward's first public-ready tracker source.
It is easy to spend the whole slice on Jira normalization instead of shipping a minimal integration.

Verdict

Third pick
Worth supporting later once the tracker abstraction is real

Trello

Strengths

Already partially proven inside ward via ward-kdl.
Good webhook story.
Cheap technically.

Weaknesses

Too board/list/card-shaped for release-blocking source-of-truth issue lifecycle.
Weakest workflow semantics for ward issue refs.
Existing surface in ward is not enough to justify choosing it as the canonical out-of-band tracker.

Verdict

Do not use as the public-release source of truth

Minimum viable ward surface

For the first integration, ward should stay narrow and mirror the current issue-thread abstraction instead of designing a provider-neutral mega-surface.

Host-side tracker client contract

The minimum viable contract should be:

get work item - read one item body + state + canonical URL + labels/team/workflow metadata
list thread - read the full comment thread in durable order
create work item
comment on work item
transition work item state - open/reopen/close, or provider-specific move-to-state mapped to ward semantics
search work items - by text and by external ref
link external ref - attach Forgejo/GitHub issue or PR URL back to the tracker item
lock or reserve fallback - if native thread locking does not exist, ward keeps using the reservation comment / immutable-thread discipline it already has

Recommended command surface for Shortcut first

Keep it provider-shaped, not abstracted too early:

ward ops shortcut story get <id>
ward ops shortcut story create ...
ward ops shortcut story comment <id> --text ...
ward ops shortcut story transition <id> --workflow-state-id ...
ward ops shortcut search ...
ward ops shortcut workflow list
ward ops shortcut webhook get/create/delete ...
ward ops shortcut external-link find --url <forge-url>
ward ops shortcut external-link attach <story-id> --url <forge-url> ...

The host dispatch path does not need all of those on day one. For ward agent parity it only needs read/thread/create/comment/transition/search/linkback. Webhook management can land in the same slice only if it stays small.

Requirements the first integration must enforce

Auth

For Shortcut first, the security bar should be:

use a dedicated Shortcut service account or workspace-bot identity, never a personal daily-use token
isolate it to the smallest workspace/team surface possible
keep token resolution host-side and off argv/audit payloads, matching ward's Forgejo/GitHub posture
split credentials by mode if possible: read token and write token, even if provider scopes are coarse
make write commands explicit-gated and audit-rowed

This is the biggest risk in the Shortcut choice. The official docs say the token gives complete access to the account. That means ward must compensate operationally.

For Linear later, the auth model is better:

prefer OAuth2 app installation with narrow scopes
use actor=app where the integration is service-like
request only read, issues:create, comments:create, and the minimum extra write scope required

Webhooks

Minimum webhook requirements regardless of tracker:

HMAC verification required before processing
raw-body verification, not reserialized JSON
replay window check where the provider supports it
idempotent delivery handling keyed by provider delivery id or webhook id + timestamp
backoff/retry-aware handling with explicit 2xx/5xx semantics
bounded fallback polling path when webhooks fail

Provider notes:

Shortcut - Payload-Signature, HMAC-SHA-256: docs
Linear - Linear-Signature plus webhookTimestamp: docs
Jira - X-Hub-Signature: docs
Trello - webhook lifecycle is token/model-scoped and callback URL must validate at creation time: docs

ID mapping

Ward should keep two identifiers for every linked item:

provider-native immutable id
provider-native human-facing display ref or canonical URL

For Shortcut first, use:

immutable: story id
human-facing: app URL / story public reference
reverse lookup: external-link lookup rather than regex-only comment scraping where possible

For Linear later, keep both:

immutable: UUID id
human-facing: identifier like ENG-123

Failure modes

The integration is not release-ready unless it defines degraded behavior up front:

tracker read down - ward can continue local work, but cannot claim new tracker-driven work items
tracker write down - ward must refuse externally visible state changes and preserve a local retry artifact
webhook down - switch to bounded polling and mark state stale
token expired / revoked - fail fast with a named auth error before any work starts
search ambiguous - never guess which tracker item a forge ref belongs to
state mapping missing - refuse transition rather than silently choosing the wrong workflow state
duplicate linkbacks - link attachment/update must be idempotent

Open questions that still need explicit policy

These are the real unresolved decisions, not blockers to the recommendation:

For Shortcut, what exact workflow-state mapping is ward allowed to assume for open, in progress, and done? This likely has to be configured per workspace/team, not hard-coded.
Is the first slice allowed to rely on comments for linkback truth, or must it use provider-native link surfaces from day one?
Does ward want a provider-neutral tracker: issue ref syntax immediately, or should the first slice stay provider-specific and only normalize internally?
Is webhook ingestion in scope for the very first integration, or is polling acceptable for v0 as long as the command surface is correct?

Risks to call out on the issue

Primary risk in choosing Shortcut: auth is coarse. This is an operational compensation story, not a clean least-privilege platform story.
Primary risk in choosing Linear instead: implementation size expands immediately because ward does not yet have a GraphQL generator path analogous to ward-kdl.
Primary risk in choosing Jira: the first slice disappears into normalization and admin/setup burden.
Primary risk in choosing Trello: ward gains an out-of-band tracker that still behaves too much like a board tool and too little like a durable issue source of truth.

Suggested follow-up issues to file in `coilyco-flight-deck/ward`

Single-repo work, so these should stay in this repo rather than fanning out.

Add Shortcut issue-thread client for host dispatch parity
- Implement host-side read/create/comment/transition/search/linkback for Shortcut stories.
- Mirror the current issueForge shape closely.
Define tracker state mapping config for non-forge backlogs
- Add explicit mapping from ward semantic states to provider workflow states.
- Refuse transitions when mapping is missing.
Add authenticated Shortcut webhook ingestion with HMAC verification
- Verify Payload-Signature, store dedupe keys, and define polling fallback.
Add external linkback model for forge refs in out-of-band trackers
- Store canonical Forgejo/GitHub issue and PR URLs against tracker items.
- Make reverse lookup idempotent.
Document token-handling policy for third-party trackers
- Dedicated service account, least membership, host-side resolution, audit posture, write gating.

Bottom line

Recommendation: choose Shortcut first, but treat it as a pragmatic first ship, not the final platform verdict.

The deciding logic is:

Shortcut is the fastest credible path to a real out-of-band source of truth that matches ward's current REST/spec-driven architecture.
Linear is the better long-term tracker integration, especially on auth and agent-native workflow shape, but it is a larger first implementation because it does not fit ward's current generation path.
Jira and Trello should not be the first public-release answer.

Researched and posted automatically by ward agent advisor --harness codex (ward#179). This is one-shot research, not a carried change - verify before acting on it.

— Codex, via ward agent

### 🔎 ward agent advisor `ward agent advisor --harness codex` ran a one-shot **standard** research pass on this question: > Read the issue title, body, and comment thread below as the research brief. Identify the decisions, options, open questions, and risks, then give a clear advisory recommendation that can be posted back on the issue. --- ## Recommendation **Support Shortcut first for public release readiness, with Linear as the planned second integration.** That is not because Shortcut is the strongest product overall. It is because it is the best **first shipping fit for ward as it exists today**: - ward already treats the tracker thread as a durable automation surface, and its current host abstraction is small: `get`, thread read, `create`, `comment`, `close/reopen`, optional `lock` fallback in [`cmd/ward/forge.go`](https://forgejo.coilysiren.me/coilyco-flight-deck/ward/src/branch/main/cmd/ward/forge.go). - ward already ships a spec-driven `ward-kdl` path for REST/OpenAPI surfaces, and already vendors a third-party tracker surface for Trello. Shortcut is a straightforward REST API with webhook docs and stable workflow-state semantics, so it matches the existing architecture better than Linear's GraphQL-first surface. - Shortcut is already operationally relevant to Kai, which lowers adoption friction. - Trello is technically close because ward already vendors its spec, but it is the weakest fit semantically for "source of truth" issue lifecycle. - Jira is viable but heavy. It solves the wrong problem first. **Important caveat:** if the deciding constraint is strictly "least-privilege auth before all else," then **Linear** is the better platform. Its current docs support OAuth2, scoped permissions, app-actor installs, signed webhooks, and explicitly agent-oriented workflows. Shortcut's public API docs, by contrast, document token auth only, and say those tokens provide complete account access. So the call here is: - **First ship:** Shortcut - **Best long-term target:** Linear ## Why Shortcut wins the first slice ### 1. It fits ward's current integration shape Ward's existing cross-forge issue surface is deliberately narrow. The current `issueForge` contract only needs read/create/comment/state-change plus optional conversation lock fallback. Shortcut can satisfy that with REST endpoints and workflow-state transitions without forcing a new generator or a hand-rolled GraphQL client layer. Relevant repo context: - `issueForge` host abstraction in [`cmd/ward/forge.go`](https://forgejo.coilysiren.me/coilyco-flight-deck/ward/src/branch/main/cmd/ward/forge.go) - GitHub implementation mirrors that surface in [`cmd/ward/github_ops.go`](https://forgejo.coilysiren.me/coilyco-flight-deck/ward/src/branch/main/cmd/ward/github_ops.go) - `ward-kdl` is explicitly the build-time generator for spec-driven ops surfaces in [`docs/ward-kdl.md`](https://forgejo.coilysiren.me/coilyco-flight-deck/ward/src/branch/main/docs/ward-kdl.md) ### 2. The Shortcut API has the minimum needed product semantics As of **July 9, 2026**, Shortcut's official docs show: - REST API v3 marked current, with backwards-compatible changes promised: [Shortcut REST API v3](https://developer.shortcut.com/api/rest/v3) - token auth via `Shortcut-Token` header - rate limiting documented at 200 requests/minute - story comments via `POST /stories/{story-public-id}/comments` - search via `GET /search` - workflows and workflow states via `GET /workflows` - story history and state update surfaces - external-link lookup via `GET /external-link/stories` - outgoing webhooks with HMAC-SHA-256 signatures via `Payload-Signature`: [Shortcut Webhook API v1](https://developer.shortcut.com/api/webhook/v1) That covers the small integration surface this issue asks for without inventing workflow semantics on top of a board tool. ### 3. It is better than Trello for source-of-truth work Trello is already present in ward's `ward-kdl` docs, which means it is the cheapest technical path. But the product model is still card/board/list, not issue/workflow/thread. Repo evidence: - ward already vendors a Trello surface: [`docs/ward-kdl/ward-kdl.trello.guardfile.md`](https://forgejo.coilysiren.me/coilyco-flight-deck/ward/src/branch/main/docs/ward-kdl/ward-kdl.trello.guardfile.md) - that surface exposes board/list/card/comment operations, but not the stronger issue-lifecycle semantics ward wants from a release-blocking source of truth. Official Trello docs also reinforce the mismatch: - auth is API key + token, or OAuth-style delegated token flow: [Trello authorization](https://developer.atlassian.com/cloud/trello/guides/rest-api/authorization/) - webhooks are token-scoped to watched models and require callback URL validation: [Trello webhooks](https://developer.atlassian.com/cloud/trello/guides/rest-api/webhooks/) Useful, but still board-shaped. ## Option assessment ### Shortcut **Strengths** - REST surface matches ward's current generator and ops style. - Workflow states map cleanly to "open / in-progress / done" semantics. - Search, comments, history, and webhook support are already documented. - External-link lookup is unusually useful for mapping Forgejo/GitHub refs back to tracker items. - Operational leverage is immediate because Kai already uses it. **Weaknesses** - Official auth docs show only token auth, and explicitly warn the token has complete account access. That is a real least-privilege weakness. - Public docs do not show the same app-install / scoped OAuth posture that Linear does. - If ward wants per-workspace service identities with narrow write scopes, Shortcut is weaker today. **Verdict** - **Best first implementation target** - **Not the strongest long-term auth story** ### Linear **Strengths** - Strongest product fit after Shortcut, arguably the strongest overall. - Official docs support personal API keys and OAuth2: [Linear GraphQL getting started](https://linear.app/developers/graphql), [Linear OAuth2](https://linear.app/developers/oauth-2-0-authentication) - OAuth scopes are narrow and relevant, including `issues:create` and `comments:create`. - App-actor installation is explicitly documented for agents: [Linear agents](https://linear.app/developers/agents) - Webhooks are signed with `Linear-Signature` and include replay guidance using `webhookTimestamp`: [Linear webhooks](https://linear.app/developers/webhooks) - Issue attachments are designed for integrations and can be queried by URL, which is excellent for linkback/idempotency: [Linear attachments](https://linear.app/developers/attachments) - Linear is now explicitly documenting agent interaction patterns and issue-thread context surfaces, which aligns with ward's direction. **Weaknesses** - GraphQL is the main blocker. It does not fit ward's current OpenAPI/specverb path. - A good Linear integration likely wants a dedicated client layer, typed mutation/query wrappers, or a new generator path. - That makes the first slice materially larger than Shortcut even though the platform is excellent. **Verdict** - **Best second integration** - **Could become the default public recommendation later** ### Jira **Strengths** - Enterprise-compatible and extremely durable as a backlog source. - Rich issue, comment, transition, search, remote-link, and webhook surfaces are all present in current docs. - Remote links are first-class, which helps Forgejo/GitHub linkage: [Jira remote issue links](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-remote-links/) - Search and workflow transition APIs are mature: [Jira issue search](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-search/), [Jira issues API](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/) - Webhooks support HMAC signing: [Jira webhooks](https://developer.atlassian.com/cloud/jira/platform/webhooks/) **Weaknesses** - Highest setup and workflow overhead. - The product model is powerful, but that power becomes config burden for ward's first public-ready tracker source. - It is easy to spend the whole slice on Jira normalization instead of shipping a minimal integration. **Verdict** - **Third pick** - Worth supporting later once the tracker abstraction is real ### Trello **Strengths** - Already partially proven inside ward via `ward-kdl`. - Good webhook story. - Cheap technically. **Weaknesses** - Too board/list/card-shaped for release-blocking source-of-truth issue lifecycle. - Weakest workflow semantics for ward issue refs. - Existing surface in ward is not enough to justify choosing it as the canonical out-of-band tracker. **Verdict** - **Do not use as the public-release source of truth** ## Minimum viable ward surface For the first integration, ward should stay narrow and mirror the current issue-thread abstraction instead of designing a provider-neutral mega-surface. ### Host-side tracker client contract The minimum viable contract should be: - `get work item` - read one item body + state + canonical URL + labels/team/workflow metadata - `list thread` - read the full comment thread in durable order - `create work item` - `comment on work item` - `transition work item state` - open/reopen/close, or provider-specific move-to-state mapped to ward semantics - `search work items` - by text and by external ref - `link external ref` - attach Forgejo/GitHub issue or PR URL back to the tracker item - `lock or reserve fallback` - if native thread locking does not exist, ward keeps using the reservation comment / immutable-thread discipline it already has ### Recommended command surface for Shortcut first Keep it provider-shaped, not abstracted too early: - `ward ops shortcut story get <id>` - `ward ops shortcut story create ...` - `ward ops shortcut story comment <id> --text ...` - `ward ops shortcut story transition <id> --workflow-state-id ...` - `ward ops shortcut search ...` - `ward ops shortcut workflow list` - `ward ops shortcut webhook get/create/delete ...` - `ward ops shortcut external-link find --url <forge-url>` - `ward ops shortcut external-link attach <story-id> --url <forge-url> ...` The host dispatch path does not need all of those on day one. For `ward agent` parity it only needs read/thread/create/comment/transition/search/linkback. Webhook management can land in the same slice only if it stays small. ## Requirements the first integration must enforce ### Auth For **Shortcut first**, the security bar should be: - use a **dedicated Shortcut service account or workspace-bot identity**, never a personal daily-use token - isolate it to the smallest workspace/team surface possible - keep token resolution host-side and off argv/audit payloads, matching ward's Forgejo/GitHub posture - split credentials by mode if possible: read token and write token, even if provider scopes are coarse - make write commands explicit-gated and audit-rowed This is the biggest risk in the Shortcut choice. The official docs say the token gives complete access to the account. That means ward must compensate operationally. For **Linear later**, the auth model is better: - prefer OAuth2 app installation with narrow scopes - use `actor=app` where the integration is service-like - request only `read`, `issues:create`, `comments:create`, and the minimum extra write scope required ### Webhooks Minimum webhook requirements regardless of tracker: - HMAC verification required before processing - raw-body verification, not reserialized JSON - replay window check where the provider supports it - idempotent delivery handling keyed by provider delivery id or webhook id + timestamp - backoff/retry-aware handling with explicit 2xx/5xx semantics - bounded fallback polling path when webhooks fail Provider notes: - **Shortcut** - `Payload-Signature`, HMAC-SHA-256: [docs](https://developer.shortcut.com/api/webhook/v1) - **Linear** - `Linear-Signature` plus `webhookTimestamp`: [docs](https://linear.app/developers/webhooks) - **Jira** - `X-Hub-Signature`: [docs](https://developer.atlassian.com/cloud/jira/platform/webhooks/) - **Trello** - webhook lifecycle is token/model-scoped and callback URL must validate at creation time: [docs](https://developer.atlassian.com/cloud/trello/guides/rest-api/webhooks/) ### ID mapping Ward should keep **two identifiers** for every linked item: - provider-native immutable id - provider-native human-facing display ref or canonical URL For Shortcut first, use: - immutable: story id - human-facing: app URL / story public reference - reverse lookup: external-link lookup rather than regex-only comment scraping where possible For Linear later, keep both: - immutable: UUID `id` - human-facing: `identifier` like `ENG-123` ### Failure modes The integration is not release-ready unless it defines degraded behavior up front: - **tracker read down** - ward can continue local work, but cannot claim new tracker-driven work items - **tracker write down** - ward must refuse externally visible state changes and preserve a local retry artifact - **webhook down** - switch to bounded polling and mark state stale - **token expired / revoked** - fail fast with a named auth error before any work starts - **search ambiguous** - never guess which tracker item a forge ref belongs to - **state mapping missing** - refuse transition rather than silently choosing the wrong workflow state - **duplicate linkbacks** - link attachment/update must be idempotent ## Open questions that still need explicit policy These are the real unresolved decisions, not blockers to the recommendation: - For Shortcut, what exact workflow-state mapping is ward allowed to assume for `open`, `in progress`, and `done`? This likely has to be configured per workspace/team, not hard-coded. - Is the first slice allowed to rely on **comments for linkback truth**, or must it use provider-native link surfaces from day one? - Does ward want a provider-neutral `tracker:` issue ref syntax immediately, or should the first slice stay provider-specific and only normalize internally? - Is webhook ingestion in scope for the very first integration, or is polling acceptable for v0 as long as the command surface is correct? ## Risks to call out on the issue - **Primary risk in choosing Shortcut:** auth is coarse. This is an operational compensation story, not a clean least-privilege platform story. - **Primary risk in choosing Linear instead:** implementation size expands immediately because ward does not yet have a GraphQL generator path analogous to `ward-kdl`. - **Primary risk in choosing Jira:** the first slice disappears into normalization and admin/setup burden. - **Primary risk in choosing Trello:** ward gains an out-of-band tracker that still behaves too much like a board tool and too little like a durable issue source of truth. ## Suggested follow-up issues to file in `coilyco-flight-deck/ward` Single-repo work, so these should stay in this repo rather than fanning out. 1. **Add Shortcut issue-thread client for host dispatch parity** - Implement host-side read/create/comment/transition/search/linkback for Shortcut stories. - Mirror the current `issueForge` shape closely. 2. **Define tracker state mapping config for non-forge backlogs** - Add explicit mapping from ward semantic states to provider workflow states. - Refuse transitions when mapping is missing. 3. **Add authenticated Shortcut webhook ingestion with HMAC verification** - Verify `Payload-Signature`, store dedupe keys, and define polling fallback. 4. **Add external linkback model for forge refs in out-of-band trackers** - Store canonical Forgejo/GitHub issue and PR URLs against tracker items. - Make reverse lookup idempotent. 5. **Document token-handling policy for third-party trackers** - Dedicated service account, least membership, host-side resolution, audit posture, write gating. ## Bottom line **Recommendation: choose Shortcut first, but treat it as a pragmatic first ship, not the final platform verdict.** The deciding logic is: - Shortcut is the fastest credible path to a real out-of-band source of truth that matches ward's current REST/spec-driven architecture. - Linear is the better long-term tracker integration, especially on auth and agent-native workflow shape, but it is a larger first implementation because it does not fit ward's current generation path. - Jira and Trello should not be the first public-release answer. --- Researched and posted automatically by `ward agent advisor --harness codex` (ward#179). This is one-shot research, not a carried change - verify before acting on it.   — Codex, via `ward agent`

coilyco-ops added the

consult

labels

2026-07-09 18:09:19 +00:00

coilyco-ops commented

2026-07-09 18:26:59 +00:00

Author

Member

Consult interrogation: the tracker decision is complete. The carrying implementation path is #634 for the git-host/Tracker split and #637 for the Shortcut adapter, with #638 keeping Linear/Jira backlog. Closing this consult shell.

coilyco-ops closed this issue

2026-07-09 18:26:59 +00:00

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

coilyco-flight-deck/ward#827

No description provided.

Rows
Columns

Choose an out-of-band issue tracker source before public release #827

🔎 ward agent advisor

Recommendation

Why Shortcut wins the first slice

1. It fits ward's current integration shape

2. The Shortcut API has the minimum needed product semantics

3. It is better than Trello for source-of-truth work

Option assessment

Shortcut

Linear

Jira

Trello

Minimum viable ward surface

Host-side tracker client contract

Recommended command surface for Shortcut first

Requirements the first integration must enforce

Auth

Webhooks

ID mapping

Failure modes

Open questions that still need explicit policy

Risks to call out on the issue

Suggested follow-up issues to file in coilyco-flight-deck/ward

Bottom line

Suggested follow-up issues to file in `coilyco-flight-deck/ward`