docs: establish canonical commercial architecture baseline - #149
Draft
seonghobae wants to merge 50 commits into
Draft
docs: establish canonical commercial architecture baseline#149seonghobae wants to merge 50 commits into
seonghobae wants to merge 50 commits into
Conversation
Contributor
📝 WalkthroughWalkthroughmightyETL의 저장소 운영 정책과 제품 문서를 보호된 Changes운영 정책과 자동화 권한
제품 상태와 아키텍처
기술·API 계약
Canonical 문서와 검증
Estimated code review effort: 4 (Complex) | ~60 minutes 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 2📝 Generate docstrings 💡
🛠️ Fix failing CI checks 💡
🧪 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 |
Collaborator
Author
|
@coderabbitai review Please review exact current head |
Contributor
🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
base='622e5e6c3d534f230c390f10e3832efadfc01825'
head='15c000a644796ef72e071dcd745dd4cf89feb38a'
echo '== Repository HEAD and requested commits =='
git rev-parse HEAD
git cat-file -t "$base"
git cat-file -t "$head"
git show -s --format='BASE %H%n%P%n%s' "$base"
git show -s --format='HEAD %H%n%P%n%s' "$head"
echo '== Changed files, literal range =='
git diff --name-status "$base" "$head"
echo '== Documentation and test files in literal range =='
git diff --name-only "$base" "$head" | grep -E '(^|/)([^/]*\.(md|MD)|[^/]*(Test|Tests)\.(java|kt|ts|tsx|js|jsx|py|go|cs))$|(^|/)(docs|adr|api|threat|test|operability|traceability)(/|$)' || true
echo '== Root repository map =='
fd -HI -d 3 -t f -E .git | sed -n '1,300p'
echo '== Structural outline of changed source/test files =='
while IFS= read -r f; do
case "$f" in
*.java|*.kt|*.ts|*.tsx|*.js|*.jsx|*.py|*.go|*.cs)
echo "--- $f"
ast-grep outline "$f" --items all 2>/dev/null || true
;;
esac
done < <(git diff --name-only "$base" "$head")
echo '== Diff: documentation and documentation-contract-related files =='
git diff --find-renames --find-copies --unified=80 "$base" "$head" -- \
'*.md' '*.MD' '*Documentation*' '*documentation*' '*Contract*' '*contract*' \
'*ADR*' '*adr*' '*UML*' '*uml*' '*ERD*' '*erd*' '*Threat*' '*threat*' \
'*Traceability*' '*traceability*' '*Operability*' '*operability*' \
'*Assessment*' '*assessment*' '*Api*' '*API*' || true
echo '== Protected-base implementation and API terminology =='
git grep -n -I -E \
'(/auth/signin|/auth/signup|BCrypt|JWT|parallel.?batch|idempotenc|durable.?job|job.?status|atomic|transaction)' \
"$base" -- ':!*.md' ':!*.MD' || trueLength of output: 6564 🏁 Script executed: #!/bin/bash
set -euo pipefail
base='622e5e6c3d534f230c390f10e3832efadfc01825'
head='15c000a644796ef72e071dcd745dd4cf89feb38a'
echo '== Changed-file statistics =='
git diff --stat "$base" "$head"
echo
echo '== Changed Java test content at literal head =='
for f in \
etl-service/src/test/java/com/xtrmetl/etl/documentation/CanonicalDocumentationContractTest.java \
etl-service/src/test/java/com/xtrmetl/etl/documentation/DocumentationValidationTest.java
do
echo "--- $f"
git show "$head:$f" | nl -ba
done
echo '== New canonical document headings, links, and status vocabulary =='
for f in $(git diff --name-only --diff-filter=A "$base" "$head" -- 'docs/**'); do
echo "--- $f"
git show "$head:$f" | nl -ba | grep -E \
'^[[:space:]]*[0-9]+[[:space:]]+(#|.*\]\(|.*implemented_on_develop|.*active_pr|.*planned|.*superseded|.*out_of_scope|.*PR #|.*PR #[0-9]+|.*endpoint|.*authentication|.*JWT|.*BCrypt|.*idempotenc|.*durable|.*atomic|.*parallel)' \
|| true
done
echo '== Root-document changed hunks =='
git diff --unified=30 "$base" "$head" -- \
ARCHITECTURE.md CHANGELOG.md PRD.md README.md SECURITY.md SUMMARY_KR.md TRD.md
echo '== Markdown links in added canonical documents and their target existence at literal head =='
python3 - <<'PY'
import subprocess, re, posixpath
base = '622e5e6c3d534f230c390f10e3832efadfc01825'
head = '15c000a644796ef72e071dcd745dd4cf89feb38a'
files = subprocess.check_output(
['git','diff','--name-only','--diff-filter=A',base,head,'--','docs/**'],
text=True).splitlines()
all_files = set(subprocess.check_output(['git','ls-tree','-r','--name-only',head], text=True).splitlines())
pattern = re.compile(r'(?<!!)\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)')
for f in files:
text = subprocess.check_output(['git','show',f'{head}:{f}'], text=True, errors='replace')
for lineno, line in enumerate(text.splitlines(), 1):
for raw in pattern.findall(line):
target = raw.strip('<>')
if target.startswith(('#','http://','https://','mailto:')): continue
target = target.split('#',1)[0].split('?',1)[0]
if not target: continue
resolved = posixpath.normpath(posixpath.join(posixpath.dirname(f), target))
print(f'{f}:{lineno}: {raw} => {resolved}: {"OK" if resolved in all_files else "MISSING"}')
PY
echo '== Protected-base endpoint mappings and security implementations =='
git grep -n -I -E \
'@(RequestMapping|GetMapping|PostMapping|PutMapping|DeleteMapping|PatchMapping)|RequestMethod\.' \
"$base" -- ':(glob)**/*.java' || true
git grep -n -I -E \
'(BCrypt|Jwt|JWT|PasswordEncoder|SecurityFilterChain|Authentication|authorizeHttpRequests|permitAll)' \
"$base" -- ':(glob)**/*.java' || true
echo '== Protected-base durable job and idempotency implementation symbols =='
git grep -n -I -E \
'(Idempoten|idempoten|Durable|durable|JobStatus|jobStatus|`@Transactional`|TransactionTemplate|atomic)' \
"$base" -- ':(glob)**/*.java' || trueLength of output: 5356 🏁 Script executed: #!/bin/bash
set -u
base='622e5e6c3d534f230c390f10e3832efadfc01825'
head='15c000a644796ef72e071dcd745dd4cf89feb38a'
echo '== Literal-head documentation contract tests =='
for f in \
etl-service/src/test/java/com/xtrmetl/etl/documentation/CanonicalDocumentationContractTest.java \
etl-service/src/test/java/com/xtrmetl/etl/documentation/DocumentationValidationTest.java
do
echo "--- $f"
git show "$head:$f" | grep -n '^' || true
done
echo '== Complete new canonical documents at literal head =='
for f in \
docs/API_CONTRACT.md \
docs/DOCUMENTATION_ASSESSMENT.md \
docs/ERD.md \
docs/OPERABILITY.md \
docs/TEST_STRATEGY.md \
docs/THREAT_MODEL.md \
docs/TRACEABILITY.md \
docs/UML.md \
docs/adr/README.md \
docs/adr/0001-canonical-documentation-and-status.md \
docs/adr/0002-atomic-etl-and-idempotency.md \
docs/adr/0003-durable-job-database-authority.md \
docs/adr/0004-cdc-delivery-and-lifecycle-truth.md \
docs/adr/0005-gateway-identity-boundary.md \
docs/adr/0006-exact-evidence-and-agent-authority.md \
docs/adr/0007-standalone-msa-and-connector-truth.md \
docs/adr/0008-purpose-bound-pii-controls.md
do
echo "--- $f"
git show "$head:$f" | grep -n '^' || true
done
echo '== Literal-head references to state labels and active PRs =='
git grep -n -I -E \
'(implemented_on_develop|active_pr|planned|superseded|out_of_scope|PR #[0-9]+|`#142`|`#149`)' \
"$head" -- '*.md' '*.MD' '*.java' || true
echo '== Markdown link target checks, added canonical documents =='
python3 - <<'PY'
import subprocess, re, posixpath
base='622e5e6c3d534f230c390f10e3832efadfc01825'
head='15c000a644796ef72e071dcd745dd4cf89feb38a'
files=subprocess.check_output(
['git','diff','--name-only','--diff-filter=A',base,head,'--','docs/**'],text=True).splitlines()
tree=set(subprocess.check_output(['git','ls-tree','-r','--name-only',head],text=True).splitlines())
rx=re.compile(r'(?<!!)\[[^\]]+\]\(([^)\s]+)')
for f in files:
content=subprocess.check_output(['git','show',head+':'+f],text=True,errors='replace')
for i,line in enumerate(content.splitlines(),1):
for target in rx.findall(line):
target=target.strip('<>').split('#',1)[0].split('?',1)[0]
if not target or target.startswith(('http://','https://','mailto:')): continue
resolved=posixpath.normpath(posixpath.join(posixpath.dirname(f),target))
if resolved not in tree:
print('MISSING {}:{} {} -> {}'.format(f,i,target,resolved))
PY
echo '== Protected-base Java routes =='
git grep -n -I -E \
'@(RequestMapping|GetMapping|PostMapping|PutMapping|DeleteMapping|PatchMapping)|RequestMethod\.' \
"$base" -- '*.java' || true
echo '== Protected-base Java security implementation terms =='
git grep -n -I -E \
'(BCrypt|Jwt|JWT|PasswordEncoder|SecurityFilterChain|Authentication|authorizeHttpRequests|permitAll)' \
"$base" -- '*.java' || true
echo '== Protected-base Java durable job, idempotency, and transaction terms =='
git grep -n -I -E \
'(Idempoten|idempoten|Durable|durable|JobStatus|jobStatus|`@Transactional`|TransactionTemplate|atomic)' \
"$base" -- '*.java' || trueLength of output: 233047 🏁 Script executed: #!/bin/bash
set -u
base='622e5e6c3d534f230c390f10e3832efadfc01825'
head='15c000a644796ef72e071dcd745dd4cf89feb38a'
echo '== Canonical Markdown fragment-anchor audit at literal head =='
python3 - <<'PY'
import re, subprocess, posixpath, unicodedata
head='15c000a644796ef72e071dcd745dd4cf89feb38a'
docs=[
'README.md','SUMMARY_KR.md','PRD.md','TRD.md','ARCHITECTURE.md','SECURITY.md',
'docs/UML.md','docs/ERD.md','docs/API_CONTRACT.md','docs/THREAT_MODEL.md',
'docs/TEST_STRATEGY.md','docs/OPERABILITY.md','docs/TRACEABILITY.md',
'docs/DOCUMENTATION_ASSESSMENT.md','docs/adr/README.md'
]
tree=set(subprocess.check_output(['git','ls-tree','-r','--name-only',head],text=True).splitlines())
content={}
for f in docs:
content[f]=subprocess.check_output(['git','show',head+':'+f],text=True,errors='replace')
def slug(s):
s=unicodedata.normalize('NFKD',s).lower()
s=re.sub(r'[`*_~]','',s)
s=re.sub(r'[^\w\s-]','',s,flags=re.UNICODE)
return re.sub(r'[\s-]+','-',s).strip('-')
anchors={}
for f,text in content.items():
counts={}
for line in text.splitlines():
m=re.match(r'^\s{0,3}#{1,6}\s+(.+?)\s*#*\s*$',line)
if m:
a=slug(m.group(1)); n=counts.get(a,0); counts[a]=n+1
anchors.setdefault(f,set()).add(a if n==0 else a+'-'+str(n))
rx=re.compile(r'(?<!!)\[[^\]]+\]\(([^)\s]+)')
for f,text in content.items():
for lineno,line in enumerate(text.splitlines(),1):
for raw in rx.findall(line):
link=raw.strip('<>')
if link.startswith(('http://','https://','mailto:')): continue
path,sep,frag=link.partition('#')
target=f if not path else posixpath.normpath(posixpath.join(posixpath.dirname(f),path))
if target not in tree:
print('MISSING_FILE {}:{} {}'.format(f,lineno,link))
elif sep and target in anchors and slug(frag) not in anchors[target]:
print('MISSING_ANCHOR {}:{} {} -> {}#{}'.format(f,lineno,link,target,slug(frag)))
PY
echo '== Literal-head documentation source-path references absent from its tree =='
python3 - <<'PY'
import re, subprocess
head='15c000a644796ef72e071dcd745dd4cf89feb38a'
docs=subprocess.check_output(
['git','diff','--name-only','622e5e6c3d534f230c390f10e3832efadfc01825',head,'--','*.md','*.MD'],
text=True).splitlines()
tree=set(subprocess.check_output(['git','ls-tree','-r','--name-only',head],text=True).splitlines())
rx=re.compile(r'`((?:[\w.-]+/)+[\w.-]+(?:\.[\w.-]+)?)`')
for f in docs:
text=subprocess.check_output(['git','show',head+':'+f],text=True,errors='replace')
for i,line in enumerate(text.splitlines(),1):
for path in rx.findall(line):
if path not in tree and not path.startswith(('http://','https://')):
print('POSSIBLE_MISSING_SOURCE_REFERENCE {}:{} {}'.format(f,i,path))
PY
echo '== Protected-base migration/bootstrap files matching ERD references =='
git ls-tree -r --name-only "$base" | grep -E \
'(^|/)(01_schema\.sql|V1__create_etl_idempotency_records\.sql|V2__create_etl_job_records\.sql)$' || true
echo '== Protected-base controller configuration and response details =='
for f in \
etl-service/src/main/java/com/xtrmetl/etl/controller/EtlJobController.java \
etl-service/src/main/java/com/xtrmetl/etl/controller/EtlController.java \
zuul-gateway/src/main/java/com/xtrmetl/gateway/security/JwtAuthenticationFilter.java \
etl-service/src/main/resources/db/migration/V2__create_etl_job_records.sql
do
echo "--- $f"
git show "$base:$f" 2>/dev/null | grep -n -E \
'(Conditional|RequestMapping|PostMapping|GetMapping|ResponseEntity|Location|Cache-Control|valid_token|job_status|CHECK|CREATE TABLE|Idempotency|Authentication)' || true
done
echo '== Status-claim enforcement inside the new literal-head contract test =='
git show "$head:etl-service/src/test/java/com/xtrmetl/etl/documentation/CanonicalDocumentationContractTest.java" \
| grep -n -E \
'(active_pr|implemented_on_develop|planned|superseded|out_of_scope|known_gap|`#121`|`#139`|`#142`|`#143`|`#148`|assertTrue)' || trueLength of output: 11850
I found two documentation-contract issues.
The protected-base code supports the main corrected claims. It contains the documented ETL and CDC routes, feature-gated durable intake/status, principal-scoped idempotency, and the literal ✅ Action performedReview finished.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 12
🤖 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 `@AGENTS.md`:
- Around line 104-108: Update the “Standards, research, and commercial
readiness” section by replacing the misspelled `doctoring/ADRs` reference with
the repository’s canonical documentation and ADR directory paths, so
contributors record APA 7 references in the correct locations.
In `@ARCHITECTURE.md`:
- Line 133: Implement bounded retention for etl_job_records.request_payload:
define TTL, purge payloads on terminal states, handle cleanup failures, and
restore cleanup behavior after restart, with migration and lifecycle tests
covering these paths. Update ARCHITECTURE.md lines 133-133 and PRD.md lines
304-321 to document the same retention contract; if implementation is deferred,
mark the capability as a known_gap and restrict production use instead.
- Line 279: Update the sentence beginning with “#121” so the issue identifier is
enclosed in Markdown backticks, preventing it from being interpreted as a
heading; leave the rest of the sentence unchanged.
In `@docs/API_CONTRACT.md`:
- Around line 143-154: Update the Problem Details contract to match
EtlApiProblemHandler’s problem.setInstance(...) response field by documenting
instance instead of path, unless an explicit path alias is implemented. Keep the
documented public fields aligned with the actual response and add or update
contract tests to lock in the chosen field name.
In `@docs/ERD.md`:
- Around line 73-75: Update the `etl_job_records` section in `docs/ERD.md` so
terminal-state `request_payload` clearing is not presented as implemented in
protected `develop`; mark it as `known_gap` or `active_pr` until the
corresponding migration and integration tests exist. Keep the documented active
and terminal status values, and retain the statement that protected develop
lacks lease, pagination, cancellation, and replay-lineage fields.
In `@docs/TEST_STRATEGY.md`:
- Around line 131-140: Update docs/TEST_STRATEGY.md lines 131-140 to include
known_gap in the canonical status taxonomy and require each capability status to
be validated against source-backed claims. Update docs/TRACEABILITY.md line 39
so the Status value is planned, moving the partial scaffold detail into the
Source / persistence or Evidence column.
In
`@etl-service/src/test/java/com/xtrmetl/etl/documentation/CanonicalDocumentationContractTest.java`:
- Around line 120-129: Replace the standalone status-token checks with
capability-to-status assertions. In
etl-service/src/test/java/com/xtrmetl/etl/documentation/CanonicalDocumentationContractTest.java:120-129,
bind protected contracts such as POST /api/etl/process, etl_idempotency_records,
and etl_job_records to documentation entries marked implemented_on_develop. In
etl-service/src/test/java/com/xtrmetl/etl/documentation/DocumentationValidationTest.java:149-158,
bind cancellation, CANCELLED, and Resource Server JWT claims to their exact
active_pr or known_gap statuses, ensuring unrelated status labels cannot satisfy
the tests.
In
`@etl-service/src/test/java/com/xtrmetl/etl/documentation/DocumentationValidationTest.java`:
- Around line 57-59: Restore the approved LICENSE file referenced by README.md
so DocumentationValidationTest.readmeInternalLinksResolve passes without
weakening the internal-link contract; if no license has been authorized, remove
the README LICENSE link instead and resolve the deployment policy before
changing the test.
In `@PRD.md`:
- Line 230: NFR-REL-1 heading을 현재 ####에서 ###로 변경해 `## 5. Non-Functional
Requirements` 아래의 계층을 한 단계씩 따르도록 수정하세요.
In `@README.md`:
- Line 22: README.md의 Databricks / Snowflake / Qlik status를 canonical 상태인
known_gap으로 변경하고, Notes 설명에는 scaffold-only를 유지하세요. 다른 상태 라벨이나 문서 구조는 변경하지 마세요.
In `@SECURITY.md`:
- Around line 67-69: Update the PR `#139` entry in SECURITY.md to replace “finite
future waiting” with the established “bounded acknowledgement wait/retry
boundary” terminology, matching ARCHITECTURE.md and PRD.md while preserving the
surrounding remediation contract description.
In `@TRD.md`:
- Around line 24-30: Update the Spring Boot and Spring Cloud version entries in
TRD.md to match the root pom.xml Maven properties: 3.5.16 and 2025.0.3. Leave
the already aligned Java and Debezium entries unchanged.
🪄 Autofix
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: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: ed81746a-f995-4246-a2d3-41c9abaf21d2
📒 Files selected for processing (28)
AGENTS.mdARCHITECTURE.mdCHANGELOG.mdCLAUDE.mdPRD.mdREADME.mdSECURITY.mdSUMMARY_KR.mdTRD.mddocs/API_CONTRACT.mddocs/DOCUMENTATION_ASSESSMENT.mddocs/ERD.mddocs/OPERABILITY.mddocs/TEST_STRATEGY.mddocs/THREAT_MODEL.mddocs/TRACEABILITY.mddocs/UML.mddocs/adr/0001-canonical-documentation-and-status.mddocs/adr/0002-atomic-etl-and-idempotency.mddocs/adr/0003-durable-job-database-authority.mddocs/adr/0004-cdc-delivery-and-lifecycle-truth.mddocs/adr/0005-gateway-identity-boundary.mddocs/adr/0006-exact-evidence-and-agent-authority.mddocs/adr/0007-standalone-msa-and-connector-truth.mddocs/adr/0008-purpose-bound-pii-controls.mddocs/adr/README.mdetl-service/src/test/java/com/xtrmetl/etl/documentation/CanonicalDocumentationContractTest.javaetl-service/src/test/java/com/xtrmetl/etl/documentation/DocumentationValidationTest.java
Collaborator
Author
|
@coderabbitai review Please review exact current head |
Contributor
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
base='622e5e6c3d534f230c390f10e3832efadfc01825'
head='e3f69c747ffdeae5212f9735b0d59e6562e344cc'
echo '== Commit identity =='
printf 'checked-out: '; git rev-parse HEAD
git cat-file -e "${base}^{commit}"
git cat-file -e "${head}^{commit}"
git show -s --format='base %H%nparents %P%nsubject %s' "$base"
git show -s --format='head %H%nparents %P%nsubject %s' "$head"
echo '== Literal diff name/status =='
git diff --name-status "$base" "$head"
echo '== Relevant changed files =='
git diff --name-only "$base" "$head" -- \
'*.md' '*.MD' \
'etl-service/src/test/java/com/xtrmetl/etl/documentation/*.java' \
'etl-service/src/main/**/*.java' \
'zuul-gateway/src/main/**/*.java'
echo '== Java test outline =='
for f in \
etl-service/src/test/java/com/xtrmetl/etl/documentation/CanonicalDocumentationContractTest.java \
etl-service/src/test/java/com/xtrmetl/etl/documentation/DocumentationValidationTest.java
do
if git cat-file -e "$head:$f" 2>/dev/null; then
echo "--- $f"
git show "$head:$f" > "/tmp/$(basename "$f")"
ast-grep outline "/tmp/$(basename "$f")" --items all || true
nl -ba "/tmp/$(basename "$f")"
fi
done
echo '== Current documentation status claims and API/state references =='
git grep -n -I -E \
'(implemented_on_develop|active_pr|planned|superseded|known_gap|out_of_scope|CANCELLED|cancellation|Resource Server|JWT|valid_token|Idempotency-Key|/api/etl/jobs)' \
"$head" -- '*.md' '*.MD' '*.java' || true
echo '== Literal-head Markdown link audit =='
python3 - <<'PY'
import posixpath, re, subprocess
head = 'e3f69c747ffdeae5212f9735b0d59e6562e344cc'
tree = set(subprocess.check_output(
['git', 'ls-tree', '-r', '--name-only', head], text=True).splitlines())
files = [p for p in tree if p.lower().endswith('.md')]
link = re.compile(r'(?<!!)\[[^\]]+\]\(([^)\s]+)')
for path in sorted(files):
text = subprocess.check_output(
['git', 'show', f'{head}:{path}'], text=True, errors='replace')
for line_no, line_text in enumerate(text.splitlines(), 1):
for raw in link.findall(line_text):
target = raw.strip('<>')
if target.startswith(('http://', 'https://', 'mailto:', '#')):
continue
target = target.split('#', 1)[0].split('?', 1)[0]
if not target:
continue
resolved = posixpath.normpath(posixpath.join(posixpath.dirname(path), target))
if resolved not in tree:
print(f'MISSING {path}:{line_no}: {raw} -> {resolved}')
PY
echo '== Protected-base literal route and security evidence =='
git grep -n -I -E \
'@(RequestMapping|GetMapping|PostMapping|PutMapping|DeleteMapping|PatchMapping)|RequestMethod\.' \
"$base" -- '*.java' || true
git grep -n -I -E \
'(valid_token|Jwt|JWT|SecurityFilterChain|Authentication|Idempoten|idempoten|Durable|durable|JobStatus|Transactional)' \
"$base" -- '*.java' '*.sql' || true
echo '== Diff for current documentation contracts =='
git diff --unified=50 "$base" "$head" -- \
README.md PRD.md TRD.md ARCHITECTURE.md SECURITY.md \
'docs/**/*.md' \
etl-service/src/test/java/com/xtrmetl/etl/documentation/CanonicalDocumentationContractTest.java \
etl-service/src/test/java/com/xtrmetl/etl/documentation/DocumentationValidationTest.javaLength of output: 6735 🏁 Script executed: #!/bin/bash
set -euo pipefail
base='622e5e6c3d534f230c390f10e3832efadfc01825'
old_head='15c000a644796ef72e071dcd745dd4cf89feb38a'
head='e3f69c747ffdeae5212f9735b0d59e6562e344cc'
show_numbered() {
git show "$1:$2" | awk '{printf "%5d %s\n", NR, $0}'
}
echo '== Documentation contract tests at literal head =='
for f in \
etl-service/src/test/java/com/xtrmetl/etl/documentation/CanonicalDocumentationContractTest.java \
etl-service/src/test/java/com/xtrmetl/etl/documentation/DocumentationValidationTest.java
do
echo "--- $f"
show_numbered "$head" "$f"
done
echo '== Changes from predecessor reviewed head to requested head =='
git diff --unified=40 "$old_head" "$head" -- \
README.md PRD.md TRD.md ARCHITECTURE.md SECURITY.md \
'docs/**/*.md' \
etl-service/src/test/java/com/xtrmetl/etl/documentation/CanonicalDocumentationContractTest.java \
etl-service/src/test/java/com/xtrmetl/etl/documentation/DocumentationValidationTest.java
echo '== Status-bearing documentation lines at literal head =='
git grep -n -I -E \
'(implemented_on_develop|active_pr|planned|superseded|known_gap|out_of_scope|CANCELLED|cancellation|Resource Server|JWT|valid_token|Idempotency-Key|/api/etl/jobs)' \
"$head" -- '*.md' '*.MD' || true
echo '== Literal-head Markdown link audit =='
python3 - <<'PY'
import posixpath, re, subprocess
head = 'e3f69c747ffdeae5212f9735b0d59e6562e344cc'
tree = set(subprocess.check_output(
['git', 'ls-tree', '-r', '--name-only', head], text=True).splitlines())
link = re.compile(r'(?<!!)\[[^\]]+\]\(([^)\s]+)')
for path in sorted(p for p in tree if p.lower().endswith('.md')):
text = subprocess.check_output(
['git', 'show', f'{head}:{path}'], text=True, errors='replace')
for line_no, line_text in enumerate(text.splitlines(), 1):
for raw in link.findall(line_text):
target = raw.strip('<>')
if target.startswith(('http://', 'https://', 'mailto:', '#')):
continue
target = target.split('#', 1)[0].split('?', 1)[0]
if target:
resolved = posixpath.normpath(posixpath.join(posixpath.dirname(path), target))
if resolved not in tree:
print(f'MISSING {path}:{line_no}: {raw} -> {resolved}')
PY
echo '== Locate protected-base sources relevant to documented contracts =='
git ls-tree -r --name-only "$base" | grep -E \
'(^|/)(Etl(Job)?Controller|JwtAuthenticationFilter|.*Security.*|V[0-9]+__.*(job|idempoten).*\.(java|sql))$' \
|| true
echo '== Protected-base route, status, and security evidence =='
git grep -n -I -E \
'@(RequestMapping|GetMapping|PostMapping|PutMapping|DeleteMapping|PatchMapping)|RequestMethod\.|valid_token|Jwt|JWT|SecurityFilterChain|Idempoten|idempoten|Durable|durable|JobStatus|Transactional' \
"$base" -- '*.java' '*.sql' || trueLength of output: 222835 🏁 Script executed: #!/bin/bash
set -euo pipefail
base='622e5e6c3d534f230c390f10e3832efadfc01825'
head='e3f69c747ffdeae5212f9735b0d59e6562e344cc'
echo '== README directory link and target =='
git show "$head:README.md" | awk 'NR >= 190 && NR <= 215 { printf "%5d %s\n", NR, $0 }'
echo '-- tracked entries under docs/connectors --'
git ls-tree -r --name-only "$head" -- docs/connectors || true
echo '-- working-tree target type --'
if [ -d docs/connectors ]; then
echo 'docs/connectors is a directory'
elif [ -e docs/connectors ]; then
echo 'docs/connectors exists but is not a directory'
else
echo 'docs/connectors does not exist'
fi
echo '== Maven version declarations at literal head =='
for f in $(git ls-tree -r --name-only "$head" | grep -E '(^|/)pom\.xml$'); do
echo "--- $f"
git show "$head:$f" | grep -n -E '(spring-boot|spring-cloud|3\.5\.|2025\.0\.)' || true
done
echo '== TRD runtime version statements =='
git show "$head:TRD.md" | awk 'NR >= 15 && NR <= 35 { printf "%5d %s\n", NR, $0 }'
echo '== Protected-base ETL problem mapping and error statuses =='
for f in \
etl-service/src/main/java/com/xtrmetl/etl/controller/EtlApiProblemHandler.java \
etl-service/src/main/java/com/xtrmetl/etl/service/EtlRequestError.java
do
echo "--- $f"
git show "$base:$f" | awk '{printf "%5d %s\n", NR, $0}' | \
grep -E -C 4 '(HttpStatus|SERVICE_UNAVAILABLE|INTERNAL_SERVER_ERROR|TRANSIENT|503|500|Target|DataAccess)' \
|| true
done
echo '== Literal-head README retry statements and canonical problem contract =='
git show "$head:README.md" | awk 'NR >= 105 && NR <= 145 { printf "%5d %s\n", NR, $0 }'
git show "$head:docs/api/problem-details.md" | awk 'NR <= 150 { printf "%5d %s\n", NR, $0 }'Length of output: 29239
I found one documentation-contract gap.
The previous Protected-base source supports the documented ETL, idempotency, feature-gated durable intake, CDC, and You are interacting with an AI system. |
This was referenced Aug 9, 2026
This was referenced Aug 10, 2026
This was referenced Aug 10, 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.
Purpose
Establish one code-current acquisition-diligence documentation graph over exact protected
develop@622e5e6c3d534f230c390f10e3832efadfc01825. Active PRs/issues, chat, statuses, and synthetic merge previews remain evidence inputs, never shipped truth.Exact current identity
develop@622e5e6c3d534f230c390f10e3832efadfc01825;docs/canonical-architecture-baseline-622e5e6;e7f7e7399fc0d1ea00724e59912bd332aef1bddb;9318881297ef6a45962e5bfbe5908dbdfb32df3b;e1c74748b00a59879422d7389244636501a70a7a: two non-destructive descendant commits, zero behind, changing onlydocs/DOCUMENTATION_ASSESSMENT.mdanddocs/TRACEABILITY.md.No check, review, approval, base snapshot, body claim, or merge preview transfers across a source-head change.
Canonical graph and whole-conversation verdict
The branch contains current PRD, TRD, root Architecture, Security, ADR index plus ADR-0001..0014, UML, ERD/logical artifact model, API Contract, Threat Model, Test Strategy, Operability, Traceability, Documentation Assessment, AGENTS/CLAUDE/README/CHANGELOG alignment, and machine-checkable contracts.
The active documentation line is substantially design-sufficient; protected
developis still acquisition-documentation insufficient.present_stalerelative to post-169 security, identity, recovery, evidence, DLT, tenancy, and release work;present_currenton PR docs: establish canonical commercial architecture baseline #149;owned_by_separate_active_prfeat(api): add machine-readable HTTP and CDC contracts #157;partial;missing_or_partialthrough issue [Acquisition diligence] Establish explicit repository licensing and copyright policy #151/[Release/Supply chain] Establish reproducible exact-head artifacts and provenance #165.present_currentis honest design authority, not protected implementation. Issue #159 remains the protected-integration/live-reconciliation completion tracker.Cross-cutting decisions added test-first
Architecture/UML now cover identity, Flyway/recovery, DLT, and evidence/release flows. ERD separates protected relational truth from conceptual/external
tenant_scope,service_identity,backup_bundle,backup_manifest_record,dead_letter_record, andexternal_effect_record; no table is invented from target design.RED → GREEN evidence
d76c2846f6827a9cf64d673576476cba642f66dd, CI31382315597, macOS93435001901: all prior documentation tests green; nine new assertions failed exactly for missing ADR/Architecture/UML/ERD authority.21ec7b2bb454d59b9f9cb9aebf2ca094fac9b369: added ADR-0009..0014 and current Architecture/UML/ERD. CI exposed one stale lexical assertion requiringsynthetic-mergerather than canonicalsynthetic merge.5780011a4e2d5c4df0dcd6bc2e03e03d7cf3b2bb: fixed that brittle punctuation assertion without weakening source-identity semantics.e1c74748b00a59879422d7389244636501a70a7a, CI31384214890, macOS93440928100: canonical/live tests green except one intended fitness/Traceability assertion; ETL 262 tests, one failure, zero errors/skips.e7f7e7399fc0d1ea00724e59912bd332aef1bddb: Assessment and Traceability recognize the now-present authorities without promoting active behavior.Current CI
31384861240, macOS job93442900410, checked out synthetic merge9318881297ef6a45962e5bfbe5908dbdfb32df3b. It proves:CrossCuttingArchitectureAuthorityTest: 10/10;CanonicalDocumentationContractTest: 8/8;LiveCommercialTraceabilityTest: 7/7;The same job still reports
Analyzed bundle 'etl-service' with 0 classesand then declares coverage checks met. That is explicitly non-acceptable coverage evidence under issue #162/PR #164 and repository-wide issue #205.Exact current gates
For source head
e7f7e7399fc0d1ea00724e59912bd332aef1bddb:31384861240: success on Ubuntu, macOS, and Windows;31384861247: success;31384861218: success;31384861286: success;31384861146: aggregate success;COMMENTEDonly;APPROVED: absent.CI and scanners executed the synthetic merge preview, not literal source. Issue #196 dependency-graph completeness and #162/#164/#205 non-vacuous coverage remain independent acceptance gates. Aggregate green is not merge or release authority.
Live work preserved as unshipped
Traceability covers #121, #139, #141–#148, #155–#169, #170/#171/#172/#174/#176/#211, #184, #189, #191/#192/#197/#199/#201/#208, #222/#224/#226/#228/#230/#236, and issue #151/#154/#159/#161/#162/#165/#185/#186/#187/#196/#205. Mutable SHAs and run IDs remain dated evidence rather than timeless Architecture.
Scope and merge boundary
This PR does not implement active product/security/recovery work, choose a license, invent certification/SLO/RPO/RTO/DR attainment, mutate separately leased repositories, or publish a release. Keep Draft until the unchanged exact head has accepted literal/subject-bound deterministic and security evidence, complete dependency materialization, non-vacuous applicable coverage, zero valid unresolved findings, current live-base integrity, and qualifying independent review.