docs: Linear integration specs (6 directions, 4 specs)#75
Conversation
Adds docs/linear-integration/ with four spec documents covering all six Linear integration directions for the Function Factory governance loop. Direction → Spec mapping: D1 (atom projection P1/P2) → SPEC-LINEAR-SYNC-SERVICE-001 D2 (Disposition Event surface) → SPEC-FF-LINEAR-BRIDGE-001 D3 (divergence projection P3) → SPEC-LINEAR-SYNC-SERVICE-001 D4 (cycle cadence) → SPEC-FF-CYCLE-HEALTH-001 D5 (commit tracing) → SPEC-FF-COMMIT-TRACING-001 D6 (health document P4) → SPEC-FF-CYCLE-HEALTH-001 Key: Linear is the We-layer during Bootstrap. The bridge translates; the WeOps Console (SPEC-WEOPS-CONSOLE-001) is the native surface. WEOPS_SIGNING_KEY shared between bridge and Console — no gateway update required during Phase 1→3 migration. Linear issues: WEO-5 through WEO-22 (Function Factory Agent Infrastructure)
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 719aedbf19
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| return command.replace( | ||
| /-m\s+(['"])([\s\S]*?)\1/, | ||
| `-m "${newMessage}"` |
There was a problem hiding this comment.
When the original commit uses single quotes to protect shell metacharacters, this rewrite always re-emits the message inside double quotes without escaping. In that case a message like git commit -m 'fix $(...)' is transformed into a command where $(), backticks, embedded ", and newlines are reparsed by the shell before git runs, which can change the committed message or execute unintended command substitutions. The spec should require argument-level parsing/reconstruction or a temporary message file instead of string replacement.
Useful? React with 👍 / 👎.
| `harness/hooks/pre_tool_call.ts`, | ||
| `harness/hooks/post_execution.ts`, |
There was a problem hiding this comment.
The repo's active hooks are under .agent/harness/hooks/ (.agent/harness/hooks/pre_tool_call.ts and .agent/harness/hooks/post_execution.ts); I searched the tree and there is no root harness/hooks directory. Implementing the spec as written would create or edit the wrong files, leaving the actual enforcement/tracing hooks unchanged.
Useful? React with 👍 / 👎.
| projectId: request.projectId, | ||
| milestoneId: request.milestoneId, | ||
| stateId: BACKLOG_STATE_ID, |
There was a problem hiding this comment.
Linear's IssueCreateInput does not accept milestoneId; project milestones are assigned with projectMilestoneId. If the atom projection sends this object as specified, every issue creation that includes a WorkGraph milestone will be rejected by the GraphQL API before any atom issue or binding is created.
Useful? React with 👍 / 👎.
| Linear signs webhooks with an HMAC-SHA256 signature in the | ||
| `Linear-Signature` header. The bridge verifies this on every request: |
There was a problem hiding this comment.
Verifying the HMAC only proves the body was originally signed by Linear; it does not stop the same signed webhook from being replayed. In the disposition flow here, replaying a prior IssueCommentCreate can write another timestamped ELC artifact and issue/send another gateway token for the same human comment, so the bridge also needs to validate webhookTimestamp freshness and/or store Linear delivery/comment IDs as idempotency keys before processing.
Useful? React with 👍 / 👎.
1 participant
What
Adds
docs/linear-integration/with four spec documents covering all six Linear integration directions for the Function Factory governance loop.Direction → Spec mapping
FACTORY_*env vars → git trailers → SHA back to LinearKey finding
Linear is already the We-layer during Bootstrap. The bridge (
SPEC-FF-LINEAR-BRIDGE-001) is a translation layer; the WeOps Console (SPEC-WEOPS-CONSOLE-001) is the native surface.WEOPS_SIGNING_KEYis shared between bridge and Console — no gateway update required during Phase 1→3 migration.Implementation order
SPEC-LINEAR-SYNC-SERVICE-001— P1 atom projection (unblocks WEO-7/8/9)SPEC-FF-LINEAR-BRIDGE-001— bridge webhook handler (unblocks human Dispositions)SPEC-FF-COMMIT-TRACING-001— commit tracing (closes lineage loop)SPEC-FF-CYCLE-HEALTH-001— cycle cadence + health document (observability)Linear
Related issues: WEO-5 through WEO-22 (Function Factory Agent Infrastructure project)