docs: establish authoritative automation control-plane specifications - #896
docs: establish authoritative automation control-plane specifications#896seonghobae wants to merge 55 commits into
Conversation
|
Warning Review limit reached
Next review available in: 5 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (55)
✨ 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 |
|
Canonical-documentation consolidation review on exact head Required delta on this existing branch, after refetching both live heads:
After those are exact-head green, request current automated review. Do not merge both #886 and #896; preserve one canonical history and close the other only after verifying no unique accepted decision was dropped. |
|
@coderabbitai review @cwl-noema-review @opencode-agent Review only exact current head |
|
I will evaluate the requested documentation graph and its machine contracts as
|
|
@coderabbitai review @cwl-noema-review @opencode-agent Review only exact current head |
|
I will evaluate the documentation graph as
|
|
@coderabbitai review @cwl-noema-review @opencode-agent Review only exact current head |
Rate Limit Exceeded
|
|
@coderabbitai review Review only exact current head |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
expected_head="aed69a1f2051ae10fde3e39cf7a1957d94233676"
printf '%s\n' '== Checked-out commit =='
git rev-parse HEAD
git status --short
printf '%s\n' '== Commit match =='
test "$(git rev-parse HEAD)" = "$expected_head" && echo "MATCH" || echo "MISMATCH"
printf '%s\n' '== PR metadata =='
gh pr view 896 --repo ContextualWisdomLab/.github \
--json number,state,baseRefName,headRefOid,mergeable,reviewDecision,statusCheckRollup \
--jq '{number,state,baseRefName,headRefOid,mergeable,reviewDecision,statusCheckRollup}'
printf '%s\n' '== Exact-head check runs =='
gh api "repos/ContextualWisdomLab/.github/commits/${expected_head}/check-runs?per_page=100" \
--jq '.check_runs[] | [.name,.status,.conclusion,.details_url] | `@tsv`' || true
printf '%s\n' '== Exact-head legacy statuses =='
gh api "repos/ContextualWisdomLab/.github/commits/${expected_head}/status" \
--jq '.statuses[]? | [.context,.state,.target_url] | `@tsv`' || true
printf '%s\n' '== Changed files =='
gh pr view 896 --repo ContextualWisdomLab/.github --json files \
--jq '.files[].path'
printf '%s\n' '== Candidate canonical documents, tests, and workflows =='
fd -t f . docs .github tests 2>/dev/null \
| rg -i '(README|PRD|TRD|ARCHITECTURE|UML|ERD|DATA.MODEL|SECURITY|THREAT|TRACEABILITY|OPERAB|RUNBOOK|CONTINUATION|ADR|CONTRACT|DOCTOR|DOCUMENT|QUALITY|WORKFLOW)' \
| sort
printf '%s\n' '== Relevant authoritative-document evidence =='
rg -n -i -C 2 \
'implemented_on_protected_main|active_pr|accepted_architecture|research_only|out_of_scope|remediation_candidate|continuation_handoff|documentation_artifact|traceability_record|double.fresh|double.exit|no.soft.timeout|source_revision|live.base|merge_revision|FigJam|ISO/IEC/IEEE 29148:2018|ISO/IEC 25010:2023|SLSA 1\.2|SSDF' \
docs .github tests 2>/dev/null || true
printf '%s\n' '== Documentation CI and coverage workflow evidence =='
rg -n -i -C 3 \
'Automation Documentation Quality CI|100%|coverage|checkout|github\.sha|event.*sha|documentation' \
.github/workflows 2>/dev/null || trueLength of output: 202554 🏁 Script executed: #!/bin/bash
set -euo pipefail
head_sha="aed69a1f2051ae10fde3e39cf7a1957d94233676"
echo "== Exact commit identity =="
printf 'checked_out='
git rev-parse HEAD
printf 'expected=%s\n' "$head_sha"
printf 'match='
if test "$(git rev-parse HEAD)" = "$head_sha"; then echo yes; else echo no; fi
echo "== Pull request state =="
gh pr view 896 --repo ContextualWisdomLab/.github \
--json state,headRefOid,baseRefOid,mergeable,reviewDecision \
--jq '{state,headRefOid,baseRefOid,mergeable,reviewDecision}'
echo "== Exact-head checks: non-success states =="
gh api "repos/ContextualWisdomLab/.github/commits/${head_sha}/check-runs?per_page=100" \
--jq '[.check_runs[] | select(.status != "completed" or (.conclusion != "success" and .conclusion != "neutral" and .conclusion != "skipped")) | {name,status,conclusion,details_url}]'
echo "== Exact-head checks: counts by conclusion =="
gh api "repos/ContextualWisdomLab/.github/commits/${head_sha}/check-runs?per_page=100" \
--jq '[.check_runs[].conclusion] | sort | group_by(.) | map({conclusion: .[0], count: length})'
echo "== Exact-head legacy-status failures =="
gh api "repos/ContextualWisdomLab/.github/commits/${head_sha}/status" \
--jq '[.statuses[]? | select(.state != "success") | {context,state,target_url}]'
echo "== Canonical documentation candidates =="
fd -t f -i 'README.md' docs 2>/dev/null | sort
fd -t f . docs 2>/dev/null \
| rg -i '/(prd|trd|architecture|uml|erd|data.model|security|threat|traceability|operability|runbook|continuation|adr|audit|standards)' \
| sort
echo "== Documentation contract test candidates =="
fd -t f . tests 2>/dev/null | rg -i '(document|documentation|contract|doctor)' | sort
echo "== Canonical document headings =="
for f in $(fd -t f -e md docs 2>/dev/null | rg -i '/(prd|trd|architecture|uml|erd|data.model|security|threat|traceability|operability|runbook|continuation|audit|standards|adr-0007)' | sort); do
echo "--- $f"
rg -n '^#{1,3} ' "$f" | head -n 50
done
echo "== Requested contract terms in documentation and tests =="
rg -l -i \
'implemented_on_protected_main|remediation_candidate|continuation_handoff|documentation_artifact|traceability_record|no.soft.timeout|double.*(exit|sweep)|source_revision|merge_revision|ISO/IEC/IEEE 29148:2018|ISO/IEC 25010:2023' \
docs tests 2>/dev/null | sort | while read -r f; do
echo "--- $f"
rg -n -i \
'implemented_on_protected_main|active_pr|accepted_architecture|planned|research_only|superseded|out_of_scope|remediation_candidate|continuation_handoff|documentation_artifact|traceability_record|no.soft.timeout|double.*(exit|sweep)|source_revision|live.base|merge_revision|ISO/IEC/IEEE 29148:2018|ISO/IEC 25010:2023' \
"$f" | head -n 80
doneLength of output: 53603 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== Documentation quality workflow candidates =="
fd -t f -e yml -e yaml .github/workflows | while read -r f; do
if rg -q -i 'automation documentation quality|test_automation_documentation_contract|documentation.*contract|full repository suite|coverage.*100|fail-under=100' "$f"; then
echo "$f"
fi
done
echo "== Documentation quality workflow focused content =="
fd -t f -e yml -e yaml .github/workflows | while read -r f; do
if rg -q -i 'automation documentation quality|test_automation_documentation_contract|documentation.*contract' "$f"; then
echo "--- $f"
rg -n -i -C 3 \
'name:|pull_request:|paths:|checkout|head\.sha|github\.sha|pytest|test_automation_documentation_contract|coverage|fail-under' \
"$f"
fi
done
echo "== Focused documentation contract assertions =="
sed -n '1,360p' tests/test_automation_documentation_contract.py
echo "== Static Markdown link and fence validation under docs/automation =="
python3 - <<'PY'
from pathlib import Path
import re
root = Path.cwd()
docs = root / "docs" / "automation"
errors = []
for path in sorted(docs.rglob("*.md")):
text = path.read_text(encoding="utf-8")
if text.count("```") % 2:
errors.append(f"unbalanced fence: {path.relative_to(root)}")
for raw in re.findall(r'(?<!!)\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)', text):
target = raw.split("#", 1)[0]
if not target or "://" in target or target.startswith("mailto:") or target.startswith("#"):
continue
candidate = (path.parent / target).resolve()
if not candidate.exists():
errors.append(f"missing link target: {path.relative_to(root)} -> {raw}")
if errors:
print("\n".join(errors))
raise SystemExit(1)
print("PASS: Markdown fences are balanced and local relative link targets exist.")
PY
echo "== Exact-head check state, refreshed =="
head_sha="aed69a1f2051ae10fde3e39cf7a1957d94233676"
gh api "repos/ContextualWisdomLab/.github/commits/${head_sha}/check-runs?per_page=100" \
--jq '[.check_runs[] | select(.status != "completed" or (.conclusion != "success" and .conclusion != "neutral" and .conclusion != "skipped")) | {name,status,conclusion,details_url}]'Length of output: 2956 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== Documentation quality workflow candidates =="
fd -t f -e yml -e yaml . .github/workflows | while read -r f; do
if rg -q -i 'automation documentation quality|test_automation_documentation_contract|documentation.*contract|full repository suite|coverage.*100|fail-under=100' "$f"; then
echo "$f"
fi
done
echo "== Documentation quality workflow focused content =="
fd -t f -e yml -e yaml . .github/workflows | while read -r f; do
if rg -q -i 'automation documentation quality|test_automation_documentation_contract|documentation.*contract' "$f"; then
echo "--- $f"
rg -n -i -C 3 \
'name:|pull_request:|paths:|checkout|head\.sha|github\.sha|pytest|test_automation_documentation_contract|coverage|fail-under' \
"$f"
fi
done
echo "== Focused documentation contract assertions =="
sed -n '1,360p' tests/test_automation_documentation_contract.py
echo "== Static Markdown link and fence validation under docs/automation =="
python3 - <<'PY'
from pathlib import Path
import re
root = Path.cwd()
docs = root / "docs" / "automation"
errors = []
for path in sorted(docs.rglob("*.md")):
text = path.read_text(encoding="utf-8")
if text.count("```") % 2:
errors.append(f"unbalanced fence: {path.relative_to(root)}")
for raw in re.findall(r'(?<!!)\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)', text):
target = raw.split("#", 1)[0]
if not target or "://" in target or target.startswith("mailto:") or target.startswith("#"):
continue
candidate = (path.parent / target).resolve()
if not candidate.exists():
errors.append(f"missing link target: {path.relative_to(root)} -> {raw}")
if errors:
print("\n".join(errors))
raise SystemExit(1)
print("PASS: Markdown fences are balanced and local relative link targets exist.")
PY
echo "== Exact-head check state, refreshed =="
head_sha="aed69a1f2051ae10fde3e39cf7a1957d94233676"
gh api "repos/ContextualWisdomLab/.github/commits/${head_sha}/check-runs?per_page=100" \
--jq '[.check_runs[] | select(.status != "completed" or (.conclusion != "success" and .conclusion != "neutral" and .conclusion != "skipped")) | {name,status,conclusion,details_url}]'Length of output: 130806
I found no source-backed actionable defect in the reviewed documentation graph. The checked-out commit matches the PR head. The documentation index, controlled maturity states, central-versus-leaf ownership audit, revision and evidence authority model, continuation contract, conceptual ERD entities, ADR set, standards baseline, and documentation contract tests are present. Local Markdown fences are balanced. Local relative links resolve.
Current acceptance evidence is incomplete. The exact-head You are interacting with an AI system. |
|
Exact-head documentation review requested: This head preserves the already-audited documentation baseline and updates only the redaction lineage/contract: #888 is closed-unmerged @cwl-noema-review @opencode-agent Please review this exact head. Its 11 Actions workflows are currently queued/in progress, so predecessor success and pending checks are not acceptance. A model comment/check/status is also not a qualifying independent formal approval. |
|
Exact-head documentation review requested: The continuation handoff sink/acknowledgement contract is aligned across the enabled hourly automation prompt, Automation Documentation Quality CI run 31321656195 checked out this exact head and completed successfully: @cwl-noema-review @opencode-agent Please review only this exact current head. Do not carry forward predecessor-head evidence, mutate the branch, merge, retarget, or change rulesets. A current automated source review and a qualifying independent non-author formal approval remain separate required authorities. |
1 participant
Outcome
The prior documentation was not sufficient as a durable automation-control-plane baseline: product requirements, technical interfaces, authority boundaries, logical evidence relationships, operations, security, standards, whole-conversation ownership, and decisions were fragmented across workflow prose, dated rollout ledgers, PR bodies, incident notes, prompts, and planning material.
This PR establishes one authoritative, indexed documentation graph and converts remaining runtime/product drift into explicit traceability debt rather than leaving documentation-family gaps implicit.
Scope
direct_or_auto, and fail-closed gate composition;source_revisionseparated from PR-base snapshot, independently resolved live-base identity, and protectedmerge_revision; operational acceptance attaches only to the integrated revision;remediation_candidate,continuation_handoff,documentation_artifact, andtraceability_record;cwl.automation-continuation/v1handoff receipt, and double-fresh-exit semantics;implemented_on_protected_main,active_pr,accepted_architecture,planned,research_only,superseded,out_of_scope;docs/doctoring/README.mdreference authority plus current standards doctoring, including SLSA 1.2, ISO/IEC/IEEE 42010:2022, current final ISO/IEC/IEEE 29148:2018 versus Edition 3 DIS as informative draft, ISO/IEC 25010:2023, final NIST SSDF 1.1 versus the v1.2 initial public draft, ISO/IEC 27001/27002/42001, GitHub secure-use/OIDC, OpenTelemetry, SOC 2 evidence boundaries and conditional CSAP readiness;Automation Documentation Quality CIon documentation/workflow/source/test changes, checking out the exact event revision and running the full repository suite with a 100% coverage gate;Exact current integration identity
main;6eb06cdd08c79a06f7b390069d4ffa49e2eb7dba(historical provenance only; merge decisions must resolve the live base tip independently);8344fe42514457143b93ee2ef9cf19d00dec7b33;Documentation-fitness judgment
For the central automation/control-plane scope, every required documentation family is classified
ADEQUATEon thisactive_prbaseline: PRD, TRD/event contracts, Architecture, UML, conceptual ERD/Data Model, Security/Threat Model, Test Strategy, Operability/Runbooks, ADR set, Traceability, and current standards/doctoring authority.That judgment is narrower than “the software is complete.”
ADEQUATEmeans the intended central contract is represented coherently enough for review and machine fitness checks; implementation/runtime gaps retain their own maturity state and evidence requirements. Product PRDs and domain models remain leaf-owned rather than duplicated centrally.The whole-conversation audit treats conversation/planning material as candidate evidence until revalidated. ADR-0007,
AUTONOMY_THREATS.md,CONTINUATION_RUNBOOK.md, and the hourly automation prompt make prompt/docs/status/review/dispatch/Draft/Ready/auto-merge/commit/merge intermediate events, treat waits as local, and require a second fresh all-lanes-nonactionable sweep rather than a soft elapsed-time stop.This PR is still
active_pr, notimplemented_on_protected_main.Verification boundary
Exact-head Automation Documentation Quality CI run 31321656195 checked out
8344fe42514457143b93ee2ef9cf19d00dec7b33and completed successfully:1000 passed, 16 subtests passed;6978/6978statements and2790/2790branches at 100%; test compilation also succeeded. All 11 exact-head pull-request workflows succeeded. Predecessor-head, skipped, or unrelated evidence is non-authorizing, and current automated source review plus a qualifying independent non-author formal approval remain separate required authorities.CodeRabbit's predecessor-head source analysis found no source-backed actionable documentation defect at
aed69a1f2051ae10fde3e39cf7a1957d94233676. It is now historical and was a conversation comment, not a formal approval. Current-head automated review and a qualifying independent non-author formal approval remain separate authorities.Require current automated review, zero valid unresolved findings, a qualifying independent non-author formal approval, and branch protection before merge. After protected merge, refetch the canonical index from protected
mainbefore changing the baseline maturity toimplemented_on_protected_main.Remaining explicit product/control-plane debt (not documentation-family omissions)
IG-001throughIG-008remainsactive_prorplannedand is linked to PR fix(actions): bound agent mention dispatch envelope #840 and Issues [Governance] Establish a counted independent-review path for protected CWL pull requests #772/[Governance] Align external-head review policy with executable dispatch behavior #889–[Reliability] Propagate scheduler mutation failures to a non-passing workflow result #894; documentation cannot promote those objects to protected-main implementation;supersededincident evidence after reachable-history re-contamination; Draft successor fix(sandbox): replay redaction after fixture-history contamination #906 is the currentactive_pr, with wrapper recursion tracked by Redact bounded env/shell wrapper command operands #907 and atomic multiline/duplicate-key JSON redaction tracked by Redact multiline and duplicate-key JSON atomically #908, and remains non-merge-ready until its documented source, security, review, approval, and protection gates pass;deploy-pages.ymlinherited-secret usage is being repaired independently in security(deploy-pages): declare minimal secret contract #901; GitHub still permits callers to choosesecrets: inherit, so CWL policy must prohibit inherited callers and keep approved callers on explicit mappings;Risk and rollback
This PR changes documentation, documentation contract tests, and stale workflow comments; it does not intentionally change workflow execution logic, permissions, rulesets, reviewer authority, or product data. Rollback is a normal protected revert. Runtime changes described as
active_pr,accepted_architecture,planned, or otherwise non-implemented are not shipped claims until traceability and protected-main evidence exist.