docs(codebase): record map source-of-truth decision#1607
Open
dbcall2 wants to merge 5 commits into
Open
Conversation
Contributor
|
| Filename | Overview |
|---|---|
| CHANGELOG.md | Adds one CHANGELOG entry for the #1595 PR 1 decision record, citing all four related issues (#1595, #958, #1498, #1492) consistently with the decision doc and vBRIEF. |
| docs/FILES.md | Inserts codebase-map-source-of-truth.md between claude-code-integration.md and getting-started.md — alphabetically correct (cl < co < ge). A previous review raised an ordering concern that has been addressed in this diff. |
| docs/codebase-map-source-of-truth.md | New decision record documenting the #958 disposition and the vBRIEF-as-source-of-truth contract; well-structured with decision, superseded direction, metadata schema, projection contract, rollout sequence, and non-goals sections. |
| vbrief/completed/2026-06-12-1595-pr1-codebase-map-source-of-truth-decision.vbrief.json | New completed vBRIEF with all four issue references (#1595, #958, #1498, #1492) present, matching the decision document and CHANGELOG entry — previously flagged missing references are now included. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart TD
A["vBRIEF-owned Architecture Metadata\n(plan.architecture.codeStructure)"] -->|"source of truth"| B["modules[]\npathOwnership[]\nallowedPatterns[]\nprojectionManifest[]"]
B -->|"generates"| C["Codebase MAP\n(primary projection)"]
B -->|"optionally generates"| D["Source File Headers\n(opt-in, generated only)"]
C -->|"drift check against"| B
D -->|"drift check against"| B
E["#958 Hand-authored Headers"] -->|"superseded as\nimplementation plan"| B
style E fill:#f99,stroke:#c66
style A fill:#6af,stroke:#36c
style C fill:#6f9,stroke:#3a6
style D fill:#fc9,stroke:#a63
Reviews (5): Last reviewed commit: "Merge remote-tracking branch 'upstream/m..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![deft-slizard[bot]](https://avatars.githubusercontent.com/in/3532919?s=60&v=4){kind=small}
There was a problem hiding this comment.
⏱ SLizard session timeout
Semantic analysis partially completed before the session wall.
Salvage tier: post-validation · last phase: post-comments.
Findings below reflect work salvaged before timeout; treat as incomplete.
The GitHub Check Run may show timed_out while this comment carries salvaged output.
Machine-readable verdict
{
"slizard_verdict": {
"schema_version": 1,
"decision": "comment",
"severity": {
"P0": 0,
"P1": 0,
"P2": 0,
"P3": 0
},
"confidence": 0.35,
"decision_confidence": 0.35,
"finding_count": 0,
"merge_impact": "non-blocking degraded review",
"version": "slizard v0.3.1347",
"analysis_outcome": "session_timeout_semantic_partial",
"semantic_layer": "partial",
"salvage_tier": "post-validation",
"last_phase": "post-comments",
"head_sha": "3cd0d01c5ac72982c6eff74dc9547c3afae60a92"
}
}Decision: comment
There was a problem hiding this comment.
Machine-readable verdict
{
"slizard_verdict": {
"schema_version": 1,
"decision": "approve",
"severity": {
"P0": 0,
"P1": 0,
"P2": 0,
"P3": 0
},
"confidence": 0.7983,
"decision_confidence": 0.7983,
"finding_count": 0,
"merge_impact": "non-blocking",
"version": "slizard v0.3.1354",
"analysis_outcome": "clean_with_rationale",
"head_sha": "edac4dd8689850a641fca3dde82aebe0dc97804d"
}
}No issues detected. Code looks clean based on completed analysis passes.
Re-review context
This is a follow-up review on new commits. Prior review: comment with 0 finding(s) at confidence 0.35.
⚠️ Prior review also found 0 issues at confidence 0.35 — this area may require deeper manual inspection.
Clean-review rationale:
- Changed invariant: The system now formally documents that vBRIEF-owned architecture metadata is the source of truth for codebase structure, superseding any prior inclination to use hand-authored source file headers. Generated codebase MAPs and optional file headers are treated as projections from this vBRIEF metadata.
- Preserved behavior: CHANGELOG.md:16: The project continues to adhere to Semantic Versioning.; docs/FILES.md:74: The directory structure and existing documentation files remain unchanged, with the addition of a new decision record.; docs/codebase-map-source-of-truth.md:1: The
docs/directory continues to contain human-readable documentation and decision records. - Tests reviewed: n/a
Deterministic checks: passed — vBRIEF traceability checks passed.
Review coverage
- Reviewed files:
CHANGELOG.md,docs/FILES.md,docs/codebase-map-source-of-truth.md,vbrief/completed/2026-06-12-1595-pr1-codebase-map-source-of-truth-decision.vbrief.json - Skipped files: none
- Source: github @
edac4dd86898
Context used
- Static findings: 1
- Static tools: description-diff-consistency
- Graph/blast radius: 0 changed node(s), 0 affected node(s)
- Vector context chunks: 0
- Context availability: full
- Review categories: default
- Deterministic checks:
400/401 passed, 1 failed: description-diff-consistency
vbrief-traceability=passed, markdown-fences=passed, unused-exports=passed, query-docstring=passed, xss-sprintf=passed, markdown-xref=passed, aria-target=passed, semantic-role=passed, aria-containment=passed, redundant-assertion=passed, tautological-assertion=passed, resource-lifecycle=passed, cross-diff-consistency=passed, redundant-css-block=passed, template-placeholder=passed, void-async-signal=passed, spread-override=passed, json-indent-consistency=passed, dep-swap=passed, powershell-scoping=passed, diff-truncation=passed, exception-type-contract=passed, dead-none-guard=passed, access-declaration=passed, unused-option=passed, css-property-interaction=passed, jsx-style-indent=passed, regex-breadth=passed, cartesian-fan-out=passed, exec-stdout-parse=passed, sentinel-error-wiring=passed, hardcoded-filemode=passed, api-response-shape=passed, python-cli-arg=passed, taskfile-namespace=passed, vbrief-schema=passed, go-shell-injection=passed, go-discarded-error=passed, go-json-field-exposure=passed, go-mutable-exported-slice=passed, go-silent-error-branch=passed, go-comment-log-contradiction=passed, go-unconditional-message=passed, inline-style-proliferation=passed, unnecessary-nonnull-assertion=passed, double-cast=passed, unguarded-await-cast=passed, ssrf-guard-completeness=passed, error-message-leak=passed, puppeteer-resource-cap=passed, trivial-argument=passed, unused-imports=passed, duplicate-import=passed, dead-store=passed, phantom-import=passed, fetch-timeout-guard=passed, log-level-expected-path=passed, unified-diff-construction=passed, sentinel-index-assertion=passed, unguarded-map-lookup=passed, unbounded-prompt-injection=passed, description-diff-consistency=failed, render-branch-symmetry=passed, go-gorm-unchained-error=passed, go-gorm-rowsaffected-noop=passed, error-handling-loop-break=passed, sync-state-batching=passed, sync-revoke-object-url=passed, go-like-wildcard-injection=passed, go-basename-dedup-gap=passed, go-missing-seed-in-migrate=passed, go-write-then-read-unfiltered=passed, go-direct-db-access=passed, async-handler-try-catch=passed, chat-sdk-history=passed, dead-code-ternary=passed, go-context-background=passed, go-git-arg-order=passed, go-n-plus-one=passed, go-nested-transaction=passed, go-ref-injection=passed, go-scanner-error=passed, go-toctou-db=passed, go-unused-validated-field=passed, hardcoded-literal=passed, hardcoded-undefined-field=passed, python-exception=passed, python-path-construction=passed, python-isdigit-int=passed, deprecated-python-utcnow=passed, python-variable-shadow=passed, frozen-dataclass-mutable-field=passed, sentinel-value=passed, sibling-constant=passed, url-interpolation=passed, jsx-guard-removal=passed, asymmetric-clamp=passed, optional-prop-guard=passed, server-lifecycle=passed, go-asymmetric-org-scope=passed, fetch-body-scope-omission=passed, regex-breadth-inconsistency=passed, typeof-object-array-guard=passed, test-production-divergence=passed, argument-axis-mismatch=passed, click-propagation-gap=passed, sanitization-gap=passed, response-shape-consistency=passed, keydown-target-guard=passed, changelog-test-count=passed, unbounded-metadata-assignment=passed, unchecked-json-response=passed, response-body-leak=passed, json-syntax=passed, requestid-route-param=passed, dict-key-as-value=passed, redundant-transitive-call=passed, incomplete-iteration=passed, empty-nested-array-return=passed, call-site-parameter-consistency=passed, markdown-heading-level=passed, cross-section-order-contradiction=passed, dangling-reference=passed, typescript-compilation=passed, go-compilation=passed, useref-dead-store=passed, fetch-redirect-guard=passed, response-body-buffering=passed, svg-content-type=passed, conditional-mode-exclusion=passed, join-separator-inconsistency=passed, prompt-injection-guard=passed, asymmetric-guard=passed, unsafe-json-cast=passed, storage-unsafe-cast=passed, markdown-single-line-interpolation=passed, postmessage-origin-guard=passed, css-iframe-scope=passed, markdown-entry-completeness=passed, python-set-duplicate=passed, state-setter-symmetry=passed, changelog-sibling-truncation=passed, ternary-exhaustiveness=passed, exclusive-output-constraint=passed, nullish-fallback-regression=passed, shell-pipefail=passed, vbrief-acceptance-contradiction=passed, css-property-diff=passed, go-sync-call-labeled-background=passed, prompt-guardrail-conflict=passed, prompt-identity-duplication=passed, asymmetric-truncation=passed, claim-source-tracing=passed, go-duplicate-event-publish=passed, go-create-without-cleanup=passed, go-find-then-create-without-cleanup=passed, go-persist-without-validate=passed, ts-put-without-get=passed, go-fetch-id-without-liveness=passed, go-event-subscribe-without-publish=passed, go-log-aggregation-run-scoping=passed, falsy-string-fallback=passed, useeffect-unstable-prop-dep=passed, unused-state-read=passed, blob-mime-mismatch=passed, parseint-nan-guard=passed, shared-state-across-map=passed, context-menu-click-guard=passed, touch-action-ancestor=passed, usestate-innerwidth-matchmedia=passed, prefix-match-loop=passed, hardcoded-new-field=passed, enum-subset-completeness=passed, optional-guard-fallthrough=passed, html-template-token=passed, label-association=passed, empty-src-img=passed, jsx-prose-link-mismatch=passed, try-catch-scope=passed, viewport-meta-accessibility=passed, go-github-api-response-id=passed, go-github-api-pagination=passed, go-gorm-first-without-errrecordnotfound=passed, fetch-cache-consistency=passed, oauth-session-state-binding=passed, go-switch-exhaustiveness=passed, go-test-mutex-asymmetry=passed, nextjs-suspense-boundary=passed, nullable-nested-response=passed, nullish-coalesce-empty-url=passed, asymmetric-callback-state-reset=passed, go-docstring-contract-mismatch=passed, replace-dollar-pattern=passed, conditional-fallthrough-gap=passed, sanitization-completeness=passed, bare-selector-fallback=passed, element-inspector-metadata=passed, sanitization-context-mismatch=passed, json-escape-completeness=passed, catch-block-guard-parity=passed, early-exit-guard-subset=passed, html-escape-context-collision=passed, cross-file-inline-duplication=passed, collection-gate-ordering=passed, regex-denylist-anchor-gap=passed, handler-validation-symmetry=passed, go-http-handler-body-persist-without-authz=passed, go-first-element-without-disambiguation=passed, ternary-wrapper-asymmetry=passed, promise-then-without-outer-catch=passed, effect-persist-hydration-race=passed, css-animation-ref=passed, idb-open-lifecycle=passed, interactive-role-mismatch=passed, array-duplicate-field=passed, mid-file-static-import=passed, changelog-section-deletion=passed, comment-anchored-regex=passed, source-string-test=passed, weak-version-sort-assertion=passed, stale-state-getter-deps=passed, diff-eof-newline=passed, screenshot-timeout-cdn=passed, go-sprintf-json-body=passed, go-deft-install-deposit=passed, go-deft-install-bootstrap=passed, observer-boundary-mismatch=passed, hook-return-shape-mismatch=passed, layout-record-flat-coord-access=passed, raw-vs-effective-state=passed, unstable-mapped-key=passed, parallel-state-init-divergence=passed, value-callback-prop-coherence=passed, cap-expansion-order=passed, cross-file-comment-claim=passed, useeffect-cleanup=passed, filter-ratio-threshold=passed, setter-argument-asymmetry=passed, panel-scoped-notification=passed, unawaited-async-dependency=passed, prompt-html-anti-pattern=passed, go-empty-collection-write-guard=passed, go-inconsistent-error-wrapping=passed, sentinel-substring-guard=passed, hardcoded-color-in-themed-context=passed, modal-escape-handler=passed, property-read-without-write-path=passed, iframe-nav-intercept-completeness=passed, tagname-case-sensitivity=passed, guard-clause-subsumption=passed, effect-cleanup-race=passed, style-template-injection=passed, textarea-min-height=passed, greedy-lookahead-futility=passed, window-open-null-guard=passed, orphaned-ambient-declaration=passed, char-ordinal-bounds=passed, stale-ref-callback-race=passed, missing-init-check=passed, stderr-redirect=passed, gitignore-tracked-file=passed, eager-defeats-lazy-import=passed, redundant-call-in-scope=passed, test-source-list-diff=passed, mixed-dict-access-pattern=passed, md-fragile-regex-lookahead=passed, misleading-none-branch=passed, discarded-validation-return=passed, loopback-range=passed, trust-proxy=passed, fly-toml-schema=passed, dockerfile-copy-shell-op=passed, dockerfile-build-secret=passed, string-dispatch=passed, python-toctou-file-lock=passed, python-non-reentrant-lock=passed, go-sibling-handler-guard=passed, stale-test-assertion=passed, go-batch-response-counter=passed, go-single-status-error-handler=passed, go-base64-body-size-mismatch=passed, dict-write-lookup-asymmetry=passed, identical-branch=passed, postmessage-targetorigin-regression=passed, react-namespace-import=passed, comment-payload-contradiction=passed, conditional-gating-dead-path=passed, go-mock-interface-completeness=passed, toggle-setter-mismatch=passed, localhost-in-allowlist=passed, unawaited-waitfor=passed, cli-example-validator=passed, python-tz-comparison-asymmetry=passed, missing-wildcard-guard=passed, react-ref-hydration-trigger=passed, react-unused-callback-dep=passed, scope-intent-mismatch=passed, supabase-join-path-mismatch=passed, incomplete-optional-property-guard=passed, retry-reenqueue-without-guard=passed, stale-self-call-in-callback=passed, empty-body-control-flow=passed, self-increment-comparison=passed, sequential-replace-dedup=passed, breaking-export-removal=passed, vacuous-test-assertion=passed, silent-fallible-coalesce=passed, dual-threshold-warning=passed, unresolved-relative-import=passed, coalescing-callback-dispatch=passed, removed-event-propagation-stopper=passed, jsx-inline-style-scope-leak=passed, hook-after-early-return=passed, fs-access-overwrite=passed, type-import-divergence=passed, conditional-state-no-clear=passed, gated-operation-silent-persist=passed, hardcoded-sentinel-dead-path=passed, swift-filepath-disclosure=passed, swift-lba-overflow=passed, swift-xpc-listener-validation=passed, python-weak-substring-match=passed, python-docstring-class-ref=passed, python-autonomy-enabled-guard=passed, python-reviewer-disagreement-reason=passed, python-mirror-function=passed, python-unused-subprocess-output=passed, python-narrow-exception-handler=passed, python-service-replay-except-gap=passed, usememo-missing-dep=passed, localstorage-stale-cache=passed, localstorage-scope=passed, dead-action-variant=passed, switch-param-forwarding-gap=passed, changelog-entry-style=passed, artifact-conversation-log-kind=passed, artifact-export-placeholder-regex=passed, artifact-card-scope-slug-collision=passed, vbrief-edge-completeness=passed, pr-body-vbrief-scope=passed, abort-signal-timeout-guard=passed, whitespace-control-char=passed, transient-error-permanent-state=passed, unused-variable=passed, postmessage-source-null-check=passed, atob-encoding-check=passed, phantom-identity-fallback-check=passed, workflow-comment-secret=passed, rls-circular-dep=passed, writable-stream-abort=passed, error-type-shadowing=passed, unguarded-iteration-component=passed, ci-checksum-provenance=passed, drizzle-updated-at-hook=passed, auth-allowlist-open-fallback=passed, nextauth-v5-env-naming=passed, process-env-nonnull-assertion=passed, ci-build-missing-secrets=passed, proxy-reflect-get-receiver=passed, approval-trust-tier=passed, react-error-cache-nav-reset=passed, shell-injection-template=passed, flag-reset=passed, excess-property=passed, timestamp-sanitization-reuse=passed, boolean-null-guard=passed, catch-typeof-swallow=passed, optional-strict-compare=passed, leaked-debug-text=passed, inconsistent-component-import=passed, wrong-domain-copy=passed, unconditional-lfs-filter=passed, toml-config-injection=passed, dead-popen-timeout-except=passed, python-unused-local=passed, async-event-lock-no-recovery=passed, webkit-cancel-compat=passed, dom-cleanup-racing-interaction=passed, nonstandard-code-fence=passed, vba-value2-single-cell=passed, vba-doc-error-handler=passed, officejs-doc-sync-batching=passed, regex-word-boundary-method-name=passed, sliding-window-dedup=passed, double-localstorage-key-write=passed, new-class-missing-option=passed, branch-reset-asymmetry=passed, changelog-placeholder=passed, cockpit-state-before-try=passed, format-conversion-fallthrough=passed, normalize-to-empty=passed, sql-cursor-pagination-index=passed, temporary-debug-flag=passed, debug-console-log=passed, mock-api-preview=passed, canvas-phosphor-lifecycle=passed, theme-codegen=passed, graph-incompleteness=passed, orphaned-module=passed, graph-validation-gap=passed, lockfile-version-suppression=passed
Suggested verification
- (agent) Spot-check the highest-risk changed files and confirm the clean review did not skip relevant files or context.
- (static) Review 1 deterministic/static finding(s) included in the evidence set.
Agent verification brief
- PR/CR:
deftai/directive#1607 - Head SHA:
edac4dd8689850a641fca3dde82aebe0dc97804d - Decision: approve
- Highest-risk claims: none
- Reviewed files:
CHANGELOG.md,docs/FILES.md,docs/codebase-map-source-of-truth.md,vbrief/completed/2026-06-12-1595-pr1-codebase-map-source-of-truth-decision.vbrief.json - Skipped files: none
- Evidence sources: static analysis, call graph/blast radius, deterministic checks
- Known blind spots: none recorded
Decision: approve
Merge impact: non-blocking
Review confidence: 0.80
Decision confidence: 0.80
Finding confidence: n/a
Reason: No findings survived validation and all configured analysis completed.
Important files: 4 changed file(s) reviewed; no finding hotspots identified.
Review scope: 4 files, 199 additions, 0 deletions
slizard v0.3.1354
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
Records the #1595 PR 1 decision that durable codebase-structure metadata belongs in vBRIEF-owned architecture metadata, while generated codebase MAPs and optional file headers are projections.
Related Issues
Refs #1595, #958, #1498.
Checklist
/deft:change <name>- N/A; docs/vBRIEF-only PR 1 slice scoped by feat(codebase): generate codebase MAP from vBRIEF-owned codeStructure metadata #1595 and confirmed with explicit implementation directive.CHANGELOG.md- added entry under[Unreleased].ROADMAP.md- N/A; feat(codebase): generate codebase MAP from vBRIEF-owned codeStructure metadata #1595 remains the multi-PR tracker.