Epic: v1.3 Coworker context integration and v1.3.x Graphify extension

[jeffhuber]

Code Mower 1.3: Coworker context integration

Status: complete. C1–C7 are merged through Code Mower, v1.3.0 is published on GitHub and PyPI, the published-package campaign and upgrade rehearsal are complete, and the local installation is verified. Graphify #876 remains a separate v1.3.x candidate.

Outcome

A user selects an organization context connection for a repository, authenticates through the provider's supported flow, and starts Code Mower from Claude or Codex. The orchestrator retrieves a small set of relevant, cited facts for a work item. The work order, builder, and independent reviewer receive the same authorized evidence. Existing users who configure no context provider keep their current installation, session, tracker, and review behavior.

The host remains the implicit orchestrator. A context provider gains no builder, reviewer, tracker-write, or merge authority. Claude and Codex remain the default participants. Adding a context provider does not select additional participants.

Existing foundation

• src/code_mower/work_orders.py: external-context manifests, local previews, issue plans, work orders, and provenance.
• src/code_mower/plan_context.py: bounded context rendering and trusted-base project doctrine.
• src/code_mower/claude_audit_pr.py and codex_audit_pr.py: existing plan-context delivery to independent reviews.
• src/code_mower/session.py: host-neutral operating briefs, single-writer lease, and optional MCP enrichment rules.
• docs/planning-work-orders.md, docs/sessions.md, and CONTRIBUTING.md: planning, operation, privacy, and PR conventions.

Extend these surfaces. Do not introduce a second orchestrator, a background memory service, or a separate work-order format.

Architecture

The flow is: authoritative work item and repository scope -> selected context connection -> bounded retrieval -> validated local context packet -> work order and authorized builder/reviewer inputs.

Use four small responsibilities:

1. Local connection store. Separate provider identity, authenticated principal/workspace, credential reference, and authorized destinations from shareable repository policy. Repository configuration may contain a generic logical connection reference and limits. Account emails, tenant identifiers, endpoint URLs containing tenant information, credentials, and operator-specific aliases remain outside tracked files and public artifacts. Default JSON/status outputs redact them. Any identity display is an explicit local operator action.
2. Context adapter. A narrow capability contract covers connection verification, discovery of supported read operations, bounded search/retrieval, and normalization. Select a maintained MCP client/auth implementation after the Coworker contract spike; do not invent endpoint paths, tool names, OAuth scopes, identity claims, or token refresh behavior. Keep optional dependencies isolated from the base install. Host-managed authentication is acceptable only if it provides equivalent verifiable identity binding and process isolation; do not scrape another client's credential cache.
3. Packet validation and storage. Extend the current manifest pipeline with a versioned, bounded representation. Keep provider kind, context kind, citations, observed timestamps, optional source revision, extraction/confidence metadata, truncation/completeness state, and content integrity together. Private connection/principal/workspace binding, work-item scope, permitted recipients, and expiry travel in a protected local envelope. Provider-supplied text never establishes identity or policy by itself.
4. Delivery. Deliver the same validated evidence to authorized participants, with independent reasoning and verdicts. Preserve source citations and contradictions rather than forwarding a builder-authored conclusion as organizational truth. Integrate a trusted runtime payload channel alongside existing trusted-base doctrine; do not weaken path/base-ref protections or load context configuration from the proposed PR. Keep existing audit sandbox and ambient-MCP restrictions. Reviewers receive the approved packet, not the Coworker credential.

Account, permission, and retention contract

• Authenticate the explicitly selected connection; verify its principal and organization against trusted auth/provider metadata. A prompt email, local alias, or query filter is not proof. If identity cannot be verified, report identity_unverified and do not retrieve private material. Never substitute the host's default account.
• Use per-connection credentials and caches. Bind cache reuse to provider endpoint, tenant, principal, repository/work item, and relevant policy version. Two organizations with similarly named projects must remain distinct.
• Use supported secure token storage and restrict private files/directories. Do not put credentials in command arguments, URLs, generated examples, issue bodies, PRs, manifests intended for sharing, or logs.
• Keep retrieval read-only by an explicit allowlist of verified tools and operations. Tool annotations alone are not sufficient. Disable generic agent invocation, writes, and arbitrary follow-up URLs in the first adapter.
• Check authorization before new retrieval and before replay to a recipient. Disconnect, revoked/expired authorization, account changes, or destination changes invalidate access and cached reuse. A cache lifetime is not a substitute for authorization. Deletion removes Code Mower's local copy; it cannot recall content already sent to an authorized model.
• Treat retrieved text as evidence, not executable instructions or approved doctrine. Conflicting or uncited assertions remain explicitly uncertain. A material ambiguity in required task context requires a bounded owner action.
• Private text and citations may be delivered only to configured approved recipients. Public PR comments, Board, and CodeMower.com get no raw text, private source links, email/tenant IDs, private aliases, prompts, tokens, or raw provider output. Use an allowlisted metadata schema; keep source/content digests local unless the cloud contract explicitly permits them.

Retrieval and failure behavior

Retrieve once per work order/review input version where possible, and reuse only an authorized, unexpired packet. Enforce request/page/document/byte/time limits before and during retrieval. Keep missing billing data unknown; record observed usage locally when exposed. No broad organization crawl, unbounded pagination, or automatic paid redispatch.

An explicitly absent or optional unavailable provider produces a bounded next action and leaves the ordinary workflow usable. A required provider/context failure pauses the dependent work. Wrong-account or permission failures never trigger a fallback to another account. For review, required context that cannot be delivered yields an explicit incomplete/UNKNOWN input outcome, never a fabricated PASS. New material context produces a new packet identity and requires review again; the PR's current-head requirement remains intact.

Implemented user experience

The supported setup, retrieval request and delivery commands are documented in context setup, retrieval and delivery. Initial connection and diagnosis:

code-mower context connect coworker --connection example-context
code-mower context doctor --connection example-context --online --json
code-mower context disconnect --connection example-context

Connection setup stores private identity locally and verifies it before saving a usable connection. Existing init can optionally select an already configured context connection; it must not add a login step to the default Claude/Codex installation. Session briefs should say context is ready, optional/unavailable, or requires owner action using the same vocabulary across hosts. Generalize the current Rovo-specific enrichment wording while preserving Code Mower REST as Jira queue/mutation authority and GitHub as PR/gate authority.

Graphify extension point for v1.3.x

Keep provider identity separate from context kind (organization or repository). Capability differences must be explicit: a remote organization service can expose principal/workspace access, while a local graph can bind a repository path and revision without a SaaS login. Use a discriminated connection model rather than requiring fake OAuth fields for local providers.

Allow optional repository revision, graph build time, and extracted/inferred/unknown evidence classifications. A graph must be identifiable as matching, stale for, or unbound to the current repository revision. A synthetic local-graph fixture should prove the common packet and delivery path works without importing Graphify or adding another runtime.

The later candidate evaluates only the official Graphify-Labs/graphify project and graphify.com. Graphify Labs states that graphify.net is unaffiliated. Start with deterministic local code parsing and read-only graph queries; hosted graphs and model-backed semantic extraction require separate explicit decisions. Graphify is not a 1.3.0 dependency or completion criterion.

Delivery sequence

Step	Deliverable	Dependencies
C1	Coworker: verify the MCP authentication and read-only retrieval contract	None
C2	Context: add provider-neutral connection and packet contracts with a local graph fixture	C1
C3	Coworker: add isolated local account connection and authorization lifecycle	C1, C2
C4	Coworker: retrieve bounded read-only context into validated local packets	C2, C3
C5	Context: deliver the same authorized evidence to orchestrators, builders and peer reviewers	C2, C4
C6	Context: add optional setup, actionable readiness and metadata-only reporting	C3, C4, C5
C7	Coworker: qualify the private pilot and prepare the v1.3 adoption documentation	C1, C2, C3, C4, C5, C6
G1	Context: evaluate official Graphify as a local repository provider for v1.3.x	C2, C5, C7

The default sequence is C1 -> C2 -> C3 -> C4 -> C5 -> C6 -> C7. C2 can use synthetic fixtures while provider access is pending, but C3/C4 production assumptions must follow the verified C1 contract. G1 is a later candidate using the same contract, not a blocker for Coworker.

Code Mower execution protocol

Use this epic as the plan of record and each child issue as one bounded work order. Before implementation, read current repository instructions and acquire the normal session lease in an isolated checkout. Do not take over another active orchestrator's working copy. Use Claude/Codex by default, one assigned builder and one writer per branch. Do not change a child to dispatch-ready until its dependencies and concrete work order are ready.

For each implementation PR: link the child issue, record builder provenance, run focused offline regression tests and relevant CONTRIBUTING checks, and request an independent Code Mower audit of the current PR head. The author cannot satisfy its own peer-review requirement. Fix every P0/P1/P2 blocking finding or use the existing explicit owner-decision mechanism; do not reinterpret a BLOCKED verdict. Keep the required code-mower/gate and normal CI passing before merge. No umbrella implementation PR is required.

Record actual reviewer verdicts, PR/head, tests, dependencies, and next action in child/epic status. Generating critique prompts is not a completed review. Preserve the metadata-only reporting boundary. Release/tag/publication use the existing release lane; this planning epic does not independently authorize publication.

Definition of done

• An explicitly authorized account returns relevant cited context for a bounded private pilot; public evidence uses synthetic/anonymized examples.
• Starting from either Claude or Codex selects the correct connection and delivers the same packet identity to the builder and independent reviewer without sharing credentials.
• Tests demonstrate wrong-account isolation, credential refresh/revocation, stale/changed context, malicious retrieved instructions, size/time bounds, and optional-provider degradation.
• Existing plain setup and old manifests still work with no new provider dependency or login.
• A synthetic graph provider proves the interface supports local revision-bound context.
• Pilot reporting covers useful facts/constraints found, questions to the owner, relevant regression tests, time to reviewed PR, and observed usage/spend; two tasks establish feasibility, not a statistical productivity claim.
• Cold-install/package qualification and privacy checks pass before the feature is included in a release.

Qualified provider contract and operating limits

Coworker's public MCP page describes account/SSO-based access and admin enablement. Its organizational-memory page lists OM2 as Enterprise, separately from the MCP plan statements. The selected-account contract is now qualified in docs/context-provider-contract.md. Search returned bounded OM2 Attribute evidence and partial results; cost remains unknown. Revoking the refresh token prevents renewal, while already-issued access tokens can remain valid. Every dependent fetch and packet replay must therefore force an online refresh and validate signed identity. Runtime capability readiness must still be checked per connection.

Sources: Coworker MCP, Coworker organizational memory, Code Mower v1.2.2, planning, sessions, official Graphify, Graphify domain clarification.

Delivery checklist

• Coworker: verify the MCP authentication and read-only retrieval contract #869 (C1): merged in docs: establish optional context provider boundaries #877, docs: qualify Coworker MCP login, identity, refresh, and search #881 and docs: qualify Coworker revocation before context replay #882
• Context: add provider-neutral connection and packet contracts with a local graph fixture #870 (C2): merged in feat(context): validate private provider-neutral evidence packets #878
• Coworker: add isolated local account connection and authorization lifecycle #871 (C3): merged in feat(context): isolate Coworker account connections and authorization #883
• Coworker: retrieve bounded read-only context into validated local packets #872 (C4): merged in feat(context): retrieve bounded Coworker evidence into private packets #884
• Context: deliver the same authorized evidence to orchestrators, builders and peer reviewers #873 (C5): merged in feat(context): deliver authorized evidence across Claude and Codex reviews #885
• Context: add optional setup, actionable readiness and metadata-only reporting #874 (C6): merged in feat(context): simplify optional setup and readiness #886
• Coworker: qualify the private pilot and prepare the v1.3 adoption documentation #875 (C7): merged in release: v1.3.0 optional Coworker context #887; v1.3.0 published and qualified

Later candidate: #876 (G1), tracked separately from 1.3.0 completion.

Current next action: none for v1.3.0. Graphify remains separately tracked in #876. Private pilot identity and source evidence remain outside this epic.

Implementation and release are complete. Each issue shipped independently through Code Mower; no umbrella implementation PR was required.

Audit follow-up

• Context: enforce single-line Unicode identifiers and citations #879: enforce Unicode single-line identifiers and citations (merged PR fix(context): reject Unicode line separators in identifiers #880).

Final release evidence

• v1.3.0 release and PyPI 1.3.0 are published. Release PR release: v1.3.0 optional Coworker context #887 merged as 97af705639c6fbe5b846e900b15728a451463f44; its tree matches the independently reviewed head.
• Independent current-head Claude audit: PASS, no findings. Required Code Mower gate and Python 3.12–3.14/package CI passed. Full local regression: 2,795 tests passed; privacy, Ruff, compile, no-provider smoke, cold clone and package rehearsal passed.
• Published-package campaign campaign-v1.3.0 is complete. Both required maintained adapters executed: Claude PASS; Codex PASS_WITH_WARNINGS (one installation warning, zero required owner actions). Both ended on 1.3.0.
• Published-package upgrade rehearsal from 1.2.2 to 1.3.0 completed: PASS_WITH_WARNINGS (eight doctor warnings, zero required owner actions). Package installation, Board, lane status and overhead steps passed. Warning details are not retained by the allowlisted result schema.
• Local installation now uses code-mower[coworker]==1.3.0. The installed CLI's explicit online connection diagnostic reports ready/verified_online. Code Mower's own Board was refreshed and reports healthy on 1.3.0.
• Sanitized pilot scorecard: two bounded frozen-reference cases; identical authorized evidence delivered across Claude/Codex orchestrator, builder and reviewer roles. One related-control consistency question was corroborated; the other case added no actionable constraint. This was not a new live private-PR gate trial or a measured productivity gain. Private identities, source evidence and owner follow-up remain local.
• Optional cloud upload remains unconfigured and off. No raw private pilot data was published. Graphify Context: evaluate official Graphify as a local repository provider for v1.4.1 #876 remains a later candidate.

All C1–C7 deliverables are complete; no release blocker or required owner action remains.

[jeffhuber]

C2 implementation is in #878, current head a6b95708ba27f3f06a8a64976f98fa295769414e. Codex is the assigned builder under an isolated Code Mower session; builder provenance is recorded. Independent current-head Claude audit is running through the Code Mower wrapper.

Implemented the optional closed policy/connection/packet contracts, private bounded file reader, authorization-on-replay binding checks, coarse shareable summaries, and additive manifest preservation. Synthetic organization and local repository graph fixtures use one validator without a provider dependency.

Validation so far: 18 new contract tests, 27 work-order tests, 11 trusted plan-context regressions, easy-mode source smoke, privacy scan, Ruff, compileall, and diff checks pass. Full offline suite and CI are running. The contract-only scope and remaining C3/C4/C5 enforcement responsibilities are explicit in the documentation.

The earlier C1 architecture ADR merged as #877 after Claude PASS and all required checks. Authenticated C1 qualification still awaits the customer-supported MCP setup details; no live account data or production tool schema is assumed by this PR.