docs(automation): establish canonical control-plane architecture baseline - #886
docs(automation): establish canonical control-plane architecture baseline#886seonghobae wants to merge 29 commits into
Conversation
📝 WalkthroughWalkthrough자동화 제어 평면의 정식 문서, 아키텍처·운영·보안 계약, ADR, 문서 감사 테스트와 exact-revision CI 검증을 추가했습니다. 문서 그래프와 continuation handoff 규칙도 정의했습니다. Changes자동화 제어 평면
Estimated code review effort: 3 (Moderate) | ~30 minutes Possibly related issues
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 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 |
|
@coderabbitai review Review exact current head |
|
I will check the specified documentation authority boundaries and fitness contracts. I will not mutate the branch, create approval, change protection, or use predecessor-head evidence. ✅ Action performedReview finished.
|
|
Documentation review on live head
Do not convert standards references into shipped runtime claims. Preserve the controlled maturity vocabulary and leaf-vs-central ownership boundary. Re-run exact-head Automation Documentation Quality CI after the repair. |
|
Consolidation boundary: concurrent #896 is now the broader candidate canonical automation documentation line. Preserve this branch and its unique whole-conversation/continuation work, but do not merge a competing second canonical graph. #896 has been instructed to absorb the unique #886 contracts before either line is closed: conversation-to-repository reconciliation, controlled maturity states, explicit prompt/document/status-as-intermediate semantics, double-exit/no-soft-timeout continuation, conceptual continuation/documentation/traceability/remediation entities, and their machine gates. Keep this PR open as source evidence until #896 proves exact-head parity for those unique decisions. After that proof, this PR should close as superseded rather than merge in parallel. If #896 fails to preserve any unique accepted decision, retain #886 and reconcile the other direction instead. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 15
🤖 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 @.github/workflows/automation-documentation-quality-ci.yml:
- Around line 6-12: Update the paths list in the workflow configuration to
include every workflow path defined by WORKFLOW_REFERENCES in
tests/test_automation_documentation.py. Ensure all four live workflow files are
covered so additions, removals, or renames trigger the documentation contract
check, while preserving the existing path entries.
- Line 36: Update the test step in the automation documentation quality workflow
to run the full repository test suite with coverage via `python -m coverage run
-m pytest tests -q` instead of invoking only
`tests/test_automation_documentation.py`, while preserving the existing workflow
step context.
In `@docs/automation/adr/0010-continuation-documentation-handoff.md`:
- Around line 75-77: Clarify the scope of the “No GitHub runtime workflow ... is
changed” statement in the “Migration and rollback” section to distinguish
production/control-plane runtime workflows from the documentation quality CI
workflow added by this PR. Update the wording so it no longer contradicts the
addition of .github/workflows/automation-documentation-quality-ci.yml, while
preserving the rollback and safety-boundary details.
In `@docs/automation/ARCHITECTURE.md`:
- Around line 39-42: Update the “Canonical documentation plane” statement in
ARCHITECTURE.md so only docs/automation/** and the ADR index are identified as
the durable design authority, using docs/automation/README.md as the reference
graph; describe AGENTS.md, CLAUDE.md, and CHANGELOG.md solely as linked
summary/traceability surfaces, not parallel sources of design authority.
In `@docs/automation/DATA_MODEL.md`:
- Around line 56-60: Update the ERD entity definitions and mappings in
DATA_MODEL.md to explicitly represent or map every evidence authority named in
the invariants, including model, merge, external-automation, and runtime
evidence. Add or identify the corresponding model_evidence and merge_evidence
entities, and define how external-automation evidence relates to
automation_control_record, while preserving separation from review, check,
status, workflow, and other authorities.
- Around line 10-11: DATA_MODEL의 pull_request_snapshot과 source_revision 및
base_revision 관계를 일대일에서 다대일로 변경하세요. 각 revision이 여러 pull_request_snapshot에서 재사용될
수 있도록 두 관계 모두 snapshot 쪽은 다수, revision 쪽은 하나를 나타내는 카디널리티로 수정하고 관계 의미는 유지하세요.
In `@docs/automation/DOCUMENTATION_AUDIT.md`:
- Around line 37-47: Update the repository responsibility table entries to
include a full cross-repository identifier for every referenced repository,
using the owning organization plus repository name and issue/PR number
(owner/repo#num) or a complete URL. Apply this consistently to the repositories
listed in the table, including naruon, and preserve the existing responsibility
descriptions.
In `@docs/automation/INCIDENT_RUNBOOK.md`:
- Around line 41-43: Update the merge gate statement in INCIDENT_RUNBOOK.md to
require the complete gate contract from the automation requirements, including
protected exact-head required checks, completed automated review, no valid
unresolved findings, counted independent approvals, and no bypass. Keep the
existing operational-defect runtime evidence requirements, and do not treat the
general evidence check as a substitute for these merge conditions.
In `@docs/automation/PRD.md`:
- Around line 56-58: Update the termination rule in the PRD section covering
fresh whole-queue sweeps so every invocation always performs two fresh sweeps
before exiting, including when the first sweep finds no safe executable work.
Preserve the existing requirement that any action found by the first sweep is
followed by a second sweep, and align the wording with the final-action
requirement in the continuation handoff ADR.
In `@docs/automation/README.md`:
- Around line 27-30: Update the status validation in
test_automation_documentation.py to collect all status matches instead of
relying on re.search, then assert that each canonical document contains exactly
one status declaration. Preserve the existing validation of the allowed status
values.
In `@docs/automation/SECURITY.md`:
- Line 31: Update the immutable pin and hash-verification statement in
SECURITY.md to remove the ambiguous “where practical” language or define
explicit exceptions consistent with THREAT_MODEL.md. If exceptions remain,
document their scope, approval requirements, compensating controls, and
validation tests so mutable action references are not implicitly permitted.
- Line 20: Update the reusable workflow guidance in SECURITY.md to remove the
exception permitting secrets: inherit. Require callers to pass only explicitly
mapped secrets matching the reusable workflow’s on.workflow_call named secret
contract, preserving the minimal-secret requirement.
In `@docs/automation/TEST_STRATEGY.md`:
- Around line 29-31: Align the documentation contract description with
enforcement in the documentation test module: add deterministic assertions for
detailed ADR acceptance criteria, DOCUMENTATION_AUDIT.md content, and the
authority and termination rules in INCIDENT_RUNBOOK.md and TRACEABILITY.md,
including continuation/reconciliation invariants. Alternatively, reduce the
documented scope to the checks actually implemented, but ensure README’s stated
contract and the test coverage remain consistent.
In `@docs/automation/TRD.md`:
- Around line 51-55: Define a consistent budget-exhaustion rule for both
termination sweeps: if the budget is exhausted before the first sweep’s required
action, terminate with reason budget_exhausted and record evidence instead of
forcing execution; apply the same rule after the final substantive action for
the second sweep. Update docs/automation/TRD.md (lines 51-55) and
docs/automation/adr/0003-work-conserving-execution.md (lines 17-19) to match,
and add regression coverage for exhaustion at each sweep.
In `@docs/automation/UML.md`:
- Around line 55-61: Update the Execute-to-RefetchAffectedState transition
description in the state-machine diagram to also include review request and
defer decision mutations, preserving the existing action, merge, RCA,
documentation, and prompt entries. Ensure the diagram explicitly represents that
these operations require queue reselection and continuation_handoff rather than
allowing early termination.
🪄 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: f736f23f-4ca0-417c-a75c-26b9903b5cd9
📒 Files selected for processing (29)
.github/workflows/automation-documentation-quality-ci.ymlAGENTS.mdCHANGELOG.mdCLAUDE.mddocs/automation/ARCHITECTURE.mddocs/automation/DATA_MODEL.mddocs/automation/DOCUMENTATION_AUDIT.mddocs/automation/INCIDENT_RUNBOOK.mddocs/automation/OPERABILITY.mddocs/automation/PRD.mddocs/automation/README.mddocs/automation/SECURITY.mddocs/automation/TEST_STRATEGY.mddocs/automation/THREAT_MODEL.mddocs/automation/TRACEABILITY.mddocs/automation/TRD.mddocs/automation/UML.mddocs/automation/adr/0001-writer-leases.mddocs/automation/adr/0002-exact-head-live-base.mddocs/automation/adr/0003-work-conserving-execution.mddocs/automation/adr/0004-evidence-authority-separation.mddocs/automation/adr/0005-bounded-bootstrap-retries.mddocs/automation/adr/0006-explicit-secret-contracts.mddocs/automation/adr/0007-independent-review-governance.mddocs/automation/adr/0008-protected-main-acceptance.mddocs/automation/adr/0009-central-control-plane-ownership.mddocs/automation/adr/0010-continuation-documentation-handoff.mddocs/automation/adr/README.mdtests/test_automation_documentation.py
| paths: | ||
| - "docs/automation/**" | ||
| - "tests/test_automation_documentation.py" | ||
| - ".github/workflows/automation-documentation-quality-ci.yml" | ||
| - "AGENTS.md" | ||
| - "CLAUDE.md" | ||
| - "CHANGELOG.md" |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
라이브 워크플로 변경 시 문서 계약 검사를 실행하세요.
tests/test_automation_documentation.py Line 113-115는 4개 라이브 워크플로의 존재를 검사합니다. 현재 paths에는 이 파일들이 없습니다. 해당 워크플로를 삭제하거나 이름을 변경하는 PR은 이 품질 게이트를 실행하지 않고 병합될 수 있습니다.
WORKFLOW_REFERENCES의 모든 경로를 paths에 추가하세요.
수정 예시
- ".github/workflows/automation-documentation-quality-ci.yml"
+ - ".github/workflows/opencode-review.yml"
+ - ".github/workflows/opencode-review-dispatch.yml"
+ - ".github/workflows/pr-review-merge-scheduler.yml"
+ - ".github/workflows/pr-auto-rebase.yml"📝 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.
| paths: | |
| - "docs/automation/**" | |
| - "tests/test_automation_documentation.py" | |
| - ".github/workflows/automation-documentation-quality-ci.yml" | |
| - "AGENTS.md" | |
| - "CLAUDE.md" | |
| - "CHANGELOG.md" | |
| paths: | |
| - "docs/automation/**" | |
| - "tests/test_automation_documentation.py" | |
| - ".github/workflows/automation-documentation-quality-ci.yml" | |
| - ".github/workflows/opencode-review.yml" | |
| - ".github/workflows/opencode-review-dispatch.yml" | |
| - ".github/workflows/pr-review-merge-scheduler.yml" | |
| - ".github/workflows/pr-auto-rebase.yml" | |
| - "AGENTS.md" | |
| - "CLAUDE.md" | |
| - "CHANGELOG.md" |
🤖 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 @.github/workflows/automation-documentation-quality-ci.yml around lines 6 -
12, Update the paths list in the workflow configuration to include every
workflow path defined by WORKFLOW_REFERENCES in
tests/test_automation_documentation.py. Ensure all four live workflow files are
covered so additions, removals, or renames trigger the documentation contract
check, while preserving the existing path entries.
| shell: bash --noprofile --norc -e -o pipefail {0} | ||
| run: | | ||
| test "$(git rev-parse HEAD)" = "${{ github.event.pull_request.head.sha || github.sha }}" | ||
| python tests/test_automation_documentation.py |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Tracked workflow files:"
git ls-files '.github/workflows/**/*.yml' '.github/workflows/**/*.yaml' | sed -n '1,120p'
echo
echo "Target workflow:"
if [ -f .github/workflows/automation-documentation-quality-ci.yml ]; then
nl -ba .github/workflows/automation-documentation-quality-ci.yml | sed -n '1,120p'
else
echo "missing .github/workflows/automation-documentation-quality-ci.yml"
fi
echo
echo "Tests files:"
git ls-files tests | sed -n '1,80p'
echo
echo "Search tests/automation and test commands:"
rg -n "unit|unittest|pytest|tox|python (tests/|-m unittest)|test_automation|automation-documentation|document" . -g '!*.png' -g '!*.jpg' -g '!*.svg' -g '!package-lock.json' -g '!pnpm-lock.yaml' -g '!yarn.lock' | sed -n '1,240p'Repository: ContextualWisdomLab/.github
Length of output: 248
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Tracked workflow files:"
git ls-files '.github/workflows/**/*.yml' '.github/workflows/**/*.yaml' 2>/dev/null || git ls-files '.github/workflows/*' 2>/dev/null || true
echo
echo "Target workflow:"
if [ -f .github/workflows/automation-documentation-quality-ci.yml ]; then
awk '{printf "%6d\t%s\n", NR, $0}' .github/workflows/automation-documentation-quality-ci.yml | sed -n '1,120p'
else
echo "missing .github/workflows/automation-documentation-quality-ci.yml"
fi
echo
echo "Tests files:"
git ls-files tests 2>/dev/null | sed -n '1,120p' || true
echo
echo "Search relevant keywords in workflows/tests:"
python3 - <<'PY'
import pathlib, re
for p in pathlib.Path('.github').rglob('*'):
if p.is_file() and p.suffix in {'.yml','.yaml'} and p.parts[:2] == ('.github','workflows'):
txt=p.read_text(errors='ignore')
if any(s in txt for s in ['automation-documentation','pull_request_target','python tests/test_automation_documentation.py','run: python']):
print(f'--- {p}')
for i,line in enumerate(txt.splitlines(),1):
if ('automation-documentation' in line or 'pull_request_target' in line or 'python tests/test_automation_documentation.py' in line or re.search(r'run:\s*python', line)):
print(f'{i}: {line}')
if pathlib.Path('tests').exists():
for p in pathlib.Path('tests').rglob('*.py'):
print(f'--- {p}')
txt=p.read_text(errors='ignore')
for i,line in enumerate(txt.splitlines(),1):
if 'unittest' in line or 'pytest' in line or 'def test_' in line or 'class ' in line or 'main' in line:
print(f'{i}: {line}')
PYRepository: ContextualWisdomLab/.github
Length of output: 50384
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Candidate dependency/config files:"
git ls-files | rg '(^|/)(pyproject\.toml|setup\.py|setup\.cfg|tox\.ini|pytest\.ini|requirements.*\.txt|Pipfile|uv\.lock|poetry\.lock)$' || true
echo
echo "Test command declarations:"
rg -n "pytest|unittest|tox|coverage|python -m|safe_pytest_command" .github tests pyproject.toml setup.cfg tox.ini pytest.ini 2>/dev/null || true
echo
echo "Target test entrypoint contents:"
if [ -f tests/test_automation_documentation.py ]; then
awk '{printf "%6d\t%s\n", NR, $0}' tests/test_automation_documentation.py | sed -n '1,160p'
fi
echo
echo "Programmatic check: does automation workflow execute only tests/test_automation_documentation.py in repository paths?"
python3 - <<'PY'
from pathlib import Path
p = Path(".github/workflows/automation-documentation-quality-ci.yml")
t = p.read_text()
lines = [i+1 for i,l in enumerate(t.splitlines()) if "python tests/test_automation_documentation.py" in l]
files_in_tests = sorted([str(p) for p in (Path("tests")).rglob("*.py")])
print("lines_invoking_target:", lines)
print("files_invoking_target_in_repo_paths:", [k for k,l in enumerate(t.splitlines(),1) if "python " in l or "pytest" in l or "unittest" in l])
print("tests_py_count:", len(files_in_tests))
print("target_py_exists:", Path("tests/test_automation_documentation.py").exists())
for k,l in enumerate(t.splitlines(),1):
if ("python " in l or "pytest" in l or "unittest" in l) and "python tests/test_automation_documentation.py" not in l:
print(f"OTHER_TEST_COMMAND_AT_{k}: {l.strip()}")
PYRepository: ContextualWisdomLab/.github
Length of output: 50384
전체 테스트 스위트를 실행하세요.
.github/workflows/automation-documentation-quality-ci.yml의 tests/test_automation_documentation.py 단계는 저장소 전체 테스트 (pytest) 결과 없이 자동화 문서 변경만 실행합니다. workflow/구성 변경은 다른 정확 문자열 및 구조 계약도 포함하므로, 이 단계에서 python -m coverage run -m pytest tests -q와 같은 저장소 전체 테스트 명령을 실행하도록 바꾸세요.
🤖 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 @.github/workflows/automation-documentation-quality-ci.yml at line 36, Update
the test step in the automation documentation quality workflow to run the full
repository test suite with coverage via `python -m coverage run -m pytest tests
-q` instead of invoking only `tests/test_automation_documentation.py`, while
preserving the existing workflow step context.
Source: Coding guidelines
| ## Migration and rollback | ||
|
|
||
| No GitHub runtime workflow, reviewer identity, credential, branch protection rule, or merge authority is changed by adopting this documentation decision. The external scheduled writer prompt is updated independently and can be rolled back to the prior configuration if continuation logic causes unsafe lane selection; writer leases and GitHub gates remain the safety boundary during rollback. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
워크플로 변경 범위를 정확히 기술하세요.
Line 77은 GitHub runtime workflow가 변경되지 않았다고 선언합니다. 그러나 이 PR은 .github/workflows/automation-documentation-quality-ci.yml을 추가합니다. 해당 문장이 production/control-plane runtime workflow만 의미한다면 그 범위를 명시하세요. 그렇지 않으면 현재 PR 설명과 모순됩니다.
🤖 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/automation/adr/0010-continuation-documentation-handoff.md` around lines
75 - 77, Clarify the scope of the “No GitHub runtime workflow ... is changed”
statement in the “Migration and rollback” section to distinguish
production/control-plane runtime workflows from the documentation quality CI
workflow added by this PR. Update the wording so it no longer contradicts the
addition of .github/workflows/automation-documentation-quality-ci.yml, while
preserving the rollback and safety-boundary details.
| ### Canonical documentation plane | ||
|
|
||
| `docs/automation/**`, the ADR index, AGENTS/CLAUDE/CHANGELOG links, and their machine-checkable fitness gate are the durable design authority. Pull-request bodies, incident comments, conversation history, and downloadable planning artifacts supply evidence and candidate decisions, but material durable decisions must be reconciled into this graph with explicit maturity. | ||
|
|
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
문서 권한의 단일 출처를 명확히 하세요.
Line 41은 AGENTS.md, CLAUDE.md, CHANGELOG.md links를 durable design authority와 함께 열거합니다. 이 문장은 세 파일이 별도 설계 권한이라는 의미로 읽힐 수 있습니다. docs/automation/**와 ADR index만 durable design authority로 두고, 세 파일은 링크·요약·추적성 표면으로 명시하세요.
As per coding guidelines, docs/automation/README.md를 기준 그래프로 사용하고 병렬 문서 권한을 만들지 않아야 합니다.
수정 예시
- `docs/automation/**`, the ADR index, AGENTS/CLAUDE/CHANGELOG links, and their machine-checkable fitness gate are the durable design authority.
+ `docs/automation/**` and the ADR index are the durable design authority. AGENTS.md, CLAUDE.md, and CHANGELOG.md only link to, summarize, or trace that graph. Their machine-checkable fitness gate verifies the canonical graph.📝 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.
| ### Canonical documentation plane | |
| `docs/automation/**`, the ADR index, AGENTS/CLAUDE/CHANGELOG links, and their machine-checkable fitness gate are the durable design authority. Pull-request bodies, incident comments, conversation history, and downloadable planning artifacts supply evidence and candidate decisions, but material durable decisions must be reconciled into this graph with explicit maturity. | |
| ### Canonical documentation plane | |
| `docs/automation/**` and the ADR index are the durable design authority. AGENTS.md, CLAUDE.md, and CHANGELOG.md only link to, summarize, or trace that graph. Their machine-checkable fitness gate verifies the canonical graph. |
🤖 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/automation/ARCHITECTURE.md` around lines 39 - 42, Update the “Canonical
documentation plane” statement in ARCHITECTURE.md so only docs/automation/** and
the ADR index are identified as the durable design authority, using
docs/automation/README.md as the reference graph; describe AGENTS.md, CLAUDE.md,
and CHANGELOG.md solely as linked summary/traceability surfaces, not parallel
sources of design authority.
Source: Coding guidelines
| pull_request_snapshot ||--|| source_revision : identifies | ||
| pull_request_snapshot ||--|| base_revision : targets |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
source_revision과 base_revision의 카디널리티를 수정해야 합니다.
동일한 head 또는 base commit은 여러 pull_request_snapshot에서 재사용될 수 있습니다. 현재 ||--|| 관계는 하나의 revision이 하나의 snapshot에만 연결되는 의미를 만듭니다. 이 모델을 구현하면 동일 head 재수집과 여러 PR의 공통 base 표현이 불가능해집니다.
수정 예시
- pull_request_snapshot ||--|| source_revision : identifies
- pull_request_snapshot ||--|| base_revision : targets
+ source_revision ||--o{ pull_request_snapshot : identifies
+ base_revision ||--o{ pull_request_snapshot : targets📝 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.
| pull_request_snapshot ||--|| source_revision : identifies | |
| pull_request_snapshot ||--|| base_revision : targets | |
| source_revision ||--o{ pull_request_snapshot : identifies | |
| base_revision ||--o{ pull_request_snapshot : targets |
🤖 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/automation/DATA_MODEL.md` around lines 10 - 11, DATA_MODEL의
pull_request_snapshot과 source_revision 및 base_revision 관계를 일대일에서 다대일로 변경하세요. 각
revision이 여러 pull_request_snapshot에서 재사용될 수 있도록 두 관계 모두 snapshot 쪽은 다수, revision
쪽은 하나를 나타내는 카디널리티로 수정하고 관계 의미는 유지하세요.
| ## Credential contract | ||
|
|
||
| - Deterministic gates run before model credentials are required or materialized. | ||
| - Reusable workflows declare named minimal secrets; blanket `secrets: inherit` is rejected unless a separately reviewed interface proves every inherited value necessary. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "## context files"
git ls-files | rg '(^docs/(WELCOME|CWL-MASTER-CONTEXT|agent-github-project-protocol)\.md$|docs/automation/README\.md$|docs/automation/SECURITY\.md$|docs/automation/.*/ADR-0006|ADR-0006)' || true
echo
echo "## docs/automation/SECURITY.md around relevant lines"
sed -n '1,80p' docs/automation/SECURITY.md | cat -n
echo
echo "## search ADR-0006 and named minimal secret references"
rg -n "ADR-0006|named minimal secret|minimal secrets|secrets: inherit|inherit|reusable workflow|Reusabl" docs/automation docs || trueRepository: ContextualWisdomLab/.github
Length of output: 13661
🌐 Web query:
GitHub Actions reusable workflows secrets inherit passes all secrets to called workflow documentation
💡 Result:
When using GitHub Actions, the secrets: inherit keyword allows a calling workflow to automatically pass all secrets available to it—including repository, organization, and environment secrets—to a directly called reusable workflow [1][2]. Key details regarding the use of secrets: inherit include: Implicit Availability: When you use secrets: inherit, the called workflow can reference secrets even if they are not explicitly defined in the on.workflow_call section of the reusable workflow [1]. Scope and Limitations: - Single-Level Passing: Secrets are only passed to the directly called workflow [3]. In a workflow chain (e.g., A calls B, and B calls C), workflow C will only receive secrets from A if they are explicitly or implicitly passed from A to B, and then from B to C [3]. - Environment Secrets: While declaring an environment in a reusable workflow is intended to allow access to environment-scoped secrets, users have noted that relying solely on this definition may result in empty values for those secrets [2][4]. Incorporating secrets: inherit in the calling workflow is often required to ensure environment secrets resolve correctly [2][4]. - Security Context: Because secrets: inherit shares all secrets the caller has access to, it is generally recommended for use within the same organization or enterprise to maintain security boundaries [1]. If you choose not to use secrets: inherit, you must explicitly map each required secret individually using the secrets keyword [3][5].
Citations:
- 1: https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows
- 2: [BUG] Environment-scoped secrets unreachable from reusable workflow without secrets: inherit, despite called job declaring environment actions/runner#4453
- 3: https://github.com/github/docs/blob/main/content/actions/how-tos/reuse-automations/reuse-workflows.md
- 4: [Docs Bug] Reusable workflow env-scope secrets section missing the secrets: inherit requirement (see actions/runner#4453) github/docs#44458
- 5: https://github.blog/changelog/2022-05-03-github-actions-simplify-using-secrets-with-reusable-workflows/
🌐 Web query:
site:docs.github.com/en/actions/reusing-workflows/workflows-reused-by-other-workflows secrets inherit GitHub Actions
💡 Result:
In GitHub Actions, secrets don’t “inherit” automatically across workflows/levels; instead, you must explicitly make them available, or use the reusable-workflow mechanism that supports inheritance. 1) Secret precedence / “inheritance” across levels - Secrets can be defined at the organization, repository, and environment levels, and if the same secret name exists at multiple levels, the lowest level takes precedence (environment > repository > organization). [1] - Environment secrets are read when a job referencing that environment starts (not earlier). [1] 2) Reusable workflows: using secrets: inherit - When a workflow calls a reusable workflow, you can pass secrets from the caller to the directly called workflow using jobs.<job_id>.secrets.inherit (or the shorthand jobs:... secrets: inherit in the call). [2] - GitHub’s docs note that if you use secrets: inherit, you can reference inherited secrets in the reusable workflow even if they aren’t explicitly defined in the on: block. [2] - Warning/limitation: environment secrets cannot be passed from the caller workflow to a reusable workflow via on.workflow_call; environment secret behavior is restricted in that scenario. [2] Example (caller workflow): jobs: call-workflow: uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main with: config-path:.github/labeler.yml secrets: inherit 3) What “inherit” does NOT do - This inheritance is about passing secrets from a caller workflow to a directly called reusable workflow. GitHub specifies secrets are only passed to directly called workflow in the workflow chain. [3] - Secrets are only available to a workflow/job when GitHub reads them at the appropriate time (repo/org at queue; environment at job start). [1] If you tell me what specific scenario you mean by “inherit” (reusable workflows vs. environments vs. forks/pull_request), I can map the exact behavior and show a correct YAML pattern for that case.
Citations:
- 1: https://docs.github.com/en/actions/reference/security/secrets
- 2: https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows
- 3: https://docs.github.com/en/enterprise-cloud@latest/actions/how-tos/reuse-automations/reuse-workflows
secrets: inherit 예외를 제거하고 명시적 secret 매핑 만 허용하세요.
secrets: inherit는 호출 workflow가 가진 모든 secret을 직접 호출된 재사용 workflow에 전달합니다. 별도 검토라도 호출 workflow에 새 secret이 추가되면 재사용 workflow가 자동으로 그 secret을 받을 수 있습니다. ADR-0006의 명시적 최소 secret 계약과 충돌합니다. 재사용 workflow에는 on.workflow_call의 named secret 목록만큼만 secrets에 명시적으로 전달해야 합니다.
🤖 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/automation/SECURITY.md` at line 20, Update the reusable workflow
guidance in SECURITY.md to remove the exception permitting secrets: inherit.
Require callers to pass only explicitly mapped secrets matching the reusable
workflow’s on.workflow_call named secret contract, preserving the minimal-secret
requirement.
|
|
||
| ## Supply-chain and execution controls | ||
|
|
||
| Actions and trusted bootstrap inputs use immutable pins and verified hashes where practical. PR-controlled execution runs tokenless, with bounded filesystem access, output limits, timeouts, process-group cleanup, and network denial unless an explicit reviewed operation requires egress. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== files =="
git ls-files | rg '(^|/)(docs/automation/(README|SECURITY|THREAT_MODEL)\.md|CWL-MASTER-CONTEXT\.md|docs/agent-github-project-protocol\.md)$|(^|/)docs/automation/README\.md$|(^|/)docs/automation/SECURITY\.md$|(^|/)docs/automation/THREAT_MODEL\.md$' || true
echo "== target excerpts =="
if [ -f docs/automation/SECURITY.md ]; then
sed -n '1,60p' docs/automation/SECURITY.md
fi
echo "---"
if [ -f docs/automation/THREAT_MODEL.md ]; then
sed -n '1,80p' docs/automation/THREAT_MODEL.md
fi
echo "---"
if [ -f docs/CWL-MASTER-CONTEXT.md ]; then
sed -n '1,80p' docs/CWL-MASTER-CONTEXT.md
fi
echo "---"
if [ -f docs/agent-github-project-protocol.md ]; then
sed -n '1,100p' docs/agent-github-project-protocol.md
fi
echo "== searches for pin/hash action/security terms =="
rg -n "immutable (action )?pin|hash verification|hash-verified|tokenless|mutabl|egress|timeout|filesystem|Actions and trusted bootstrap inputs|supply|공급망|action reference|trusted bootstrap" docs README.md .github 2>/dev/null || trueRepository: ContextualWisdomLab/.github
Length of output: 50385
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== references to practical/practical exceptions =="
rg -n "where practical|where practical|practical|muable|mutable|immutable.*pin|pin|hash verification|hash-verified|verified hash|origin/redirect" docs docs/automation 2>/dev/null || true
echo "== static workflow references that are mutable version-like =="
python3 - <<'PY'
from pathlib import Path
import re
for p in sorted(Path(".github/workflows").glob("*.yml")):
text = p.read_text()
for i, line in enumerate(text.splitlines(), 1):
if "uses:" in line:
use = re.sub(r"\s*#.*", "", line).split("uses:",1)[1].strip()
if "@" in use and not re.search(r"@[0-9A-Fa-f]{7,40}$", use.split("@",1)[1]):
print(f"{p}:{i}: {use}")
PYRepository: ContextualWisdomLab/.github
Length of output: 22610
where practical를 변경하거나 예외 기준을 정의하세요.
docs/automation/SECURITY.md의 where practical은 docs/automation/THREAT_MODEL.md의 immutable action pins/hash verification 예방 통제와 일치하지 않습니다. 예외가 필요하다면 대상, 승인 조건, 보완 통제, 검증 테스트를 명시하세요. 아니면 공급망 보안 계약이 모호해져 mutable action ref 사용이 문서상 허용될 수 있습니다.
🤖 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/automation/SECURITY.md` at line 31, Update the immutable pin and
hash-verification statement in SECURITY.md to remove the ambiguous “where
practical” language or define explicit exceptions consistent with
THREAT_MODEL.md. If exceptions remain, document their scope, approval
requirements, compensating controls, and validation tests so mutable action
references are not implicitly permitted.
| `tests/test_automation_documentation.py` verifies required documents and indexes, controlled implementation status, Mermaid fence integrity, absence of ephemeral full SHAs in timeless documents, detailed ADR coverage through ADR-0010, the documentation-fitness audit, continuation/reconciliation invariants in core documents, and traceability to live workflow paths. `.github/workflows/automation-documentation-quality-ci.yml` runs the contract on the exact source revision. | ||
|
|
||
| Documentation tests are intentionally dependency-free and should fail before implementation/documentation repair when a new canonical artifact or invariant is introduced. A documentation file being present is necessary but not sufficient; the controlled maturity state prevents active or planned behavior from being mistaken for protected-main implementation. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift
문서 테스트가 선언한 계약을 실제로 검증하도록 확장하십시오.
Line 29는 tests/test_automation_documentation.py가 상세 ADR 계약, DOCUMENTATION_AUDIT.md의 내용, continuation/reconciliation 불변조건을 검증한다고 설명합니다. 현재 테스트는 문서·상태·색인 존재, fence와 SHA 형식, workflow 경로, 제한된 continuation 용어만 확인합니다. 상세 ADR acceptance 조건이나 INCIDENT_RUNBOOK.md와 TRACEABILITY.md의 권한·종료 규칙은 검증하지 않습니다. 따라서 테스트가 통과해도 핵심 규칙이 삭제되거나 약화될 수 있습니다. 해당 불변조건에 대한 결정적 assertion을 추가하거나 이 문장의 범위를 실제 검사로 줄이십시오. (raw.githubusercontent.com)
As per path instructions, docs/automation/README.md가 문서 품질과 제어 평면 계약의 기준이므로, 테스트 설명과 실제 enforcement 범위를 일치시켜야 합니다. (raw.githubusercontent.com)
🤖 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/automation/TEST_STRATEGY.md` around lines 29 - 31, Align the
documentation contract description with enforcement in the documentation test
module: add deterministic assertions for detailed ADR acceptance criteria,
DOCUMENTATION_AUDIT.md content, and the authority and termination rules in
INCIDENT_RUNBOOK.md and TRACEABILITY.md, including continuation/reconciliation
invariants. Alternatively, reduce the documented scope to the checks actually
implemented, but ensure README’s stated contract and the test coverage remain
consistent.
Source: Path instructions
| Termination requires a double exit sweep: | ||
|
|
||
| 1. the first fresh queue-wide sweep must find no execute-now item; if it finds one, execute the highest-value safe item and restart continuation selection; | ||
| 2. a second fresh queue-wide sweep after the final substantive action must also find no execute-now item, unless the practical invocation/tool budget is exhausted. | ||
|
|
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
첫 번째 종료 스윕의 예산 소진 규칙이 없습니다.
두 문서 모두 첫 번째 sweep에서 작업을 발견하면 실행을 강제하지만, 예산 소진 예외는 두 번째 sweep에만 둡니다. 첫 번째 작업 실행 전에 예산이 소진되면 정상 종료와 강제 종료를 구분할 수 없습니다.
docs/automation/TRD.md#L51-L55: 두 sweep 모두에budget_exhausted종료 사유와 증거 기록을 정의하거나 종료 스윕용 실행 예산을 예약하십시오.docs/automation/adr/0003-work-conserving-execution.md#L17-L19: TRD의 동일한 예산 소진 규칙을 반영하고 회귀 테스트를 추가하십시오.
📍 Affects 2 files
docs/automation/TRD.md#L51-L55(this comment)docs/automation/adr/0003-work-conserving-execution.md#L17-L19
🤖 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/automation/TRD.md` around lines 51 - 55, Define a consistent
budget-exhaustion rule for both termination sweeps: if the budget is exhausted
before the first sweep’s required action, terminate with reason budget_exhausted
and record evidence instead of forcing execution; apply the same rule after the
final substantive action for the second sweep. Update docs/automation/TRD.md
(lines 51-55) and docs/automation/adr/0003-work-conserving-execution.md (lines
17-19) to match, and add regression coverage for exhaustion at each sweep.
Source: Path instructions
| Execute --> RefetchAffectedState: action, merge, RCA, doc or prompt mutation | ||
| RefetchAffectedState --> Execute: another safe lane exists | ||
| RefetchAffectedState --> ExitSweepOne: no execute-now lane observed | ||
| ExitSweepOne --> Execute: first sweep finds work | ||
| ExitSweepOne --> ExitSweepTwo: first sweep finds none | ||
| ExitSweepTwo --> Execute: second sweep finds work | ||
| ExitSweepTwo --> BoundedTermination: second sweep finds none |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
review request와 defer decision의 재선택 경로를 상태 머신에 명시해야 합니다.
현재 전이 설명은 action, merge, RCA, 문서 변경, prompt 변경만 열거합니다. 그러나 OPERABILITY.md Line 11과 이 문서 Line 65는 review request와 defer decision도 queue reselection과 continuation_handoff를 요구합니다. 이 항목을 누락하면 해당 동작 뒤에 조기 종료가 허용되는 것으로 해석될 수 있습니다.
수정 예시
- Execute --> RefetchAffectedState: action, merge, RCA, doc or prompt mutation
+ Execute --> RefetchAffectedState: action, merge, RCA, review request, defer decision, documentation/prompt/status mutation📝 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.
| Execute --> RefetchAffectedState: action, merge, RCA, doc or prompt mutation | |
| RefetchAffectedState --> Execute: another safe lane exists | |
| RefetchAffectedState --> ExitSweepOne: no execute-now lane observed | |
| ExitSweepOne --> Execute: first sweep finds work | |
| ExitSweepOne --> ExitSweepTwo: first sweep finds none | |
| ExitSweepTwo --> Execute: second sweep finds work | |
| ExitSweepTwo --> BoundedTermination: second sweep finds none | |
| Execute --> RefetchAffectedState: action, merge, RCA, review request, defer decision, documentation/prompt/status mutation | |
| RefetchAffectedState --> Execute: another safe lane exists | |
| RefetchAffectedState --> ExitSweepOne: no execute-now lane observed | |
| ExitSweepOne --> Execute: first sweep finds work | |
| ExitSweepOne --> ExitSweepTwo: first sweep finds none | |
| ExitSweepTwo --> Execute: second sweep finds work | |
| ExitSweepTwo --> BoundedTermination: second sweep finds none |
🤖 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/automation/UML.md` around lines 55 - 61, Update the
Execute-to-RefetchAffectedState transition description in the state-machine
diagram to also include review request and defer decision mutations, preserving
the existing action, merge, RCA, documentation, and prompt entries. Ensure the
diagram explicitly represents that these operations require queue reselection
and continuation_handoff rather than allowing early termination.
|
The unique durable contracts from this line have now been reconciled into broader canonical candidate #896: whole-conversation candidate-evidence discipline; the exact seven-state maturity vocabulary; same-invocation continuation; prompt/document/status/review/dispatch/Draft/Ready/auto-merge/commit/merge as intermediate events; explicit no-soft-timeout semantics and double fresh exit sweep; central-versus-leaf product ownership; Close this PR as superseded historical design evidence rather than merging two competing canonical document graphs. If a later exact comparison finds a unique accepted #886 contract absent from #896, restore that contract on #896 or reopen this line; do not merge both. |
1 participant
Purpose
Establish the canonical automation/control-plane documentation graph that was previously scattered across workflows, incident notes, pull-request bodies, automation prompts, downloadable planning artifacts, and conversation history.
Completed scope
automation_control_record,execution_lane,deferred_item,continuation_handoff, documentation baselines/fitness results, and evidence authorities without claiming a persistence implementation;Conversation-to-repository discipline
The graph distinguishes
implemented_on_protected_main,active_pr,accepted_architecture,planned,research_only,superseded, andout_of_scope. Conversation history, automation prompts, PR bodies, and planning artifacts are candidate evidence only. Durable shared automation decisions are reconciled into this canonical GitHub line after live implementation/ownership is refetched; product-specific PRD/TRD/ADR/UML/ERD remain in the owning leaf repositories rather than being duplicated centrally.Exact current identity
Current head:
b099d5fa86534e0320512b854f259856a8413bc0.The prior successful documentation run on predecessor head
6671dc90963beebcd7d49339719826d806d73e69is historical only. The current exact-head Automation Documentation Quality, Strix, security, CodeQL, Semgrep, Secret Scan, OSV, Scorecard, and SBOM runs have been regenerated and are queued/pending as of the latest observation; none is represented as success until it completes on this unchanged head.Current formal reviews and inline review threads are absent, so a qualifying independent non-author approval and fresh current-head automated review remain required.
No runtime claim
This PR changes documentation and documentation fitness contracts. It does not change GitHub workflow runtime behavior, reviewer identity, credential scope, branch protection, or merge authority. The separately updated external scheduled writer prompt is control-plane configuration evidence, not a protected-main GitHub implementation claim.
Merge gate
Merge only after every required exact-head documentation/security/supply-chain check succeeds, current automated review is complete, zero valid unresolved findings remain, a qualifying independent non-author formal approval exists, and repository protection accepts the unchanged head without bypass. After protected integration, premature-termination behavior still requires runtime acceptance evidence before the operational incident is considered closed.
Summary by CodeRabbit
새 기능
문서
테스트
품질 개선