Li ecosystem governance — GitHub org, standards, traceability¶

Applies to: package-scaffold, package-manager-lip, li-httpd, and all first-party / standard libraries.

Goal: Official Li software and standard packages live under a defined GitHub organization, with documentation and metadata that meet international conventions and a traceability chain from requirements → design → tests → releases.

GitHub organization policy¶

Canonical org: li-langverse — all official Li software and standard packages MUST live here.

Canonical remote: https://github.com/li-langverse/lic.git — docs and mkdocs.yml use li-langverse. See master plan § Repository separation.

Agents: For any human-only action (new repo, GitHub settings, org apps, secrets, notifications setup) — post “Action needed from you”, list exact steps, wait for confirmation. See master plan — human-only actions. Do not proceed without confirmation.

When to create an org repo (mandatory)¶

Create a new repository under li-langverse when any of:

1. Package is listed as Li standard (docs/ecosystem/official-packages.md).
2. Package is a dependency of more than one first-party product (httpd, compiler std, benchmarks).
3. Package will be lip publish’d to the public registry as maintained by the Li project.
4. Release cadence is independent of lic (own semver tags).

Stay in monorepo (packages/<name>/) when:

• Experimental / single-consumer only.
• Tightly coupled to compiler bring-up (until import + lip stable).
• Promote to org repo at 1.0.0 or when a second consumer appears (document promotion in CHANGELOG).

Repo creation checklist (human or agent)¶

# After li-new-package locally validates
gh repo create li-langverse/li-foo --public --description "Li package: one line" \
  --license apache-2.0
git remote add origin git@github.com:li-langverse/li-foo.git
# push; enable branch protection on main; link lic / lip / lit in README

Templates: scripts/templates/github-repo/ — README.md, SECURITY.md, CHANGELOG.md, .github/PULL_REQUEST_TEMPLATE.md, PUBLISH.md.

Agent skill: extend create-li-package — if official or std, run org checklist and link traceability IDs.

Cross-repo dependency notifications¶

When lic, lit, lip, or any official li-* package releases, dependents MUST be notified so pins (li-toolchain.toml, li.lock) and CI are updated.

Required per repository (official / std)¶

Upstream release hub (lic repo)¶

• .github/workflows/notify-downstream.yml — runs on release v*
• .github/li-downstream-repos.txt — one repo per line: li-langverse/lip, li-langverse/lit, li-langverse/li-std-core, …
• Dispatches event li-upstream-release with payload: component, version, url

Agents: On new official repo, append to li-downstream-repos.txt in the same PR that adds the repo to official-packages.md. Remind human to enable Renovate on the org if TOML pins should auto-PR.

Optional (recommended org-wide)¶

• Renovate on li-langverse — regex managers for lic_version / lit_version in li-toolchain.toml
• Org team Watching releases on lic, lit, lip
• Phase 8d registry: webhook when a depended package publishes (complements GitHub)

Master plan phase: 8-sync — see master plan.

International documentation standards (practical subset)¶

Li docs align with widely used de facto international practice (not certifying to ISO unless explicitly required):

Language: Primary docs in English (en). User-facing strings in code: English first; i18n out of scope until std stabilizes.

Accessibility: MkDocs Material theme; semantic headings; alt text on diagrams in docs; no information conveyed by color alone in published plots.

Traceability model¶

Every normative or release-blocking item gets an ID and backlinks.

flowchart LR
  SPEC["Design spec\nREQ-xxx"]
  PLAN["Master plan\nPhase Pkg / 8x"]
  TEST["li-tests\nT-xxx"]
  PKG["Package\nPKG-xxx"]
  REL["Release\nCHANGELOG / tag"]
  SPEC --> PLAN
  PLAN --> TEST
  PLAN --> PKG
  TEST --> PKG
  PKG --> REL

ID prefixes¶

Required files per org package repo¶

Monorepo packages/ traceability¶

• Root docs/ecosystem/official-packages.md lists all PKG-* with path or org repo URL.
• Each packages/*/PUBLISH.md includes Traceability: PH-…, T-…, REQ-….

Update discipline (when anything ships)¶

1. Code/test change → update li-tests/manifest.toml note with T- id if new behavior.
2. New package → assign PKG-; add row to official-packages; create org repo if policy says so.
3. Release → CHANGELOG section with version + date; tag vX.Y.Z; bump li.toml version.
4. Spec change → new or updated REQ-; link from master plan phase row.
5. Docs → mkdocs nav + cross-links; DOC- id in page HTML comment or first line <!-- DOC-lip-user-guide -->.

CI (planned): scripts/check-traceability.sh — fails if PKG- in official-packages has no PUBLISH.md; manifest tests missing note for verify_ok suites.

Standard packages registry (documentation)¶

File: docs/ecosystem/official-packages.md (create on execute)

Third-party packages are not listed here; they appear only in the public lip registry index.

Integration with scaffold + lip¶

Scaffold flag (planned): --official sets package.metadata.lip.maintainer = "li-langverse" and generates docs/traceability.md skeleton.

Master plan placement¶

Agent coordination (documented)¶

Exit gate (governance slice)¶

• Confirm org access: gh api orgs/li-langverse (or org owner invites bot/users)
• docs/ecosystem/official-packages.md with PKG- table (all repos under li-langverse)
• On execute: align mkdocs.yml repo_url / GitHub Pages with li-langverse/li-language when repo home moves
• docs/ecosystem/governance.md user-facing summary (links here)
• scripts/templates/github-repo/ + scripts/check-traceability.sh
• create-li-package skill: --official → org checklist
• At least one example package PUBLISH.md with full traceability block in monorepo (packages/li-demo/PUBLISH.md, …)