docs: fold the Rules feature spec into the codebase#16
Merged
Conversation
Replace the standalone Docs/AGENT_RULES_FEATURE_SPEC.md with the spec living where it belongs — as /// doc comments on the source each topic owns — and slim the central doc to Docs/RULES_SPEC.md, a navigational index: concept, current navigation map, the §4.8 cross-cutting "strictest wins" invariant, the background-architecture overview, a topic → source table, and a historical appendix for the pre-reskin custom design. The codebase already documented its behavior thoroughly in doc comments, so this mostly recognizes that and makes it navigable. A few durable details were added where the spec was richer than the code: the Schedule-only rationale in RuleConfiguration and the Allow-Only "can't punch a hole" invariant in ShieldController. Reframe doc ownership (AGENTS.md, CLAUDE.md, AGENT_SWIFT_GUIDELINES.md): the rules spec is now human-owned and co-maintained — update the owning file's doc comment in the same commit as the code. Adds a "shared" bucket to the AGENT_-prefix contract so RULES_SPEC.md is editable by both humans and agents. Build green; 240/240 tests pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012E73uBVKkqL25RJrF7tfmm
Fold the standalone Docs/RULES_SPEC.md into AGENTS.md as a "Rules feature map" section — AGENTS.md is the thin agent directory, so the spec's un-foldable residual (concept pointer, screen tree, topic → source table, out-of-scope) belongs there rather than in a parallel Docs file. The §4.8 "strictest enforcement wins" invariant goes the other way — into the RuleEnforcer doc comment that owns it — so the only remaining cross-cutting prose is the map itself. Removes Docs/RULES_SPEC.md; points CLAUDE.md and AGENT_SWIFT_GUIDELINES.md at the map; drops the now-dangling "spec §4.8" references in RuleEnforcer / ShieldController / RuleEnforcerTests (the invariant now reads self-contained in RuleEnforcer). The pre-reskin design remains recoverable from git history. Build green; 240/240 tests pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012E73uBVKkqL25RJrF7tfmm
brendan-ch
added a commit
that referenced
this pull request
Jun 20, 2026
Resolve conflicts from PR #16 (feature spec folded into source doc comments): - AGENTS.md: adopt main's three-bucket Documentation structure; keep the Docs/Agents/ ownership-by-location note; add the OpenAppLockReport extension, DayStartStore, and an authoritative-usage row to the layout + feature map. - Docs/AGENT_RULES_FEATURE_SPEC.md: accept main's deletion — the hardening behavior is already documented in source doc comments (DayStartStore, LimitEnforcement, MonitoringPlan, the report files, RuleEnforcer). - Retarget the design spec's references from the deleted file to the new doc-comment convention. RuleEnforcer.swift and RuleEnforcerTests.swift auto-merged cleanly. Merged tree builds; 253/253 unit tests pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TD4vdHbB8KqLPGYNbYNS5U
This was referenced Jun 20, 2026
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
Folds the standalone
Docs/AGENT_RULES_FEATURE_SPEC.md(~620 lines) into thecodebase itself, so the rules-feature spec lives where contributors actually
work and is maintained alongside the code it describes.
The key realization while doing this: the codebase already documented its
behavior thoroughly in
///doc comments on each type. So "folding the spec in"was mostly recognizing that, adding the few durable details the comments
lacked, and replacing the parallel
Docsfile with navigation + ownershipwiring — not bulk-pasting prose (which would have duplicated what the code
already says).
What changed
///doc comments on the source each topic owns. A fewgenuinely-missing rationales were added: the Schedule-only reasoning in
RuleConfiguration, the Allow-Only "can't punch a hole" invariant inShieldController, and the full "strictest enforcement wins" invariant(formerly §4.8) in
RuleEnforcer.Docs/AGENT_RULES_FEATURE_SPEC.mdremoved. Its un-foldable residual(concept pointer, screen tree, topic → source map, out-of-scope) now lives
as a "Rules feature map" section in
AGENTS.md— the thin agent directory— so there is no parallel spec file to drift.
AGENTS.md,CLAUDE.md,AGENT_SWIFT_GUIDELINES.md):the spec is co-maintained with the code — update the owning file's doc comment
in the same commit as the behavior change. The doc-ownership contract gained a
"shared (human + agent)" bucket for it.
Net:
Docs/now holds onlyAGENT_SWIFT_GUIDELINES.md; the spec is the codeplus a one-screen map. The pre-reskin custom design is preserved in git history.
Test plan
AGENT_RULES_FEATURE_SPEC,RULES_SPEC,§allresolved or removed)
AGENTS.mdmap verified to exist on diskAGENTS.md"Rules feature map" and a coupleof the folded doc comments to confirm the structure reads well
🤖 Generated with Claude Code
https://claude.ai/code/session_012E73uBVKkqL25RJrF7tfmm