Visitar URL original
Onboarding: STANDUP.md + cold-start self-test; enforce the audit as definition of done by ptr727 · Pull Request #311 · ptr727/ProjectTemplate · GitHub
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

@ptr727 ptr727 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>
Copilot AI review requested due to automatic review settings July 16, 2026 05:14
Copilot AI reviewed Jul 16, 2026
View reviewed changes

Copilot AI 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.

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

Comment thread AGENTS.md Resolved
Comment thread AUDIT.md Resolved
Comment thread reports/conformance-matrix.md Resolved
@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>
Copilot AI review requested due to automatic review settings July 16, 2026 05:20
Copilot AI reviewed Jul 16, 2026
View reviewed changes

Copilot AI 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 thread STANDUP.md Resolved
Comment thread reports/conformance-matrix.md Resolved
@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>
Copilot AI review requested due to automatic review settings July 16, 2026 05:24
Copilot AI reviewed Jul 16, 2026
View reviewed changes

Copilot AI 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 thread AGENTS.md Resolved
Comment thread reports/conformance-matrix.md Resolved
@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>
Copilot AI review requested due to automatic review settings July 16, 2026 05:27
Copilot AI reviewed Jul 16, 2026
View reviewed changes

Copilot AI 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 thread AUDIT.md Resolved
@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>
Copilot AI review requested due to automatic review settings July 16, 2026 05:31
Copilot AI reviewed Jul 16, 2026
View reviewed changes

Copilot AI 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 thread STANDUP.md Resolved
Comment thread reports/conformance-matrix.md Resolved
@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>
Copilot AI review requested due to automatic review settings July 16, 2026 14:04
Copilot AI reviewed Jul 16, 2026
View reviewed changes

Copilot AI 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 thread reports/conformance-matrix.md Resolved
Comment thread STANDUP.md Resolved
@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>
Copilot AI review requested due to automatic review settings July 16, 2026 14:15
Copilot AI reviewed Jul 16, 2026
View reviewed changes

Copilot AI 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 thread reports/conformance-matrix.md Resolved
@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>
Copilot AI review requested due to automatic review settings July 16, 2026 14:19
Copilot AI reviewed Jul 16, 2026
View reviewed changes

Copilot AI 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 thread STANDUP.md Resolved
@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>
Copilot AI review requested due to automatic review settings July 16, 2026 14:27
Copilot AI reviewed Jul 16, 2026
View reviewed changes

Copilot AI 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 develop Jul 16, 2026
7 checks passed
@ptr727
ptr727 deleted the onboarding-standup-selftest branch July 16, 2026 14:39
@ptr727 ptr727 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)
@ptr727 ptr727 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 #310 slice 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 free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
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