oh-my-claudecode/.omx/plans/source-overall-cleanup/generated-artifact-policy.md

Generated Artifact Policy and Static/Security Gate

Scope and source anchors

This policy satisfies the Lane 0 generated-artifact gate for the source-overall aggressive cleanup. It is a readiness artifact only: no src/ files, generated build outputs, or .omx/ultragoal files are changed by this task.

Authoritative anchors:

• PRD scope requires generated build artifacts to be handled only after implementation and requires an explicit decision for dist/, bridge/*.cjs, bridge/team.js, composed docs/shared outputs, and CLI/runtime/server bridge outputs produced by npm run build (.omx/plans/prd-source-overall-aggressive-cleanup.md:6-10).
• Lane 6 requires full test/build/lint, a static/security scan where available, then applying this Lane 0 generated-artifact policy (.omx/plans/prd-source-overall-aggressive-cleanup.md:107-111).
• Blocking gate 2 requires this policy before final verification; blocking gate 4 treats package exports, bins, hook events, MCP tool output, team runtime status, CLI text/exit codes, and state-file layout as public-surface changes requiring contract tests/release notes if incompatible (.omx/plans/prd-source-overall-aggressive-cleanup.md:115-119).
• Test spec requires final build-output verification beyond dist/, including bridge/*.cjs, bridge/team.js, composed docs/shared outputs, runtime CLI, team server, and MCP bridge outputs (.omx/plans/test-spec-source-overall-aggressive-cleanup.md:46-50).
• Static/security default is npm audit --omit=dev as a non-mutating check after final build/test/lint (.omx/plans/test-spec-source-overall-aggressive-cleanup.md:52-53).

Package/build evidence

package.json makes generated outputs part of the shipped public package:

• Main/types/exports point at dist/index.js and dist/index.d.ts (package.json:6-12).
• Published bins oh-my-claudecode, omc, and omc-cli point at bridge/cli.cjs (package.json:14-18).
• Published file allowlist includes dist, bridge, specific bridge bundles, commands, hooks, scripts, skills, templates, and docs (package.json:19-39).
• npm run build runs tsc, builds the skill bridge, MCP server, team bridge entry, composed docs, runtime CLI, team server, and CLI/team entrypoints (package.json:40-47).
• prepublishOnly repeats npm run build && npm run compose-docs, confirming that generated artifacts are packaging-critical (package.json:66-68).

Build-script output evidence inspected for this policy:

• scripts/build-skill-bridge.mjs writes dist/hooks/skill-bridge.cjs.
• scripts/build-mcp-server.mjs writes bridge/mcp-server.cjs.
• scripts/build-bridge-entry.mjs writes bridge/team-bridge.cjs.
• scripts/compose-docs.mjs writes composed docs and copies partials into docs/shared/.
• scripts/build-runtime-cli.mjs writes bridge/runtime-cli.cjs.
• scripts/build-team-server.mjs writes bridge/team-mcp.cjs.
• scripts/build-cli.mjs writes bridge/cli.cjs and bridge/team.js.

Decision

Commit regenerated package/public artifacts when a cleanup lane changes their source inputs or public-surface behavior. Do not regenerate or commit generated outputs during planning/readiness-only tasks.

Rationale:

1. dist, bridge, and docs outputs are published or used as executable entrypoints, so source changes can otherwise leave the repository/package in a mixed source-vs-runtime state.
2. The cleanup PR may intentionally refactor public-adjacent internals while preserving contracts; committing generated outputs makes final verification and downstream consumers exercise the same code that will ship.
3. Readiness artifacts like this file do not modify source inputs for the build pipeline, so generated outputs should remain untouched until an implementation lane makes a source/doc-template change.

Artifact classes and required action

Artifact/output class	Generated by	Public/package impact	Policy
dist/**/*.js, dist/**/*.d.ts, maps	tsc via npm run build	main, types, and package export target	Commit after any src/** or tsconfig change that affects emitted JS/types.
dist/hooks/skill-bridge.cjs	scripts/build-skill-bridge.mjs	Runtime hook/skill bridge bundle	Commit after changes to src/hooks/learner/bridge.ts or dependencies imported into that bundle.
bridge/mcp-server.cjs	scripts/build-mcp-server.mjs	Plugin/package MCP bridge	Commit after changes to MCP server source or public MCP tool contracts.
bridge/team-bridge.cjs	scripts/build-bridge-entry.mjs	Team bridge runtime entry	Commit after changes to src/team/bridge-entry.ts or imported team bridge dependencies.
bridge/runtime-cli.cjs	scripts/build-runtime-cli.mjs	Runtime CLI entry	Commit after runtime CLI source/contract changes.
bridge/team-mcp.cjs	scripts/build-team-server.mjs	Team MCP/server bridge	Commit after team server/MCP source changes.
bridge/cli.cjs	scripts/build-cli.mjs	oh-my-claudecode, omc, omc-cli bins	Commit after CLI source, command text, exit-code, or option parsing changes.
bridge/team.js	scripts/build-cli.mjs	Team JS entrypoint	Commit after team CLI/runtime source changes.
docs/shared/*.md and composed docs outputs	scripts/compose-docs.mjs	Published docs and skill reference material	Commit after docs template/partial changes or source changes that intentionally require composed-doc updates.
.omx/plans/source-overall-cleanup/*.md	Human/agent readiness artifacts	Planning evidence only	Commit as readiness artifacts; they are not build products and do not trigger generated output regeneration.

Final verification procedure

After each implementation lane that changes source inputs:

1. Run targeted tests for the touched module/lane before build-output review.
2. Run npm run build to regenerate dist, bridge bundles, and composed docs.
3. Inspect git status --short dist bridge docs/shared and include any changed generated files that correspond to touched source inputs.
4. Smoke-check public entrypoints when affected, at minimum node bridge/cli.cjs --help after CLI/bin changes and team/MCP bridge smoke where their source changed.
5. If npm run build changes an unexpected generated file outside the touched lane, classify it as either expected transitive output, unrelated pre-existing drift, or blocker requiring leader review before commit.
6. Run final npm test -- --run, npm run build, npm run lint, then npm audit --omit=dev.

Static/security gate decision

Use npm audit --omit=dev as the required non-mutating static/security gate after final test/build/lint.

Decision notes:

• The test spec names npm audit --omit=dev as the default non-mutating dependency/security check (.omx/plans/test-spec-source-overall-aggressive-cleanup.md:52-53).
• This cleanup plan forbids new dependencies unless explicitly added later, so production dependency audit is the lowest-risk security gate that still catches shipped dependency issues.
• If the audit cannot complete because the registry/network is unavailable, final reporting must mark the security gate as blocked with the exact command output and must not claim a security PASS.

Public-surface and release-note rule

Generated output changes alone do not justify release notes. Release/migration notes are required only when the source lane intentionally changes public behavior or incompatibly affects package exports, bins, hook events, MCP tool output, team runtime status, CLI text/exit codes, or state-file layout. If generated artifacts change because a compatible implementation refactor was rebuilt, record them as generated parity updates in the lane report.