Skip to content

Onboarding: STANDUP.md + cold-start self-test; enforce the audit as definition of done - #311

Merged
ptr727 merged 9 commits into
developfrom
onboarding-standup-selftest
Jul 16, 2026
Merged

Onboarding: STANDUP.md + cold-start self-test; enforce the audit as definition of done#311
ptr727 merged 9 commits into
developfrom
onboarding-standup-selftest

Conversation

@ptr727

@ptr727ptr727 commented Jul 16, 2026

Copy link
Copy Markdown
Owner

Implements the docs + matrix slice of the onboarding-strengthening roadmap (#310), from the Financial-Modeling retrospective. Left open for maintainer review - it adds governance wording to AGENTS.md and a new procedure doc, so it should be read before it lands.

Why

The hub already encoded what a conformant repo of each type needs (spec/files.json, spec/project-types.json, AUDIT.md), and running the audit against Financial-Modeling would have flagged every gap we hit reactively. The failure was operational: nothing required running the audit, there was no create-to-conformance counterpart, and no proof the docs are sufficient for a cold agent.

Changes

  • AUDIT.md section 0 - when to run + definition of done. Onboarding or touching a repo is complete only when it passes the audit or carries a tracked reports/<repo>/audit.md + issue, and the registry entry is reconciled to reality. Calls out that spec/validate.py proves catalog self-consistency, not that the catalog matches the live repo.
  • STANDUP.md (new) - the inverse of AUDIT.md. Ordered create-to-conformance steps (classify/catalog, carry baseline files, stand up workflows, apply settings/rulesets/secrets, verify), a "new repo type" procedure, and the cold-start self-test: a context-free agent stands each type up from the docs alone, then the audit must pass; iterate the docs until every type stands up cold.
  • reports/conformance-matrix.md (new) - per-type cold-standup + last-audited tracker, every type seeded not-tested.
  • AGENTS.md "Repository Onboarding and Conformance" - binds the above as obligations: definition of done is the audit, the registry is ground truth about reality, and a type that cannot be stood up cold is a documentation defect.

Validation

  • markdownlint - 0 errors; editorconfig-checker - clean; reference-link integrity (STANDUP.md, conformance-matrix.md) - no missing/unused defs.
  • New docs are CRLF per the [*] default; reference-style links grouped + alphabetized (AGENTS/copilot-instructions keep inline per the doc-style rule).

Refs #310. Queued next: the live python3 + gh fleet-audit runner (D).

🤖 Generated with Claude Code

@ptr727@claude
Add STANDUP.md + cold-start self-test; enforce the audit as definitio…
e5160b7
…n of done
Strengthens onboarding after the Financial-Modeling retrospective (#310). The
hub already encoded what a conformant repo needs (spec/files.json,
project-types.json, AUDIT.md), but nothing required running the audit, there
was no create-to-conformance counterpart, and no proof the docs suffice cold.
- AUDIT.md 0: when to run + definition of done. Onboarding/touching a repo is
complete only when it passes the audit or carries a tracked report + issue;
the registry must be reconciled to reality (validate.py proves catalog
self-consistency, not that it matches the live repo).
- STANDUP.md (new): the inverse of AUDIT.md - ordered create-to-conformance
steps zero to operational, reusing the same manifests, plus a "new repo
type" procedure and the cold-start self-test.
- reports/conformance-matrix.md (new): per-type cold-standup + last-audited
tracker; every type seeded not-tested.
- AGENTS.md: "Repository Onboarding and Conformance" section binding the above
as obligations (definition of done, registry-is-reality, prove-docs-suffice).
Part of #310 (docs + matrix slice; live fleet-audit runner queued next).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
CopilotAI review requested due to automatic review settings July 16, 2026 05:14
CopilotAI reviewed Jul 16, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR strengthens onboarding governance by adding a stand-up (create-to-conformance) procedure, a per-type cold-start self-test concept, and explicit “audit is definition-of-done” language so onboarding and conformance changes are driven by the manifests and verified by AUDIT.md.

Changes:

  • Add STANDUP.md as the create-to-conformance counterpart to AUDIT.md, including a cold-start self-test procedure.
  • Add reports/conformance-matrix.md to track per-type cold-standup status and last-audited dates.
  • Update AUDIT.md and AGENTS.md to explicitly bind “done” to passing the audit (or tracking residual deltas) and to require reconciling registry/repos.json to reality.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

FileDescription
STANDUP.mdNew stand-up procedure doc and cold-start self-test guidance aligned to existing manifests and audit.
reports/conformance-matrix.mdNew tracker for cold-standup results and last-audited timestamps per supported type.
AUDIT.mdAdds a “when to run / what done means” section and links STANDUP.md + spec/validate.py in that framing.
AGENTS.mdAdds onboarding/conformance obligations tying “done” to the audit and the registry-to-reality reconciliation.

Comment threadAGENTS.md Outdated
Comment threadAUDIT.md Outdated
Comment threadreports/conformance-matrix.md Outdated
@ptr727@claude
Present-tense the onboarding docs (Copilot#311)
d5fcf55
Restate three sentences in present tense per the doc-style rule (no historical
framing): AGENTS "proved" -> "is", AUDIT "was partially set up" -> "is", and the
conformance-matrix note drops the "drove/tracked" history. Also aligns the
STANDUP wording ("chose" -> "uses").
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
CopilotAI review requested due to automatic review settings July 16, 2026 05:20
CopilotAI reviewed Jul 16, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

Comment threadSTANDUP.md Outdated
Comment threadreports/conformance-matrix.md Outdated
@ptr727@claude
Address second Copilot pass on#311
560c6b3
- STANDUP.md: show configure.sh args as optional ([owner/repo]) matching the
script's documented signature and defaults.
- reports/conformance-matrix.md: render the operational row's type as a code
literal for table consistency.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
CopilotAI review requested due to automatic review settings July 16, 2026 05:24
CopilotAI reviewed Jul 16, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

Comment threadAGENTS.md Outdated
Comment threadreports/conformance-matrix.md Outdated
@ptr727@claude
Address third Copilot pass on#311
0b02be6
- AGENTS.md: the onboarding section lists three obligations, not two.
- reports/conformance-matrix.md: present-tense the intro and the value legend.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
CopilotAI review requested due to automatic review settings July 16, 2026 05:27
CopilotAI reviewed Jul 16, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

Comment threadAUDIT.md Outdated
@ptr727@claude
Present-tense one more AUDIT.md line (Copilot#311)
848419a
"records what is, not what was intended" -> "records reality, not intent".
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
CopilotAI review requested due to automatic review settings July 16, 2026 05:31
CopilotAI reviewed Jul 16, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

Comment threadSTANDUP.md Outdated
Comment threadreports/conformance-matrix.md Outdated
@ptr727@claude
Address the two remaining Copilot threads on#311
f5669ea
- STANDUP.md: point the adapt-before-propagating reference at the CODESTYLE.md
callout so readers can find the rule.
- reports/conformance-matrix.md: document the Last-audited date format
(YYYY-MM-DD).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
CopilotAI review requested due to automatic review settings July 16, 2026 14:04
CopilotAI reviewed Jul 16, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

Comment threadreports/conformance-matrix.md Outdated
Comment threadSTANDUP.md Outdated
@ptr727@claude
Rename per-type to per-shape in the self-test surfaces (Copilot#311)
fac1f66
"operational" is a workflowModel overlay, not a spec/project-types.json type;
the matrix, self-test, and AGENTS obligation now say repo "shape" (project
type(s) plus workflow model) so the terminology matches WORKFLOW.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
CopilotAI review requested due to automatic review settings July 16, 2026 14:15
CopilotAI reviewed Jul 16, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

Comment threadreports/conformance-matrix.md Outdated
@ptr727@claude
Document the Last-audited placeholder (Copilot#311)
92221f5
"-" is the canonical not-yet-audited value alongside the YYYY-MM-DD date.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
CopilotAI review requested due to automatic review settings July 16, 2026 14:19
CopilotAI reviewed Jul 16, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

Comment threadSTANDUP.md Outdated
@ptr727@claude
Name the real registry field in the STANDUP secrets step (Copilot#311)
0e6f772
"every requiredSecret" implied a singular field; the registry field is
requiredSecrets[], and the baseline secrets are implicit - say both.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
CopilotAI review requested due to automatic review settings July 16, 2026 14:27
CopilotAI reviewed Jul 16, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

@ptr727
ptr727 merged commit b665424 into developJul 16, 2026
7 checks passed
@ptr727
ptr727 deleted the onboarding-standup-selftest branch July 16, 2026 14:39
@ptr727ptr727 mentioned this pull request Jul 16, 2026
Merged
ptr727 added a commit that referenced this pull request Jul 16, 2026
@ptr727
Promote develop to main: onboarding governance (STANDUP/self-test) + …
10ff417
…carry robustness (#315)
Promotes two squashed increments:
- **#311** - onboarding governance (part of the #310 roadmap):
`STANDUP.md` (create-to-conformance, inverse of `AUDIT.md`), the
cold-start self-test + `reports/conformance-matrix.md`, `AUDIT.md`
section 0 (when to run / definition of done), and the `AGENTS.md`
"Repository Onboarding and Conformance" obligations. Maintainer-reviewed
and approved.
- **#314** - #313 incorporation (Financial-Modeling carry findings):
`configure.sh` fails fast on a missing/nameless ruleset payload;
`repo-config/README.md` is downstream-neutral (Downstream Carry section,
no private-hub URL links from downstream, parameterized regen snippet,
per-mechanism secrets applicability); `publish-release.yml` drops the
vestigial exists-gate (dispatch-only = create-or-refresh, no behavior
change); `WORKFLOW.md` D4 records the gate N/A on dispatch-only
publishers.
Refs #310 (roadmap - slice D, the live fleet-audit runner, remains
queued).
Closes#313.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
@ptr727ptr727 mentioned this pull request Jul 16, 2026
Merged
ptr727 added a commit that referenced this pull request Jul 16, 2026
@ptr727@claude
Add spec/audit.py: on-demand live fleet audit (roadmap#310slice D) (#…
95e56d6
…324)
The "runner next" half of the #310 roadmap decision (docs + matrix
landed in #311). Scope per owner direction: **on-demand only,
owner-initiated** (onboarding, suspected drift, deliberate changes) - no
scheduled workflow, no App-token machinery; it runs under the local `gh`
auth.
## What it does
`python3 spec/audit.py [RepoName ...]` (default: all 21 cataloged repos)
executes the deterministic subset of `AUDIT.md` per repo, read-only:
- **Settings** vs `repo-config/settings.json` (+ computed
`has_discussions`/`default_branch`)
- **Rulesets** vs the model's payloads (normalized diff;
missing/stray/duplicate flagged; `operational` repos compare
`operational/develop.json`)
- **Secrets (names only)** vs `spec/secrets.json`: baseline +
per-mechanism required in the right stores, forbidden anywhere,
unclaimed flagged as stale
- **File presence** on the ground-truth branch per `spec/files.json`
(model-aware `develop` payload path)
- **Branch facts**: main/develop existence, registry `hasDevelop` vs
reality, and content divergence via **tree compare** - commit counts
mislead under merge-commit promotions, so only a `develop...main` diff
with changed files (main carries content develop lacks) reports
Findings are typed `DEFECT` / `LETTER` (file absent, intent unverified
per AUDIT.md section 7) / `DRIFT`; exit is non-zero on defect/letter.
`AUDIT.md` section 0 references the runner.
## Live-tested (read-only)
- **Financial-Modeling** - reports exactly its known standup state: the
#14 files (`WORKFLOW.md`, `version.json`, `repo-config/*`,
`dependabot.yml`) absent on `main` pending PR #15;
settings/rulesets/secrets clean (as applied).
- **ProjectTemplate / PlexCleaner / HomeAutomation-Config** - exercised
the release, docker-secrets, and operational paths. Genuine drift
surfaced (stale hub secrets incl. `NINJA_API_KEY`/`NUGET_API_KEY`;
HomeAutomation-Config missing the baseline App pair; PlexCleaner missing
the repo-config carry) - reported to the maintainer separately, not
acted on.
Refs #310 (the cold-start self-test matrix remains the roadmap's open
acceptance item).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code reviewCopilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@ptr727