|
| 1 | +# html4tree hourly review-repair caller |
| 2 | + |
| 3 | +검토 기준일: **2026-08-17** |
| 4 | + |
| 5 | +## Decision |
| 6 | + |
| 7 | +ContextualWisdomLab operates one protected hourly caller for |
| 8 | +`ContextualWisdomLab/html4tree` (standalone MIT directory-index generator |
| 9 | +that writes `index.html` trees in the style of Apache `mod_autoindex`). |
| 10 | +The caller runs at minute 15, delegates to the product-neutral central |
| 11 | +review-fix scheduler, inspects at most 50 open pull requests targeting |
| 12 | +protected `master`, and dispatches at most one bounded repair per |
| 13 | +heartbeat. |
| 14 | + |
| 15 | +A paying buyer of governed directory listings would feel live html4tree |
| 16 | +pull requests stalling while hourly NVIDIA NIM repair scanned only |
| 17 | +Clearfolio, DiskSage, and fast-mlsirm. Live heads such as |
| 18 | +ContextualWisdomLab/html4tree#475 (localized navigation labels), |
| 19 | +ContextualWisdomLab/html4tree#472 (TOCTOU on `.html4ignore`), and |
| 20 | +ContextualWisdomLab/html4tree#454 (BiDi spoof / Trojan Source) target |
| 21 | +`master` and never enter those other callers. |
| 22 | + |
| 23 | +html4tree is a public fork of `yencarnacion/html4tree`. Fork status is |
| 24 | +not a categorical exclusion: onboarding is an explicit repository |
| 25 | +decision, and pull-request mutation remains capability-gated per head. |
| 26 | +The caller does not implement review or mutation logic itself. |
| 27 | +html4tree remains standalone; naruon and other CWL services may consume |
| 28 | +generated indexes without owning the crawler. Privileged automation |
| 29 | +stays in `ContextualWisdomLab/.github`. |
| 30 | + |
| 31 | +## Root-cause analysis and remediation feasibility |
| 32 | + |
| 33 | +The reusable worker performs exact-head root-cause analysis and tests |
| 34 | +remediation feasibility before it edits. The reusable worker must: |
| 35 | + |
| 36 | +1. Refetch the exact live head, base, reviews, checks, changed paths, and |
| 37 | + writer state. |
| 38 | +2. Establish the causal chain rather than repeat the terminal symptom. |
| 39 | +3. Enumerate materially distinct minimal remedies. |
| 40 | +4. Reject remedies that lack writer authority, cross sealed paths, require |
| 41 | + unavailable credentials or protected-setting changes, violate stack |
| 42 | + order, cannot be verified, or do not alter the diagnosed cause. |
| 43 | +5. Dispatch at most one feasible repair. Otherwise leave the tree |
| 44 | + unchanged. |
| 45 | + |
| 46 | +A queued or pending check remains a merge blocker but is not itself a |
| 47 | +code finding. The independent non-author approval remains an external |
| 48 | +authorization gate and is never synthesized by the repair worker. The |
| 49 | +worker cannot approve, merge, release, resolve review findings by |
| 50 | +inference, change protection, or manufacture passing checks. |
| 51 | + |
| 52 | +## Cadence and concurrency |
| 53 | + |
| 54 | +The caller uses a single concurrency group and `cancel-in-progress: false`. |
| 55 | +This preserves an in-flight bounded RCA instead of discarding directory- |
| 56 | +listing evidence when the next hourly heartbeat arrives. The reusable |
| 57 | +scheduler cancels only its own superseded short queue scan. |
| 58 | + |
| 59 | +The caller sets a **two-hour same-head retry floor**. Central OpenCode and |
| 60 | +NVIDIA NIM work, plus BiDi or TOCTOU analysis, can legitimately approach |
| 61 | +two hours. An hourly redispatch of the same unchanged head would create |
| 62 | +duplicate writer pressure rather than faster remediation. |
| 63 | + |
| 64 | +GitHub scheduled workflows can be delayed under load and execute only |
| 65 | +from the default branch. The cron expression is a heartbeat, not a |
| 66 | +real-time SLA. |
| 67 | + |
| 68 | +## Credential and model boundary |
| 69 | + |
| 70 | +The caller keeps workflow `GITHUB_TOKEN` at `contents: read` and grants |
| 71 | +the reusable job `id-token: write` so the central scheduler can mint the |
| 72 | +OpenCode GitHub App token from GitHub OIDC when the mapped PAT is absent |
| 73 | +(GitHub, n.d.-c). It maps only `PR_REVIEW_MERGE_TOKEN` and |
| 74 | +`OPENCODE_APPROVE_TOKEN`. It never uses `secrets: inherit`, receives |
| 75 | +`NVIDIA_NIM_API_KEY`, or introduces `COPILOT_GITHUB_TOKEN`. CWE-250 |
| 76 | +forbids executing the caller with write or model privileges it does not |
| 77 | +need (MITRE, 2026). |
| 78 | + |
| 79 | +Model execution remains inside the central worker. The model credential |
| 80 | +is the GitHub Secret `NVIDIA_NIM_API_KEY`; the caller does not receive or |
| 81 | +forward it. |
| 82 | + |
| 83 | +Before protected-master activation, the repository variable |
| 84 | +`OPENCODE_REPOSITORY_DISPATCH_TARGETS` must contain the exact |
| 85 | +`ContextualWisdomLab/html4tree` target. Missing or mismatched |
| 86 | +configuration fails before mutation credential materialization. |
| 87 | + |
| 88 | +## Security, standalone operation, and modularity |
| 89 | + |
| 90 | +The caller adds no html4tree runtime dependency, database object, |
| 91 | +network endpoint, tenant authority, or product credential. html4tree |
| 92 | +continues to run as a standalone directory-index generator. Naruon and |
| 93 | +other CWL services may consume its `index.html` trees, but they cannot |
| 94 | +weaken its exact-head, approval, or security gates. |
| 95 | + |
| 96 | +## Verification and rollback |
| 97 | + |
| 98 | +Machine-checkable contracts require the exact target/base, minute 15 |
| 99 | +cadence, non-cancelling single-flight group, one dispatch, two-hour |
| 100 | +retry floor, explicit secret mapping, read-only contents plus job-scoped |
| 101 | +`id-token: write`, focused path-filter coverage, and absence of model or |
| 102 | +Copilot credentials. Independent `pull_request`, `push`, and `compileall` |
| 103 | +path blocks must each name the caller, doctoring, or contract they own. |
| 104 | + |
| 105 | +After source integration, closure requires a scheduled or manual |
| 106 | +protected-master consumer run proving the exact html4tree repository |
| 107 | +and `master` base. Source checks alone are not protected-master operational acceptance. |
| 108 | +Merge still requires zero unresolved valid findings and a |
| 109 | +qualifying independent non-author approval. |
| 110 | + |
| 111 | +Rollback removes the html4tree caller, its focused test, doctoring, and |
| 112 | +central path-filter/documentation entries. It must not remove scheduler |
| 113 | +dispatch validation or affect independent product callers. |
| 114 | + |
| 115 | +## APA 7th references |
| 116 | + |
| 117 | +GitHub, Inc. (n.d.-a). *Events that trigger workflows*. GitHub Docs. |
| 118 | +Retrieved August 17, 2026, from |
| 119 | +https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#schedule |
| 120 | + |
| 121 | +GitHub, Inc. (n.d.-b). *Reuse workflows*. GitHub Docs. Retrieved August |
| 122 | +17, 2026, from |
| 123 | +https://docs.github.com/en/actions/how-tos/sharing-automations/reuse-workflows |
| 124 | + |
| 125 | +GitHub, Inc. (n.d.-c). *Automatic token authentication*. GitHub Docs. |
| 126 | +Retrieved August 17, 2026, from |
| 127 | +https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token |
| 128 | + |
| 129 | +MITRE. (2026). *CWE-250: Execution with unnecessary privileges*. |
| 130 | +https://cwe.mitre.org/data/definitions/250.html |
| 131 | + |
| 132 | +National Institute of Standards and Technology. (2022). *Secure software |
| 133 | +development framework (SSDF) version 1.1: Recommendations for mitigating |
| 134 | +the risk of software vulnerabilities* (NIST Special Publication 800-218). |
| 135 | +https://doi.org/10.6028/NIST.SP.800-218 |
| 136 | + |
| 137 | +NVIDIA. (n.d.). *NVIDIA NIM for large language models documentation*. |
| 138 | +Retrieved August 17, 2026, from |
| 139 | +https://docs.nvidia.com/nim/large-language-models/latest/ |
| 140 | + |
| 141 | +OpenCode. (n.d.). *OpenCode documentation*. Retrieved August 17, 2026, |
| 142 | +from https://opencode.ai/docs/ |
0 commit comments