Files

Defame1297 82b7bbcf5c docs: close the PR #135 documentation review findings

Group 3 of the validated PR #135 review fixes. Every figure and commit
citation below was re-verified at HEAD before being written.

ADR and architecture:
- #7 ADR-0025 cited 61b0b9c, which no published branch reaches. Repointed
  to 620f20b (identical parent tree, reachable from the PR branch), with a
  note that neither is reachable from origin/main. The parser-drift
  paragraph now credits 598a7c3 (the reachable PR #129 squash) and keeps
  484357a only as a pre-squash parenthetical.
- #8 architecture.md dropped the pointer at the LESSONS.md entry this
  branch deleted.
- #9 architecture.md's ADR entry points now name ADR-0015 (the one
  compiler) and ADR-0024, and list ADR-0024 as superseding ADR-0017.
- #10 ADR-0024 section 4 rewritten: the standing patch-bump rule is
  apm-workflow's configure.md, not ADR-0006's, and this change does not
  trigger it. ADR-0015:93 carries a correction for the misattribution.
- N5 ADR-0021 gained a Correction note for the deleted
  scripts/check-manifests.sh (e647f14).

gates.md:
- #11a the four ADR-0020 constants live in lib-checks-skill.sh:313-316 and
  lib-checks-agent.sh:164-165, not in validate.sh.
- #11b the pretty-format-json exclude is two alternations expanding to
  three tracked files, including .claude/apm-hooks.json.
- #11c the ADR-0020 contract suite runs 28 -> 27 -> 29 (620f20b,
  4de5b6b, ef27c97), 29 at HEAD; the unverifiable 25 is dropped.
- #11d the boundary resolver is one copy since ef27c97.
- #12 apm-audit-ci documents the 10 root checks and the 1 plugin check
  apm 0.28.0 actually runs, that content-integrity IS the hidden-Unicode
  scan, that manifest-parse is not a named check, and that the hook needs
  a completed apm install. The offline claim is qualified accordingly.
- N9 gates.md:142-146 verified to still match the hook description.

AGENTS.md:
- #12 the no-network session rule is qualified to a populated
  apm_modules/.

Audit note:
- A1 hook counts corrected to 27/9 -> 26/8 -> 27/9 -> 26/8 (26 and 8 at
  HEAD) and the dangling pointer dropped.
- A2 skill-size-check.sh is 509 lines with the resolver sourced, not 1,522
  embedded; citations repointed to skill-size-check.sh:323-335 and
  lib-checks-skill.sh:235-283 (fail() at :265 and :280), and that library
  is 627 lines.
- A3 consumers receive 15 test files across 5 skills; 16 tracked test
  paths repo-wide.
- A4 the "do not run apm update on this branch" instruction is marked
  superseded, with the branch-aware guidance in its place.
- Finding 31's "true orphans" claim corrected for HOTL and Sycophancy,
  both still used in core/ai-constitution.md.

Same class, found during group 2:
- skill-author's deployment-modes.md no longer points at .mcp.json
  configs (deleted in c96ca9c); metadata.version 1.0.2 -> 1.0.3.
- git-orchestrate's context contract clarifies that
  user_config_overrides is caller-supplied session state, not a config
  read. The field name is unchanged.
- B3 root apm.yml's executables.allow comment: grants are version-blind
  in apm 0.28.0, so the #2.0.0 suffix is cosmetic to apm and a bump does
  not break the hook; the suffix stays because
  check-executables-allow-sync.sh requires it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NwD8Egs5r4ndqeFLmhusX2

2026-09-19 21:30:29 +00:00

5.8 KiB

Raw Blame History

Working in this repo

The global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects.

This file carries only what applies to every session. Setup, prerequisites, and test commands are in README.md; the reasoning behind each enforcement gate is in docs/spec/gates.md.

Structure

plugins/<name>/.apm/ is the only authoring source for plugin content. .claude/skills/ and .claude/agents/ are gitignored apm install output — never edit them.
providers/claude-code/ is the Claude Code adapter, deployed to ~/.claude/ by scripts/install.sh.

Repo layout table: README.md. Deployment mechanics and plugin boundaries: docs/spec/architecture.md.

Prefer plugin skills over raw shell

This repo dogfoods its own plugins. Before shelling out, check whether a skill already owns the operation — it usually does:

Commits, branches, history, worktrees, remotes → git-commits, git-branches, git-history, git-worktrees, git-remotes
Pre-commit hook install/config/troubleshooting → pc-run / pc-author
Issues, PRs, labels, milestones → gitea-issues, gitea-prs, gitea-labels-milestones; also gitea-branches, gitea-files, gitea-releases, or gitea-workflow when the domain is ambiguous
Vale prose linting → vale-config / vale-run
This repo's own AGENTS.md → agentsmd-author / agentsmd-audit

Use the bare, unnamespaced names. That is what apm install deploys and the only form this repo's own install produces — a project skill has no plugin to prefix (ADR-0018). Whether the <plugin>: form (gitea:gitea-prs) also resolves depends on native plugin installs at user scope, outside this repo; write the bare name either way.

Fall back to raw shell only when no skill covers it.

Session rules

Do not add repo-owned keys to .claude/settings.json. apm treats it as its own deployed artifact and apm audit --ci replays the install and diffs, so anything apm would not have written is permanent drift that fails the apm-audit-ci pre-push hook. A hook you want here is authored in plugins/<name>/.apm/hooks/ and deployed by apm, never hand-written into that file. The SessionStart entry already in it is exactly that: kyberforge authors it in plugins/kyberforge/.apm/hooks/hooks.json and apm merges it in, so it is apm's own output, it is what the replay expects, and it belongs in the commit — do not strip it (ADR-0019). Machine-specific settings go in the gitignored .claude/settings.local.json; shared enforcement goes in .pre-commit-config.yaml.
apm.lock.yaml turning up modified is expected, not a bug. kyberforge's SessionStart hook keeps the install current on launch and rewrites the lock in the process (ADR-0019). On main, commit or discard it deliberately. On a feature branch, discard it (git checkout -- apm.lock.yaml, then apm install). This keeps unrelated lock churn out of the branch diff and keeps apm pack --check-clean consistent with the committed lock. The session then runs the older main that the lock records, which is accepted on a branch, and the next session start refreshes again.
A .apm/ edit is not live until it is on the remote's main. The six dependencies resolve from the holocron remote, unpinned against the default branch, so pushing a feature branch does not deploy it (ADR-0019). apm install deploys from the lock; apm update is what re-resolves refs.
No pre-push hook needs the network — once apm install has run. Root apm.yml's marketplace has no remote package entries, so every hook resolves locally. The guarantee is a property of a populated apm_modules/, not of the hook set: on a fresh clone apm-audit-ci's deployed-files-present fails outright, and its drift and config-consistency install-replays have no cache to replay from and clone from the remote. Run apm install once on a new checkout and the offline guarantee holds from then on (docs/spec/gates.md, "Pushing without a network").
This repo and Gitea are the only source of truth. All project state, decisions, and working conventions live here. Do not use an external memory system for this project — cached state diverges from the repo and you get a split brain. Before answering any design or architecture question, check docs/adr/ for an existing decision.

Key documents

Read CONTEXT.md at the start of every session — it is this repo's domain glossary, and the terms it defines are used unglossed everywhere else. It is not exhaustive: terms it does not carry are defined at their point of use, mostly in docs/spec/.

Read these on demand:

README.md — prerequisites, install, and test commands
docs/VISION.md — the phased roadmap and where this is going; read when a decision turns on product direction
LESSONS.md — patterns that went wrong once; read before repeating a class of change that has burned the repo before
docs/spec/gates.md — what each pre-commit and pre-push hook enforces and why; read when a gate fails or before changing hook config
docs/spec/architecture.md — directory structure, install pipeline, provider model
docs/adr/ — architectural decisions; read before answering design questions or proposing structural changes
core/ai-constitution.md — full governance evidence base; read when a governance decision needs justification
docs/research/ai-coding-factory/ai-coding-factory-principles.md — factory design rationale; read when implementing, auditing, or reviewing skills or factory structure
docs/notes/factory-integration-decisions.md — decisions from the factory integration grill; read when making skill authoring or factory design decisions
Governance rules are always in effect — core/instructions/governance.md (agent rules); docs/research/governance_principles/CONTROLS.md