Release he-maintainer v1

he-maintainer/references/monorepo.md

@@ -7,17 +7,33 @@ Use this reference when the repository contains multiple apps, packages, crates,
 - workspace root vs package roots
 - shared libraries vs deployable apps
 - root-level commands vs package-level commands
-- ownership boundaries between packages
+- ownership or responsibility boundaries between packages
+- which decisions are global vs package-local
 
 ## Common risks
 
-- commands at the root may not validate a specific package well
+- root-level commands may not validate a specific package well
-- agents may edit shared packages when a local override is safer
+- agents may edit shared packages when a package-local change is safer
-- build, lint, and test commands may vary by package manager and workspace tool
+- build, lint, and test commands may vary by package manager, workspace tool, or package type
+- one package may require a spec, ADR, or risk note even when the rest of the repo does not
+- status can become ambiguous when several packages move in parallel
 
 ## Good harness patterns
 
 - include a short workspace map
-- show how to run commands for one package
+- show how to run commands for one package or crate
 - define allowed scope for a task
 - prefer targeted validation for the touched package first
+- record cross-package rules in a durable place
+- use specs or status docs for multi-package migrations or coordinated refactors
+
+## Artifact guidance
+
+In monorepos, keep the top-level working guide short. Push detail into focused supporting artifacts when needed:
+
+- project map for workspace layout and boundaries
+- task contracts for per-package scope
+- ADRs for cross-cutting decisions
+- status docs for migrations spanning several packages
+
+Do not duplicate every package's README into the harness.

he-maintainer/references/scoring-rubric.md

@@ -5,34 +5,44 @@ Use this when asked to audit or score a repository's harness quality.
 ## Dimensions
 
 ### 1. Project map clarity
-- strong: key directories and entrypoints are documented and current
+- strong: key directories, entrypoints, and subsystem boundaries are documented and current
-- partial: some structure is documented but stale or incomplete
+- partial: some structure is documented but stale, shallow, or incomplete
 - weak: little or no useful repo map exists
 
 ### 2. Validation commands
-- strong: build, test, lint, and typecheck are clear and runnable
+- strong: build, test, lint, typecheck, or equivalent validation commands are clear and runnable
-- partial: some commands exist but are incomplete or ambiguous
+- partial: some commands exist but are incomplete, stale, or ambiguous
-- weak: commands are missing, stale, or unverified
+- weak: commands are missing, misleading, or unverified
 
 ### 3. Fast feedback
-- strong: targeted checks or quick tests exist
+- strong: targeted package-, crate-, app-, or feature-scoped checks exist
-- partial: only slower validation exists
+- partial: only slower validation paths exist, or quick checks are incomplete
-- weak: no obvious quick validation path
+- weak: no obvious fast validation path exists
 
-### 4. Task templates
+### 4. Task contract quality
-- strong: reusable templates exist for common work types
+- strong: reusable task contracts or templates define scope, constraints, validation, and acceptance criteria
-- partial: ad hoc instructions exist but are inconsistent
+- partial: ad hoc task instructions exist but are inconsistent or underspecified
-- weak: every task must be reinvented
+- weak: every task must be reinvented from scratch
 
 ### 5. Guardrails
-- strong: high-risk areas and forbidden changes are explicit
+- strong: high-risk areas, forbidden changes, generated-file boundaries, and slow validations are explicit
-- partial: some constraints exist but are vague
+- partial: some constraints exist but are vague or fragmented
-- weak: almost no constraints are documented
+- weak: almost no meaningful constraints are documented
 
-### 6. Doc-code alignment
+### 6. Architecture decision durability
-- strong: harness docs match the current repo layout and commands
+- strong: durable decisions are easy to find in ADRs, accepted docs, or equivalent records
-- partial: mixed accuracy
+- partial: some decisions are documented but scattered, stale, or inconsistently applied
-- weak: obviously stale or misleading
+- weak: important architecture or workflow decisions must be rediscovered from chat or code archaeology
+
+### 7. Failure feedback loop quality
+- strong: repeated AI or implementation failures are converted into durable harness, validation, or CI improvements
+- partial: some failures are documented, but fixes remain mostly conversational or one-off
+- weak: the same classes of failure recur without system updates
+
+### 8. Doc-code alignment
+- strong: harness docs match the current repo layout, commands, and constraints
+- partial: mixed accuracy with some stale sections
+- weak: obviously stale or misleading guidance dominates
 
 ## Output format
 
@@ -41,11 +51,13 @@ Keep the score compact. Example:
 - project map clarity: partial
 - validation commands: strong
 - fast feedback: weak
-- task templates: weak
+- task contract quality: weak
 - guardrails: partial
+- architecture decision durability: weak
+- failure feedback loop quality: weak
 - doc-code alignment: partial
 
 Top priorities:
-1. Add a fast unit test or package-scoped validation command
+1. Add a targeted validation command for the touched package or crate
-2. Refresh AGENTS.md directory map
+2. Record one durable architecture decision in an ADR or accepted design note
-3. Document forbidden change areas
+3. Turn the most common repeated failure into a task-contract, guardrail, or CI rule

he-maintainer/scripts/inspect-harness.sh

@@ -5,16 +5,51 @@ repo_root="${1:-.}"
 cd "$repo_root"
 
 echo "== Harness files =="
-find . -maxdepth 3 \( -name 'AGENTS.md' -o -name 'CLAUDE.md' -o -name 'AI_GUIDE.md' \) | sort || true
+find . -maxdepth 4 \( \
+  -name 'AGENTS.md' -o \
+  -name 'CLAUDE.md' -o \
+  -name 'AI_GUIDE.md' -o \
+  -path '*/ai/*.md' -o \
+  -path '*/ai/*/*.md' -o \
+  -path '*/docs/adr/*.md' -o \
+  -path '*/docs/specs/*.md' \
+\) | sort || true
 
 echo
 echo "== Stack markers =="
-find . -maxdepth 3 \( -name 'package.json' -o -name 'pnpm-workspace.yaml' -o -name 'turbo.json' -o -name 'Cargo.toml' -o -name 'go.mod' -o -name 'pyproject.toml' -o -name 'requirements.txt' \) | sort || true
+find . -maxdepth 4 \( \
+  -name 'package.json' -o \
+  -name 'pnpm-workspace.yaml' -o \
+  -name 'turbo.json' -o \
+  -name 'Cargo.toml' -o \
+  -name 'go.mod' -o \
+  -name 'pyproject.toml' -o \
+  -name 'requirements.txt' \
+\) | sort || true
 
 echo
 echo "== CI files =="
-find . -maxdepth 4 \( -path '*/.github/workflows/*' -o -path '*/.gitlab-ci.yml' \) | sort || true
+find . -maxdepth 5 \( -path '*/.github/workflows/*' -o -path '*/.gitlab-ci.yml' \) | sort || true
 
 echo
 echo "== Common test/build/lint config =="
-find . -maxdepth 3 \( -name 'tsconfig.json' -o -name 'vitest.config.*' -o -name 'jest.config.*' -o -name 'playwright.config.*' -o -name 'tox.ini' -o -name 'noxfile.py' -o -name '.golangci*' -o -name 'rust-toolchain.toml' -o -name 'Makefile' \) | sort || true
+find . -maxdepth 4 \( \
+  -name 'tsconfig.json' -o \
+  -name 'vitest.config.*' -o \
+  -name 'jest.config.*' -o \
+  -name 'playwright.config.*' -o \
+  -name 'tox.ini' -o \
+  -name 'noxfile.py' -o \
+  -name '.golangci*' -o \
+  -name 'rust-toolchain.toml' -o \
+  -name 'Makefile' \
+\) | sort || true
+
+echo
+echo "== Likely status / roadmap files =="
+find . -maxdepth 4 \( \
+  -iname '*roadmap*.md' -o \
+  -iname '*status*.md' -o \
+  -iname '*plan*.md' -o \
+  -iname '*vision*.md' \
+\) | sort || true