Spec slice: Capability-pack governance

[ganesh47]

Parent: #32

Source slice: docs/specs/cstack-capability-pack-governance-slice.md

Capability-Pack Governance 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 workflow-attached capabilities should become explicit, policy-visible, and inspectable.

Thesis

cstack should expose capability packs as a first-class policy surface so workflows can declare which external research, browser, GitHub, shell, or other capability families are allowed, requested, available, and actually used.

Why This Slice Exists

The current product already implies capability boundaries through workflow design and local tooling.

What is still missing is a stable contract for:

• which capability packs a workflow may attach
• which packs were requested versus actually available
• when external research or browser use was allowed by policy
• how capability usage is made inspectable after the run

Product Decision

This slice turns capability-pack governance into explicit config, artifact, and inspection surfaces.

It should strengthen workflow control without turning capability attachment into prompt soup.

Scope

This slice owns:

• workflow-level capability allowlists
• config for requested versus allowed capability packs
• artifact recording for requested, available, and used capabilities
• external research and browser-use policy visibility
• inspector views for capability usage

This slice does not own:

• issue lineage semantics
• validation strategy design
• initiative graph UX

Independent Team Contract

The capability-pack governance team is responsible for:

• capability config schema
• workflow attachment rules
• requested-versus-observed capability recording
• inspector support for capability visibility

The team is explicitly not responsible for:

• inventing new workflows solely to justify capability packs
• embedding arbitrary role files into prompts
• broad autonomous orchestration semantics

Capability Model

Recommended capability families:

• shell
• web
• github
• browser
• mcp:<server>
• skill:<name>

Each workflow should be able to record:

• allowed packs
• requested packs
• available packs
• used packs
• downgraded or denied packs

Config Contract

Recommended future config shape:

[workflows.discover.capabilities]
allowed = ["shell", "web", "github"]
defaultRequested = ["shell"]

[workflows.deliver.capabilities]
allowed = ["shell", "github", "browser"]
defaultRequested = ["shell", "github"]

Artifact Contract

Recommended additions:

• artifacts/capabilities.json
• artifacts/capability-policy.md

Recommended meanings:

• capabilities.json
  • requested, allowed, available, used, and denied capability packs for the run
• capability-policy.md
  • human-readable explanation of workflow capability posture and downgrades

Recommended capabilities.json shape:

{
  "workflow": "discover",
  "allowed": ["shell", "web", "github"],
  "requested": ["shell", "web"],
  "available": ["shell"],
  "used": ["shell"],
  "downgraded": [
    {
      "name": "web",
      "reason": "disabled by repo policy"
    }
  ]
}

Inspector and Ledger Expectations

inspect should be able to show:

• which capabilities were requested
• which were actually available
• which were used
• which were downgraded or denied and why

runs may later expose coarse capability summaries for filtering and audit.

Acceptance Criteria

This slice is complete when:

• workflows can declare allowed capability packs
• run artifacts show requested, available, and actually used capabilities
• external research is policy-visible rather than implicit
• capability usage remains bounded and inspectable

Release Boundary

First release for this slice should include:

• capability config schema
• workflow policy integration
• capability artifacts
• inspector support for capability visibility

It should not require:

• initiative graph support
• issue lineage support
• validation strategy support

Non-Goals

This slice should not:

• encourage unconstrained prompt assembly
• imply that capability availability is identical across environments
• hide downgraded capabilities behind silent fallback

[ganesh47]

Kickoff note: this issue is now the independent execution thread for the capability-pack governance 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:

• generalize existing discover-time requested/available capability recording into a workflow-level capability contract
• record allowed, requested, available, and used capabilities in run artifacts
• make external research policy visible in inspect

Primary code touchpoints:

• src/types.ts
• src/config.ts
• src/discover.ts
• src/prompt.ts
• src/validation.ts
• src/inspector.ts
• test/config.test.ts
• test/discover.test.ts
• test/prompt.test.ts
• test/validation.test.ts

Constraint:

• keep downgrades explicit and avoid turning capability packs into arbitrary prompt concatenation.

[ganesh47]

Execution kickoff:

• First shippable slice: add workflow capability policy in config and artifact recording for allowed/requested/available/used capabilities.
• Primary code touchpoints: src/config.ts, src/types.ts, src/discover.ts, src/validation.ts, src/prompt.ts, src/inspector.ts.
• First tests: config accepts capability policy, discover writes capability artifacts, and inspector renders downgrades plus reasons.
• Constraint: no arbitrary prompt concatenation and no silent capability fallback.

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

[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 turn capability governance into unconstrained prompt assembly in the first slice.

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

[ganesh47]

Implementation kickoff from current codebase shape:

• Primary touchpoints: src/config.ts, src/types.ts, src/commands/discover.ts, src/commands/spec.ts, src/commands/deliver.ts, src/discover.ts, src/validation.ts, src/inspector.ts.
• Existing signals already worth building on:
  • discover records requestedCapabilities and availableCapabilities in research-plan.json
  • discover records webResearchAllowed
  • config already has workflow-local policy for research and validation behavior
• First shippable slice:
  • define workflow capability allowlists in config
  • record requested, allowed, available, and used capability families in a common artifact
  • surface capability downgrades or denials in inspect
• Recommended first artifact:
  • artifacts/capabilities.json
• Keep the first release limited to visibility and policy, not dynamic capability negotiation across every tool surface.
• Tests to add:
  • config validation for workflow capability allowlists
  • discover/spec/deliver runs record capability visibility consistently
  • inspector shows capability downgrades and web research policy clearly

Non-goals for the first release:

• arbitrary prompt-pack composition
• hidden fallback when a capability is denied
• new workflow surface created only to justify capability packs

[ganesh47]

Autonomous kickoff note:

• Local tracker: docs/research/cstack-workstream-kickoff-tracker.md
• First shippable slice: add capability allowlists for discover and deliver, write capabilities.json and capability-policy.md, and render requested vs available vs used capabilities in inspect.
• Primary code touchpoints: src/types.ts, src/config.ts, src/prompt.ts, src/discover.ts, src/validation.ts, src/inspector.ts.
• Initial tests: test/config.test.ts, test/prompt.test.ts, test/discover.test.ts, test/inspect.test.ts.
• Non-goal for v1: do not turn capability packs into unconstrained prompt assembly.

[ganesh47]

Implementation status update: this workstream is now implemented.

Implemented:

• workflow-level capability policy in config with allowed/default requested packs
• run artifacts now record requested/available/used capability families and policy denials
• external research policy downgrades are inspectable
• inspect shows capability usage and downgrade reasons

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

[ganesh47]

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