code-jig 0.12.0__py3-none-any.whl

codejig/_core/skills/bug-hunt/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: bug-hunt
+description: Use when the user asks to hunt for bugs nobody reported, audit a codebase or a path for latent bugs and vulnerabilities, fuzz code, write property-based tests, run mutation testing, or check whether the tests would catch a regression.
+---
+
+# Bug hunt
+
+Find real bugs nobody reported, and prove each one with a failing test. Deterministic tools pick the candidates; you judge them in context; generated inputs and mutations find what reading misses.
+
+## Scope
+
+Take scope from the request: a path, a category (security, logic, data integrity, error handling, performance), a minimum severity. Default: the whole repo, or `--base main` on a feature branch.
+
+## 1. Recon, all deterministic
+
+With the code-jig core on `PYTHONPATH`, or the `code-jig` launcher on `PATH`:
+
+```
+code-jig analyze --json [--base main] [path]
+git ls-files | grep -E "(^|/)\.env($|\.)|\.(pem|key|pfx|p12)$|credentials\.json$|secrets?\.(json|ya?ml)$"
+git log --oneline -i -E --grep="security|cve|vuln|bypass|injection|xss|csrf|auth" -n 30
+git log --since=90.days --name-only --format= | sort | uniq -c | sort -rn | head -20
+git grep -n -i -E "(TODO|FIXME|HACK|XXX).*(security|auth|unsafe|bypass|vuln|temp)|disable.*(auth|ssl|tls|verif)|skip.*validat"
+```
+
+PowerShell: write a `NAME=value command` line as `$env:NAME = 'value'; command`, replace `grep -E` with `Select-String -Pattern`, and the churn line with `git log --since=90.days --name-only --format= | Group-Object | Sort-Object Count -Descending | Select-Object -First 20 Count, Name`.
+
+- A tracked `.env`, key or credentials file is CRITICAL before anything else: open it, confirm it holds a real-looking secret and not a placeholder or example value, and report it first. Removing it does not un-leak it; the secret must be rotated.
+- Past fix commits show what this codebase gets wrong; read them and look for the same mistake elsewhere.
+- Hotspots, files that are both in the churn list and in `analyze`'s complexity findings, get read first.
+- Security TODOs are bugs the authors already found.
+- `analyze` already reports vulnerable dependencies (osv-scanner, and NuGet audit warnings from `dotnet build`) and dead code (vulture, knip); a function nobody calls is a bug hiding place and a deletion candidate.
+
+### Dependencies, deeper
+
+- One package against osv.dev, sending only its name and version: `curl -s -d '{"package":{"name":"lodash","ecosystem":"npm"},"version":"4.17.20"}' https://api.osv.dev/v1/query` (PowerShell: `Invoke-RestMethod -Method Post -Uri https://api.osv.dev/v1/query -ContentType application/json -Body '{"package":{"name":"lodash","ecosystem":"npm"},"version":"4.17.20"}'`). The fixed versions are in `vulns[].affected[].ranges[].events[].fixed`.
+- Upgrade suggestions for npm and Maven, only when the user asked for fixes: `osv-scanner fix --strategy=in-place -L package-lock.json`. It rewrites the lockfile, so review the diff and run the tests. Its default `--data-source deps.dev` sends package names to deps.dev, and `--data-source native` sends them to the package registry; add `--offline-vulnerabilities --download-offline-databases` so the vulnerability matching itself stays local.
+- .NET: `DOTNET_CLI_TELEMETRY_OPTOUT=1 dotnet list package --vulnerable --include-transitive --format json`. Restore already asks nuget.org for advisories.
+
+### Infrastructure code
+
+- Docker, Kubernetes, Terraform, ARM: `trivy config --disable-telemetry --skip-version-check --skip-check-update --format json .` (the bundled checks; no telemetry, no version or check download).
+- Bicep and ARM against Azure's Well-Architected rules: `Install-Module -Name PSRule.Rules.Azure -Scope CurrentUser`. Turn on expansion before scanning, or the templates are not read: in `ps-rule.yaml` set `configuration: { AZURE_BICEP_FILE_EXPANSION: true, AZURE_PARAMETER_FILE_EXPANSION: true }`, or for one run `$Env:PSRULE_CONFIGURATION_AZURE_BICEP_FILE_EXPANSION = 'true'` and `$Env:PSRULE_CONFIGURATION_AZURE_PARAMETER_FILE_EXPANSION = 'true'`. Then `Invoke-PSRule -Format File -InputPath ./infra -Module PSRule.Rules.Azure -Outcome Fail`.
+
+## 2. Confirm: the reality gate
+
+For every candidate, read at least 20 lines around it and answer: is this a real problem in this code's actual context? A pattern match on safe code is a false positive; drop it silently. Skip test and mock code, with one exception: a test that asserts the buggy behaviour is reported together with the bug it locks in.
+
+| Severity | Meaning |
+|---|---|
+| CRITICAL | Exploitable now: auth bypass, injection, remote code execution, data loss |
+| HIGH | Likely to break in normal use, or a real security weakness |
+| MEDIUM | Needs specific conditions, or a missing guard on a reachable path |
+| LOW | Fragile code with no current impact |
+
+Calibrate down: needs authentication plus unusual conditions is MEDIUM, not CRITICAL. A purely theoretical concern is not reported.
+
+When a bug is confirmed, check its siblings; bugs cluster.
+
+| Found | Also check |
+|---|---|
+| Missing authorization on an endpoint or controller action | The other actions in the same controller or router |
+| String-built SQL or command | Every other query or process call in the module |
+| Unbounded query or loop over request data | The other list endpoints of the same API |
+| Missing input validation | The other POST, PUT and PATCH handlers of the route |
+| Swallowed exception | The other catch blocks in the same layer |
+| Hardcoded credential | The other config files in the same folder |
+| Disposable or subscription not released | The other resources in the same class or component |
+
+With many candidates and a subagent tool available, split them by category, one subagent each on the default role (judging a bug is not a lookup, so not `explorer`), and give every subagent this reality gate and severity table.
+
+## 3. Prove
+
+- A confirmed bug gets a failing test that reproduces it (the `regression-tests` skill) when the code has a test framework; otherwise record the command and output that reproduce it. Fix it only if the user asked for fixes.
+- Logic that looks wrong but resists a single example gets a property test or a fuzz run.
+- For hotspot files, run mutation testing to see what the existing tests would miss.
+
+### Property-based tests
+
+State a rule that holds for all inputs; keep the shrunk counterexample as a fixed test.
+
+| Stack | Library | Shape |
+|---|---|---|
+| Python | Hypothesis | `@given(st.text())` on a pytest test |
+| TS/JS | fast-check | `fc.assert(fc.property(fc.string(), (s) => ...))` |
+| .NET | FsCheck (`[Property]` with FsCheck.Xunit) or CsCheck (`Gen.Int.Sample(i => ...)`) | |
+
+Good properties: decode(encode(x)) == x; sorting is idempotent; a result stays inside its bounds; the fast path equals a slow reference.
+
+### Coverage-guided fuzzing
+
+| Stack | Tool | Run |
+|---|---|---|
+| Python | atheris (Linux x86_64 wheels only; on Windows run it in WSL) | a script calling `atheris.Setup(sys.argv, test_one_input)` and `atheris.Fuzz()`, run with `-max_total_time=60` |
+| TS/JS | jazzer.js | `npx jazzer <fuzz-target-module> -- -max_total_time=60`, the module exporting `fuzz(data)` |
+| .NET | SharpFuzz | a console project with the `SharpFuzz` package and the target assembly instrumented by the `sharpfuzz` tool (`dotnet tool install SharpFuzz.CommandLine` in a tool manifest). With afl-fuzz (Linux) the harness calls `Fuzzer.OutOfProcess.Run(stream => ...)`; with libfuzzer-dotnet (Windows and Linux) it calls `Fuzzer.LibFuzzer.Run(span => ...)`. Follow its README (https://github.com/Metalnem/sharpfuzz) and `docs/libFuzzer.md` |
+| HTTP APIs | schemathesis | `schemathesis run http://localhost:<port>/openapi.json`, only against a local instance |
+
+Bound every run by time. Each crashing input becomes a test.
+
+### Mutation testing
+
+The tool flips conditions and removes calls, then reruns the tests; a surviving mutant is a regression the tests would miss. Keep it to the hotspot or changed files.
+
+| Stack | Tool | Run |
+|---|---|---|
+| Python | mutmut (POSIX; on Windows use WSL) | `[tool.mutmut]` with `source_paths = ["pkg/module.py"]` in `pyproject.toml`, then `mutmut run`, `mutmut results`, `mutmut show <mutant>`. mutmut 3 refuses code imported as `src.…`: run it on a scratch copy with the package renamed. List every non-Python file the tests read in `also_copy`. |
+| TS/JS | Stryker | `npx stryker run --mutate "src/module.ts"` (`npx stryker init` once) |
+| .NET | Stryker.NET | `dotnet new tool-manifest` once, `dotnet tool install dotnet-stryker`, then `DOTNET_CLI_TELEMETRY_OPTOUT=1 dotnet stryker --mutate "**/Module.cs"` or `--since:main` |
+
+Each surviving mutant gets a test that kills it, or a sentence on why it is equivalent to the original.
+
+### Techniques without a new tool
+
+- **Bisect a regression**: `git bisect start <bad> <good>`, then `git bisect run <command that runs the failing test>`; the first bad commit names the cause. Bisect writes inside `.git`, which the Codex sandbox keeps read-only, so request escalation for these commands, and finish with `git bisect reset`.
+- **Flaky tests**: shuffle and repeat. pytest with the `pytest-randomly` plugin installed (it shuffles every run) and a loop; `npx jest --randomize`; for .NET, run `DOTNET_CLI_TELEMETRY_OPTOUT=1 dotnet test --filter <name>` in a loop of 20. A test that fails only sometimes hides a race, shared state or an order dependency.
+- **Differential testing**: run the old and the new implementation (or two libraries) on the same generated inputs and compare.
+- **Metamorphic relations**: when the right answer is unknown, test relations instead: sorting a shuffled list gives the same result, filtering twice equals filtering once, a search for a superset term returns a superset.
+- **Invariants**: assert what must always hold at module boundaries in tests (totals add up, IDs stay unique) and let property tests drive them.
+
+## 4. Report
+
+Most severe first, one block per finding:
+
+```
+CRITICAL  Tenant check missing on invoice download
+  src/Api/InvoicesController.cs:88
+  Any signed-in user can fetch another tenant's invoice by ID. Proven by InvoicesTests.Download_OtherTenant_Forbidden (fails today).
+```
+
+End with counts per severity, what was scanned, which tools `analyze` skipped, and the fuzzing and mutation runs with their durations. No finding without a location and its proof from step 3: a failing test, or where there is no test framework, the command and output that reproduce it.

codejig/_core/skills/code-analysis/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: code-analysis
+description: Use when the user asks to analyse code quality, find bugs, code smells, complexity, duplication, security issues, leaked secrets or vulnerable dependencies, or asks what Sonar or SonarQube would complain about.
+---
+
+# Code analysis
+
+`code-jig analyze` runs the local analyzers for every stack it finds (.NET, Node, Python) and prints one summary grouped the way Sonar groups issues. It never downloads a tool and never sends code anywhere.
+
+## Run it
+
+From the repository root run `code-jig analyze` (the launcher installed with the pack). Without the launcher, point `PYTHONPATH` at the code-jig checkout, the folder that contains `codejig/` (POSIX: `PYTHONPATH=<checkout> python -m codejig analyze`; Windows PowerShell: `$env:PYTHONPATH = "<checkout>"; py -3 -m codejig analyze`):
+
+```
+code-jig analyze                 # whole repo
+code-jig analyze --base main     # only files changed since main, plus untracked ones
+code-jig analyze --top 30        # more findings per category
+code-jig analyze --json          # machine-readable
+```
+
+Exit 0 means clean, 1 means findings or a tool error, 2 means no project, a bad `--base`, or no analyzer installed.
+
+## What runs
+
+| Tool | Stack | Finds |
+|---|---|---|
+| lizard | all | Cognitive complexity (Sonar's metric, limit 15), cyclomatic complexity (15), functions over 100 lines or 7 parameters, duplicated blocks |
+| ruff | Python | Bugs, smells, security (`S` rules, the bandit set) |
+| vulture | Python | Dead code at 80% confidence and up: unused imports, variables and arguments, unreachable code, conditions that can never be true. Unused functions and classes score 60%: for a full sweep, set `[tool.vulture]` with `paths` and `min_confidence = 60` in `pyproject.toml`, which `analyze` then uses as-is |
+| mypy | Python, with a mypy config | Type errors |
+| eslint | Node, with an eslint config | Whatever the config enables; `sonarjs/*` and `security/*` rules are grouped as complexity or security |
+| knip | Node | Unused files, exports, types and dependencies; dependencies used but not listed, and imports that do not resolve |
+| tsc | Node, with `tsconfig.json` | Type errors |
+| dotnet build | .NET | Compiler and analyzer warnings, SonarAnalyzer and Roslynator included when the project references them, and NuGet audit warnings (NU1901-NU1904) for vulnerable packages; restore asks nuget.org for advisories, sending package names |
+| semgrep | all, with `.semgrep.yml` or `.semgrep/` | Your own local rules only, run with `--metrics=off` |
+| gitleaks | all | Secrets in the working tree, uncommitted files included, and in the git history; the secret itself is never printed |
+| osv-scanner | all | Known vulnerabilities in lockfiles, with `--offline`: the first run downloads the vulnerability database, no project data leaves |
+
+`code-jig analyze` itself sets `DOTNET_CLI_TELEMETRY_OPTOUT=1`, `SEMGREP_SEND_METRICS=off` and `KIOTA_CLI_TELEMETRY_OPTOUT=1` for every tool, in any shell; there is nothing to export. Missing tools are listed as skipped with an install hint.
+
+Analysis executes the repo's own code: `eslint.config.js`, MSBuild targets, mypy plugins and the tools in `node_modules/.bin`. Run it only where you would run the repo's tests.
+
+## Fix in this order
+
+1. `secret`: report it to the user first: the secret must be rotated (only its owner can, and only with their approval), then removed from the code. Removing it from the code does not un-leak it.
+2. `security`, then `dependency` (upgrade to the fixed version osv-scanner names).
+3. `bug` and `type`.
+4. `complexity`: extract functions, return early, replace flag arguments, split by responsibility. Behaviour must not change; run the tests before and after.
+5. `unused`: remove the dead code (git keeps it), after checking reflection, dependency injection, public API and framework entry points that tools cannot see.
+6. `duplication`: extract the shared code only when both copies change for the same reason.
+
+Rerun with `--base` and the branch this one will merge into (`main` when it exists; check with `git rev-parse --verify main`) to confirm the branch is clean. With no such branch, rerun on the whole repository.
+
+## Add Sonar's rules to a repo
+
+Only with the user's agreement, as dev dependencies:
+
+- .NET: in `Directory.Build.props`, `<PackageReference Include="SonarAnalyzer.CSharp" PrivateAssets="all" />` and `<PackageReference Include="Roslynator.Analyzers" PrivateAssets="all" />`. Raise rules in `.editorconfig`, for example `dotnet_diagnostic.S3776.severity = warning`. SonarAnalyzer is under SonarSource's source-available licence, free to use but not open source; Roslynator and the built-in CA rules are the open-source alternative. Run dotnet commands with `DOTNET_CLI_TELEMETRY_OPTOUT=1`.
+- Node: `npm install -D eslint eslint-plugin-sonarjs eslint-plugin-security typescript-eslint`, then in `eslint.config.mjs`:
+
+  ```js
+  import sonarjs from "eslint-plugin-sonarjs";
+  import security from "eslint-plugin-security";
+  export default [sonarjs.configs.recommended, security.configs.recommended];
+  ```
+
+- Python: `pip install ruff mypy vulture` in the project's dev dependencies, plus a `[tool.mypy]` section. For stricter typing, pyright in strict mode (`"typeCheckingMode": "strict"` in `pyrightconfig.json`) catches more than mypy's defaults; run it as `pyright --outputjson`.
+- TypeScript: `typescript-eslint`'s `strictTypeChecked` config adds `no-floating-promises` and `no-misused-promises`, which catch unawaited async calls; it needs `parserOptions.projectService: true`. Add `knip` as a dev dependency.
+- C#: `<Nullable>enable</Nullable>` and `<WarningsAsErrors>nullable</WarningsAsErrors>` turn null-reference warnings into build errors.
+- All stacks: `pip install lizard`; gitleaks and osv-scanner from their GitHub releases; semgrep only with local rule files.
+
+What a Sonar server adds that this does not: taint analysis across files and the history dashboard.

codejig/_core/skills/codegen/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: codegen
+description: Use when the user asks to generate an API client or server stubs from an OpenAPI spec, scaffold a project or component, or apply the same mechanical change across many files (a codemod, a rename, an API migration).
+---
+
+# Code generation
+
+Generators and codemods are deterministic: the same input gives the same output, at no token cost. Prefer them to writing repetitive code by hand.
+
+## Rules
+
+- The generation command lives in the repo: an npm script, an MSBuild target, a `scripts/` file or the generator's own config file. Anyone can rerun it.
+- Never edit generated files by hand. Change the input or the generator's config and regenerate.
+- Pin the generator version in the repo's dev dependencies or tool manifest.
+- Review the generated diff like any other diff, then run the build and tests.
+
+## OpenAPI clients
+
+| Stack | Tool | Command |
+|---|---|---|
+| .NET | NSwag | `dotnet new tool-manifest` once, `dotnet tool install NSwag.ConsoleCore`, keep an `nswag.json`, then `DOTNET_CLI_TELEMETRY_OPTOUT=1 dotnet nswag run nswag.json` |
+| .NET, TS, Python | Kiota | `KIOTA_CLI_TELEMETRY_OPTOUT=1 kiota generate -l CSharp -d openapi.yaml -o src/Client -n My.Client -c ApiClient` (`-l TypeScript`, `-l Python`) |
+| TS, Python | openapi-generator | `npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o src/client` (`-g python`); needs Java, and the first run downloads the generator jar |
+
+Kiota sends usage telemetry unless `KIOTA_CLI_TELEMETRY_OPTOUT=1` is set; set it in the script, not only in your shell.
+
+Windows PowerShell has no `NAME=value command` form: write the variable first in the same command, for example `$env:DOTNET_CLI_TELEMETRY_OPTOUT = '1'; dotnet test`.
+
+## Codemods with ast-grep
+
+ast-grep matches syntax, not text, so it does not touch strings or comments that merely look like code.
+
+```
+ast-grep run --lang ts --pattern 'console.log($A)' --rewrite 'logger.debug($A)'            # preview
+ast-grep run --lang ts --pattern 'console.log($A)' --rewrite 'logger.debug($A)' --update-all
+```
+
+For a change applied more than once, write a rule file and keep it in the repo (`sgconfig.yml` plus `rules/`), then `ast-grep scan --update-all`. Languages include C#, TypeScript, JavaScript and Python.
+
+## Scaffolding
+
+Use the stack's own templates: `dotnet new <template>` (with `DOTNET_CLI_TELEMETRY_OPTOUT=1`), `npm create <template>`, or a template the repo already has. Do not invent a project layout the repo does not follow.
+
+## After generating
+
+Then run the repository's own build and test commands (from its README, AGENTS.md or CI configuration) and `code-jig analyze --base main`, and report what changed, which generator or script made the change, and the build, test and analysis results.

codejig/_core/skills/cross-review/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: cross-review
+description: Use when a plan, design, document or diff would benefit from a review by a model from a different family before it is committed, or when the user asks for a second opinion, a cross-model review or an adversarial review.
+---
+
+# Cross-review
+
+A reviewer from another model family catches different mistakes. The `review` tier is configured with one.
+
+## Run it
+
+From the directory under review:
+
+```
+code-jig cross-review                 # the working tree against HEAD
+code-jig cross-review --base main     # the branch against main
+code-jig cross-review docs/plan.md    # one or more files
+```
+
+Run it from the repository under review with the installed launcher: `code-jig cross-review` (alias `cjig cross-review`; the URL bootstrap installs both). Untracked files are not part of a diff, so pass them as files. The command refuses input over 200,000 bytes; split the review instead.
+
+The reviewer runs in an ephemeral session with a read-only sandbox, no command escalation and no web search, treats the material as untrusted data, and prints its findings.
+
+## Verify before acting
+
+The findings are claims, not facts. For each one:
+
+1. Open the cited location and check the claim against the code or text.
+2. Classify it as `confirmed` (reproduced or clearly true), `plausible` (cannot be checked cheaply but holds up), or `rejected` (wrong, with the reason).
+3. Report confirmed and plausible findings with their location and fix. Give the rejected ones as a single line each, so the user can disagree.
+
+Do not apply a fix only because the reviewer said so. A confirmed finding gets a failing test before the fix when the code has tests.

codejig/_core/skills/grilling/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: grilling
+description: Use when the user wants a plan, decision, design or idea stress-tested before committing to it, or says "grill me", "grill this", "stress-test this", "poke holes in this", "what am I missing". Do not fire on your own.
+---
+
+# Grilling
+
+Run only when the user asks to be grilled or to stress-test something; never start a grilling on your own. Interview the user until you both understand the decision the same way. Map it as a design tree: every decision branches into the decisions that hang off it.
+
+Work the tree in rounds. The frontier is every decision whose prerequisites are already settled, which are the questions you can ask now without guessing answers you have not heard. Ask the frontier at most three questions per round. Number each question, give the options, and give your recommendation. Then wait for the answers before the next round.
+
+Nothing stays in the user's head between turns, so every round carries its own state.
+
+## Round format
+
+```
+**Settled (N):** <one short clause per settled decision, most recent last>
+
+**Round K. Frontier: <count>.**
+
+**Q1 - <title>**: <question>
+
+a) ... b) ... c) ...
+
+Recommendation: <your answer, what you would reject and why, and context they may have forgotten>
+
+**Deferred**: <titles of questions blocked on this round, or "none">
+```
+
+Never skip the settled line or the deferred line, even in a one-question round. A question whose answer depends on another open question belongs to a later round. A frontier wider than three spills into the next round, and its titles go in the deferred list.
+
+## Skip
+
+The user may answer `skip`. Take your recommendation, mark it `(assumed)`, and keep going. At the end, list every assumed answer once for a yes or no confirmation.
+
+## Facts are yours, decisions are theirs
+
+When a question needs a fact from the environment (files, tools, docs, the web), find it yourself, with an `explorer` subagent when subagents are available. A web lookup from a sandbox without network needs an approved escalation; if it is refused, say the fact is unverified and ask the rest of the frontier. Never ask the user for something you can look up. Only questions that depend on a pending lookup wait for it; ask the rest of the frontier now. State the fact when you use it.
+
+## Tree file
+
+Write `grill-<slug>.md` in the current workspace (never outside it, which the sandbox may refuse) and update it at the end of every round. In a read-only sandbox, keep the same structure in your reply instead:
+
+```markdown
+# Grill: <topic>
+
+## Settled
+- Q1 <title>: <answer> (over <rejected option>) - <one-line why>
+- Q2 <title>: <answer> (assumed)
+
+## Open
+- Frontier: <titles>
+- Deferred: <titles>
+```
+
+## Ending
+
+The session ends when the frontier is empty: every branch visited, nothing silently assumed. Confirm the assumed answers, then summarise the settled tree and ask whether to write it up as a spec or plan. Do not act on the outcome until the user confirms you agree.
+
+These thoughts mean you are quitting early. Recompute the frontier and ask the next round instead: "the rest is implementation detail", "we can figure that out later", "the remaining questions are obvious", "good enough to start".

codejig/_core/skills/hld-trace/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: hld-trace
+description: Use when the user asks whether the code follows the high-level design (HLD), which requirements have tests, which are untested, or wants tests linked to requirement or work item IDs.
+---
+
+# HLD trace
+
+Requirements get IDs, tests cite them, and `code-jig trace` checks the links deterministically. Judging whether a test really proves its requirement stays with you.
+
+## 1. Get the requirement IDs
+
+Write them to a file, one per line, or as JSON (a list of IDs, or objects with an `id` field).
+
+Before any `az` command below, check that `az` exists (`command -v az`; PowerShell: `Get-Command az`) and is logged in (`az account show`), that the `azure-devops` extension is there (`az extension show --name azure-devops`), and that defaults are set (`az devops configure --list`). Before any `gh` command, check `command -v gh` (PowerShell: `Get-Command gh`) and `gh auth status`. Logging in is interactive, so never run `az login` or `gh auth login` yourself: ask the user to run it in their own terminal, then check again. Ask before `az extension add --name azure-devops` and before `az devops configure --defaults organization=<url> project=<name>`.
+
+- Azure DevOps work items (child items of a feature or epic):
+
+  ```
+  az boards query --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.Parent] = 1234" -o json > ids.json
+  ```
+
+- Azure DevOps wiki, when the HLD page lists IDs such as `REQ-12`:
+
+  ```
+  az devops wiki page show --wiki <wiki> --path "/Design/Login" --include-content --query page.content -o tsv > hld.md
+  grep -oE "REQ-[0-9]+" hld.md | sort -u > ids.txt
+  ```
+
+  PowerShell: `Select-String -Path hld.md -Pattern "REQ-\d+" -AllMatches | ForEach-Object { $_.Matches.Value } | Sort-Object -Unique > ids.txt`.
+
+- GitHub issues: `gh issue list --label requirement --json number --jq ".[].number" > ids.txt` (`--jq` is built into `gh`, so the line is the same in PowerShell).
+- A Markdown HLD in the repo: the same `grep` as the wiki case.
+
+When `az` or `gh` is missing, or the user cannot log in, do not install anything: ask the user to paste the IDs or export the page (a work item query saved as CSV or JSON, the wiki page as Markdown, `gh issue list` output), and turn it into the ID file above before tracing: a CSV export becomes one ID per line with `python3 -c "import csv,sys; [print(r['ID']) for r in csv.DictReader(open(sys.argv[1], encoding='utf-8-sig'))]" export.csv > ids.txt` (PowerShell: `Import-Csv export.csv | ForEach-Object { $_.ID } > ids.txt`), using the export's ID column name; Markdown gets the same `grep` as the wiki case.
+
+## 2. Tag the tests
+
+For each requirement, search the test files for the names it uses (endpoint, function, field, error message) with `rg -i` (`grep -rni` where `rg` is missing; PowerShell: `Select-String`), read the matching tests, and add the requirement's tag to those whose assertions check it, in the form the framework below uses; tests written in step 4 get the tag as they are written. Default tag: `REQ-<id>`, anywhere in a test file, case-insensitive.
+
+| Framework | Example |
+|---|---|
+| xUnit | `[Trait("Requirement", "REQ-1234")]` |
+| NUnit | `[Property("Requirement", "REQ-1234")]` |
+| MSTest | `[TestProperty("Requirement", "REQ-1234")]` |
+| Jest, Vitest | `it("REQ-1234 rejects an expired token", ...)` |
+| pytest | `@pytest.mark.req("REQ-1234")`, with the `req` marker registered in the pytest config |
+
+Teams that already write Azure Boards links in tests can keep them: `--pattern "AB#{id}"`. The pattern is literal text with one `{id}` placeholder.
+
+## 3. Run the trace
+
+```
+code-jig trace ids.txt                     # or ids.json, or - for stdin
+code-jig trace ids.txt --path services/api
+code-jig trace ids.txt --pattern "AB#{id}" --json
+```
+
+It reads test files that git tracks or would track (`tests/`, `__tests__/`, `*.test.ts`, `test_*.py`, `*Tests.cs`, `*.Tests/` projects and similar) and reports requirements with tests, `missing` requirements, and `unknown` IDs that tests cite but the list does not contain. Exit 0 when nothing is missing or unknown, 1 otherwise, 2 for unusable input.
+
+## 4. Close the gaps
+
+- Missing: write the test (the `regression-tests` skill), tagged.
+- Unknown: the requirement was renamed or removed, or the tag has a typo. Ask before deleting a test.
+- Covered: read each requirement next to its tests and confirm the assertions prove it. A tag on a test that checks something else is worse than no tag.
+- After changing any test or tag, rerun step 3 so the report uses current results.
+
+## 5. Report
+
+One table: each requirement ID, `covered`, `missing` or `unknown`, the test files that cite it, and for covered ones whether the assertions prove it. List the tests tagged, the tests written, and any deletion still waiting for the user. Commit nothing; the user reviews the diff.

codejig/_core/skills/improve/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: improve
+description: Use when the user asks to improve code-jig, its rules, Guardian policy, skills or knowledge from experience on this machine, or says "remember this for next time", "make this a rule", "teach code-jig", "teach the harness".
+---
+
+# Improve
+
+Turn something learned into a durable change, in the right place, without leaking what must stay local.
+
+## Start
+
+1. Run `code-jig doctor` and fix any FAIL first.
+2. Read `overlay.toml` in the overlay (`$CODE_JIG_OVERLAY`, in PowerShell `$env:CODE_JIG_OVERLAY`, or the path the user gives). `core_writable` decides where you may write.
+
+## Where changes go
+
+| Change | Slot |
+|---|---|
+| A rule every session should follow | `AGENTS.overlay.md` |
+| Something Guardian should treat as riskier or safer | `guardian-policy.md` (additions to the upstream policy, never a replacement) |
+| A model for a tier | `profiles.toml` |
+| A command rule | `rules/<name>.rules`. Prefer `forbidden` rules. An `allow` rule runs the command outside the sandbox with no review, and the agent can change what a test or build command runs, so allow only what you would run unsupervised in that repo. |
+| A repeatable workflow | `skills/<name>/SKILL.md`, then run the `skill-validate` skill on it |
+| A fact about tools, services or conventions here | `knowledge/<slug>.md`, one fact per file, plus one line in `knowledge/INDEX.md` |
+
+With `core_writable = false`, write only to these overlay slots. Never edit the core checkout. With `core_writable = true` (a bench machine), core edits are allowed, with tests, and are committed in the core repo.
+
+## Knowledge
+
+- One fact per file: what is true, why it matters, how to apply it.
+- Before adding, search the index for a file that already covers it, and update that file instead.
+- Keep `INDEX.md` at 150 lines or fewer, one line each. Merge related facts. When a fact is no longer true, name the file to the user and delete it only after they agree.
+
+## Finish
+
+1. Run `code-jig install`, then `code-jig doctor`.
+2. Summarise what changed and where.
+3. End with **Upstream candidates**: improvements that would help anyone, written in generic language. Leave out company and product names, hosts, people, numbers measured at work, and code copied from work. The user decides whether to restate them on another machine. Nothing is copied across.

codejig/_core/skills/redacao/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: redacao
+description: Use when writing, rewriting or editing a technical article or blog post in Portuguese, or when the user says "escreve um artigo", "reescreve o post", "redação", "pauta", "revisa o texto", "tira a cara de IA".
+---
+
+# Redação
+
+You are the reporter. The user is the editor of the newsroom (editor da redação). Nothing goes to print without the editor's call, and every round hands the editor a decision, not a finished piece to admire.
+
+The editor is also the author. The opinions, the scenes, the doubts and the register come from them; the facts come from your apuração. A draft built only from facts reads as a changelog narrated by nobody, and readers notice in the first paragraph. When a section needs something only the author knows, ask. Never invent a feeling, a habit or a reason for them.
+
+Output in Brazilian Portuguese. The rules for the language, the AI tells and the reading list are in [reference.md](reference.md). Read it before the first draft.
+
+## Hard rules
+
+- No fact without a source. Every number, version, file name and claim comes from a command you ran, a file you read or a URL you opened. Write it to the fact sheet before it enters the text. A fact you could not check is cut or flagged to the editor, never softened into a vague sentence.
+- Never commit or `git add` the article. The editor publishes. Code examples, configs and fixes found along the way follow the repo's normal rules.
+- Voice comes from the author's own text, in this order: a style guide the author keeps, when one exists (for example one generated by a `style-guide` skill installed on this machine; ask where it is, never invent one), then the entrevista answers, then anything the author wrote by hand (an earlier version of the article in git history, a vault note). On voice and style it wins over reference.md; the rules in this file and the checks in reference.md still apply. Never fall back to your default voice.
+- Text an AI wrote (old drafts, vault notes, specs, an earlier version of the post) is a source of facts and links only. Re-check every fact you take from it and never reuse its sentences, headings or structure: that is how the old voice leaks back in.
+- Personal details (health, family, money) enter only when the author wrote them for this article, even if the vault has more.
+- A published version the author approved is the base of any rewrite. Keep its text and change only what the new angle needs; list every change in `Mudanças`. A rewrite from zero replaces their approved voice with yours. This holds even when an AI wrote that version: the author's approval made it their text, so the rule above about AI text covers only drafts and notes they never approved.
+- The author's idea sets the scope. When the apuração turns up a better story, it goes to `Fica de fora` as its own pauta; it does not take over this article.
+- Never present the AI tells checklist as a detector. It is a list of habits that make prose worse, whoever wrote it.
+
+## 1. Entrevista
+
+Before the apuração, ask the author up to six questions, in one message:
+
+1. Why this article, and why now?
+2. The moment that made you want to write it: what happened, where you were, what you did next.
+3. What do you think about it that most people get wrong?
+4. What surprised, annoyed or embarrassed you along the way?
+5. What are you still unsure about?
+6. If an earlier draft or note exists, which part of it still sounds like you?
+
+Ask for answers typed fast or dictated, without revising; typos stay. Save them verbatim in `entrevista-<slug>.md`. These answers are the raw material: keep their words, their order and their slang in the text, and take the tese from them. If the author declines, use their hand-written text from the voice list above and say so in the pauta.
+
+When the author hands raw text instead, it is the spine of the article. Keep their sentences and their order; fix only spelling, agreement and punctuation, and list every fix in `Mudanças`. Build the rest around it from facts. Every bridging sentence they did not write is marked `⚠` in the draft until they confirm, rewrite or cut it. If they also ask for the full piece, the pauta still comes first: present it and wait for `aprova`, then write every section in one draft and run the next rounds on that draft instead of section by section.
+
+## 2. Apuração
+
+Before writing a word, gather the facts yourself. Read the code, run the tests, the build and the linters, read the git log and any specs. Measure the published state, not a dirty working tree: find the published commit first (the release tag, or `git rev-parse '@{upstream}'` for what was pushed; the quotes keep PowerShell from reading the braces; ask the author when neither says what is live), then measure in a detached worktree of that commit (`git worktree add --detach <dir> <commit>`). Do not delete it yourself: in the final report, give its path and the `git worktree remove <dir>` line for the editor.
+
+Write `apuracao-<slug>.md` in the workspace: one line per fact, with its source (`command`, `path:line` or URL). Mark the gaps and the things that contradict the story you expected. Those are often the best material.
+
+For links, start from the links in the currently published version of the article (commits, issues, the articles that motivated it), then what the project actually used: the specs, design docs and READMEs behind it. Prefer a GitHub commit, issue or file that shows the thing over a sentence describing it. Open every URL before citing it and quote what it says in the fact sheet. A link earns its place by backing a sentence the reader cares about.
+
+The fact sheet is a quarry, not the outline. Most facts stay out of the text. A fact enters when the story needs it at that point, not because it was checked.
+
+`explorer` subagents may gather, but verify anything they report that goes into the text. They summarise confidently and get file states wrong.
+
+## 3. Pauta
+
+The first round is the pitch. Present:
+
+```
+**Pauta: <working title>**
+
+Leitor: <who reads this and what they already know>
+Tese: <one sentence the article proves, in the author's words from the entrevista>
+Tamanho: <target word count; a personal post rarely needs more than 1,200>
+Gancho: <the concrete fact or scene that opens it>
+Seções:
+1. <heading> - <what it shows, in one line>
+2. ...
+Fica de fora: <what you will not cover and why>
+Fontes: <the strongest three facts from the apuração>
+Destino: <the file the final article goes to; ask the editor when the repo does not make it obvious>
+
+❓ **Decisões** (at most 3, numbered, each with options a/b/c and your recommendation)
+```
+
+Wait for the editor. Do not draft sections before the pauta is approved.
+
+## 4. Rodadas
+
+Draft one section per round, two if both are short. Each round:
+
+```
+**Fechado (N):** <one clause per approved section or decision, latest last>
+
+**Rodada K: <section heading>**
+
+<the section, final prose, one paragraph per line>
+
+**Mudanças**
+- "<old fragment>" → "<new fragment>": <why, in a few words>
+(on a rewrite, compare against the original text; on a first draft, list the choices a reader would question)
+
+**Checagem:** <facts used in this section and their sources from the apuração>
+
+**Do autor:** <what in this section came from the entrevista or the author's own text; if nothing did, ask a question instead of shipping the section>
+
+❓ **Decisões** (at most 3, with options and your recommendation)
+
+**Na fila:** <headings still to write>
+```
+
+The editor answers per section: `aprova`, `corta <trecho>`, `reescreve <instrução>`, or a question. A `aprova` moves the section to Fechado. Anything else is the next round for the same section. The editor may answer `pula` to a decision: take your recommendation, mark it `(assumido)`, and list every assumed decision once before closing.
+
+Keep the state in `redacao-<slug>.md` next to the fact sheet and update it every round: approved text, open decisions, the queue. Nothing lives in the editor's head between turns.
+
+## 5. Fechamento
+
+When every section is approved:
+
+1. Assemble the full text and save it as `rascunho-<slug>.md` in the workspace. Write the title, the description (frontmatter) and the first paragraph last, now that you know what the article proves.
+2. Run `python3 "<skill dir>/checar.py" rascunho-<slug>.md` (Windows: `py -3 "<skill dir>\checar.py" rascunho-<slug>.md`); `<skill dir>` is the folder this SKILL.md is in. LanguageTool is optional: it runs as a local server, and without one the script still prints the rhythm numbers. It prints the rhythm numbers and the LanguageTool pt-BR matches; it starts nothing, and tells you the `podman run` line when LanguageTool is down. Fix real spelling, agreement and crase errors. Ignore matches on English technical terms, and never take a suggestion that flattens the author's register. LanguageTool misses agreement errors ("nossas vida"), so it is not a substitute for reading. Then run the checklist in reference.md over the whole text. Read it aloud in your head; a sentence you would not say to a colleague gets rewritten.
+3. Present the full text with a final `Mudanças` list for anything the assembly changed, then ask for the last `aprova`.
+4. After approval, write it to the `Destino` file from the approved pauta. Do not commit it. Say where it is and what the editor still has to do (translation, images, publishing).
+
+## Quitting early
+
+These thoughts mean you are skipping the editor. Stop and run the round instead: "the editor will like this, I'll do the next three sections", "this change is too small to list", "the pauta is obvious", "I'll fix the facts at the end", "I can write the author's opinion for them", "every checked fact deserves a place".