Complete the governance tooling and smooth first-time adoption - #12
Merged
Conversation
added 14 commits
July 25, 2026 12:52
…t only the reviewer Before, only the review exported, so a deployment with audit.sink on captured the reviewer's decisions but lost the produce side (developer/council), the test and documentation agents, and the operator agents. Now every path records through one route and exports from a credential-safe point: operate-run (the produce wrapper) exports if a sink credential is present; run-agent, dev-council.sh, and test/docsync export at their end; the untrusted PR review keeps its record/publish split. test/docsync record and export on any exit (dry-run, guard refusal, real run) via a trap, and the export is inert without a sink credential. audit-export.sh derives the governed repo from the git remote when GITHUB_REPOSITORY is unset, so the same-repo refusal holds on host runs, not only CI. A dynamic doctor completeness check enumerates every record-writing path and warns on any with no export route, so a new agent cannot silently drop its trail. Tests for all of it, and audit-export.test.sh + the runner-trail test wired into the base suite (audit-export was untested before). Signed-off-by: Christoph <awchristoph@gmail.com>
An OpenSpec change (spec only, no implementation): an opt-in capture store, separate from the thin ledger, holding the full input+output of each agent call, deployment-owned and never public. Per-record schema with model_class (frontier|open); outcome labelling from governance signals (pending -> positive on clean merge -> negative on an escaped-defect link); knowledge and corpus views derived from the one store. The content-safe companion to the audit-trail completeness work: that ships the digest to the sink, this captures the full trajectory so the org can own its coding data and, later, train its own open models. Off by default; builtin mirror included. Signed-off-by: Christoph <awchristoph@gmail.com>
…st suite conventions.preflight (the adopter's own ruff/pytest/mypy command) was declared and shown to the agents but never run. asdd-preflight.yml now runs it on every PR via .github/asdd/preflight.sh, so a regression the model review missed is caught by the real suite; the command's exit status is the gate. Distinct from the model test-runner agent, holds no secrets (safe for a fork PR behind the fork-workflow approval), and an opt-in no-op until the command is set. Copied by init; a self-test (pass, a broken test fails, unconfigured is a no-op) is wired into the base suite. Signed-off-by: Christoph <awchristoph@gmail.com>
… as JSON Add three preflight and intake guards that catch a misconfiguration up front instead of after the work is done: - doctor warns when user.name / user.email are unset, so a contributor learns their commits cannot be signed off before the first commit, not at intake. - connect-check gains --json: the per-role connected status is machine-readable for a setup script or CI, with the same accounting and exit code. - intake warns (without failing) when a change labelled chore adds or edits a spec, since the chore lane is spec-exempt and such a change is a mislabelled feature or fix. Each guard is deterministic and covered by its self-test; the full base suite stays green (30/30). Signed-off-by: Christoph Welsbach <awchristoph@gmail.com>
…ting-started guide The developer is always the contributor's own, so a contributor's assistant has to find the repository's rules on its own. init now writes a thin pointer for each common assistant that references AGENTS.md: - CLAUDE.md for Claude Code and the Claude app - .cursor/rules/asdd.mdc for Cursor - AGENTS.md itself for Codex and any tool following that convention Each pointer is skipped if the file already exists, so an existing rule file is never overwritten. A new guide, docs/guides/bring-your-own-developer.md, walks the path from an idea (talk it through with the spec agent, no engineering background needed) to a merged change, and notes the operate agents run on open-source Goose. The README get-started step now shows the same. init.test.sh asserts the pointers ship in the base profile, reference AGENTS.md, and do not clobber an existing file. Signed-off-by: Christoph Welsbach <awchristoph@gmail.com>
The completeness check enumerated record-writing paths under cli/ and .github/asdd/, and treated a recorder as covered if any sibling file named it and exported. That escape is wrong for a CI workflow: the sink credential lives in the job, so a workflow that runs a recorder which does not itself export must export in that same job, and cannot lean on a runner it bypassed. A deployment that wires dev-council.py straight into a workflow, instead of through the exporting dev-council.sh runner, would otherwise drop the produce trail with the sibling-runner escape hiding it. The check now scans .github/workflows and holds a workflow that runs dev-council.py or a raw audit.py append/from-review to an in-job export step. The framework's own workflows go through the exporting runners, so they stay green; only a bypassing deployment is warned. Covered by two new doctor self-test cases (flagged without an in-job export, clean with one); the base suite stays green. Signed-off-by: Christoph Welsbach <awchristoph@gmail.com>
init copies asdd-preflight.yml and preflight.sh, but the self-test did not check they land, unlike every other copied workflow and its script. A rename could drop the pair and leave a workflow calling a script that is not there. Assert both reach a plain adopter. Signed-off-by: Christoph Welsbach <awchristoph@gmail.com>
The setup guide showed the human connect-check output but not the --json flag, so a reader wiring it into a setup script or CI would not find it. Add the one-line usage next to the human form. Signed-off-by: Christoph Welsbach <awchristoph@gmail.com>
The deploy guide enumerates what init writes, but not the editor pointers it now drops (CLAUDE.md, the Cursor rule), so a reader comparing the guide to their tree would find files the guide does not mention. Add them, note the skip-if-exists behaviour, and link the bring-your-own-developer guide. Signed-off-by: Christoph Welsbach <awchristoph@gmail.com>
…nto governance-completeness-and-getting-started
…nto governance-completeness-and-getting-started
…to governance-completeness-and-getting-started # Conflicts: # CHANGELOG.md
…vernance-completeness-and-getting-started # Conflicts: # CHANGELOG.md # cli/doctor.test.sh
…' into governance-completeness-and-getting-started # Conflicts: # CHANGELOG.md # cli/init.test.sh
The declared docs convention holds that a command or gate is not shipped until the CLI reference describes it, and a new guide must be indexed. Update the references for the CLI changes in this branch: - cli/README.md: connect-check --json, and doctor's new warnings (unset git identity, a reasoning-model reviewer, and any record path or CI job with no audit export route). - docs/reference/README.md: add connect-check to the command list. - docs/README.md: index the bring-your-own-developer guide. Signed-off-by: Christoph Welsbach <awchristoph@gmail.com>
|
ASDD review - advisory (recommendation:
The review runtime returned invalid output; a human should review manually. Security scan (deterministic + SAST): 4 finding(s). Impact scan: 1 finding(s), 0 block. SECURITY - ok
IMPACT - concerns
Generated by the ASDD advisory review. Mode: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Five related improvements that make a governed setup complete out of the box and easier to adopt. Each is independently self-tested; the deterministic validation suite passes 33 of 33.
doctorenumerates every record-writing path, including the CI workflow surface, and warns on any with no export route, so a new recorder cannot silently drop its trail.doctorwarns on an unset git identity and on a heavy reasoning-model reviewer;connect-checkgains--jsonfor CI; intake warns when achorechange authors a spec.initwrites a pointer for the common assistants (CLAUDE.md,.cursor/rules/asdd.mdc; Codex readsAGENTS.md) so a contributor's tool loads the constitution automatically, plus a guide covering the path from a plain-language idea to a merged change.Disclosure (required - ASDD)
Agent identity (if any): Claude
Instructed by (human handle): welsbach
Spec
Adds
docs/specs/agent-trajectory-capture.mdandopenspec/changes/agent-trajectory-capture/. The remaining changes are governance tooling and documentation.Checklist