Sense 49 — The Branch

Sense 49 · Forming · Last touched 2026-08-20

last_verified: 2026-07-27

Synced from docs/design/sense_49_the_branch.md in the engine repo — that’s the source; this page is a build-time mirror.

A pack is a trunk. Branches are opt-in modules that carry Anchors, Facts, source systems, Gold contract entries, and the themes that stand on them. A tenant grafts the branches it needs — and only those. Grafting a branch enables its full stack; leaving one out leaves its concerns invisible. Same pack. Different weight per tenant.

Status: proposed Authors: the owner + Claude (drafting, 2026-07-02) Reference: the_jinflow.md; Senses 20 (Seam), 26 (Workshop), 27 (Funnel), 36 (Lineage), 42 (Landscape).

The problem

A rich domain pack accumulates concerns.

For a hospital, numetrix started as material flow and grew to touch supply-org pricing, billing reconciliation, revenue leakage, catalogue health, cost-centre integrity. For an academic-medical institution, hrcentral started as workforce visibility and — under the pressure of a real stakeholder’s questions — wants to grow into strategic-objective execution, HR program effectiveness, recruiting funnel quality, performance analytics, publication productivity, cohort pipeline. Each is a legitimate concern for some tenants; none is legitimate for every tenant.

Today’s pack architecture doesn’t let a tenant choose. A pack ships as a monolith. jin init --pack hrcentral gives every tenant every signal, every thesis, every verdict, every source-system contract, every Wisdom entry, every Gold column. Tenants that only need workforce visibility carry the weight of everything a demanding prospect has asked for. Tenants that need a specialist concern the pack doesn’t ship carry nothing.

Both failure modes have the same shape: the unit of adoption is the whole pack, when the unit of concern is much smaller.

This Sense proposes the smaller unit: the branch.

The core claim

A pack decomposes into a set of branches. A branch is the smallest unit of pack composition that carries a coherent concern end-to-end — from source system to Anchors to Facts to Gold contract to instrument themes.

A tenant declares which branches it grafts at init. The rest are absent. Not merely disabled — absent. Their Anchors are not registered, their Gold columns are not present, their source-system contracts are not required, their instrument themes are not compiled, their Wisdom entries are not baked. The tenant’s KLS is literally lighter.

Grafting a new branch later is a discrete verb — jin afs graft <branch> — that pulls the branch’s full stack into the tenant AFS, extends the Gold contract, requires the source systems, and compiles the themes. Removing a branch is the mirror: jin afs prune <branch>. Both are versioned pack operations, subject to the same Seam discipline (Sense 20) as pack updates.

The pack is the trunk. Branches are what the tenant grafts on.

What a branch is made of

A branch is a coherent bundle across the pack’s structural layers. Concretely, a branch declares:

1. Source systems it depends on

Named entries in the pack’s source_types. A branch cannot activate without the tenant providing all of its source systems — the extractor contract (Sense 31: The Inlet) is the gate. If a branch requires an lms feed and the tenant hasn’t set one up, the branch cannot graft. This makes source dependencies explicit rather than assumed.

2. Anchors and Facts it introduces

Named entity types the branch adds to the pack’s substrate. A branch’s Anchors are only registered in the tenant KLS when the branch is grafted. Their tables are created; without the graft, they simply don’t exist. Same for Facts. This keeps the substrate minimal.

Cross-branch references are allowed but explicit — a branch can reference Anchors from another branch it depends on, and its manifest declares that dependency (depends_on: [workforce_state]). Grafting a dependent branch pulls its dependencies automatically.

3. Gold contract entries

The columns each branch’s Anchors and Facts add to the Gold layer. When a branch is not grafted, its Gold columns are not part of the tenant’s Gold contract. This means signals from other branches cannot reference columns that don’t exist — no dangling references, no runtime “column not found” errors.

4. Instrument themes

The signals, perspectives, theses, verdicts, and Wisdom that stand on the branch’s substrate. Themes are the analytical output of a branch — the reason it exists.

A branch typically hosts one to five themes, each with its own set of signals plus a perspective and verdict layer. The themes are the reason a stakeholder cares about grafting the branch.

5. Design notes (extends Sense 26)

Each branch ships its own scoped design notes. When a tenant grafts a branch, the branch’s design notes travel with the graft. This means stakeholders reading a tenant’s JinDesk can find the why of each instrument without leaving the tenant surface — extends the Workshop pattern from artefact-level to branch-level.

6. Wisdom scope

The pack’s Wisdom entries are declared per branch. Wisdom entries outside every branch are trunk-Wisdom — always present. Wisdom entries inside a branch are only present when the branch is grafted. This matters both for JinDesk rendering (the tenant sees only the Wisdom that applies to it) and for jin evolve’s structural awareness: an AI colleague reasoning about a tenant knows which branches are grafted → knows which Anchors exist → won’t propose analyses over concerns the tenant doesn’t have.

Anatomy: what a branch manifest looks like

A branch declares itself in a branch.yml file at packs/<pack>/branches/<branch_id>/. Sketch of the required fields:

branch_id: intentional_workforce
name:
  en: Intentional Workforce Management
  de: Absichtsvolle Personalführung
  fr: Gestion intentionnelle du personnel
description:
  en: |
    Plans, programs, sources — the intentional side of workforce
    management. Answers "what did we set out to do, what did we
    invest in, and where did we get our people from?"

depends_on:
  - workforce_state

source_systems:
  - lms
  - finance_hr
  - performance_mgmt
  - ats

anchors:
  - StrategicObjective
  - HRProgram
  - PerformanceReview
  - CompensationBand
  - Candidate
  - Application
  - RecruitingSource
  - InterviewStage
  - AssessmentType

facts:
  - ObjectiveOutcome
  - ProgramParticipation
  - PerformanceRating
  - CompensationChange
  - ProductivityMetric
  - ApplicationEvent
  - AssessmentResult
  - OfferMade
  - HireLinkage
  - RecruitingCost

gold_contract:
  extends:
    - path: contracts/gold_contract.v1.json
      adds:
        - StrategicObjective
        - HRProgram
        # ... etc.

themes:
  - strategic_execution
  - hr_program_effectiveness
  - recruiting_funnel_quality

wisdom:
  scope: branch
  files:
    - smebit_perspective_is_correlation_not_causation
    - smebit_assessment_predictive_validity_requires_periodic_recalibration
    # ... etc.

The branch is its own thing — a first-class artefact under branches/, alongside signals/, theses/, verdicts/ etc. Every artefact in the pack that belongs to a branch declares its membership with a branch: field. Trunk artefacts (belonging to no branch) declare no such field.

Grafting: the tenant side

A tenant declares its grafted branches in the tenant AFS jinflow.yml:

pack: hrcentral
pack_version: 0.6.0
branches:
  - workforce_state       # trunk-adjacent — always sensible
  - intentional_workforce  # opt-in for this tenant

jin init accepts --branches <list> (default: only branches marked recommended_default: true in the pack manifest). jin afs graft <branch> adds one after the fact. jin afs prune <branch> removes one, subject to a safety check that no downstream artefacts reference the branch.

Grafting is versioned — jin afs graft intentional_workforce@0.6.0 pins the branch’s version to the pack version’s snapshot of it. This matters when the pack ships an updated branch and the tenant hasn’t adopted the newer version yet.

Lifecycle: init, graft, prune, upgrade

The four lifecycle operations, each expressed at branch grain:

init

jin init --pack hrcentral --branches workforce_state,intentional_workforce creates a tenant AFS with only the two branches’ artefacts + trunk artefacts. Gold contract is composed from the trunk + the two branches’ entries. Source systems required: the union of the two branches’ declarations.

graft

jin afs graft <branch> pulls a not-yet-active branch into the tenant AFS. The Seam pattern (Sense 20) mediates — pack files are copied into the tenant AFS with provenance markers (📦 pack-original per Sense 36 Lineage). Gold contract is re-composed. Source systems required expand.

prune

jin afs prune <branch> removes an active branch’s artefacts from the tenant AFS. Safety check: any tenant-original artefact that references a branch-owned Anchor or Fact blocks the prune. Once resolved, the branch is removed. Gold contract shrinks; source systems no longer required.

upgrade

Pack version bumps can update a branch. jin afs update (existing verb from Sense 20) now works at branch grain: it can update just the branches the tenant has grafted, leaving un-grafted branches alone. This matters because a tenant that has never grafted the recruiting-funnel branch shouldn’t be forced to reason about its changes.

The Wisdom of “not everything”

The subtle claim underneath this Sense: a pack that ships everything is a pack that has no opinions. If hrcentral ships all possible workforce concerns, it says nothing about which concerns are proximate to which tenants. A tenant learning what to care about learns nothing from adoption.

Branches force the pack to have opinions. Every branch is a statement: these concerns belong together, and a tenant can sensibly want them or sensibly not want them. The pack’s branch catalogue becomes a map of the domain’s concerns, at a resolution a stakeholder can navigate.

For hrcentral, this Sense predicts a branch catalogue roughly:

workforce_state — the current core (workforce visibility, overcommitment, credential compliance, succession fragility, affiliation drift, data protection, infrastructure stewardship, project portfolio). Default-recommended for every tenant.
intentional_workforce — new. Strategic execution + HR program effectiveness + recruiting funnel quality. What Statements 1, 3, and 5 collectively point at.
research_output — new. Publication productivity + research activity + grant success. Gold has Publication and Grant Anchors already, no themes stand on them.
student_pipeline — new. Cohort funnel + SIS reconciliation. Wisdom already exists (smebit_bachelor_master_doctoral_funnel); no signals yet.
event_dynamics — new. Wave analysis of hire/departure/promotion events. Gold has Event but no themes.

Any given tenant grafts some subset. VAI probably grafts all five. A small clinical institute might graft only workforce_state. A research consortium might graft workforce_state + research_output.

Cross-references

Sense 20 — The Seam. Branches are the unit of pack↔tenant mediation. The Seam already carries pack updates through jin afs update; it now carries branch grafts/prunes. The Seam pattern (Anchor stability, Fact evolution, deprecation cycles) applies at branch grain.

Sense 26 — The Workshop. Packs ship design notes; branches ship their own scoped ones. This extends the Workshop pattern from artefact-level design notes to branch-level design notes, plus trunk-level notes for the pack as a whole.

Sense 27 — The Funnel. Narrow at the source. Sense 27 said aggregations travel; rows stay home. This Sense adds: concerns travel; irrelevant substrate stays absent. Tenants narrow at the concern level, not just the row level.

Sense 36 — The Lineage. A tenant remembers its birth pack; extends now to remember its grafted branches, their versions, and graft/prune events over time. Every branch operation lands in the tenant’s lineage record.

Sense 42 — The Landscape. River + Garden as substrate. Branches organise what’s allowed to sit in the Garden. Grafting a branch extends the Garden with the branch’s Gold columns; pruning shrinks it. The Garden’s shape becomes tenant-specific in a controlled way.

Sense 31 — The Inlet. Extractor discipline per source system. Branches make source-system dependency explicit — a branch that requires lms cannot graft into a tenant that hasn’t set up the lms inlet.

Open questions

Do trunk-only packs exist? — Could a pack ship no branches, just a trunk? Probably yes — small packs with a single coherent concern don’t need branches. The trunk is the pack. Sense 49 applies where composition is beneficial, not where it’s forced.
Can branches ship different pack authors? — Could an independent contributor publish a hrcentral::research_output branch alongside the core pack? The manifest supports this conceptually, but the tooling would need branch-level trust signals (Sense 25 Pass adjacent). Deferred.
What happens when Anchor semantics diverge across branches? — If two branches both introduce a Person-like Anchor with different meanings, they can’t both graft. Resolution: pack authors negotiate at pack time; the pack ships a coherent set of Anchors regardless of which branch introduces them. The trunk holds the base Anchors; branches only extend.
How does JinDesk render branch state? — Grafted vs ungrafted branches probably need a visible affordance somewhere (e.g. an “About this tenant” surface that lists grafted branches, their versions, and their design notes). Follows once the substrate lands.
Provenance for branch operations. — Every graft or prune event is a first-class lineage entry (per Sense 36). The Ledger (Sense 18) records who initiated the graft. Same discipline applies to branches as to any AFS-write event.

Phase 1 — what we ship first

The minimum viable form of this Sense:

A branches/ directory in packs. Each branch is a folder with a branch.yml manifest declaring source_systems, anchors, facts, themes, wisdom.
Membership field on artefacts. Existing artefact YAMLs (signals, theses, verdicts, smebits, dossiers, perspectives) gain a branch: field. Trunk artefacts declare none.
Tenant jinflow.yml gains branches: — an ordered list of grafted branch IDs.
jin init --branches — accepts a list; defaults to the pack manifest’s recommended_default branches.
jin afs graft, jin afs prune, jin afs branches — three new subcommands. Graft adds a branch. Prune removes one (with safety check). Branches lists what’s grafted, with versions.
Compilation respects branch scope. Signal/thesis/verdict/ smebit/dossier compilers filter by grafted branches. Only grafted artefacts land in the tenant KLS.
Gold contract composition. The tenant’s effective Gold contract is pack_trunk ∪ (all grafted branches' contract entries). dbt sees only that.
Lineage records branch operations. Every graft/prune lands in the tenant’s lineage record per Sense 36.

Deferred: cross-pack branches, JinDesk branch UI, per-branch capability scoping, per-branch trust signals.

The hrcentral test

This Sense was born watching a real stakeholder’s questions overwhelm a monolithic pack. The test of whether it’s the right shape: can hrcentral be split into workforce_state + intentional_workforce

research_output + student_pipeline + event_dynamics without any tenant losing what it already had? And can the same tenant grow into more branches over time without a rebuild?

If yes — and the sketch above suggests yes — this Sense earns its number.

the_jinflow.md — the five-name model
sense_20_the_seam.md — pack ↔ tenant mediation
sense_26_the_workshop.md — packs ship their own design notes
sense_27_the_funnel.md — narrow at the source
sense_31_the_inlet.md — extractor discipline
sense_36_the_lineage.md — the tenant remembers its birth pack
sense_42_the_landscape.md — River + Garden as substrate

Numerical neighbors: ← Sense 48: The Stage — dev/prod plane separation · Sense 50: The Beacon →

jinflow is a jazzisnow product

v0.64.7 · built 2026-09-20 19:48 UTC 