Spec slice: GitHub planning lineage

[ganesh47]

Parent: #32

Source slice: docs/specs/cstack-github-planning-lineage-slice.md

GitHub Planning Lineage Slice

Historical note:

• This document is a future slice spec, not part of the active shipped contract.
• The active shipped contract remains docs/specs/cstack-spec-v0.1.md.
• This slice defines how GitHub should become part of the planning control plane for cstack.

Thesis

cstack should treat GitHub issues as first-class planning anchors that can be linked to discover, spec, build, review, ship, and deliver runs through durable local artifacts.

Why This Slice Exists

Current cstack already uses GitHub as part of delivery:

• issue linkage during ship and deliver
• PR and release evidence
• GitHub-aware readiness evaluation

What is still missing is planning lineage:

• explicit run-to-issue relationships
• issue-aware spec synthesis
• inspector views that show issue, PR, and release lineage together
• artifact contracts that let the user reconstruct the planning graph locally

Product Decision

This slice makes GitHub part of the planning control plane without making GitHub the durable source of truth.

The durable source of truth remains the local run directory. GitHub linkage is recorded as referenced external state.

Scope

This slice owns:

• issue-to-run linkage in run metadata
• spec issue synthesis from saved planning artifacts
• issue references inside run artifacts
• issue and PR lineage views in inspect
• local artifact schemas for issue linkage and planning lineage

This slice does not own:

• deployment evidence
• post-ship monitoring loops
• validation strategy generation

Independent Team Contract

The GitHub planning lineage team is responsible for:

• run metadata additions for issue linkage
• issue-aware spec and planning outputs
• artifact storage for linked issue state
• inspector support for upstream and downstream GitHub planning lineage

The team is explicitly not responsible for:

• introducing a new deployment workflow
• changing the validation stage logic
• building initiative-level grouping beyond issue-scoped lineage

Command and Workflow Impact

Likely future surface:

• spec --issue <n>
• discover --issue <n>
• deliver --issue <n> continues to exist, but records richer linkage
• optional issue synthesis or issue-update step from spec

Hard rule:

• any GitHub write must remain optional and policy-driven
• the local run must still be useful even when GitHub mutation is disabled

Artifact Contract

Recommended additions:

• artifacts/github-planning.json
• artifacts/issue-draft.md
• artifacts/issue-lineage.json

Recommended meanings:

• github-planning.json
  • normalized issue linkage and planning state observed or requested for the run
• issue-draft.md
  • proposed issue body synthesized from discover or spec artifacts
• issue-lineage.json
  • issue, run, PR, and release references connected to this run

Recommended issue-lineage.json shape:

{
  "linkedIssue": {
    "number": 123,
    "repo": "ganesh47/cstack",
    "state": "open"
  },
  "sourceRuns": [
    {
      "runId": "discover-20260327-120000",
      "workflow": "discover"
    }
  ],
  "derivedRuns": [
    {
      "runId": "spec-20260327-121500",
      "workflow": "spec"
    }
  ],
  "pullRequests": [
    {
      "number": 45,
      "state": "open"
    }
  ],
  "releases": [
    {
      "tag": "v0.18.0",
      "state": "draft"
    }
  ]
}

Inspector and Ledger Expectations

inspect should be able to show:

• linked issue
• source planning runs
• downstream PR and release references
• whether issue linkage was requested, observed, created, updated, or unavailable

runs should be able to filter or summarize by linked issue when this slice ships.

Acceptance Criteria

This slice is complete when:

• a run can be explicitly tied to a GitHub issue
• spec can emit a structured issue draft artifact
• inspect can show upstream and downstream issue and PR lineage
• all issue lineage is reconstructable from local artifacts alone

Release Boundary

First release for this slice should include:

• issue-linked run metadata
• issue draft synthesis capability
• issue-aware inspector support

It should not require:

• post-ship feedback support
• initiative graph support
• deployment evidence support

Non-Goals

This slice should not:

• make GitHub the only planning surface
• require issue mutation for local planning workflows
• hide GitHub API gaps behind fake certainty
• introduce broad project-management abstractions beyond issue-scoped lineage

[ganesh47]

Kickoff note: this issue is now the independent execution thread for the GitHub planning lineage workstream under #32. A codebase-mapping agent is collecting exact touchpoints, first-slice scope, risks, and test coverage recommendations so implementation can begin without depending on the other workstreams.

[ganesh47]

Autonomous team kickoff:

• Parent umbrella: Spec: end-to-end product delivery workstreams beyond gstack #32
• Source slice: use the spec body already attached to this issue as the contract.
• Execution rule: first release must be independently shippable and artifact-driven.
• Evaluation rule: prove product value, operational independence, and inspection quality.
• Deliverables for the first implementation slice:
  • explicit artifact schema
  • inspector or ledger impact
  • tests for the new artifact/reporting surface
  • clear non-goals to keep the slice bounded

[ganesh47]

Implementation kickoff from codebase scan:

• Primary touchpoints: src/types.ts, src/commands/spec.ts, src/prompt.ts, src/inspector.ts, optional later src/run.ts.
• First shippable slice:
  • add cstack spec --issue <n>
  • persist planning-specific issue metadata in run.json
  • write artifacts/issue-draft.md
  • write artifacts/issue-lineage.json
  • extend inspect with a narrow issue-aware summary and show issue
• Keep GitHub mutation out of the first slice. Local artifact synthesis is enough for the first independent release.
• Tests to add:
  • test/spec.test.ts for --issue, issue-linked run metadata, issue-draft.md, and issue-lineage.json
  • test/inspect.test.ts for issue-aware inspection and show issue

Non-goals for the first release:

• creating or updating GitHub issues remotely
• initiative grouping
• downstream PR/release backfill

[ganesh47]

Kickoff mapping from the current codebase:

First shippable slice:

• add issue-linked run metadata for discover and spec
• emit artifacts/issue-draft.md and artifacts/issue-lineage.json
• surface linked issue plus downstream PR/release references in inspect

Primary code touchpoints:

• src/types.ts
• src/commands/spec.ts
• src/commands/discover.ts
• src/run.ts
• src/github.ts
• src/inspector.ts
• test/spec.test.ts
• test/discover.test.ts
• test/inspect.test.ts

Constraint:

• GitHub must stay optional; local artifacts remain the durable source of truth.

[ganesh47]

Autonomous workstream kickoff:

• Parent umbrella: Spec: end-to-end product delivery workstreams beyond gstack #32
• This workstream must ship a first useful release without waiting on the other five slices.
• The first implementation slice must define: artifact schema, inspector impact, tests, and explicit non-goals.
• Keep local artifacts as the durable source of truth.
• Record requested behavior separately from observed behavior.
• Do not expand scope into deployment orchestration, post-ship loops, or initiative graphs in the first slice.

Repo tracker: docs/research/cstack-end-to-end-workstream-tracker.md

[ganesh47]

Execution kickoff:

• First shippable slice: add issue-linked run metadata, spec issue-draft synthesis, and issue-aware inspector output.
• Primary code touchpoints: src/types.ts, src/run.ts, src/commands/spec.ts, src/commands/discover.ts, src/commands/ship.ts, src/commands/deliver.ts, src/github.ts, src/inspector.ts, src/prompt.ts.
• First tests: issue-linked spec artifacts, persistence in run.json, and inspect rendering of linked issue plus downstream PR/release lineage.
• Constraint: GitHub linkage stays optional and artifact-derived; GitHub is not the durable source of truth.

Tracker: docs/research/cstack-workstream-execution-tracker.md

[ganesh47]

Autonomous kickoff note:

• Local tracker: docs/research/cstack-workstream-kickoff-tracker.md
• First shippable slice: add --issue <n> to spec, persist linked issue numbers into run.json, write artifacts/issue-draft.md and artifacts/issue-lineage.json, and surface issue linkage in inspect.
• Primary code touchpoints: src/types.ts, src/commands/spec.ts, src/commands/discover.ts, src/run.ts, src/inspector.ts, src/github.ts.
• Initial tests: test/spec.test.ts, test/inspect.test.ts, test/runs.test.ts.
• Non-goal for v1: do not require GitHub mutation or initiative-level grouping.

[ganesh47]

Implementation status update:

The first independent slice is now implemented locally.

Delivered in code:

• cstack spec --issue <n>
• planning issue metadata persisted in run.json
• artifacts/issue-draft.md
• artifacts/issue-lineage.json
• inspect support via summary output and show issue
• rerun preserves planning issue linkage

Verification run locally:

• npm run typecheck
• npm test -- --run test/spec.test.ts test/inspect.test.ts test/prompt.test.ts

[ganesh47]

Implementation status update: this workstream is complete in current branch.

Implemented:

• planning issue linkage in run metadata for discover/spec/build/review/ship/deliver via planningIssueNumber fields
• cstack spec --issue support
• persisted artifacts/issue-draft.md and artifacts/issue-lineage.json
• inspect shows issue-aware lineage with upstream/downstream issue, PR, and release refs
• rerun and downstream lineage rendering now preserve planning issue context

Verification: npm run typecheck and npm test (all suites pass), with targeted coverage in test/spec.test.ts, test/inspect.test.ts, and test/prompt.test.ts.

[ganesh47]

Completed by PR #46, merged into main on March 28, 2026 as commit 8c115d3.