Spec slice: Initiative graph and run control plane

[ganesh47]

Parent: #32

Source slice: docs/specs/cstack-initiative-graph-slice.md

Initiative Graph And Run Control Plane 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 cstack should move from single-run lineage into initiative-level grouping and inspection.

Thesis

cstack should support a higher-level initiative graph that groups issues, runs, pull requests, releases, mitigations, and follow-up work into one local-first control plane without introducing a remote scheduler or database as the source of truth.

Why This Slice Exists

Current lineage is strong inside one run and across direct parent-child run relationships.

What remains missing is a durable answer to:

• which runs belong to one initiative
• which PRs and issues are part of the same product effort
• how follow-up mitigations connect back to the originating work
• how operators inspect one initiative rather than one run at a time

Product Decision

This slice adds initiative-level metadata and inspection while keeping run directories as the source of truth.

The first release should use artifact-derived grouping, not a separate service or hidden state store.

Scope

This slice owns:

• initiative or epic identifiers in run metadata
• initiative graph artifacts
• grouped inspection over related runs, issues, PRs, releases, and follow-ups
• initiative-aware run ledger views
• parent-child work item linkage above the single-run level

This slice does not own:

• validation internals
• deployment evidence collection
• GitHub mutation semantics already handled by ship or deliver

Independent Team Contract

The initiative graph team is responsible for:

• initiative metadata model
• cross-run graph artifact model
• initiative-aware runs output
• grouped inspect surfaces

The team is explicitly not responsible for:

• adding new workflow stages
• changing review or ship policy
• replacing local artifacts with a persistent service

Metadata Model

Recommended additions to run metadata:

• initiativeId
• initiativeTitle
• parentWorkItem
• relatedWorkItems

Recommended work item kinds:

• issue
• run
• pull-request
• release
• follow-up
• mitigation

Artifact Contract

Recommended additions:

• artifacts/initiative-graph.json
• artifacts/initiative-summary.md

Recommended meanings:

• initiative-graph.json
  • normalized relationship graph for the current initiative
• initiative-summary.md
  • operator-readable summary of current initiative state, open branches, and remaining work

Recommended initiative-graph.json shape:

{
  "initiative": {
    "id": "initiative-identity-hardening",
    "title": "Identity hardening"
  },
  "nodes": [
    {
      "kind": "issue",
      "id": "issue-123",
      "label": "#123"
    },
    {
      "kind": "run",
      "id": "spec-20260327-120000",
      "label": "spec"
    }
  ],
  "edges": [
    {
      "from": "issue-123",
      "to": "spec-20260327-120000",
      "type": "planned-by"
    }
  ]
}

Ledger and Inspector Expectations

runs should be able to:

• group by initiative
• summarize initiative status
• show recent runs within one initiative

inspect should be able to:

• show the initiative summary
• show related issues, PRs, releases, and follow-ups
• explain how a mitigation or follow-up connects back to the originating initiative

Acceptance Criteria

This slice is complete when:

• multiple runs can be grouped under one initiative
• runs and inspect can surface initiative-level state
• initiative lineage remains artifact-derived and local-first
• follow-up and mitigation work can be connected back to the originating initiative

Release Boundary

First release for this slice should include:

• initiative metadata in runs
• initiative graph artifacts
• initiative-aware ledger and inspector views

It should not require:

• GitHub issue mutation
• post-ship feedback support
• capability-pack policy support

Non-Goals

This slice should not:

• become a generic PM tool
• require every run to belong to an initiative
• introduce opaque global state that cannot be rebuilt from artifacts

[ganesh47]

Kickoff note: this issue is now the independent execution thread for the initiative graph and run control plane workstream under #32. A codebase-mapping agent is collecting exact touchpoints, first-slice scope, risks, and test coverage recommendations so implementation can proceed independently.

[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]

Kickoff mapping from the current codebase:

First shippable slice:

• add optional initiative metadata to run records
• emit artifacts/initiative-graph.json
• support initiative-aware summaries in runs and inspect

Primary code touchpoints:

• src/types.ts
• src/run.ts
• src/commands/runs.ts
• src/commands/inspect.ts
• src/inspector.ts
• test/run.test.ts
• test/runs.test.ts
• test/inspect.test.ts
• test/intent.test.ts

Constraint:

• use artifact-derived grouping only; do not introduce a remote state service.

[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 add a remote scheduler or opaque state service in the first slice.

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

[ganesh47]

Execution kickoff:

• First shippable slice: add initiative metadata to runs and derive grouped initiative views from existing run directories.
• Primary code touchpoints: src/types.ts, src/run.ts, src/commands/runs.ts, src/commands/inspect.ts, src/inspector.ts.
• First tests: runs with shared initiative metadata group in ledger output, and inspect renders initiative summary plus related runs.
• Constraint: artifact-derived grouping only; no remote state service and no requirement that every run belong to an initiative.

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

[ganesh47]

Implementation kickoff from current codebase shape:

• Primary touchpoints: src/run.ts, src/commands/runs.ts, src/inspector.ts, src/types.ts, plus any workflow command that writes run.json.
• First shippable slice:
  • add initiative-scoped metadata to RunRecord.inputs or adjacent run metadata
  • generate a local initiative-graph.json artifact
  • extend runs and inspect to show grouped initiative state without adding a remote datastore
• Keep the first release artifact-derived. The source of truth remains .cstack/runs/<run-id>/.
• Tests to add:
  • grouped ledger output for runs that share an initiative id
  • initiative-aware inspection over related runs
  • clean behavior when a run has no initiative metadata

Non-goals for the first release:

• PM-suite behavior
• mandatory initiative assignment
• remote coordination service

[ganesh47]

Autonomous kickoff note:

• Local tracker: docs/research/cstack-workstream-kickoff-tracker.md
• First shippable slice: add optional initiativeId and initiativeTitle to one initiating workflow first, persist initiative-graph.json, and expose initiative grouping in runs and inspect using artifact-derived local state only.
• Primary code touchpoints: src/types.ts, src/run.ts, src/commands/runs.ts, src/inspector.ts, plus one initiating workflow command such as src/commands/spec.ts.
• Initial tests: test/runs.test.ts, test/inspect.test.ts, targeted command tests.
• Non-goal for v1: no remote scheduler or external state service.

[ganesh47]

Implementation status update: this workstream is now implemented and validated.

Implemented:

• initiative metadata fields are attached in run inputs
• initiative graph artifacts are generated (artifacts/initiative-graph.json) for initiative-level grouping
• runs and inspect output support initiative-aware grouping/summaries
• run lineage can be reconstructed by initiative across multiple runs

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

[ganesh47]

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