Skip to content

docs: make HELM ecosystem map authoritative #34

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
mindburnlabs wants to merge 1 commit into from
Closed

docs: make HELM ecosystem map authoritative #34

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 13 additions & 8 deletions scripts/generate-helm-ecosystem-map.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
MIGRATION_INDEX_PATH = File.join(WORKSPACE_ROOT, "production-readiness", "estate", "migration-index.json")
TEAM_DOC_PATH = File.join(WORKSPACE_ROOT, "docs_for_team", "docs", "onboarding", "helm-ecosystem-directory-map.md")
ROOT_DOC_PATH = File.join(WORKSPACE_ROOT, "docs", "architecture", "helm-ecosystem-directory-map.md")
HANDBOOK_DOC_PATH = File.join(WORKSPACE_ROOT, "docs-engineering-handbook", "docs", "architecture", "helm-ecosystem-directory-map.md")
ROUTING_DOC_PATH = File.join(WORKSPACE_ROOT, "docs_for_team", "docs", "onboarding", "helm-task-routing.md")

OPTIONS = {
Expand Down Expand Up @@ -102,7 +103,7 @@ def group_for(name)
case name
when ".github"
"GitHub Metadata"
when "app-developer-portal", "app-helm-console", "app-mindburn-web"
when "app-developer-portal", "app-helm-console", "app-helm-docs", "app-mindburn-web"
"Frontend / User Surfaces"
when "app-docs-platform", "platform-design-system"
"Archived UI / Design"
Expand All @@ -120,7 +121,7 @@ def group_for(name)
"Platform / Policy Substrate"
when /^infra-/, /^gitops-/, "mindburn-infra"
"Infrastructure / GitOps"
when "docs-engineering-handbook", "docs_for_team", "dev-orchestration", "homebrew-tap"
when "docs", "docs-engineering-handbook", "docs_for_team", "dev-orchestration", "homebrew-tap"
"Docs / Onboarding / Local Ops"
when "ml-orggenome-compiler"
"OrgGenome / ML"
Expand Down Expand Up @@ -315,6 +316,7 @@ def render_markdown(state)
lines << "- Code, route registries, schemas, generated contracts, release manifests, and GitOps evidence outrank prose docs."
lines << "- UI code is never an authorization boundary."
lines << "- RLM output is advisory evidence only; it does not verify HELM behavior by itself."
lines << "- HELM is the only Mindburn Labs product. Company Builder, Company OS, and HELM Network are product motions inside HELM; design-partner work becomes reusable HELM blueprints and evidence."
lines << "- Local `*-wt-*` directories are task checkout directories by naming convention, not separate products or canonical repos."
lines << "- Compatibility/local-only directories are not GitHub repository truth unless they appear in `.github-repo/repo-manifest.yaml`."
lines << ""
Expand Down Expand Up @@ -351,11 +353,12 @@ def render_markdown(state)
lines.concat markdown_table(
["If you are working on...", "Start here"],
[
["HELM product strategy, Company Builder, Company OS, Network, or design-partner reuse", "`docs/ai/helm-ai2027-economy-and-growth-strategy.md`, then `docs/architecture/source-truth.md`"],
["Kernel verdicts, receipts, EvidencePacks, conformance", "`helm-ai-kernel`"],
["Paid HELM AI Enterprise backend/product logic", "`helm-ai-enterprise`, then `svc-helm-control-plane`"],
["Console UX", "Future React console repo; backend truth from `svc-helm-control-plane`"],
["Public docs", "Future website/docs React repo plus headless contract docs"],
["Public marketing site", "Future website/docs React repo"],
["Console UX", "`app-helm-console`; backend truth from `svc-helm-control-plane`"],
["Public docs", "`app-helm-docs`; source content and claims remain governed by their owning repos"],
["Public marketing site", "`app-mindburn-web`; public claims remain evidence-gated"],
["Connector contracts or packs", "`helm-ai-enterprise`, `contracts-catalog`, `svc-helm-certification`, `integration-helm`"],
["Production release state", "`integration-mindburn-platform`, `gitops-apps`, `gitops-platform`"],
["Infrastructure/server access", "`mindburn-infra`, `docs_for_team`"],
Expand Down Expand Up @@ -456,7 +459,7 @@ def validate_state!(state, markdown)
end

def write_outputs(markdown)
[TEAM_DOC_PATH, ROOT_DOC_PATH].each do |path|
[ROOT_DOC_PATH, TEAM_DOC_PATH, HANDBOOK_DOC_PATH].each do |path|

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 14, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Whitelist the handbook map before writing it

In a full workspace after this generated output is committed to docs-engineering-handbook, the headless-UI reference gate will scan that active repo but still only allows docs/onboarding/helm-ecosystem-directory-map.md in docs_for_team (scripts/check-headless-ui-references.rb lines 57-67). The generated markdown always includes the manifest deleted repositories (app-docs-platform and platform-design-system) from lines 306-307, and both names are banned by that gate, so make lint/the org docs-truth scan will fail for the new handbook copy unless this path is allowed or excluded.

Useful? React with 👍 / 👎.

FileUtils.mkdir_p(File.dirname(path))
File.write(path, markdown)
end
Expand All @@ -470,12 +473,14 @@ def write_outputs(markdown)
write_outputs(markdown)
puts "Wrote #{TEAM_DOC_PATH}"
puts "Wrote #{ROOT_DOC_PATH}"
puts "Wrote #{HANDBOOK_DOC_PATH}"
end

if options[:check]
expected = {
ROOT_DOC_PATH => markdown,
TEAM_DOC_PATH => markdown,
ROOT_DOC_PATH => markdown
HANDBOOK_DOC_PATH => markdown
}
stale = expected.filter_map do |path, content|
if !File.exist?(path)
Expand All @@ -495,7 +500,7 @@ def write_outputs(markdown)
"manifest_repositories" => state.fetch(:manifest_repos).count,
"local_directories" => state.fetch(:local_dirs).count,
"migration_entries" => state.fetch(:migration_entries).count,
"outputs" => [TEAM_DOC_PATH, ROOT_DOC_PATH]
"outputs" => [ROOT_DOC_PATH, TEAM_DOC_PATH, HANDBOOK_DOC_PATH]
}
puts JSON.pretty_generate(summary)
end
Loading