Bridge profile format — kos-bridge.yaml for pack-shipped artifact descriptions

[arcaven]

Context

Each sideshow pack could ship a kos-bridge.yaml that describes the pack's artifacts in a format kos can consume for seed scanning. This enables automatic knowledge graph population from any sideshow-managed project.

Part of: #9 (SDD system survey)
Ref: kos finding-042

The Problem

kos needs to scan projects and discover what SDD systems are in use, what artifacts exist, and how they map to kos node types. Today this detection logic would need to be hardcoded in kos for each system. With 12+ systems surveyed, that doesn't scale.

Proposed Solution

Each sideshow pack ships a kos-bridge.yaml alongside its pack.yaml. When kos runs a seed scan, it reads bridge profiles from sideshow's install path and uses them to detect and interpret artifacts.

Bridge Profile Structure (sketch)

# kos-bridge.yaml — shipped with each sideshow pack

system: speckit
version: "1.0"

fingerprints:
  - path: .specify/
    type: directory
  - path: .specify/init-options.json
    type: file

version_detection:
  file: .specify/init-options.json
  field: speckit_version
  # or: pattern, command, etc.

artifact_map:
  - glob: "specs/*/spec.md"
    kos_type: requirement
    confidence: frontier
  - glob: ".specify/templates/*.md"
    kos_type: template
    confidence: bedrock
  - glob: ".claude/commands/speckit/*.md"
    kos_type: command
    confidence: bedrock

version_ranges:
  ">=2.0":
    # layout changes in v2
    artifact_map:
      - glob: "specs/*/requirements.md"
        kos_type: requirement

references:
  repo: https://github.com/spec-kit/speckit
  docs: https://speckit.dev/docs
  changelog: https://github.com/spec-kit/speckit/releases

Design Constraints

1. After pack.yaml stabilizes — the bridge profile format depends on sideshow's pack manifest format. Don't design this until pack.yaml is settled
2. Optional — not every pack needs a bridge profile. Packs without one still work; kos just can't auto-detect their artifacts
3. kos owns the interpretation — the bridge profile describes what's there, kos decides what to do with it
4. Version ranges — different system versions may have different artifact layouts. The profile should handle this
5. No runtime dependency — kos reads bridge profiles from disk. It doesn't need sideshow running

Relationship to Other Work

• sideshow pack.yaml format needs to stabilize first
• kos seed scan (not yet built) would consume these profiles
• spectacle's kos-bridge.md (in spectacle repo) documents the integration path conceptually — this issue is about the concrete file format
• Each individual pack candidate issue (Pack candidate: spectacle — IEEE/ISO spec templates #10, Pack candidate: speckit — spec-driven development pipeline #11, Pack candidate: chainlink — hierarchical issue tracker for AI agents #12, Pack candidate: beads — version-controlled issue tracking #13) would eventually ship a bridge profile

Open Questions

• Should the bridge profile live inside pack.yaml as a section, or as a separate kos-bridge.yaml file?
• How does kos discover installed packs' bridge profiles? Does it query sideshow, or scan a known directory?
• Should bridge profiles support custom kos node type definitions, or only map to kos's built-in types?