docs: standardize frontmatter routing descriptions - #208
Conversation
📝 WalkthroughWalkthroughThe pull request updates the Evidence Console design metadata, adds frontmatter routing rules, and clarifies applicability boundaries across ADR-0002 through ADR-0097. It also adds ADR-0097 and updates the ADR index and authoring guidance. ChangesDocumentation frontmatter and ADR metadata
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ec1d0b2ba0
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| architecture decisions, and `DESIGN.md`. A new agent-facing document class | ||
| inherits the same rule unless a later accepted ADR records and configures an | ||
| explicit exception. | ||
| 2. Every description is English-only, contains 40–500 English characters, |
There was a problem hiding this comment.
The new rule makes every frontmatter description English-only, but the backfilled description in docs/decisions/0004-wecom-only-weak-acl-degradation.md:5 still contains the Chinese text 企业微信. Consequently, the committed tree already violates this accepted rule despite being presented as a clean baseline; translate the parenthetical or narrow the rule explicitly. Accepted ADRs are implementation authority in this repository.
AGENTS.md reference: AGENTS.md:L22-L24
Useful? React with 👍 / 👎.
| hop into post-authorization ranking. | ||
| hop into post-authorization ranking. Use when publishing rich Markdown link | ||
| lineage or ranking one authorized graph hop. Not for link edges as authority, | ||
| content-bearing pre-Kernel graphs, or unreauthorized cross-Article content. |
There was a problem hiding this comment.
When an agent uses this frontmatter to route graph-expansion work, the nonexistent word unreauthorized obscures the security boundary being prohibited. Replace it with an unambiguous phrase such as “cross-Article content without reauthorization,” because every cross-Article expansion must receive a new authorization decision.
AGENTS.md reference: AGENTS.md:L110-L110
Useful? React with 👍 / 👎.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/decisions/0015-rls-transaction-context-and-schema-manifest.md`:
- Around line 6-8: Update the scope statement in the ADR introduction to keep
owner-role isolation tests included, while continuing to exclude only
organization-only access and tests unrelated to RLS role isolation. Remove the
“Not for owner-role isolation tests” exclusion without changing the ADR’s
coverage of PostgreSQL RLS, schema-owner/runtime/worker roles, or
transaction-scoped actor context.
In
`@docs/decisions/0073-compose-explicit-release-candidates-from-current-corpus.md`:
- Around line 7-9: Update the ADR scope statement to avoid excluding the
operator-authorized promote-release workflow defined around the promote-release
command and ContextLearning.evaluate. Limit the exclusion to direct promotion
that bypasses ContextLearning, while preserving the existing restriction against
publication outside Learning.
In
`@docs/decisions/0093-activate-leased-rich-markdown-and-revision-link-graph.md`:
- Line 9: In the exclusion clause, replace the misspelled term “unreauthorized”
with “unauthorized,” leaving the surrounding text unchanged.
- Around line 7-8: Update the ADR-0093 scope description to explicitly cover
only immutable, content-free Revision-link edges and a single authorized graph
hop; remove the reference to publishing rich Markdown link lineage and clearly
exclude content-bearing graph work.
In `@docs/decisions/0095-bridge-runtime-rerank-through-one-internal-package.md`:
- Around line 5-10: Update the applicability clause in the decision introduction
to restrict this decision exclusively to the authorized rerank bridge; remove
the broader reference to other Runtime-internal model inference while preserving
the existing exclusions around activation, internal grants or packages, and
sealed authorization and egress.
In `@docs/decisions/0097-require-routing-clauses-in-agent-facing-frontmatter.md`:
- Line 14: Update the Date field in the ADR frontmatter to the actual acceptance
date, August 1, 2026, so it is not future-dated.
In `@docs/decisions/README.md`:
- Line 35: Update the ADR-0097 row in the decisions table so its
prohibited-condition text matches the accepted exception rule, replacing the
unqualified “Document-class exceptions” wording with “Informal document-class
exceptions” or an equivalent phrase requiring an accepted refining ADR.
- Around line 13-25: Update the ADR skeleton in the README frontmatter so all
decision-specific routing text is visibly placeholder-based, including the name,
description choice, trigger, shortcut, exclusion, and deferred capability.
Require authors to replace every placeholder with language derived from the new
ADR’s Decision before review, while preserving the existing YAML structure.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 6b50a5ce-2660-4864-9996-735a909572d0
📒 Files selected for processing (95)
.claude/skills/context-engine/SKILL.mdDESIGN.mddocs/decisions/0002-bot-gateway-outside-engine.mddocs/decisions/0003-group-chat-intersection-authorization.mddocs/decisions/0004-wecom-only-weak-acl-degradation.mddocs/decisions/0005-python-stack.mddocs/decisions/0006-engine-delivers-context-not-answers.mddocs/decisions/0007-postgres-as-authorization-truth.mddocs/decisions/0008-modular-monolith-plus-worker.mddocs/decisions/0009-pgvector-first-index.mddocs/decisions/0010-policy-epoch-revocation.mddocs/decisions/0011-read-write-plane-separation.mddocs/decisions/0012-sealed-authorization-projection-pipeline.mddocs/decisions/0013-trusted-delivery-egress-and-capability-taxonomy.mddocs/decisions/0014-curation-snapshot-and-release-ownership.mddocs/decisions/0015-rls-transaction-context-and-schema-manifest.mddocs/decisions/0016-implementation-authority-and-vertical-slice-roadmap.mddocs/decisions/0017-trusted-invocation-and-closed-runtime-access.mddocs/decisions/0018-immutable-revision-publication.mddocs/decisions/0019-security-catalog-normalization.mddocs/decisions/0020-stage-organization-rls-before-actor-context.mddocs/decisions/0021-stage-http-authentication-before-provider-selection.mddocs/decisions/0022-stage-tenant-safe-empty-context-package.mddocs/decisions/0023-bind-runtime-to-current-membership-user-actor.mddocs/decisions/0024-model-effective-scope-as-finite-target-intersection.mddocs/decisions/0025-bind-materialized-projection-to-the-current-runtime-transaction.mddocs/decisions/0026-normalize-no-authorized-evidence.mddocs/decisions/0027-organization-policy-epoch.mddocs/decisions/0028-fail-closed-unavailable-runtime-capabilities.mddocs/decisions/0029-bound-first-worker-lease-to-persistent-no-op-jobs.mddocs/decisions/0030-bound-ticket-audiences.mddocs/decisions/0031-persist-authorized-context-run-lineage.mddocs/decisions/0032-bind-materialized-fields-to-membership-projection-rights.mddocs/decisions/0033-promote-organization-releases-through-one-learning-owner.mddocs/decisions/0034-execute-the-m0-security-veto-from-registered-evidence.mddocs/decisions/0035-register-file-sources-through-context-control.mddocs/decisions/0036-compile-narrow-markdown-deterministically.mddocs/decisions/0037-publish-first-file-through-exact-worker-lease.mddocs/decisions/0038-compile-and-publish-structural-markdown.mddocs/decisions/0039-deduplicate-unchanged-file-acquisitions.mddocs/decisions/0040-stage-and-atomically-activate-file-replacements.mddocs/decisions/0041-recover-file-publication-by-durable-boundary.mddocs/decisions/0042-tombstone-file-resources-before-cleanup.mddocs/decisions/0043-separate-file-acquisition-progress-from-publication-progress.mddocs/decisions/0044-disable-file-sources-before-cleanup.mddocs/decisions/0045-redeem-private-delivery-evidence-at-ingress.mddocs/decisions/0046-bind-egress-to-one-exact-package-hop.mddocs/decisions/0047-freeze-openapi-v0-through-one-runtime-path.mddocs/decisions/0048-generate-typescript-sdk-behind-a-closed-facade.mddocs/decisions/0049-prepare-one-exact-private-effect.mddocs/decisions/0050-perform-one-exact-private-effect.mddocs/decisions/0051-reauthorize-opaque-citation-opens.mddocs/decisions/0052-gate-model-generation-by-package.mddocs/decisions/0053-compose-one-private-bot-delivery.mddocs/decisions/0054-acknowledge-file-change-pages-before-cursor-advance.mddocs/decisions/0055-schedule-accepted-file-observations-explicitly.mddocs/decisions/0056-detect-file-deletions-without-tombstone-authority.mddocs/decisions/0057-execute-current-file-deletes-through-tombstone-authority.mddocs/decisions/0058-schedule-only-upserts-from-mixed-file-pages.mddocs/decisions/0059-dispatch-scheduled-file-imports-through-exact-leases.mddocs/decisions/0060-reclaim-expired-file-imports-with-bounded-retries.mddocs/decisions/0061-commit-to-the-complete-context-layer-thesis.mddocs/decisions/0062-pull-development-through-dogfood-workloads.mddocs/decisions/0063-admit-an-explicit-dogfood-authentication-composition.mddocs/decisions/0064-split-process-ceremony-along-the-kernel-seam-boundary.mddocs/decisions/0065-recurse-file-discovery-with-anchored-descriptors.mddocs/decisions/0066-embed-fragments-before-publication.mddocs/decisions/0067-discover-vector-candidates-in-the-current-runtime-transaction.mddocs/decisions/0068-activate-loopback-dogfood-runtime.mddocs/decisions/0069-admit-an-explicit-local-operator-composition.mddocs/decisions/0070-activate-file-change-feed-from-registration.mddocs/decisions/0071-compose-bounded-file-scan-cycles.mddocs/decisions/0072-report-file-source-status-with-closed-refusals.mddocs/decisions/0073-compose-explicit-release-candidates-from-current-corpus.mddocs/decisions/0074-adopt-controlled-third-party-code-reuse.mddocs/decisions/0075-reuse-onyx-capabilities-through-owned-runners-and-seams.mddocs/decisions/0076-rejoin-rank-evidence-after-authorization.mddocs/decisions/0077-fix-the-article-as-the-content-authorization-atom.mddocs/decisions/0078-narrow-the-contract-kit-gate-to-per-connector-twins.mddocs/decisions/0079-compile-rich-markdown-in-an-owned-runner.mddocs/decisions/0080-refuse-authoritative-evaluation-without-an-executor.mddocs/decisions/0084-exempt-maintainer-decided-unproduced-artifact-kinds.mddocs/decisions/0085-bound-supply-connector-executions.mddocs/decisions/0086-report-worker-batches-and-compose-source-wide-cycles.mddocs/decisions/0088-bind-local-consumers-to-fresh-evidence-bearing-packages.mddocs/decisions/0089-bound-live-feishu-to-the-existing-private-bot-composition.mddocs/decisions/0090-admit-a-co-resident-local-evidence-console.mddocs/decisions/0091-reconcile-connector-acl-freshness-at-acceptance.mddocs/decisions/0092-authorize-feishu-subjects-and-bound-mirrored-freshness.mddocs/decisions/0093-activate-leased-rich-markdown-and-revision-link-graph.mddocs/decisions/0094-admit-a-format-neutral-parsed-document-family.mddocs/decisions/0095-bridge-runtime-rerank-through-one-internal-package.mddocs/decisions/0096-bind-package-token-accounting-to-release-tokenizer.mddocs/decisions/0097-require-routing-clauses-in-agent-facing-frontmatter.mddocs/decisions/README.md
| all-table schema security manifest for PostgreSQL RLS. Use when adding tables, | ||
| RLS policies, roles, or transaction-scoped actor context. Not for | ||
| Organization-only access or owner-role isolation tests. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Keep owner-role isolation tests in scope.
This ADR separates schema-owner roles from runtime and worker roles. It also requires PostgreSQL evidence for RLS and role isolation. The Not for owner-role isolation tests clause routes those tests away from the ADR that governs them.
Exclude only organization-only slices or tests unrelated to RLS role isolation.
Proposed fix
- all-table schema security manifest for PostgreSQL RLS. Use when adding tables,
- RLS policies, roles, or transaction-scoped actor context. Not for
- Organization-only access or owner-role isolation tests.
+ all-table schema security manifest for PostgreSQL RLS. Use when adding tables,
+ RLS policies, roles, or transaction-scoped actor context. Not for
+ organization-only access slices covered by ADR-0020 or tests unrelated to RLS
+ role isolation.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| all-table schema security manifest for PostgreSQL RLS. Use when adding tables, | |
| RLS policies, roles, or transaction-scoped actor context. Not for | |
| Organization-only access or owner-role isolation tests. | |
| all-table schema security manifest for PostgreSQL RLS. Use when adding tables, | |
| RLS policies, roles, or transaction-scoped actor context. Not for | |
| organization-only access slices covered by ADR-0020 or tests unrelated to RLS | |
| role isolation. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/decisions/0015-rls-transaction-context-and-schema-manifest.md` around
lines 6 - 8, Update the scope statement in the ADR introduction to keep
owner-role isolation tests included, while continuing to exclude only
organization-only access and tests unrelated to RLS role isolation. Remove the
“Not for owner-role isolation tests” exclusion without changing the ADR’s
coverage of PostgreSQL RLS, schema-owner/runtime/worker roles, or
transaction-scoped actor context.
| base, while preserving ContextLearning as the sole publication owner. Use | ||
| when assembling an explicit Release candidate from current active File | ||
| content. Not for promotion by the operator or publication outside Learning. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Do not exclude the operator-authorized promotion workflow.
The description says this ADR is not for “promotion by the operator.” However, Lines [60-66] define the local promote-release command as an operator-authorized workflow that calls ContextLearning.evaluate and performs one promote call. Narrow the exclusion to direct promotion that bypasses ContextLearning.
Proposed wording
- when assembling an explicit Release candidate from current active File
- content. Not for promotion by the operator or publication outside Learning.
+ when assembling an explicit Release candidate from current active File
+ content. Not for promotion that bypasses ContextLearning or publication
+ outside Learning.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| base, while preserving ContextLearning as the sole publication owner. Use | |
| when assembling an explicit Release candidate from current active File | |
| content. Not for promotion by the operator or publication outside Learning. | |
| base, while preserving ContextLearning as the sole publication owner. Use | |
| when assembling an explicit Release candidate from current active File | |
| content. Not for promotion that bypasses ContextLearning or publication | |
| outside Learning. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@docs/decisions/0073-compose-explicit-release-candidates-from-current-corpus.md`
around lines 7 - 9, Update the ADR scope statement to avoid excluding the
operator-authorized promote-release workflow defined around the promote-release
command and ContextLearning.evaluate. Limit the exclusion to direct promotion
that bypasses ContextLearning, while preserving the existing restriction against
publication outside Learning.
| hop into post-authorization ranking. Use when publishing rich Markdown link | ||
| lineage or ranking one authorized graph hop. Not for link edges as authority, |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
State the content-free Revision-link boundary.
STATUS.md describes immutable, content-free Revision link edges and one authorized hop. The phrase publishing rich Markdown link lineage does not state this boundary and can route content-bearing graph work to ADR-0093.
Align the description with the documented runtime contract.
Proposed wording
- hop into post-authorization ranking. Use when publishing rich Markdown link
- lineage or ranking one authorized graph hop. Not for link edges as authority,
+ hop into post-authorization ranking. Use when activating rich Markdown or
+ traversing one authorized hop over content-free Revision link edges. Not for
+ link edges as authority,📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| hop into post-authorization ranking. Use when publishing rich Markdown link | |
| lineage or ranking one authorized graph hop. Not for link edges as authority, | |
| hop into post-authorization ranking. Use when activating rich Markdown or | |
| traversing one authorized hop over content-free Revision link edges. Not for | |
| link edges as authority, |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/decisions/0093-activate-leased-rich-markdown-and-revision-link-graph.md`
around lines 7 - 8, Update the ADR-0093 scope description to explicitly cover
only immutable, content-free Revision-link edges and a single authorized graph
hop; remove the reference to publishing rich Markdown link lineage and clearly
exclude content-bearing graph work.
| hop into post-authorization ranking. | ||
| hop into post-authorization ranking. Use when publishing rich Markdown link | ||
| lineage or ranking one authorized graph hop. Not for link edges as authority, | ||
| content-bearing pre-Kernel graphs, or unreauthorized cross-Article content. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix the typo in the exclusion clause.
Replace unreauthorized with unauthorized.
Proposed fix
- or unreauthorized cross-Article content.
+ or unauthorized cross-Article content.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/decisions/0093-activate-leased-rich-markdown-and-revision-link-graph.md`
at line 9, In the exclusion clause, replace the misspelled term “unreauthorized”
with “unauthorized,” leaving the surrounding text unchanged.
| Bridge Runtime model-backed rerank through one internal, undelivered, | ||
| audience-bound pre-rerank ContextPackage, one nominal AuthorizedModelInput, | ||
| and the mandatory internal EgressGate with its one-shot model grant. Use when | ||
| implementing authorized rerank or other Runtime-internal model inference. Not | ||
| for activating rerank, exposing internal grants or Packages, or relaxing | ||
| sealed authorization and egress outside this exact bridge. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Limit the applicability clause to the rerank bridge.
The decision body defines a rerank port, a pre-rerank package, and an exact rerank permutation. other Runtime-internal model inference is broader than this decision and can route rewrite or select carriers here without a defined contract.
Proposed wording
- implementing authorized rerank or other Runtime-internal model inference. Not
+ implementing authorized Runtime rerank through this bridge. Not📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Bridge Runtime model-backed rerank through one internal, undelivered, | |
| audience-bound pre-rerank ContextPackage, one nominal AuthorizedModelInput, | |
| and the mandatory internal EgressGate with its one-shot model grant. Use when | |
| implementing authorized rerank or other Runtime-internal model inference. Not | |
| for activating rerank, exposing internal grants or Packages, or relaxing | |
| sealed authorization and egress outside this exact bridge. | |
| Bridge Runtime model-backed rerank through one internal, undelivered, | |
| audience-bound pre-rerank ContextPackage, one nominal AuthorizedModelInput, | |
| and the mandatory internal EgressGate with its one-shot model grant. Use when | |
| implementing authorized Runtime rerank through this bridge. Not for | |
| activating rerank, exposing internal grants or Packages, or relaxing sealed | |
| authorization and egress outside this exact bridge. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/decisions/0095-bridge-runtime-rerank-through-one-internal-package.md`
around lines 5 - 10, Update the applicability clause in the decision
introduction to restrict this decision exclusively to the authorized rerank
bridge; remove the broader reference to other Runtime-internal model inference
while preserving the existing exclusions around activation, internal grants or
packages, and sealed authorization and egress.
| # 0097. Require routing clauses in agent-facing frontmatter | ||
|
|
||
| - Status: accepted | ||
| - Date: 2026-08-02 |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Use the actual acceptance date.
Date: 2026-08-02 is one day after the current date, August 1, 2026. A future-dated accepted ADR gives the decision history an incorrect chronology. Set this field to the actual acceptance date.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/decisions/0097-require-routing-clauses-in-agent-facing-frontmatter.md`
at line 14, Update the Date field in the ADR frontmatter to the actual
acceptance date, August 1, 2026, so it is not future-dated.
| Start a new ADR with this skeleton and replace each placeholder with language | ||
| derived from that ADR's own Decision: | ||
|
|
||
| ```yaml | ||
| --- | ||
| name: adr-NNNN-action-led-name | ||
| version: "1.0.0" | ||
| description: > | ||
| Record the decision-specific fixed choice. Use when the decision-specific | ||
| boundary is being implemented or reviewed. Not for the decision-specific | ||
| shortcut, exclusion, or deferred capability. | ||
| --- | ||
| ``` |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Mark all decision-specific text as explicit placeholders.
The current skeleton can be copied unchanged as apparently valid frontmatter. Its Use when ... and Not for ... clauses remain generic, so they can violate ADR-0097's requirement that routing language derive from the new ADR's Decision.
Use visible placeholders such as <decision-specific trigger> and <decision-specific exclusion>, and require authors to replace them before review.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/decisions/README.md` around lines 13 - 25, Update the ADR skeleton in
the README frontmatter so all decision-specific routing text is visibly
placeholder-based, including the name, description choice, trigger, shortcut,
exclusion, and deferred capability. Require authors to replace every placeholder
with language derived from the new ADR’s Decision before review, while
preserving the existing YAML structure.
|
|
||
| | Boundary | Accepted ADR | Fixed choice | Prohibited shortcut | | ||
| |---|---|---|---| | ||
| | Agent-facing frontmatter | [0097 — Require routing clauses in agent-facing frontmatter](0097-require-routing-clauses-in-agent-facing-frontmatter.md) | Every frontmatter description is action-led, bounded, English-only, and carries decision-specific `Use when ...` and `Not for ...` routing | Document-class exceptions, generic triggers, or routing language that changes the document's decision without a refining ADR | |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Align the exception rule with ADR-0097.
ADR-0097 permits a document-class exception when a later accepted ADR records and configures it. This row lists Document-class exceptions as prohibited without that qualification, so the implementation baseline contradicts the governing ADR.
Change the text to Informal document-class exceptions or Document-class exceptions without an accepted refining ADR.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/decisions/README.md` at line 35, Update the ADR-0097 row in the
decisions table so its prohibited-condition text matches the accepted exception
rule, replacing the unqualified “Document-class exceptions” wording with
“Informal document-class exceptions” or an equivalent phrase requiring an
accepted refining ADR.
1 participant
Closes #137.
Summary
Use when ...andNot for ...routing clauses across all 91 currently nonconforming historical ADRs while preserving every ADR body unchanged..claude/skills/context-engine/SKILL.mdandDESIGN.md, including the malformed DESIGN version.mainalready contained ADR-0094 through ADR-0096, so ADR-0097 is the next available number.This is a 95-file Markdown-only change: 91 existing ADR descriptions, one new ADR, the decision index, the repository context skill, and the design system. Existing ADR bodies are byte-identical after stripping their frontmatter.
Doc-steward evidence
Fresh default EVALUATE baseline on
origin/main(6e39b45):DESIGN.mdversion)The baseline is larger than the issue's 2026-08-01 snapshot because current
maincontains later agent-facing documents and ADR-0094 through ADR-0096.Committed-tree EVALUATE (
ec1d0b2):Command:
The doc-steward package's tier heuristic counts an in-worktree
.venvas repository source, so the committed-tree audit was run against the clean repository surface after moving the generated ignored verification environment outside the target. Generatednode_modulesare already excluded by the checker.Verification
The first
make typecheckattempt occurred before the fresh worktree's Node dependencies were installed and stopped at the ActionPlane prerequisite with missing@types/node; after the requiredmake install, the complete final run passed as recorded above.Summary by CodeRabbit