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-018SD-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)
| Area | Behavior | Source |
|---|---|---|
| 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 |
| Catalog | One catalog per checkout: workflows/activities/<NN>-*/artifacts/<type>/{meta.yml,template.md,prompt.md}. Every flow resolves the same catalog. | SKILL.md §Catalog Resolution |
| Graph | workflows/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 validation | helix_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 schema | ddx: 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.links | Referenced 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 |
| ADR | Update 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 |
| Concerns | Registry of cross-cutting engineering practices, activated per project. Not a knowledge registry. | workflows/concerns/, docs/helix/01-frame/concerns.md |
| Research-like types | component-profile (discover, optional): candidate-by-capability desk research with cited claims, scored alternatives and a verdict. | 00-discover/artifacts/component-profile/meta.yml |
| Presentation | deliverable (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-visual | No references in this repository. | grep |
2. Gap analysis
| Atlas needs | HELIX today | Gap |
|---|---|---|
| A second graph type in another folder | Multiple flows exist; all share one catalog and one graph | Per-flow profile selecting types, edge rules, authority |
| Technology brief/assessment reusable across clients | component-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 ADR | None | decision-brief |
| Strategic argument over assessments | None | position-paper (deferred) |
Typed relationships (addresses, evaluates, contradicts) | depends_on, informs, supersedes; ddx.links undefined | Extend the ddx.links {id, kind} shape with new kinds, authority, rev (ADR-018) |
| Informational vs governing authority | Implicit and positional | Explicit authority class on cross-graph references (ADR-018) |
| Reproducible publication from pinned revisions | deliverable has no source pinning or approval gate | Pinned sources, audience, outputs, review gate (§6) |
| Reuse by another graph without cloning | external_edges always empty; cross_flow undefined for external repos | Pinned external reference shape; resolution is runtime work (ADR-018) |
| Default-tolerant, publish-strict validation | Single validation tier | Profile-keyed default and publish tiers, selected by --tier |
Per-profile graph.yml | Generator is single-methodology and informs-only | Generator 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
| Type | Decision | Notes |
|---|---|---|
| Technology Brief | Generalize 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 Assessment | New 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 Brief | New decision-brief | Contextual recommendation prior to an ADR. Feeds an ADR; never replaces it. |
| Position Paper | New 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. |
| Publication | Extend 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
- No
profile:meanssoftware-delivery; behavior is byte-identical. flows:stays; nohelix_version: 3and nographs:rename. “Graph” is documentation vocabulary.workflows/graph.ymlstays as the software-delivery graph. The generator grows a--profileoption; the default output must not change.- New
meta.ymlfields are optional and ignored by older consumers (open schema). Unknown frontmatter is preserved per SKILL.md §7. ddx.linksgets 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 |
|---|---|
| T1 | Existing .helix.yml (no profile:) passes tests/validate-skills.sh unchanged. |
| T2 | Two-flow marker (software-delivery + technology-atlas) resolves by cwd; a write into the wrong flow’s root is refused. |
| T3 | generate_graph.py default output is byte-identical to the committed graph.yml; --profile technology-atlas emits a separate graph. |
| T4 | A decision-brief with missing sections validates at the default tier and fails at the publish tier until sections are present. |
| T5 | A product-flow ADR referencing an Atlas assessment treats it as advisory; the same reference does not alter the ADR’s own authority. |
| T6 | A publication built from pinned sources is byte-identical after the underlying assessment changes; rebuild at a new pin produces a new publication. |
| T7 | contradicts between two assessments is surfaced by align and does not fail validation. |
10. Open items
- Whether
component-profilegeneralizes in place or gets a sibling. - Where profile files live (
workflows/profiles/proposed). - The UMF and
umf-visualcontracts (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
materializeworks only within one repository; resolvinggraph:is runtime work (§6). - Projection to UMF and
umf-visualis not designed here (§8). - Rendering a publication (HTML, PDF) is
presentanddocumentorwork; 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"
}
]
}