|
|
|
@@ -1,6 +1,6 @@
|
|
|
|
|
---
|
|
|
|
|
name: skill-check
|
|
|
|
|
description: Routine compliance, script, hook, flow-efficiency, and cost-efficiency audit of the whole jsc skill set with no change request in hand. Sync every domain repo from the Gitea canonical marketplace, then run three parallel groups - lint-scripts.sh plus lint-frontmatter.sh plus check-behaviors.sh plus ste100-lint.sh plus check-link-format.sh plus check-wiki-rules.sh plus check-page-name.sh plus check-delegate.sh plus hook smoke, the guidelines.md checklist audit, and an optimization review that first reads each domain's SKILLSET_{HASH} so suggestions already applied or deferred are never re-scanned or re-asked, then covers parallelism, tool extraction, repeated interaction, redundant checks, misplaced gates, and avoidable token, sub-agent, API, scan, or interaction cost. Confirm compliance fixes and optimization suggestions before applying them, recording each decision with its date, re-check until accepted fixes pass, then open a PR per affected repo via jsc-git pr. Close by appending the round's result to every changed domain's SKILLSET_{HASH} and its SKILLSET_CONTENTS block, or to the plugins/meta page when no domain was changed. Use for periodic or on-demand skill-set checks; not for applying a change request (use skillset-update) or editing one skill (use skill-update).
|
|
|
|
|
description: Routine compliance, script, hook, flow-efficiency, and cost-efficiency audit of the whole jsc skill set with no change request in hand. Sync every domain repo from the Gitea canonical marketplace, then run three parallel groups - lint-scripts.sh plus lint-frontmatter.sh plus check-behaviors.sh plus ste100-lint.sh plus check-link-format.sh plus check-wiki-rules.sh plus check-page-name.sh plus check-delegate.sh plus check-skill-paths.sh plus hook smoke, the guidelines.md checklist audit, and an optimization review that first reads each domain's SKILLSET_{HASH} so suggestions already applied or deferred are never re-scanned or re-asked, then covers parallelism, tool extraction, repeated interaction, redundant checks, misplaced gates, and avoidable token, sub-agent, API, scan, or interaction cost. Confirm compliance fixes and optimization suggestions before applying them, recording each decision with its date, re-check until accepted fixes pass, then open a PR per affected repo via jsc-git pr. Close by appending the round's result to every changed domain's SKILLSET_{HASH} and its SKILLSET_CONTENTS block, or to the plugins/meta page when no domain was changed. Use for periodic or on-demand skill-set checks; not for applying a change request (use skillset-update) or editing one skill (use skill-update).
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# skill-check — audit compliance, flow efficiency, and cost efficiency
|
|
|
|
@@ -30,9 +30,10 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
|
|
|
|
- 3 — nothing was checked, because `tools/delegate-spec.tsv` is missing, the root could not be derived, or `list-skills.sh` listed no skill. Record it as 「無委派清單可查」 with the cause from stderr and carry it into the step 3 merge; **exit 3 is never a pass**, because a check that read nothing reports neither a missing row nor an extra one.
|
|
|
|
|
|
|
|
|
|
This verdict is **not** one of the guidelines.md audit-checklist items, so it stays out of the nine that step 3 merges into every domain's checklist and is reported on its own line, one line for the round.
|
|
|
|
|
8. For every shell script directly named by a SKILL.md, confirm the skill routes every exit code the script's header declares. `lint-scripts.sh` proves the script exists and declares its codes; this check is the other half — that the caller branches on each of them. Report evidence as `skill file:line -> script path`.
|
|
|
|
|
9. When the `jsc-hooks` domain is present, run `jsc-hooks/tools/wire-cli.sh smoke {cli}` for every CLI reported by `jsc-cli/tools/detect-clis.sh`; the per-CLI smokes run **in parallel**. When no CLI is detected, run `jsc-hooks/tools/wire-cli.sh smoke codex` as the minimum hook behavior check and label it 「預設 hook smoke」 in the report. Use `smoke`, not `purge` or rewiring actions, and set `JSC_READONLY=1` for the whole audit so a mistyped sub-command is refused in code (exit 6) instead of rewiring the machine; `status` and `smoke` are unaffected by that variable. Route each `smoke` exit code: 0 — the run passed its own assertions; 2 — usage error, so fix the CLI code and rerun; 4 — the smoke failed, which includes the script's own result-line count not matching what it expected. **Read the count from the script's `lines<TAB>{數量}` output line; never write the number into this skill.** The script counts its own result lines and asserts them, so a hardcoded number here goes stale the moment a hook or a decision path is added — an out-of-date count in a SKILL.md is exactly what misled the previous audit.
|
|
|
|
|
10. When a hook or script smoke fails, route it as a compliance failure with script name, exit code, output summary, and proposed fix. Do not continue to report the affected hook as compliant.
|
|
|
|
|
8. For every synced domain repo, run `tools/check-skill-paths.sh {domain-path}`. One run per domain, and the runs go **in parallel** alongside the other group 1 per-domain runs. It reads every `skills/*/SKILL.md` and `references/*.md` and resolves each `tools/…` or `hooks/…` script path written in them. `lint-scripts.sh` proves a script exists inside its own repo; this one proves the path as written reaches it. Route each exit code: 0 — no path in that domain points at a file that is not there, and the hint lines it printed are counted separately from failures; 1 — the `missing` lines name paths that resolve to nothing, so report each as a compliance failure with its file and line; 2 — usage error, the tool takes exactly one argument; 3 — nothing was scanned, because the domain path is missing or it has neither `skills/*/SKILL.md` nor `references/*.md`. Record exit 3 as 「無文件可掃」; exit 3 is **never** a pass. Its `unrooted` and `unknown` lines are hints, never failures — `unrooted` marks a path with no plugin directory name, which resolves against whatever the current directory happens to be, and `unknown` marks a cross-domain path whose repo is not on this machine. Carry the two hint counts into the report without turning them into decision-tree items: the whole skill set carries hundreds of `unrooted` paths, and promoting them to failures would turn every domain red at once, which reads the same as no report at all. This check exists because item 9 below was already supposed to catch this and could not: a human reading item 9 checks that the named script exists in `tools/`, which it does, and never asks whether the path as written reaches it — so the same defect passed review every round until a path exited 127 in front of someone. This verdict is **not** one of the guidelines.md audit-checklist items either, so it stays out of the nine that step 3 merges into every domain's checklist and is reported on its own line, one line per domain.
|
|
|
|
|
9. For every shell script directly named by a SKILL.md, confirm the skill routes every exit code the script's header declares. `lint-scripts.sh` proves the script exists and declares its codes; this check is the other half — that the caller branches on each of them. Report evidence as `skill file:line -> script path`.
|
|
|
|
|
10. When the `jsc-hooks` domain is present, run `jsc-hooks/tools/wire-cli.sh smoke {cli}` for every CLI reported by `jsc-cli/tools/detect-clis.sh`; the per-CLI smokes run **in parallel**. When no CLI is detected, run `jsc-hooks/tools/wire-cli.sh smoke codex` as the minimum hook behavior check and label it 「預設 hook smoke」 in the report. Use `smoke`, not `purge` or rewiring actions, and set `JSC_READONLY=1` for the whole audit so a mistyped sub-command is refused in code (exit 6) instead of rewiring the machine; `status` and `smoke` are unaffected by that variable. Route each `smoke` exit code: 0 — the run passed its own assertions; 2 — usage error, so fix the CLI code and rerun; 4 — the smoke failed, which includes the script's own result-line count not matching what it expected. **Read the count from the script's `lines<TAB>{數量}` output line; never write the number into this skill.** The script counts its own result lines and asserts them, so a hardcoded number here goes stale the moment a hook or a decision path is added — an out-of-date count in a SKILL.md is exactly what misled the previous audit.
|
|
|
|
|
11. When a hook or script smoke fails, route it as a compliance failure with script name, exit code, output summary, and proposed fix. Do not continue to report the affected hook as compliant.
|
|
|
|
|
|
|
|
|
|
**Group 2 — audit every skill of every domain against the guidelines.md audit checklist.** This group MUST run as a sub agent, one sub agent per domain repo, and those sub agents run **in parallel**. Each sub agent reports its findings: skill, failed checklist item, evidence (file:line), proposed fix. Cover the checklist's four flow checks by name, not only the naming and language items:
|
|
|
|
|
- Every step number, file path and section title the skill references — inside itself and in other files — really exists (the pointer points at something).
|
|
|
|
@@ -78,7 +79,7 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
|
|
|
|
|
|
|
|
|
Each optimization finding reports skill, aspect, evidence (file:line), current flow step count, proposed flow step count, what time or interaction it saves, what cost it saves, current cost driver, proposed cost driver, whether correctness decreases, which protection would be weakened if any, the **決議** (`套用`, `延後` or `自訂`) recorded in step 3, and the **決議日期** that decision was made. The last two fields start empty and are filled in by step 3; they are what step 8 writes to the wiki and what the next round reads back, so a finding that reaches step 8 with either field empty is unfinished, not optional. Cost savings may be token volume, sub-agent count, API calls, file scans, full-repo audits, or user prompts. Keep optimization findings separate from compliance failures.
|
|
|
|
|
|
|
|
|
|
Completion condition for all three groups: every domain has a `lint-scripts.sh` verdict, a `lint-frontmatter.sh` verdict, a `check-behaviors.sh` verdict, an `ste100-lint.sh` verdict and a `check-link-format.sh` verdict, `check-wiki-rules.sh`, `check-page-name.sh` and `check-delegate.sh` each have one verdict for the whole run — `check-delegate.sh` carrying its hint lines separately from its failures, or 「無委派清單可查」 where it exited 3 — every script named by a SKILL.md has an exit-code-routing verdict, and every smoked CLI has a `smoke` exit code plus the `lines` value the script printed for it; every domain has a group 2 audit result that names a verdict for all checklist items — the four flow checks included, and the nine group 1 items left blank for the step 3 merge rather than re-scanned; and every one of the six aspects has returned a verdict for every domain whose settled list was read, 「無發現」 where an aspect found nothing and every settled entry of that domain excluded rather than re-reported — a domain whose pre-read failed carries 「本輪未取得已決議清單，優化建議暫不提出」 instead, and that sentence is a complete group 3 result for it.
|
|
|
|
|
Completion condition for all three groups: every domain has a `lint-scripts.sh` verdict, a `lint-frontmatter.sh` verdict, a `check-behaviors.sh` verdict, an `ste100-lint.sh` verdict, a `check-link-format.sh` verdict and a `check-skill-paths.sh` verdict — the last one carrying its `unrooted` and `unknown` hint counts separately from its failures — `check-wiki-rules.sh`, `check-page-name.sh` and `check-delegate.sh` each have one verdict for the whole run — `check-delegate.sh` carrying its hint lines separately from its failures, or 「無委派清單可查」 where it exited 3 — every script named by a SKILL.md has an exit-code-routing verdict, and every smoked CLI has a `smoke` exit code plus the `lines` value the script printed for it; every domain has a group 2 audit result that names a verdict for all checklist items — the four flow checks included, and the nine group 1 items left blank for the step 3 merge rather than re-scanned; and every one of the six aspects has returned a verdict for every domain whose settled list was read, 「無發現」 where an aspect found nothing and every settled entry of that domain excluded rather than re-reported — a domain whose pre-read failed carries 「本輪未取得已決議清單，優化建議暫不提出」 instead, and that sentence is a complete group 3 result for it.
|
|
|
|
|
3. Merge the three groups, then present compliance failures and optimization findings separately via the `jsc-ask:ask` decision tree. Merging means one thing in code: fill the nine skipped checklist items of every group 2 sub agent report from the matching group 1 verdicts, so each domain ends with one complete checklist and no item counted twice. Seven of the nine are per-domain verdicts, one domain to one item. The other two — `check-page-name.sh` and `check-wiki-rules.sh` — are judged **once for the whole round**, and that one verdict goes into that same item of **every** domain's checklist; re-judging a whole-round item per domain is precisely the double counting this merge exists to stop. A domain that group 3 marked 「本輪未取得已決議清單，優化建議暫不提出」 still gets its full compliance checklist here; only its optimization findings are missing, and the merge report says so.
|
|
|
|
|
- Compliance failure options: apply the proposed fix / skip / custom fix. Every option states its impact scope, for example skipping leaves the skill non-compliant until the next audit.
|
|
|
|
|
- The `check-delegate.sh` failures join that same set, one decision-tree item per reported row, and they carry one extra note in their impact scope: fixing a missing row means running the delegation decision tree of [`../../references/delegate-criteria.md`](../../references/delegate-criteria.md) for that skill in step 4, which is more questions than most fixes. Its **hint** lines never become decision-tree items — a hint is a note about a row that is already there, and turning it into a question re-asks a settled judgement every round, which is the 「重複來回」 group 3 exists to catch.
|
|
|
|
@@ -93,7 +94,7 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
|
|
|
|
- Exit 0 — every copy holds identical bytes; the script verifies that itself.
|
|
|
|
|
|
|
|
|
|
Completion condition: the script exits 0 and prints the touched paths.
|
|
|
|
|
6. Re-run the group 1 script, frontmatter, behavior-list, language, link-format, wiki-rule, page-name, delegation-list and hook validation, re-check the guidelines.md audit checklist for every touched skill, then re-run the optimization aspect that produced each accepted optimization. These three re-runs are as independent as the first pass, so run them **in parallel** and merge them the same way step 3 did. On any compliance failure, **return to step 3**: confirm and fix again, until all accepted compliance fixes pass. On an accepted optimization that does not produce the promised step reduction or cost reduction, or still weakens correctness beyond the recorded decision, return to step 3 for a new decision. Completion condition: `tools/lint-scripts.sh` exits 0 or 3 for every domain, `tools/lint-frontmatter.sh` exits 0 for every domain — exit 3 is 「什麼都沒掃」 and never counts as a pass — `tools/check-behaviors.sh` exits 0 for every domain, `tools/ste100-lint.sh` exits 0 for every domain, `tools/check-link-format.sh` exits 0 for every domain — its exit 3 is 「什麼都沒掃」 and never counts as a pass — `jsc-gitea/tools/check-wiki-rules.sh` exits 0, `tools/check-page-name.sh` exits 0 — its exit 3 is 「什麼都沒查」 and never counts as a pass — `tools/check-delegate.sh` exits 0, its remaining stdout lines counted as hints rather than failures and its exit 3 read as 「無委派清單可查」 and never as a pass, every hook smoke exits 0 with the `lines` count the script itself asserted, every domain's checklist passes in full — the two whole-round verdicts filled into each domain from the one run that produced them — and every accepted optimization has a matching verification result.
|
|
|
|
|
6. Re-run the group 1 script, frontmatter, behavior-list, language, link-format, script-path, wiki-rule, page-name, delegation-list and hook validation, re-check the guidelines.md audit checklist for every touched skill, then re-run the optimization aspect that produced each accepted optimization. These three re-runs are as independent as the first pass, so run them **in parallel** and merge them the same way step 3 did. On any compliance failure, **return to step 3**: confirm and fix again, until all accepted compliance fixes pass. On an accepted optimization that does not produce the promised step reduction or cost reduction, or still weakens correctness beyond the recorded decision, return to step 3 for a new decision. Completion condition: `tools/lint-scripts.sh` exits 0 or 3 for every domain, `tools/lint-frontmatter.sh` exits 0 for every domain — exit 3 is 「什麼都沒掃」 and never counts as a pass — `tools/check-behaviors.sh` exits 0 for every domain, `tools/ste100-lint.sh` exits 0 for every domain, `tools/check-link-format.sh` exits 0 for every domain — its exit 3 is 「什麼都沒掃」 and never counts as a pass — `tools/check-skill-paths.sh` exits 0 for every domain — its exit 3 is 「什麼都沒掃」 and never counts as a pass, and its `unrooted` and `unknown` lines stay hints rather than becoming failures — `jsc-gitea/tools/check-wiki-rules.sh` exits 0, `tools/check-page-name.sh` exits 0 — its exit 3 is 「什麼都沒查」 and never counts as a pass — `tools/check-delegate.sh` exits 0, its remaining stdout lines counted as hints rather than failures and its exit 3 read as 「無委派清單可查」 and never as a pass, every hook smoke exits 0 with the `lines` count the script itself asserted, every domain's checklist passes in full — the two whole-round verdicts filled into each domain from the one run that produced them — and every accepted optimization has a matching verification result.
|
|
|
|
|
7. Call `jsc-git:pr` once per affected domain repo to open a Push Request. Completion condition: every affected repo has a PR URL, and all URLs are reported in one table with the format in [`../../references/pr-report.md`](../../references/pr-report.md).
|
|
|
|
|
8. Write the round's result to the wiki. This step **MUST run as a sub agent**, one sub agent per affected domain repo, and those sub agents run **in parallel**: each domain writes its own page, and no page waits on another.
|
|
|
|
|
|
|
|
|
|