Skip to content

SD-003: Document-graph profiles and the Technology Atlas

Example from HELIX’s own docs. This generated page comes from docs/helix/. Use it to see the method in practice; start with the artifact-type catalog for reusable templates. Historical plans and reports may describe retired architecture.

Source identity (from 02-design/solution-designs/SD-003-document-graph-profiles-and-technology-atlas.md):

ddx:
  id: SD-003
  authoring:
    home: repo
  status: draft
  depends_on:
    - helix.prd
    - ADR-017
    - ADR-018

SD-003: Document-graph profiles and the Technology Atlas

Status: Implemented in the catalog (profiles, ADR-017/016, component-profile reusable scope, decision-brief, technology-assessment, position-paper, pinned deliverable). Section 1 describes the repository before this work; sections marked Proposed are the design that was implemented; §11 lists what remains.

1. Current state (Confirmed)

AreaBehaviorSource
Flow binding.helix.yml flows: [{id, root}], optional defaults.flow, autonomy. Several flows resolve by cwd-under-root, then defaults.flow, then single entry. Writes outside the active root are refused.skills/helix/SKILL.md §3–4, workflows/modes/check.md
CatalogOne catalog per checkout: workflows/activities/<NN>-*/artifacts/<type>/{meta.yml,template.md,prompt.md}. Every flow resolves the same catalog.SKILL.md §Catalog Resolution
Graphworkflows/graph.yml is generated by scripts/generate_graph.py. It hard-codes methodology.id: helix, one node per artifact type, and only informs edges read from meta.yml relationships.informs. external_edges is always [].scripts/generate_graph.py
Type validationhelix_validate_artifact_meta.py checks required_sections against template H2s and voice-profile references. There is no closed enum of artifact types; a new type directory is accepted.scripts/helix_validate_artifact_meta.py
Instance schemaddx: frontmatter: id, authoring.home (required); type, activity, depends_on, status, supersedes, superseded_by, owner, updated, tags. Open schema: unknown fields ignored.workflows/artifact-schema.md
ddx.linksReferenced by the skill and modes for instance edges and cross_flow: true, not defined in artifact-schema.md, in use as bare id strings and {id, kind: informed_by} mappings (every deliverable).grep
ADRUpdate in place; separate superseding ADR only on request, linked by ddx.supersedes / superseded_by. Authority is positional (design-activity artifact governing downstream work in the same flow).adr/meta.yml
ConcernsRegistry of cross-cutting engineering practices, activated per project. Not a knowledge registry.workflows/concerns/, docs/helix/01-frame/concerns.md
Research-like typescomponent-profile (discover, optional): candidate-by-capability desk research with cited claims, scored alternatives and a verdict.00-discover/artifacts/component-profile/meta.yml
Presentationdeliverable (iterate): deck/one-pager/brief, driven by deliverables/deliverable-mappings.yml, rendered by skills/helix/scripts/render-deck.js.06-iterate/artifacts/deliverable/meta.yml
UMF / umf-visualNo references in this repository.grep

2. Gap analysis

Atlas needsHELIX todayGap
A second graph type in another folderMultiple flows exist; all share one catalog and one graphPer-flow profile selecting types, edge rules, authority
Technology brief/assessment reusable across clientscomponent-profile is project-scoped (needs derived from the project’s artifacts)Reusable scope for an existing type, plus one comparative assessment type
Context-specific recommendation before an ADRNonedecision-brief
Strategic argument over assessmentsNoneposition-paper (deferred)
Typed relationships (addresses, evaluates, contradicts)depends_on, informs, supersedes; ddx.links undefinedExtend the ddx.links {id, kind} shape with new kinds, authority, rev (ADR-018)
Informational vs governing authorityImplicit and positionalExplicit authority class on cross-graph references (ADR-018)
Reproducible publication from pinned revisionsdeliverable has no source pinning or approval gatePinned sources, audience, outputs, review gate (§6)
Reuse by another graph without cloningexternal_edges always empty; cross_flow undefined for external reposPinned external reference shape; resolution is runtime work (ADR-018)
Default-tolerant, publish-strict validationSingle validation tierProfile-keyed default and publish tiers, selected by --tier
Per-profile graph.ymlGenerator is single-methodology and informs-onlyGenerator refactor

3. Proposed: profile binding (see ADR-017)

Keep flows:. Add optional profile: per entry; default software-delivery so every existing marker is unchanged.

flows:
  - id: helix
    root: docs/helix/            # profile defaults to software-delivery
  - id: atlas
    profile: technology-atlas
    root: knowledge/

Terminology: artifact type = meta.yml + template/prompt; graph profile = a catalog file workflows/profiles/<id>.yml selecting types, allowed edge kinds, authority model and validation tiers; graph instance = a flow’s documents under its root; projection = derived output (publication, UMF export, diagram). No new engine: the skill already binds a catalog per flow; the profile only narrows and parameterizes it.

4. Proposed: artifact definitions

TypeDecisionNotes
Technology BriefGeneralize component-profile: allow a reusable scope (needs come from a referenced context rather than project artifacts)Avoids a duplicate type. Decide in the Phase 1 spike whether this is an in-place change or a sibling type.
Technology AssessmentNew technology-assessment (reusable comparison, findings only, pinned briefs)Added: a Decision Brief is contextual and cannot carry a context-free comparison several decisions reuse.
Decision BriefNew decision-briefContextual recommendation prior to an ADR. Feeds an ADR; never replaces it.
Position PaperNew position-paper (argued thesis, objections, limits)Added: takes a side for an audience, unlike the assessment, and is not tied to one client, unlike the brief.
PublicationExtend deliverable (§6)Separate type only if extension distorts the deck-script model.

Sections are semantic expectations, not rigid mandates. required_sections applies at the profile’s publish tier (validate-instance.py --tier publish), not at the default tier. Lifecycle status selects no tier.

5. Proposed: relationships and authority (see ADR-018)

Reuse depends_on, informs, supersedes. Define ddx.links as a list of {id, kind, authority?, rev?}, extending the existing {id, kind} shape. Initial kind vocabulary: addresses, evaluates, supported_by, informs, contradicts. Only contradicts and authority are new semantics.

Authority: within a flow, existing positional authority is unchanged. A reference that crosses a flow or Atlas boundary is advisory unless the consuming graph grants governing explicitly in its own marker or profile.

6. Publication and cross-graph references (pinning implemented; external resolution is runtime work) (see ADR-018)

Implemented (Phase 1): deliverable and decision-brief declare validation.pin_links. At the publish tier every ddx.links mapping of kind informed_by, evaluates, or supported_by must carry rev: git:<commit> (content recoverable) or sha256:<hex> (content verifiable only), never a branch or tag name. A link may carry graph: for a source in another graph; the runtime resolves it and pin-sources.py reports it without failing. skills/helix/scripts/pin-sources.py provides pin (fill revs from git history), check (verify pins resolve, report drift), and materialize (write each source as it was at its rev, so any renderer builds from pinned content). Markdown stays the authoring medium; presentation stays separate from semantics and reuses the present workflow and its renderer. Updating a source never changes an issued deliverable; it means a new revision of the deliverable, re-pinned and re-reviewed. Not implemented: audience, outputs and presentation use the existing Brief, authoring.export and Look fields rather than new keys, and a separate publication type is introduced only if the scenario shows the extension distorts the deck-script model. This is deliberately not an ADR yet; promote it once the scenario confirms the shape.

7. Compatibility and migration

  1. No profile: means software-delivery; behavior is byte-identical.
  2. flows: stays; no helix_version: 3 and no graphs: rename. “Graph” is documentation vocabulary.
  3. workflows/graph.yml stays as the software-delivery graph. The generator grows a --profile option; the default output must not change.
  4. New meta.yml fields are optional and ignored by older consumers (open schema). Unknown frontmatter is preserved per SKILL.md §7.
  5. ddx.links gets a defined vocabulary; existing uses remain valid.

8. Boundaries

  • HELIX: types, profiles, authority semantics, authoring/validation rules.
  • DDx/runtime: resolving external references, pinned fetch, build.
  • UMF / umf-visual: projection only. Not designed here because their contracts are not visible from this repository; a stub projection hook is the most that should be assumed.
  • Atlas instances: actual content.

9. Phase 1: minimal vertical slice and acceptance tests

Scope: one technology assessment, one client decision brief, one reproducible publication.

#Test
T1Existing .helix.yml (no profile:) passes tests/validate-skills.sh unchanged.
T2Two-flow marker (software-delivery + technology-atlas) resolves by cwd; a write into the wrong flow’s root is refused.
T3generate_graph.py default output is byte-identical to the committed graph.yml; --profile technology-atlas emits a separate graph.
T4A decision-brief with missing sections validates at the default tier and fails at the publish tier until sections are present.
T5A product-flow ADR referencing an Atlas assessment treats it as advisory; the same reference does not alter the ADR’s own authority.
T6A publication built from pinned sources is byte-identical after the underlying assessment changes; rebuild at a new pin produces a new publication.
T7contradicts between two assessments is surfaced by align and does not fail validation.

10. Open items

  • Whether component-profile generalizes in place or gets a sibling.
  • Where profile files live (workflows/profiles/ proposed).
  • The UMF and umf-visual contracts (need pointers).
  • Whether the Synaptiq Atlas repository depends on the plugin catalog by version or vendors a profile file.

11. Scenario test

Fixtures: tests/fixtures/scenario-runtime-choice/, synthetic stubs (an atlas repo with two reusable briefs, Node.js and Python; a client repo with a Decision Brief and a pinned publication). Checked by tests/validate-profiles.sh. The real content, such as a database comparison, belongs in the Atlas repository, not here.

Result: the Decision Brief carries a comparison without a Technology Assessment type. Approval is blocked until cross-graph links carry a rev, and an atlas revision stays resolvable after the atlas changes.

Not covered (runtime or other repositories):

  • HELIX pins cross-graph links but does not fetch them, so materialize works only within one repository; resolving graph: is runtime work (§6).
  • Projection to UMF and umf-visual is not designed here (§8).
  • Rendering a publication (HTML, PDF) is present and documentor work; the scenario test checks pinning and validation only.
Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition
model-primary
Issuer
HELIX helix
Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source
artifacts/solution-designs/SD-003-document-graph-profiles-and-technology-atlas.md
Signed
2026-11-16T15:52:45Z
Content digest
sha256:ea28297a…945cc35c

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON
{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-11-16T15:52:45Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/artifacts/solution-designs/SD-003-document-graph-profiles-and-technology-atlas/",
        "digest": {
          "alg": "sha256",
          "value": "ea28297a062fb3ebf2557dbee69cc088948effd3e063bf1b4a0fe6a5945cc35c"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "1v9wND9RhvRhIqtT1ZFHPQpTXZQELMwkr1oZAtN_1Y19Unjxa_be6JUKxCXzx1xeQQMre4S22h6-AalhAHv9CA",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}