Skip to content

adding-a-module.md

Latest commit

 

History

History
50 lines (41 loc) · 2.2 KB

adding-a-module.md

File metadata and controls

50 lines (41 loc) · 2.2 KB
Raw

Adding a Module

Module admission is intentionally manual. Harness has no module generator, scaffold engine, or automatic discovery service.

Procedure

  1. Confirm that the independent module repository actually exists.
  2. Review the module boundary and its one-sentence responsibility.
  3. Validate every requirement in the module contract.
  4. Add one exact entry to catalog/modules.json; for an Artifact protocol, include its static discovery paths relative to the submodule root.
  5. Add the repository as a Git submodule at its Plane-specific path.
  6. Check out and record the reviewed exact module commit.
  7. Smoke-test a fresh recursive clone and the read-only Harness scripts.
  8. Submit the catalog, .gitmodules, and gitlink change for Harness review.

Pinning rules

  • Prefer a relative submodule URL when the repository shares the GitHub owner.
  • Record one reviewed commit; do not configure automatic branch following.
  • A later module update is a new explicit Harness commit or pull request. The maintenance workflow may propose that pull request by querying upstream main; it does not change clone or checkout behavior.
  • Do not modify the module repository while preparing the Harness pin.
  • Do not add a planned entry, empty directory, or empty submodule for a future module.
  • For a manifest-backed Artifact protocol, the catalog's Plane, status, kind, phase, invocation owners, terminal requirement, activation, module-invocation, mutation, and Artifact paths must match the pinned manifest. The manifest is authoritative when they disagree.

Validation checklist

Before review, verify:

python3 -m json.tool catalog/modules.json >/dev/null
python3 scripts/pin_registry.py validate
git config -f .gitmodules --get-regexp '^submodule\..*\.(path|url)$'
git submodule status --recursive
scripts/bootstrap.sh
python3 scripts/pin_registry.py validate --require-clean-submodules
scripts/status.sh
scripts/search.sh '<known read-only pattern>'

Then clone the proposed Harness commit into a new temporary directory with --recurse-submodules. Confirm the catalog repository/path, .gitmodules, and recorded gitlink all describe the same module and that every worktree is clean.