IF Commons GitHub

Repoctl library, commit and doctor

0005Active

0005-repoctl-library-commit-doctor · owner if · domain commons

Requirements

FR-001checkpassing

new library <name> MUST write, under commons/<name>/, a manifest library.ts that declares the table of its layers (Kanon), package.json, release.ts, tsconfig.json, a typed about.ts, the three layers' entries, a specification kit (the registry, the enforcement register, an empty baseline and a first specification with its requirements and scenarios), a test that proves it, the check bun run verify runs, and its LICENSE made by the license program; and --dry-run MUST list the files and write nothing.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/library-commit-doctor.test.ts: the scaffold has every file, and a library made in a copy of the repository passes its verify

Proved by: repoctl/suite/library-commit-doctor.test.ts

Written in: repoctl/src/logical/scaffold.ts, repoctl/src/physical/verbs/library.ts

Tests: passed: suite/library-commit-doctor.test.ts new library --dry-run lists the files and writes nothing, and a name that is refused write; passed: suite/library-commit-doctor.test.ts a library made in a copy of the repository passes its own verify and leaves sync --check a; passed: suite/library-commit-doctor.test.ts the scaffold has every file of a library, each with the name in it, and a title is made of

Cited by: Repoctl, logical/scaffold, physical/verbs/library

FR-002checkpassing

new library MUST refuse a name that is not lower-case letters, digits and hyphens starting with a letter (E-LIBRARY-NAME), a name that family.ts of the libraries holds for a family (E-LIBRARY-RESERVED) and a name whose folder exists (E-LIBRARY-EXISTS), and MUST write nothing then.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/library-commit-doctor.test.ts: an invalid, a reserved and an existing name are refused with their codes

Proved by: repoctl/suite/library-commit-doctor.test.ts

Tests: passed: suite/library-commit-doctor.test.ts new library --dry-run lists the files and writes nothing, and a name that is refused write; passed: suite/library-commit-doctor.test.ts an invalid, a reserved and an existing name are refused with their codes

FR-003checkpassing

new library MUST classify the library for the README (its --role, a program by default) in the map of roles of readme.ts, link it, and make every generated file that needs it, so that sync --check ends with 0 after it.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/library-commit-doctor.test.ts: the role is written into the map of roles of the README and sync --check ends with 0

Proved by: repoctl/suite/library-commit-doctor.test.ts

Tests: passed: suite/library-commit-doctor.test.ts a library made in a copy of the repository passes its own verify and leaves sync --check a; passed: suite/library-commit-doctor.test.ts the role is written into the map of roles, after the last library of its role, once; passed: suite/library-commit-doctor.test.ts the spec kit of a new library is listed after the last one the configuration of the site l

Cited by: Repoctl, logical/scaffold

FR-004checkpassing

commit MUST make the commit with the author and the committer the identity of the repository's configuration (0009-repoctl-config FR-004), given to Git as -c user.name and -c user.email and never from the checkout's own configuration.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/library-commit-doctor.test.ts: in a real repository the commit has the identity as author and committer

Proved by: repoctl/suite/library-commit-doctor.test.ts

Written in: repoctl/src/governance/identity.ts, repoctl/src/logical/commit.ts

Tests: passed: suite/library-commit-doctor.test.ts in a real repository the commit has the identity as author and committer and the trailers

Cited by: governance/identity, Repoctl, logical/commit

FR-005checkpassing

The message of a commit MUST be the subject, a blank line, and then, each on a line of its own and in the order of the configuration's trailers, the reference to an issue (the configuration's prefix and the number of --refs, where it is given), the line Impact: <word> of FR-009, the line that credits the agent (--co-author, the variable REPOCTL_CO_AUTHOR or the configuration's) and Claude-Session: <address>, the address being --session or the variable CLAUDE_SESSION_URL; a subject that is not one line of at most 100 characters without a full stop, an issue that is not a number and an address that is missing or not https MUST be refused before anything is staged.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/library-commit-doctor.test.ts: the trailers are in order, and a subject, an issue and an address that do not fit are refused

Proved by: repoctl/suite/library-commit-doctor.test.ts

Tests: passed: suite/library-commit-doctor.test.ts in a real repository the commit has the identity as author and committer and the trailers ; passed: suite/library-commit-doctor.test.ts a subject, an issue and an address that do not fit are refused before anything is staged; passed: suite/library-commit-doctor.test.ts the message is the subject, a blank line, and the trailers in order, each on its own line,

Cited by: governance/identity, Repoctl

FR-006checkpassing

commit MUST refuse, naming the path and what it is, a file under .claude/, a file under node_modules/, and a file that looks like a secret by its name (an environment file, a key, a certificate, a file of credentials) or by what it holds (a private key, a token of npm, GitHub, Slack or AWS), and MUST make no commit then (E-COMMIT-FORBIDDEN).

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/library-commit-doctor.test.ts: a path of the agent, of installed packages and a secret are refused

Proved by: repoctl/suite/library-commit-doctor.test.ts

Tests: passed: suite/library-commit-doctor.test.ts a file of the agent, of installed packages or a secret is refused whether it is named or s; passed: suite/library-commit-doctor.test.ts a path of the agent, of installed packages, of a secret and a text that looks like a secre

FR-007checkpassing

commit MUST check the generated files before it commits and MUST make no commit where any generator is stale (E-STALE-GENERATED); with nothing staged and no path it MUST say so (E-COMMIT-NOTHING); and --dry-run MUST show the message and the files and commit nothing.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/library-commit-doctor.test.ts: a stale generator refuses the commit, nothing staged is said, and the preview commits nothing

Proved by: repoctl/suite/library-commit-doctor.test.ts

Tests: passed: suite/library-commit-doctor.test.ts a stale generator refuses the commit, nothing staged is said, and the preview shows the me

Cited by: Repoctl, logical/commit, physical/verbs/library

FR-008checkpassing

doctor MUST find, in the order to fix them, that Git does not run or the folder is not a working tree, that the root has no node_modules, that libraries are not linked, that Node is older than 26 or missing, that Bun is not the version the packaging ontology pins, and which generated files are stale, each with a code and the command that fixes it, and MUST say that the checkout is in order where it finds nothing.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/library-commit-doctor.test.ts: each thing wrong with a checkout is a finding with its code, in order

Proved by: repoctl/suite/library-commit-doctor.test.ts

Written in: repoctl/src/logical/doctor.ts

Tests: passed: suite/library-commit-doctor.test.ts each thing wrong with a checkout is a finding with its code, in the order to fix it, and n; passed: suite/library-commit-doctor.test.ts the facts of a real checkout are gathered through the ports: a folder with no dependencies; passed: suite/library-commit-doctor.test.ts the real checkout is in order

Cited by: Repoctl, logical/doctor, physical/verbs/check

FR-009checkpassing

commit --impact major|minor|patch MUST write the line Impact: <word> (commons 0026-works-versioning FR-021) in the place the configuration's trailers give to impact, MUST refuse a word that is none of the three with E-COMMIT-IMPACT before anything is staged, and MUST refuse the option where the configuration's trailers have no impact; a commit that gives none has no such line. repoctl new library MUST list the spec kit of the library it makes in the configuration of the site that the repository names (libraries.docsFile), so that the check of commons libraries 0001-libraries FR-025 finds it listed.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/host.test.ts: --impact writes the line in its place, a word that is none of the three and a configuration without the trailer are refused; suite/library-commit-doctor.test.ts: the message with the Impact line in order, and new library lists the spec kit in the configuration of the site

Proved by: repoctl/suite/host.test.ts

Tests: passed: suite/host.test.ts commit --impact writes the line Impact: after the reference to the issue where the configu

Acceptance scenarios

  1. Given a name and a summary, When new library --dry-run runs, Then the files are listed and none is written, per FR-001.
  2. Given a name and a summary, When new library runs in a copy of the repository, Then the library is there, its verify passes and sync --check ends with 0, per FR-001 and FR-003.
  3. Given Bad_Name, archon-x and an existing folder, When new library runs, Then each is refused with its code and nothing is written, per FR-002.
  4. Given a staged file, When commit runs, Then the commit has the identity as author and committer, whatever the checkout's configuration says, per FR-004.
  5. Given a subject, an issue and a session address, When the message is made, Then the trailers are in the order of FR-005, each on its own line.
  6. Given a staged .claude/settings.json, a .env or a file with a private key, When commit runs, Then it is refused and no commit is made, per FR-006.
  7. Given a stale generated file, When commit runs, Then it is refused with the generator named, per FR-007.
  8. Given a checkout with no node_modules, a Node of 22 and no link, When doctor runs, Then each is a finding with its code and its fix, in that order, per FR-008.

Out of scope

  • Pushing: the person pushes, with git push origin HEAD:main.
  • Signing a commit: the checkout's own configuration.

Edge cases

  • A path given to commit that is forbidden: refused before it is staged, per FR-006.
  • --refs absent: the commit has no Refs line, per FR-005.
  • A checkout with no origin: doctor warns that the tags and the base of the checks are not known, per FR-008.

Assumptions

  • The libraries of commons that Repoctl calls (libraries, the tools of commons) are on the branch that holds it, and git, bun and node are installed.

Open questions

  • None.

Key entities

  • Scaffold - the files of a new library.
  • Trailer - a line of the end of a commit message.

Success criteria

SC-001success criterion

A library made by new library passes its own verify and repoctl check.

SC-002success criterion

No commit is made with another identity, a missing trailer or a secret.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

governance/identity, Repoctl, logical/commit, logical/doctor, logical/mod, logical/scaffold, physical/verbs/check, physical/verbs/library

Titles, headings, exports, tables, columns and requirements. Esc closes.