docs: establish canonical commercial architecture baseline - #149
Draft
seonghobae wants to merge 56 commits into
Draft
docs: establish canonical commercial architecture baseline#149seonghobae wants to merge 56 commits into
seonghobae wants to merge 56 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
opencode-agent
Bot
added
priority: medium
seonghobae
added
the
documentation
ChatGPT Codex Connector
Collaborator
Author
|
Extended this existing canonical public-surface writer rather than opening a competing README/Pages PR: added |
Collaborator
Author
|
Canonical documentation handoff: stock-data capability is implemented as a path-disjoint candidate in #333, head I inspected this PR's changed-file inventory before writing: none of #333's 14 new paths replace your root README/AGENTS/CLAUDE/PRD/TRD/ARCHITECTURE/CHANGELOG or numbered ADRs. Please integrate the effective feature delta, not a whole-file overwrite, from Actual capability: Java provider/host ACL for bounded FSC daily-stock queries, exact typed values, complete-result pagination validation and raw-page SHA-256 evidence. No new numerical/security runtime, unrestricted HTTP client, SQL write, live provider verification or release. EgressWeave #246 owns the missing released cross-language transport; the primary wire-guide and approved-key retrieval remain required. Keep this as Proposed/open-PR capability until verified integration. Fresh hosted run 34115900752 passed the existing Java 25 reactor on Ubuntu/Windows/macOS; the Ubuntu log explicitly runs the new stock JUnit contract and the six-module reactor succeeds on test-merge |
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 buyer-usable, code-current acquisition-diligence documentation graph for mightyETL while keeping protected behavior, active work, evidence, release authority, and third-party obligations distinct.
Protected-develop reconciliation completed — 2026-09-02
The prior branch state was 31 protected commits behind and explicitly required reconciliation. That actionable blocker is resolved non-destructively and the current branch still contains the protected
developbase.develop@ba8911f50ed20a39927a0d51c0cf20f9b7c91820;a1dfca16a260e6f605d099499a064d7ddb330042;074d7cf...preserved the prior documentation head and then-protecteddevelopas parents; later forward commits remain descendants of that non-force reconciliation;ahead_by=56,behind_by=0, with protecteddevelopas the merge base;Every predecessor-head check/review is historical after later head movement and does not transfer.
Repository-facing product documentation
The canonical line contains PRD/TRD, Architecture, ADRs, UML, ERD/logical model, API Contract, Threat Model, Test Strategy, Operability, Traceability, Documentation Assessment, AGENTS/CLAUDE/README/CHANGELOG alignment, and machine-checkable documentation contracts.
The README is product-first and:
ContextualWisdomLab/mightyETL;developbehavior from active PRs and known gaps;Current protected-source reinspection after reconciliation confirms the README remains conservative: CDC Kafka acknowledgement work #139 is still Draft/unmerged, the stop-completion defect remains a separate gap, and the README does not claim those candidate repairs as protected behavior.
Licensing decision and due diligence
Owner policy is explicit in issue #151: ContextualWisdomLab-owned source uses a commercially usable license, normally Apache-2.0 or MIT, while noncommercial restrictions and GPL/LGPL/AGPL inbound software are not accepted by default. This branch implements the first-party decision with Apache License 2.0 for mightyETL original source/documentation.
LICENSEis the canonical Apache-2.0 text;docs/DOCUMENTATION_ASSESSMENT.mdkeeps third-party/imported-material provenance, attribution/NOTICE obligations, distributable-license enforcement, SBOM/package evidence and release provenance as separate diligence rather than pretending the source grant relicenses them;Issue #151 therefore remains open for the remaining third-party/imported provenance and distributable NOTICE/license enforcement. Issue #165 remains the release/provenance owner; no release is claimed from this documentation branch.
Documentation fitness
Current integration state
This PR remains Draft while fresh exact-head verification and residual acquisition diligence execute. For current head
a1dfca16a260e6f605d099499a064d7ddb330042, SAST Semgrep run33602552511is pending and CI33602552448, SBOM33602552811, Dependency Review33602552388, and Security Scan33602552440are queued. These are non-passing waiting states, not merge evidence. Do not infer readiness from predecessor results.Do not merge merely because ancestry is current or source licensing is explicit. Integration still requires terminal applicable CI/security/dependency/SBOM/coverage evidence, zero valid unresolved review findings, then-live governance, and no genuine commercial-license/provenance blocker affecting the distributable surface. No protection weakening, stale-evidence transfer, release claim, certification claim, or third-party relicensing is authorized.