feat: mine reusable AeroSim channel lessons
This commit is contained in:
@@ -0,0 +1,150 @@
|
||||
# Data-backed Scope integrity and bounded review
|
||||
|
||||
Use this checklist when unified delivery status, required-child roll-up, readiness, questions, or approval gates move into canonical YAML and generated Docusaurus components.
|
||||
|
||||
## Canonical-state rules
|
||||
|
||||
- Keep approval gates, unified delivery status, status source, required-child relationships, question dependencies, aliases, and readiness inputs in canonical data. Render mutable current-state claims from selectors/components rather than duplicating them in prose.
|
||||
- Historical prose may retain old IDs or states only when it is explicitly date/evidence bounded and labels old IDs as aliases. Canonical aliases must be unique and non-reusable.
|
||||
- Validate bidirectional relationships, including Epic↔question and Feature↔question links. Reject dangling IDs, one-sided links, self-dependencies, dependency cycles, and empty solution-artifact allocations.
|
||||
- Approval readiness is gate- and delivery-aware. Absence of open questions alone must not label cancelled, already approved, or actively delivered records as awaiting the wrong review.
|
||||
- Validate exact Task states against the Task enum and derive Idea/Epic/Feature states only from complete required-child sets. Reject ancestor/descendant double counting, missing required children, invalid status sources, a premature parent `TO_BE_RELEASED`/`DONE`, and cancelled children treated as complete.
|
||||
|
||||
## Human-decision integrity
|
||||
|
||||
A data record is not authorization merely because it contains approval-shaped fields.
|
||||
|
||||
- Require a stable human actor identifier from an allowlisted identity provider, UTC decision date, exact item ID, exact resulting state, explicit conditions, and durable source evidence.
|
||||
- Require conditional approval to carry every still-open question ID or an equivalent explicit condition. Architecture must preserve these as unresolved risks.
|
||||
- Evidence links must use safe, reviewable schemes (normally HTTPS). Plain identifiers may be displayed as text but must not become arbitrary clickable URIs.
|
||||
- Approval evidence and the corresponding approval event must agree on actor, authority, item, gate decision, date, conditions, and evidence.
|
||||
- Rejected and deferred approval decisions also need authorized evidence. Questions changed to Answered need the answer plus actor/date/evidence; deferred questions need decision evidence.
|
||||
- Preserve approval and exact delivery provenance as append-only events. Validate event identity, sequence/continuity, current-state agreement, and tamper-evident linkage or a checked repository baseline. Never initialize empty history by deleting existing provenance.
|
||||
- Architecture-facing components must consume the same verified-approval predicate or derived field that validation uses; do not reimplement the gate as `status && approval`.
|
||||
|
||||
## Selector parity for approval/delivery evidence and routes
|
||||
|
||||
Generated Roadmap and current-scope selectors must fail closed with the same semantics as canonical validation:
|
||||
|
||||
- Select the final append-only `decision_history` event (`at(-1)`), not the event with the greatest timestamp. History order is authoritative; validators may not require timestamps to be monotonic.
|
||||
- Call a decision **evidenced** only when that final event has both a valid canonical UTC date and at least one durable, renderable evidence URL. A non-empty evidence array or a plain evidence identifier is not enough.
|
||||
- Reuse or exactly mirror the canonical source-specific URL contract: parse with `URL`, require HTTPS, reject embedded credentials, and enforce the evidence-kind host allowlist. Do not test only for an `https://` prefix.
|
||||
- Validate calendar reality as well as timestamp syntax. JavaScript `Date.parse` normalizes impossible dates such as February 30; compare parsed UTC components back to the captured input components before accepting a timestamp.
|
||||
- Keep route identity canonical. Store an explicit `documentation_url` on each Epic and Feature, validate its exact stable-ID/parent-derived form, and verify that the corresponding source page exists. Selectors should consume that field rather than inventing a route for any record-shaped object.
|
||||
- Add RED-first tests for append-order versus timestamp-order, offset timestamps, impossible dates, evidence objects without URLs, source/host mismatches, credential-bearing URLs, unsafe hosts, missing documentation URLs, wrong parent paths, and absent source pages.
|
||||
|
||||
This parity prevents a validated data model from being weakened by a more permissive presentation selector and prevents generated runtime links from bypassing static broken-link checks.
|
||||
|
||||
## Reproducible acceptance-evidence packet consistency
|
||||
|
||||
When operational evidence is too coarse for outcome-level acceptance classification, keep the packet contract internally executable rather than merely descriptive:
|
||||
|
||||
- Every item declared mandatory in the prose must have its own explicit template field. In particular, record the application deployment origin URL separately from the route and scenario/preset; a route alone cannot reproduce which deployment was observed.
|
||||
- Bind the packet to two distinct immutable revisions: the canonical Scope-document revision that defines the ordered outcome set, and the tested application build/source revision. Never substitute one for the other.
|
||||
- If canonical `acceptance_outcomes` are ordered strings without stable outcome IDs, use an immutable revision-scoped ordinal reference such as `<FEATURE-ID>@<FULL-SCOPE-COMMIT>#AO-<N>`, where `N` is the one-based position in that Feature record's ordered outcome list at that exact commit. Reject an ordinal without the full Scope revision.
|
||||
- Require exactly one classification row for every canonical outcome at the recorded Scope revision. Mark coverage `complete` only when every mandatory packet field and every outcome row is present; otherwise keep it `partial` and incomplete.
|
||||
- Add durable validation markers or structural checks for newly cited evidence IDs and for the packet's reference scheme so later edits cannot silently remove the provenance or make the template unresolvable.
|
||||
- Review the required-field prose against the actual table as a pair. A full documentation build can pass while the governance contract remains impossible to complete.
|
||||
|
||||
## Review ordering under bounded execution
|
||||
|
||||
1. Make the smallest behavior-preserving migration.
|
||||
2. Run the full validation/build once.
|
||||
3. Stage or freeze the complete diff and dispatch an independent fail-closed review immediately—before optional polish or broadening.
|
||||
4. Apply only named blockers. Do not add unrelated schema hardening during a fix cycle.
|
||||
5. Re-run the full suite, then obtain a fresh independent verdict over the complete final diff.
|
||||
6. Only after a passing verdict proceed to commit, push, exact-head CI, and remote readback.
|
||||
|
||||
Never edit files concurrently with a reviewer or fixer that can write to the same worktree. Wait for the agent to exit, inspect its complete diff, remove temporary migration/patch artifacts, and then continue. A background process still running at the end of the execution window means the work is incomplete: do not commit, push, or report completion.
|
||||
|
||||
### When independent review cannot run
|
||||
|
||||
Reviewer unavailability is not a passing verdict. Do not replace the independent review with self-review, tests, an earlier review, or successful CI from the previous remote head.
|
||||
|
||||
Before deferring publication, try the documented isolated Hermes fallback when the main `hermes` CLI is available and authenticated. Build the prompt from the frozen complete diff in memory, pass it as a subprocess argument rather than shell-interpolating it, disable general tools with `--toolsets safe`, and require a machine-checkable final verdict:
|
||||
|
||||
```python
|
||||
import os
|
||||
import subprocess
|
||||
|
||||
repo = "/absolute/path/to/repository"
|
||||
base_ref = os.environ["REVIEW_BASE"] # verified immutable SHA or intended remote base
|
||||
base = subprocess.run(
|
||||
["git", "-C", repo, "rev-parse", "--verify", base_ref + "^{commit}"],
|
||||
check=True,
|
||||
text=True,
|
||||
capture_output=True,
|
||||
).stdout.strip()
|
||||
|
||||
# Diffing the complete working tree against the declared base includes committed
|
||||
# branch changes plus staged and unstaged tracked changes.
|
||||
diff = subprocess.run(
|
||||
["git", "-C", repo, "diff", "--binary", base, "--", "."],
|
||||
check=True,
|
||||
text=True,
|
||||
capture_output=True,
|
||||
).stdout
|
||||
|
||||
# Untracked non-ignored files are not included by git diff; append each as a
|
||||
# /dev/null patch and fail closed on any unexpected return code.
|
||||
untracked_raw = subprocess.run(
|
||||
["git", "-C", repo, "ls-files", "-z", "--others", "--exclude-standard"],
|
||||
check=True,
|
||||
capture_output=True,
|
||||
).stdout
|
||||
untracked = [p.decode("utf-8") for p in untracked_raw.split(b"\0") if p]
|
||||
for path in untracked:
|
||||
patch = subprocess.run(
|
||||
["git", "-C", repo, "diff", "--no-index", "--binary", "--", "/dev/null", path],
|
||||
text=True,
|
||||
capture_output=True,
|
||||
)
|
||||
if patch.returncode != 1:
|
||||
raise RuntimeError(f"could not encode untracked path {path!r}: {patch.stderr}")
|
||||
diff += patch.stdout
|
||||
|
||||
inventory = subprocess.run(
|
||||
["git", "-C", repo, "status", "--short", "--untracked-files=all"],
|
||||
check=True,
|
||||
text=True,
|
||||
capture_output=True,
|
||||
).stdout
|
||||
if not diff.strip() or not inventory.strip():
|
||||
raise RuntimeError("review patch or changed-path inventory is empty")
|
||||
|
||||
prompt = f"""You are an independent fail-closed reviewer.
|
||||
Review only the complete frozen patch and path inventory below at base {base}.
|
||||
Do not use tools. Do not write files.
|
||||
Return exactly PASS or BLOCK followed by actionable findings.
|
||||
Fail closed if any listed path is absent from the patch or the patch cannot be reviewed.
|
||||
|
||||
CHANGED-PATH INVENTORY:
|
||||
{inventory}
|
||||
|
||||
FROZEN COMPLETE DIFF:
|
||||
{diff}"""
|
||||
result = subprocess.run(
|
||||
["hermes", "chat", "-Q", "--toolsets", "safe", "-q", prompt],
|
||||
cwd=repo,
|
||||
text=True,
|
||||
capture_output=True,
|
||||
timeout=540,
|
||||
)
|
||||
```
|
||||
|
||||
Treat nonzero exit, timeout, empty stdout, or anything other than an exact `PASS` or actionable `BLOCK` verdict as review failure. A `BLOCK` verdict starts a bounded fix cycle: apply only its named blockers, rerun the complete suite, freeze the new complete diff, and invoke a fresh reviewer session. Never reuse the first review after changing the patch. Do not include credentials, environment output, generated build trees, or unrelated worktree changes in the embedded prompt.
|
||||
|
||||
If the fallback also cannot produce a valid verdict:
|
||||
|
||||
1. Stop broadening the change after the first clean full suite.
|
||||
2. Confirm no reviewer/fixer process remains active and run `git diff --check`.
|
||||
3. Record the complete local diff hash (for example, `git diff | sha256sum`), modified-file inventory, and validation results so a later run can prove it is reviewing the same frozen patch.
|
||||
4. Re-read the authoritative PR and exact-head CI separately. State explicitly that those remote results cover only the already-pushed head, not the unpublished local patch.
|
||||
5. Leave the local patch uncommitted and unpushed. Report the review gate as the publication blocker, not as a repository or CI failure.
|
||||
6. On the next run, fetch and compare remote state before resuming. If the frozen diff or remote base changed, rerun the complete suite and require a fresh review of the new complete diff.
|
||||
|
||||
This preserves useful work without turning a transient reviewer setup problem into false publication evidence.
|
||||
|
||||
## Dependency audit
|
||||
|
||||
For Docusaurus migrations that add visualization or parsing dependencies, run the production dependency audit before final review. Remediate actionable high-severity findings with a narrow supported upgrade or package-manager override, and rerun build/tests. Do not hand-edit installed `node_modules` as the durable fix.
|
||||
Reference in New Issue
Block a user