Skip to content

docs(skills): add /upstream-sync and /license-audit - #101

Merged
rodrigorjsf merged 1 commit into
mainfrom
feat/upstream-and-license-skills
Aug 5, 2026
Merged

rodrigorjsf merged 1 commit into
mainfrom
feat/upstream-and-license-skills

Conversation

@rodrigorjsf

@rodrigorjsf rodrigorjsf commented Aug 5, 2026 •

Copy link
Copy Markdown
Owner

Two project skills in .claude/skills/, for two maintenance operations this fork performs and had no
recorded procedure for. Both user-invoked — deliberate sweeps a human triggers, so zero context
load — and named in CLAUDE.md so a session can point at one.

/upstream-sync

Measures the drift from NVIDIA/SkillSpector and merges it in.

Its load-bearing idea: an upstream merge is the one case in this repository where a moved Behavior
Snapshot is correct.
Upstream changed what a Rule finds and the fork inherits that. So the gate
stops being pass/fail and becomes a ledger — every delta attributable to a named upstream commit, and
a delta with no commit behind it (or a missing delta a behavior-affecting commit should have
produced) is the merge going wrong. Nothing else compares the two sides, so it is the only signal
that will say so.

Six steps: measure the drift and the conflict surface · label each upstream commit behavior-affecting
or not · merge on its own branch · resolve with the fork's per-file rules (README's two halves,
pyproject.toml's version, inherited docs, fork-owned paths) · turn the gate into a ledger · hand off
to /license-audit and let a human merge.

/license-audit

Measures this fork against Apache-2.0 §4 and fixes the drift.

Its engine is a three-way classification against upstream/main — inherited, inherited-and-modified,
fork-authored — because §4(b) and §4(c) both turn on who wrote the file. It declines to pick the
fork's copyright line: that is a name on a legal notice and the maintainer's call, so it asks and
holds the header sweep while the notices and dependency work proceed.

Both were dogfooded, and both found things

Running the sync skill's first two steps against the live repo:

  • The fork has never merged upstream and is 11 commits behind. Seven are analyzer fixes; two are
    false-positive fixes in static_patterns_*, which run on every Scan regardless of Framework. The
    conflict surface is exactly 11 files. Filed as The fork is 11 commits behind upstream and has never synced #100 with the five behavior-affecting paths
    named. It also explains why the fork's pyproject.toml says 2.5.1 while upstream is at 2.5.3.

Running the audit skill's classification corrected three numbers in #95, which I filed earlier
today:

#95 said Actually
Files carrying an SPDX line 210 209
Fork-authored — the wrong-attribution set 128 43
Inherited-and-modified 45 22

The original count counted added files rather than added files carrying a header, and ran on a
branch holding unrelated work. The defect is real and unchanged in kind — roughly a third the claimed
size. 43 + 22 + 144 = 209 is now the skill's own completion check. Corrected on the issue with the
commands.

That run also surfaced 12 fork-added .py files with no header — every one under tests/fixtures/,
where a header is content the Scan reads and would move that fixture's snapshot. Correct as they
stand
, and both the skill and #95 now say so, so a future sweep does not "fix" them.

Note on ordering

/license-audit cites .claude/rules/license-compliance.md, which landed on main in PR #98 (merged before this one). The reference resolves.
on main. Merging #98 first resolves the reference; the skill is otherwise self-contained.

Validation

Documentation only; no source or test changed. make lint clean, make format-check clean, unit
tests 1082 passed. Both skills' commands were executed against the live repository rather than
written from the shape of the problem — the outputs above are what they returned.

… this fork

Two maintenance operations this fork performs and had no recorded procedure for.
Both are user-invoked -- they are deliberate sweeps a human triggers, so they
cost no context load, and `CLAUDE.md` names them so a session can point at one.

`/upstream-sync` measures the drift from NVIDIA/SkillSpector and merges it in.
Its load-bearing idea is that an upstream merge is the **one** case in this
repository where a moved Behavior Snapshot is correct rather than a regression:
upstream changed what a Rule finds and the fork inherits that. The gate stops
being pass/fail and becomes a ledger, where every delta is attributable to a
named upstream commit -- and a delta with no commit behind it, or a missing delta
a behavior-affecting commit should have produced, is the merge going wrong. It is
the only signal that will say so, since nothing else compares the two sides.

`/license-audit` measures this fork against Apache-2.0 §4. Its engine is a
three-way classification against `upstream/main` -- inherited, inherited-and-
modified, fork-authored -- because §4(b) and §4(c) both turn on who wrote the
file. It declines to pick the fork's copyright line, which is a name on a legal
notice and the maintainer's call.

Both were dogfooded rather than written from the shape of the problem. Running
the sync skill's first steps returned 11 unmerged upstream commits and a conflict
surface of exactly 11 files -- filed as #100, with the five behavior-affecting
paths named. Running the audit skill's classification corrected three numbers in
#95: the wrong-attribution set is 43 files, not 128, because the original count
counted added files rather than added files carrying a header, on a branch that
held unrelated work. `43 + 22 + 144 = 209` is now the skill's own arithmetic
check.

That run also found 12 fork-added `.py` files with no header, every one a
`tests/fixtures/` file where a header would be content the Scan reads and would
move that fixture's snapshot. Correct as they stand, and both the skill and #95
say so, so a future sweep does not "fix" them.

`/license-audit` cites `.claude/rules/license-compliance.md`, which is on the
branch of PR #98 rather than on `main` yet.

Refs #95, #100

Signed-off-by: Rodrigo França <rodrigo_rjsf@hotmail.com>
@rodrigorjsf
rodrigorjsf force-pushed the feat/upstream-and-license-skills branch from 5f77336 to bf8c78f Compare August 5, 2026 18:39
@rodrigorjsf
rodrigorjsf merged commit f1e691f into main Aug 5, 2026
5 checks passed
@rodrigorjsf
rodrigorjsf deleted the feat/upstream-and-license-skills branch August 5, 2026 18:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant