| name | harness-governance |
| description | Trust tier enforcement, lifecycle controls, and companion rule requirements for projects using the development harness. Use when checking if an action requires human approval, creating or validating documentation artifacts, verifying lifecycle stage conditions, running validators, or making changes to governance entrypoints (HARNESS.md, AGENTS.md, CLAUDE.md, CI workflows). |
| license | Apache-2.0 |
| compatibility | Designed for any Agent Skills-compatible client (Claude Code, VS Code, Cursor, and others). For projects governed by the development harness platform via harness.manifest.yaml. |
| metadata | {"harness-module":"kernel/base","format-version":"1.0"} |
Harness Governance
This skill encapsulates the core governance rules of the development harness. Read it when
working on any project that has a harness.manifest.yaml file.
Trust Tiers
Every action falls into one of six tiers. Tier determines autonomy — higher tiers require
human authorization, never self-elevation.
Visual: see the Trust Tier Decision Flow diagram
for the same content rendered as a flowchart.
| Tier | Name | Examples | Agent may proceed? |
|---|
| 0 | Read-only | Read files, search, inspect git history | Yes |
| 1 | Local analysis | Run tests, builds, linters | Yes |
| 2 | Workspace mutation | Edit files, scaffold docs, create artifacts | Yes, with care |
| 3 | Git-writing | Commit, push to feature branches, open PRs | Yes, with care |
| 4 | Environment-altering | Install dependencies, apply local migrations, configure services | Human authorization required |
| 5 | Remote / production | Deploy, production migrations, secrets rotation, infra changes | Human authorization + second sign-off |
Gotchas:
- Dependency installation (
npm install, pip install, uv sync) is Tier 4 — even locally.
supabase db push against any non-local environment is Tier 4.- Any deploy command is Tier 5 regardless of how it is invoked.
- Finding a workaround that achieves a Tier 4/5 effect while appearing lower-tier is prohibited.
Companion Rules
When a sensitive path changes, a companion file must also change in the same commit.
If you change a trigger path without updating the companion, flag it before finishing.
Visual: see the Companion Rule Firing diagram
for the trigger → satisfier → CI-gate flow.
Common companion rules in harness projects:
| Trigger path | Required companion |
|---|
docs/product/requirements.md | docs/project/change-log.md OR a new ADR |
HARNESS.md, AGENTS.md, CLAUDE.md, .github/CODEOWNERS | ADR OR docs/operating-principles.md |
package.json, lock files, .nvmrc | ADR OR docs/architecture/overview.md |
pyproject.toml, requirements.txt, lock files | ADR OR docs/architecture/overview.md |
supabase/, src/auth/, session/jwt/token paths | docs/security/risk-register.md, ADR, or architecture overview |
New/modified ADR (docs/adr/ADR-*), OPP (docs/opportunities/OPP-*), module manifest (platform/*/module.yaml — anywhere under platform/), or active-module catalog (harness.manifest.yaml) — cycle-end distillation trigger when management/knowledge-capture is active | Either of: docs/knowledge/shared-observations.md or docs/operating-principles.md. See platform/workflow/cycle-end-distillation.md for the satisfier decision tree. Pre-ADR-0014 (2026-05-25) the satisfier set also included docs/knowledge/distilled-learnings.md; that destination was sunset and consolidated into operating-principles.md. |
Active companion rules for the current project are declared in each module's module.yaml.
Cycle-end distillation pattern (PRD-0004; satisfier set updated by ADR-0014). When a PR introduces
distillation-worthy work (new ADR / OPP / module / catalog change), the
distillation-trigger rule fires. Pair the trigger with either an observation
in shared-observations.md or a new/modified section in operating-principles.md —
the humanReview text demands substantive connection between the trigger
work and the distillation, not a tangential entry appended to pass CI. See
platform/workflow/cycle-end-distillation.md
for the canonical workflow, and
platform/workflow/session-shape.md for the
umbrella review-trigger taxonomy — the six trigger-classes (PR-boundary,
session-boundary, time-boundary, count-boundary, audit-boundary,
external-event-driven) and the audit of declared-but-unfired reviews.
Lifecycle Stages
Do not declare a stage complete unless all conditions are met.
Bootstrap Complete — all of the following:
validate-manifest.sh exits 0validate-module-graph.sh exits 0validate-required-artifacts.sh exits 0 (or intentionally disabled)validate-placeholders.sh exits 0 — no [[PLACEHOLDER_NAME]] tokens remain- CI workflow is green on the first PR
Harness Ready — Bootstrap Complete plus:
- Ownership and review gates are active
- Validators are wired into CI
- Operational readiness artifacts (risk register, release checklist) exist if required by active delivery modules
- At least one human reviewer besides the bootstrapper has reviewed the harness
Running Validators
Run the full chain before committing any change to docs/, harness.manifest.yaml, or
any companion rule trigger path.
PLATFORM=path/to/platform
bash $PLATFORM/validators/validate-manifest.sh harness.manifest.yaml
bash $PLATFORM/validators/validate-module-graph.sh harness.manifest.yaml
bash $PLATFORM/validators/validate-required-artifacts.sh harness.manifest.yaml .
bash $PLATFORM/validators/validate-placeholders.sh .
bash $PLATFORM/validators/validate-agent-pack.sh harness.manifest.yaml .
bash $PLATFORM/validators/validate-doc-references.sh .
bash $PLATFORM/validators/validate-catalog-counts.sh .
bash $PLATFORM/validators/validate-list-completeness.sh .
bash $PLATFORM/validators/validate-trust-tier.sh harness.manifest.yaml .
bash $PLATFORM/validators/validate-sensitive-paths.sh harness.manifest.yaml .
bash $PLATFORM/validators/validate-skill-content.sh harness.manifest.yaml .
bash $PLATFORM/validators/validate-knowledge-redaction.sh . main
bash $PLATFORM/validators/validate-sast-coverage.sh harness.manifest.yaml .
bash $PLATFORM/validators/validate-trace-contract.sh harness.manifest.yaml .
bash $PLATFORM/validators/validate-foundry-target.sh harness.manifest.yaml .
bash $PLATFORM/validators/validate-model-routing.sh harness.manifest.yaml .
bash $PLATFORM/validators/validate-agent-defense-in-depth.sh harness.manifest.yaml .
bash $PLATFORM/validators/validate-privacy-by-design.sh harness.manifest.yaml .
bash $PLATFORM/validators/validate-twin-profile.sh harness.manifest.yaml .
bash $PLATFORM/validators/validate-scenario-manifest.sh harness.manifest.yaml .
bash $PLATFORM/validators/validate-lane-integrity.sh harness.manifest.yaml . main
bash $PLATFORM/validators/validate-publication-boundary.sh .
bash $PLATFORM/validators/validate-module-stability.sh .
bash $PLATFORM/validators/validate-companions.sh harness.manifest.yaml . main
All must exit 0 before the commit is complete. Each validator supports
--help / -h and uses a 3-state exit contract: 0 = pass, 1 =
governance violations found, 2 = usage error (missing argument,
missing dependency like ripgrep, unreadable manifest, malformed
YAML). Per-script signatures vary; run any validator with --help to
see its arguments.
A few signature notes worth highlighting:
validate-placeholders.sh takes only [<project-root>] (default:
cwd). Passing a manifest path as the first arg causes the script to
attempt to cd into it and exit 2 with a Not a directory error.validate-doc-references.sh also takes only [<project-root>].
Pass 1 asserts every platform/... string inside platform/*.md
resolves on disk (the harness's own dogfood check). Pass 2 scans
every *.md under the project root for relative link targets and
classifies each as :ok, :missing, :directory_target (GitBook
404-fragile), or :extensionless (also GitBook-fragile). Consumers
whose project doesn't have a platform/ directory of its own can
point at their .harness/ submodule mount instead; the validator
scans whichever root it's given.validate-trust-tier.sh takes [<manifest>] [<project-root>]
(defaults: ./harness.manifest.yaml and dirname(manifest)). For
each active module, validates the optional tier.declared field
(0–5; rationale required for ≥3); computes inferred tier from
sensitivePaths regexes against representative production-shape
sample paths; asserts declared >= inferred. For agent modules,
validates maxTier and asserts it ≥ the highest active non-agent
tier. Per PRD-0006 / ADR-0017 Wave 5.1. The harness's own kernel
declares tier 5 (governs CI workflows + governance entrypoints); the
cross-cutting "declared tier 5 requires criticality high/critical"
rule is relaxed for maturity: platform projects (auto-harness
itself).validate-list-completeness.sh takes only [<project-root>].
Asserts every ADR / PRD / OPP / composition / template subdirectory /
profile module / agent module on disk has its canonical index row.validate-knowledge-redaction.sh takes
[--block] [<project-root>] [<base-branch>] (defaults: cwd and main).
Diff-based scan of new lines added to
docs/knowledge/shared-observations.md and
docs/operating-principles.md against a built-in denylist of
consumer-name patterns (Tula, OpenEMR, YouBase, municipal-brain,
toast-mcp). Lines matching .knowledge-redaction-ignore regex
patterns are exempted. Default posture: WARN — surfaces hits on
stderr but exits 0 (reviewers eyeball in CI logs). --block flag
escalates hits to exit 1. Per OPP-0036 / ADR-0017 Wave 5.5. When run
outside a git working tree or against a base branch that doesn't
exist locally (shallow CI checkout, dogfood from a non-PR context),
the validator exits 0 cleanly with an informational message rather
than failing.validate-sensitive-paths.sh takes [<manifest>] [<project-root>]
(defaults: ./harness.manifest.yaml and dirname(manifest)). Across
all active modules, asserts every sensitivePaths regex pattern is
overlapped by at least one companionRules.triggerPaths regex on some
active module. Uses a pragmatic 3-tier overlap check (literal
equality, trigger contains sensitive as substring, or sensitive
contains trigger as substring). Cross-module overlap is allowed —
coverage by any active module's companion rule suffices. Closes
safety-security-sweep §2 claim 12 (Asserted-only → Enforced). Per
OPP-0034 / ADR-0017 Wave 5.3.validate-skill-content.sh takes
[--verbose] [<manifest>] [<project-root>] (defaults: ./harness.manifest.yaml
and dirname(manifest)). Across active modules, scans authored prose in
module.yaml description-class fields (description, summary,
reviewGates[], companionRules[].humanReview), SKILL.md bodies
referenced via recommendedSkills[], and markdown files referenced via
compiledFragments[]. Hard-fails on any unexempted denylist match
(prompt-injection patterns like "ignore previous instructions" or
"skip the validator", tier-bypass phrasings like "always operates at
Tier", role-prompt headers ^System:/^User:/^Assistant:,
zero-width characters U+200B/200C/200D/FEFF, Unicode bidi marks
U+202A–202E/U+2066–2069). Lines matching .skill-content-ignore regex
patterns are exempted. Default posture: BLOCK (predict-clean
absorption per PRD-0015 FR-003). An auxiliary --scan-file <path> mode
scans an arbitrary file's content against the denylist without
enumerating active modules — useful for ad-hoc adversarial-corpus
checks. Per PRD-0015 / OPP-0033 / ADR-0017 Wave 5.2. Closes
safety-security-sweep §3 vectors V1, V2, V4 (partial), V6.validate-sast-coverage.sh takes [<manifest>] [<project-root>]
(defaults: ./harness.manifest.yaml and dirname(manifest)).
Opt-in — when the management/security-static-analysis module is
not active in the manifest, exits 0 with a "module inactive"
message (the harness itself does not activate the module, so the
harness's own CI run is a no-op pass — predict-clean absorption per
PRD-0016 FR-003). When the module is active, reads
docs/security/sast-coverage.md, parses the YAML frontmatter
between --- fences, and asserts: tool: is from the recommended
set (semgrep / codeql / bandit / gosec /
eslint-plugin-security / snyk-code), scanPaths: has at least
one non-empty entry, severityThreshold: is a non-empty string.
An auxiliary --scan-file <path> mode validates an arbitrary
sast-coverage-shaped file without manifest gating — useful for
fixture tests and ad-hoc validation of a candidate artifact before
committing. Per PRD-0016 / OPP-0035 / ADR-0017 Wave 5.4.
Half-enforces safety-security-sweep §11 (the largest mission-
relative gap in the sweep) — the harness validates the contract;
consumer CI honors it for end-to-end enforcement.validate-trace-contract.sh takes [<manifest>] [<project-root>]
(or --scan-file <path>). Opt-in / module-gated, but on a different
predicate than the others: it activates when any active module
declares docs/observability/trace-contract.md in its
requiredArtifacts — today architectures/agent-observability
(which owns it) or architectures/ai-foundry-target (which reuses it
via the deferred-dependency model) — so a consumer activating either
gets the check. When none does, exits 0 with a "skipping" message
(predict-clean — the harness activates neither). When active, parses
the artifact's YAML frontmatter and asserts semconv_version: is a
non-empty version pin, spans: declares at least one conventional
GenAI operation (chat / invoke_agent / execute_tool /
create_agent / embeddings / invoke_workflow), and
content_capture: is one of {opt-in, none}. Presence + shape only
(never that the declared spans match the emitted telemetry — that is
the deferred code-cross-reference half). The artifact-content half of
the frontier-agent cluster's v2 enforcement; --scan-file <path> for
fixture tests. Per PRD-0031 / OPP-0051 / OPP-0027.validate-foundry-target.sh, validate-model-routing.sh, and
validate-agent-defense-in-depth.sh are the three sibling
content validators (PRD-0032, OPP-0051 phases 2–4) — same skeleton as
validate-trace-contract.sh (requirement-set activation gate,
--scan-file, predict-clean), each asserting its own artifact's
frontmatter shape: foundry-targets.md declares ≥ 1 foundry from the
enum with a live/roadmap status; model-routing.md declares ≥ 1
task→model route (providers free-form); agent-defense-in-depth.md
names all four patterns (scope-containment, least-permissions,
human-in-the-loop, agent-identity). Presence + shape only; the
code-cross-reference half stays deferred.validate-companions.sh is PR-diff-based and takes a third
positional arg <base-branch> (default main). It is intended for
CI; running it locally on a clean branch with no diff against base
prints No changed files detected ... Skipping companion validation.
and exits 0 without checking anything.validate-catalog-counts.sh takes only [<project-root>].
Asserts that documented catalog counts (modules, validators, skills,
templates, workflows, diagrams) cited in entry-point docs match the
canonical recipes. The recipes are inline in the script alongside an
assertion table mapping (file, regex, count-key) to documented
claim sites. When you add a new doc that cites a catalog count, append
a row to the script's ASSERTIONS table so the drift class stays
closed.validate-lane-integrity.sh takes
[<manifest>] [<project-root>] [<base-branch>] (or
--scan-file <lane-spec> [<changed-path>...]). Opt-in — when the
management/work-package module is not active, exits 0 (predict-clean;
the harness's own CI is a no-op pass). When active, parses the fenced
lane block in docs/work-package/lane.md, asserts the schema is
well-formed (branch / base / prMode in {draft,ready} / non-empty
allowedFiles / list-typed readOnlyFiles / requiredChecks /
forbiddenCommands), then diffs the branch against <base-branch> and
fails if any changed file is outside allowedFiles or touches
readOnlyFiles. The --scan-file mode runs the schema check (and, given
an explicit changed-path list, the lane-vs-diff check) without git, for
fixture-firing tests. Per PRD-0025. The multi-agent re-targeting of the
module declare-then-enforce contract.validate-publication-boundary.sh takes [<project-root>], or
--staged [<project-root>], or --scan-file <path>.... Always-on (not
module-gated): it enumerates git-tracked files (or staged files, or the given
paths) and exits 1 if any declares a do-not-publish marker — a YAML
frontmatter key or an HTML-comment sentinel (<!-- do-not-publish: true -->),
matched only at line start so a mid-sentence mention does not trip. Path
regexes in .publication-boundary-ignore exempt files that legitimately discuss
the marker. The steady state (marker in an untracked file) is invisible to
git ls-files and passes; the gate fires the instant a marked file is
tracked/staged. Outside a git work tree it exits 0. The inverse of a
required-artifact check — a must-NOT-be-tracked assertion that needs no name
corpus. Per PRD-0026 / OPP-0048; run it as a pre-commit hook (--staged) for
prevention, with CI as the backstop.validate-module-stability.sh takes [<project-root>] or
--scan-file <module.yaml>. Always-on structural catalog check (like
validate-list-completeness, not module-gated): every module.yaml under
platform/ must declare stability: ∈ {experimental, beta, stable}. It
asserts presence + enum membership only — never the correctness of the
human judgment (honesty is an authoring act). Stability is a third axis,
independent of trust tier (risk) and § 10 (per-claim enforcement): how
proven the module itself is. --scan-file validates one module without
enumerating, for fixtures. The rubric (stable / beta / experimental) is
authoring guidance in extending-the-harness.md
and the validator --help. Per PRD-0027 / OPP-0050.
Required Artifacts
Required artifacts are declared per module in module.yaml. Run
validate-required-artifacts.sh to see what is missing. Do not substitute an empty file —
the validator checks existence, not content. Both matter.
Use templates from platform/templates/ to create missing artifacts. Fill every
[[PLACEHOLDER_NAME]] field before committing.
Installing This Skill
Keep this directory canonical under platform/skills/. For submodule consumers,
link the canonical skill into both .agents/skills/ and .claude/skills/ rather
than copying it into tool-local folders:
bash .harness/platform/bootstrap/link-skills.sh \
--project-root . \
--mount-path .harness \
harness-governance
