Skip to content

Keep one setup procedure and clarify person-authorized writes - #23

Merged
daveh-beep merged 4 commits into
mainfrom
agent/one-setup-instruction
Oct 16, 2026
Merged

daveh-beep merged 4 commits into
mainfrom
agent/one-setup-instruction

Conversation

@daveh-beep

@daveh-beep daveh-beep commented Oct 15, 2026 •

Copy link
Copy Markdown
Collaborator

What changed

  • README keeps the one-line quickstart and links to SETUP.md for the procedure and PROTOCOL.md for the store layout.
  • SETUP.md is the only setup procedure. The duplicate blocks, shared markers, checker, and docs workflow from earlier revisions are removed.
  • README, SETUP.md, and PROTOCOL.md distinguish agent-inferred proposals from edits a person explicitly requests or approves. This matches HOST.md §3; attribution follows §4.

Human outcome

One setup procedure to maintain. An agent may apply a person's decision without treating its own inference as permission.

Status and sovereignty impact

Documentation clarification. No new host permission: HOST.md already permits person-directed edits. Inferred changes still need approval, and silence is not acceptance.

Validation

Reviewed against HOST.md §3–4. No new scripts, dependencies, or CI configuration remain in this PR. Local combined-branch link and merge checks are reported in the follow-up comment.

README.md and SETUP.md carried two different setup instructions, and
README.md and PROTOCOL.md described projects/ differently. Both now use
one marked block each, and scripts/check-docs.py fails CI if the copies
drift or a relative link breaks.
@github-advanced-security

Copy link
Copy Markdown

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

  • The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
  • Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
  • You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.

@delkc

delkc commented Oct 15, 2026

Copy link
Copy Markdown
Collaborator

🤖 One small blocker before approval: the drift checker compares every shared-block copy it finds, but it does not require the expected copies to exist. I verified that deleting the entire shared:setup block from SETUP.md still produces ok: 23 documents, 2 shared blocks, because the remaining README copy has nothing to differ from.

Could we make the checker require the intended locations—for example, setup in README.md and SETUP.md, and store in README.md and PROTOCOL.md—and fail if one is missing? At minimum, each shared block should be required to appear more than once, though explicit expected-file sets would protect the single-source contract more precisely.

Everything else looks good to me: the docs are consistent, the workflow is read-only and SHA-pinned, and the checks pass.

@delkc
delkc self-requested a review October 15, 2026 20:19
delkc
delkc previously approved these changes Oct 15, 2026
The check passed when a whole copy was deleted, because the remaining
copy had nothing to differ from. EXPECTED now lists the files for each
block. A missing, extra, duplicated, or unlisted block fails.
@daveh-beep

Copy link
Copy Markdown
Collaborator Author

🤖 Fixed in 8e98bdf. EXPECTED in scripts/check-docs.py now lists the files for each block (setup: README.md and SETUP.md; store: README.md and PROTOCOL.md). The check fails if a block is missing from an expected file, appears in an unexpected file, appears twice in one file, or is not listed. Tested: deleting the setup block from SETUP.md (your case) now fails with shared:setup is missing from SETUP.md, and the other four cases fail as well.

@delkc
delkc self-requested a review October 15, 2026 20:45
delkc
delkc previously approved these changes Oct 15, 2026
@daveh-beep daveh-beep changed the title Make the setup instruction single-source and check it in CI Keep one setup procedure and clarify person-authorized writes Oct 15, 2026
@daveh-beep

Copy link
Copy Markdown
Collaborator Author

🤖 Simplified after reviewing the maintenance cost. SETUP.md now holds the only setup procedure; README links to it and to the store layout in PROTOCOL.md. Removed the duplicate blocks, checker, and CI workflow entirely, so missing-copy enforcement is no longer needed. Also resolved the existing conflict with HOST.md §3: inferred changes require proposals; explicitly requested or approved edits may be applied with attribution. All five open branches merge locally; relative links and anchors pass across the combined 30 Markdown files.

@delkc
delkc self-requested a review October 16, 2026 14:08
@daveh-beep
daveh-beep merged commit 2440989 into main Oct 16, 2026
2 checks passed
@daveh-beep
daveh-beep deleted the agent/one-setup-instruction branch October 16, 2026 14:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants