@litfamily/litcodex 1.0.0

package/marketplace/plugins/litcodex/skills/structural-search/references/rewrite-safety.md

@@ -0,0 +1,266 @@
+# Structural rewrite safety
+
+Use this reference only when the user has requested mutation. Finding a match does not itself
+authorize a rewrite. A codemod is accepted only when its target set, preview, diff, and verification
+are all observable.
+
+## Preconditions
+
+Before constructing a replacement:
+
+1. Confirm the active Git root and inspect `git status --short`.
+2. Separate pre-existing changes from task-owned paths.
+3. Name target roots and exclusions.
+4. Identify generated, vendored, cached, fixture, snapshot, and lockfile paths.
+5. Confirm the parser language and version-sensitive syntax.
+6. Find the project's formatter plus at least one parser/compiler/typecheck/test gate.
+7. Define expected match and changed-file counts as ranges if exact counts are not yet known.
+
+If an unrelated dirty edit overlaps the target, stop and ask rather than overwriting it.
+
+## Two distinct passes
+
+Never collapse preview and mutation into one command.
+
+### Pass 1: preview
+
+```sh
+"$STRUCTURAL_SEARCH_BIN" run \
+  --lang TypeScript \
+  --pattern 'console.log($$$ARGUMENTS)' \
+  --rewrite 'logger.info($$$ARGUMENTS)' \
+  src
+```
+
+This command shape relies on the CLI's default non-updating behavior. Confirm it in the installed
+`run --help`. If the installed version provides structured diff output, use it only for capture;
+also retain a human-readable preview.
+
+Review:
+
+- every matched syntax class;
+- every file path;
+- capture preservation;
+- comment and whitespace placement;
+- import or declaration prerequisites;
+- nested forms and multiline arguments;
+- generated or vendored false positives.
+
+### Pass 2: apply
+
+Only after the preview is accepted:
+
+```sh
+"$STRUCTURAL_SEARCH_BIN" run \
+  --lang TypeScript \
+  --pattern 'console.log($$$ARGUMENTS)' \
+  --rewrite 'logger.info($$$ARGUMENTS)' \
+  --update-all \
+  src
+```
+
+Before using `--update-all`, verify that exact flag in the installed help. Do not combine mutation
+with JSON or another output mode unless the live CLI documentation explicitly guarantees both
+effects; separate commands make the receipt unambiguous.
+
+Immediately inspect:
+
+```sh
+git diff --check
+git status --short
+git diff -- src
+```
+
+Stop if an unlisted path changed.
+
+## Replacement design
+
+### Every replacement capture must be bound
+
+This is reviewable:
+
+```text
+pattern: console.log($$$ARGUMENTS)
+rewrite: logger.info($$$ARGUMENTS)
+```
+
+This is not:
+
+```text
+pattern: console.log($VALUE)
+rewrite: logger.info($MESSAGE)
+```
+
+`$MESSAGE` has no source. A missing binding can fail, produce invalid output, or behave
+version-dependently.
+
+### Syntax validity is necessary, not sufficient
+
+Changing:
+
+```text
+console.log(value)
+```
+
+to:
+
+```text
+logger.info(value)
+```
+
+can produce parseable code while still failing because `logger` is not imported, initialized, or
+available in that scope. Use structural rewriting for the local shape and a compiler/typechecker or
+project test for integration facts.
+
+### Avoid context-dependent shortcuts
+
+Examples that need more than a local rewrite:
+
+- converting promise chains to `await` requires an async-capable enclosing function and equivalent
+  error behavior;
+- replacing Rust `.unwrap()` with `?` requires a compatible return type and conversion;
+- converting CommonJS imports to ESM affects module mode, file extensions, globals, and load timing;
+- changing allocations or ownership constructs can alter lifetime and cleanup semantics;
+- deleting a list element may require separator-aware range expansion.
+
+For these, use a relational rule plus project analysis, a compiler-native codemod, or a deliberately
+staged migration. Do not advertise a one-line replacement as complete.
+
+## YAML fixes
+
+A reusable rule may contain `fix`:
+
+```yaml
+id: direct-console-log
+language: TypeScript
+severity: warning
+message: "Use the project logger"
+rule:
+  pattern: console.log($$$ARGUMENTS)
+fix: logger.info($$$ARGUMENTS)
+files:
+  - "src/**/*.ts"
+  - "src/**/*.tsx"
+ignores:
+  - "**/*.generated.ts"
+```
+
+First scan without applying:
+
+```sh
+"$STRUCTURAL_SEARCH_BIN" scan \
+  --rule rules/direct-console-log.yml \
+  src
+```
+
+Then check `scan --help` for the installed fix flag and apply only after the same target set has
+been reviewed. A stored rule does not waive the two-pass requirement.
+
+### Deletion and range expansion
+
+An empty fix can delete a match, but deleting an element from a comma-separated list, declaration
+group, or argument sequence can leave invalid punctuation. When the installed schema supports a
+range-expanding fix configuration, test:
+
+- first element;
+- middle element;
+- last element;
+- only element;
+- trailing comma;
+- attached comments.
+
+If those cases cannot be proven, do not apply the delete codemod broadly.
+
+### Transforms and rewriters
+
+Transforms can derive new text from captures, and rewriters can recursively rewrite captured
+subtrees. They multiply the proof surface. Require:
+
+- a bounded input alphabet or explicit constraint;
+- positive cases for each transform branch;
+- a no-change case;
+- a check that derived identifiers are valid in the target language;
+- a preview that displays the final replacement;
+- formatter and compiler evidence after application.
+
+Prefer a direct capture-preserving fix when it is expressive enough.
+
+## Changed-file manifest
+
+Capture the intended target set before application. One reproducible approach:
+
+```sh
+git status --short
+"$STRUCTURAL_SEARCH_BIN" run \
+  --lang TypeScript \
+  --pattern 'console.log($$$ARGUMENTS)' \
+  src
+```
+
+Record the paths from the preview as the manifest in the task evidence. After applying, compare
+`git status --short` and `git diff --name-only` against that manifest. Account for pre-existing
+dirty paths separately.
+
+Do not construct destructive shell pipelines from raw matcher output. Paths may contain spaces,
+newlines, leading dashes, or untrusted text.
+
+## Verification ladder
+
+Run the smallest relevant checks first so a bad codemod fails quickly:
+
+1. `git diff --check`
+2. project formatter in check mode, or formatter on only changed files
+3. parser/compiler/typechecker for the changed language
+4. narrow tests for changed behavior
+5. broader package/repository gate when coupling warrants it
+6. re-run the old structural query
+7. run a query for the new shape
+8. inspect representative diffs manually
+
+The old query need not reach zero if some matches were intentionally excluded. Report expected and
+remaining counts with reasons.
+
+## Behavior-preserving review questions
+
+- Does evaluation order remain identical?
+- Are arguments evaluated the same number of times?
+- Are thrown errors, returned promises, and short-circuit behavior preserved?
+- Did the rewrite add a symbol that is missing in some scopes?
+- Did a comment move from one node to another?
+- Did automatic formatting expose malformed syntax?
+- Are overloads, decorators, macros, templates, or preprocessor forms involved?
+- Did the rewrite cross a language-version boundary?
+- Did ignored or generated files need regeneration through a project command rather than direct
+  editing?
+
+When any answer is uncertain, narrow the transformation or escalate to the project-native semantic
+tool.
+
+## Failure handling
+
+If the apply result is unexpected:
+
+1. stop all further mutation;
+2. capture `git status --short`, changed paths, and the relevant diff;
+3. distinguish task-owned edits from pre-existing work;
+4. revert only task-owned edits using a scoped patch or other recoverable method;
+5. reduce the pattern to a minimal fixture or one representative source file;
+6. fix the query and repeat the preview phase;
+7. do not claim success from a later green test if the unexplained diff remains.
+
+Never use broad destructive Git commands to recover from a codemod.
+
+## Completion receipt
+
+A structural rewrite report must include:
+
+- validated executable and version;
+- parser language;
+- pattern/rule and replacement/fix;
+- target roots and exclusions;
+- preview count and intended manifest;
+- actual changed-file count;
+- `git diff --check` result;
+- formatter/compiler/test results;
+- old-shape remaining count and expected exclusions;
+- cleanup result for temporary fixtures or rule files.

package/marketplace/plugins/litcodex/skills/visual-qa/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: visual-qa
+description: "Validate material visual evidence. Use for visual QA or an exact blocked receipt."
+---
+
+## #contract.activation
+
+```yaml
+contract_schema_version: 1
+artifact_kind: litcodex_skill_entrypoint
+skill_name: "visual-qa"
+host: Codex CLI
+reader_projection: shared_rule
+registration_surface: "plugins/litcodex/skills/visual-qa/SKILL.md"
+selection_surface: "$litcodex:visual-qa in the Codex skill picker"
+automatic_route: false
+```
+
+Top-level activation begins with one `▲ LIT · visual-qa` line; supporting skills add none. Selection grants no browser access.
+
+## #contract.inputs
+
+Require an evidence-eligible `litfamily.design-contract/v1beta2` with immutable source identity, finite inventory, tier, material captures, and truthful capture/auth/reviewer capabilities. Existing `v1beta1` contracts remain valid. Optional `taste` uses integer `variance`, `motion`, and `density` values from 1 through 10. Alpha cannot PASS evidence.
+
+## #contract.mode_matrix
+
+| Mode | Required inventory | Appropriate use | PASS boundary |
+| --- | --- | --- | --- |
+| `smoke` | Primary route, critical interaction, extreme viewports | Fast checkpoint | Proves only the finite smoke inventory |
+| `full` | Complete declared inventory | Product-ready review | Requires complete coverage and host-proven independent review |
+| `reference-fidelity` | Full inventory plus hashed references | Supplied-target comparison | Requires integrity and reference comparison |
+| `blocked` | Exact unavailable capability | Missing safe capture/auth/review | Cannot become PASS through prose |
+
+## #contract.procedure
+
+1. Use the first current-session capture option actually callable through Codex or the project; installed-only is unavailable.
+2. Record renderer/process identity, session, target, interaction, viewport, source hash, and binary observable.
+3. Validate bounded regular artifact bytes, dimensions, hashes, freshness, inventory coverage, and cleanup.
+4. For `full` and `reference-fidelity`, require host-proven independent review over identical immutable inputs.
+5. Return PASS, measured FAIL, or an exact BLOCKED receipt. BLOCKED outranks FAIL.
+
+## #contract.outputs
+
+Return tier, hashes, renderer identity, inventory, findings, review/cleanup status, and `PASS`, `FAIL`, or `BLOCKED`.
+
+## #contract.evidence
+
+Use `schemas/design-contract.v1beta2.json` for new contracts. Use evidence-eligible `schemas/evidence-manifest.v1beta1.json`, compatibility-only `schemas/evidence-manifest.v1alpha1.json`, and `litfamily.review-receipt/v1alpha1` with the installed validators. Beta binds a caller-authorized evidence root to bounded regular PNG files. Load `references/capture-playbook.md` and `references/complete-contract.md` for details.
+
+```bash
+LITCODEX_VISUAL_QA_ROOT="${CODEX_HOME:-$HOME/.codex}/marketplaces/litcodex/plugins/litcodex/skills/visual-qa"
+node "$LITCODEX_VISUAL_QA_ROOT/scripts/validate-design-contract.mjs" --input design-contract.json
+node "$LITCODEX_VISUAL_QA_ROOT/scripts/validate-review-receipt.mjs" < receipt.json
+node "$LITCODEX_VISUAL_QA_ROOT/scripts/validate-evidence.mjs" \
+  --input evidence-bundle.json \
+  --tier smoke --now 2026-07-25T06:00:00.000Z \
+  --evidence-root evidence-root
+node "$LITCODEX_VISUAL_QA_ROOT/scripts/cli.mjs" image-diff reference.png actual.png
+node "$LITCODEX_VISUAL_QA_ROOT/scripts/cli.mjs" tui-check capture.txt --cols 80
+```
+
+## #contract.hard_stops
+
+Do not install dependencies, mutate Codex configuration, reuse personal cookies, attach to unrelated processes, or accept self-attested independence. Return stable codes including `BLOCKED_RENDERER_UNAVAILABLE`, `BLOCKED_AUTH_UNAVAILABLE`, `BLOCKED_RENDERER_OWNERSHIP_UNVERIFIED`, `BLOCKED_EVIDENCE_STALE`, `BLOCKED_REVIEW_TIMEOUT`, and `BLOCKED_INDEPENDENT_REVIEW_UNAVAILABLE`. Full and reference-fidelity remain blocked until Codex exposes host-owned reviewer provenance.
+
+## #contract.anti_patterns
+
+Reject prose-only PASS, paths without validated bytes, stale or non-image captures, HTTP as render proof, similarity as verdict, hidden failure states, and incomplete cleanup.

package/marketplace/plugins/litcodex/skills/visual-qa/references/capture-playbook.md

@@ -0,0 +1,141 @@
+# Codex visual capture playbook
+
+Read this before browser, application, or manual visual capture. It supplements `SKILL.md`; the
+skill's contracts and hard stops remain authoritative.
+
+## Select a capture surface
+
+Use a project-owned automated path when one exists. It can usually reproduce route, viewport,
+state, locale, color scheme, and reduced-motion settings with the least ambiguity.
+
+For an unauthenticated page, the current-session in-app Browser capability is the preferred
+interactive path when it can navigate, inspect the page, and return screenshots. For an explicitly
+authorized user-browser task, the Chrome capability may be appropriate. Do not assume either
+capability is callable because its plugin is installed; prove the action in the current session.
+
+Use an existing project-configured MCP only within its documented scope. Do not add or reconfigure a
+server as a hidden QA prerequisite.
+
+If no automated capture path is safe, ask the user to perform a manual capture using the metadata
+packet below. Manual evidence can support a verdict only when its provenance and completeness are
+verifiable. Otherwise return `BLOCKED_RENDERER_UNAVAILABLE`.
+
+## Renderer ownership receipt
+
+Before navigation, record:
+
+- repository and working directory;
+- exact start command or already-running project command;
+- PID/process identity and owner;
+- bound address or application identity;
+- readiness signal;
+- capture session/context identity;
+- whether this run owns the process and session;
+- exact cleanup action permitted at the end.
+
+Never attach to an arbitrary debugging port. Do not reuse a browser profile, cookie jar, terminal
+session, or server merely because it is reachable. If the renderer belongs to another task or
+ownership is unclear, use `BLOCKED_RENDERER_OWNERSHIP_UNVERIFIED`.
+
+## Automated browser capture packet
+
+For each inventory ID, record:
+
+- URL/route and application state;
+- viewport width and height;
+- device scale factor;
+- scroll position;
+- locale and time zone;
+- light, dark, or system color scheme;
+- reduced-motion preference;
+- authentication boundary and redaction note;
+- readiness assertion used before capture;
+- console and failed-network observations;
+- screenshot or trace path;
+- canonical capture timestamp and SHA-256.
+
+Set the viewport and state before the capture. Match exact reference geometry for pixel comparison.
+When a reference gives no responsive guidance, label additional breakpoint captures as contract
+extrapolations rather than pixel targets.
+
+Inspect the returned image before review: verify its signature, dimensions, full composition, font
+readiness, expected route, and absence of unintended overlays. A blank, partial, stale, or
+misidentified image is an evidence defect.
+
+## Interaction and motion packet
+
+Drive the real input path. For mouse and pointer interactions, record rest, hover, pressed/active,
+and settled states as applicable. For keyboard, record focus arrival, visible focus, activation,
+escape/reversal, and the resulting semantic state. For scroll and entrance effects, record before,
+in-transition, and settled frames.
+
+For each animated interaction or transition required by the design contract and implementation,
+capture:
+
+1. the trigger and initial frame;
+2. a middle frame or trace proving continuity;
+3. the stable endpoint;
+4. the same journey under reduced motion.
+
+Do not compare an animated intermediate frame to a settled reference. First compare endpoints, then
+assess duration, easing, interruption, layout shift, and purpose. Nondeterministic animation needs a
+declared freeze point or it remains blocked for pixel comparison.
+
+## Accessibility and responsive packet
+
+Screenshots do not prove these checks. Capture the relevant browser or project output for:
+
+- tab order and reverse traversal;
+- visible focus and focus restoration;
+- accessible name, role, value, and state;
+- headings, landmarks, labels, descriptions, and live regions;
+- keyboard activation and escape behavior;
+- reflow at declared viewports and intermediate breakpoint boundaries;
+- zoom, long text, CJK, and high-content-density behavior;
+- reduced-motion result;
+- console errors caused by interaction or resize.
+
+Pair each record with the rendered screenshot for the same route/state/viewport identity.
+
+## Manual capture packet
+
+When the user must capture the surface, provide a finite checklist rather than “send a screenshot.”
+Ask for:
+
+- inventory ID;
+- full application/window identity without secrets;
+- route or screen name;
+- viewport or window dimensions and display scale;
+- locale, color scheme, and reduced-motion setting;
+- exact actions used to reach the state;
+- UTC capture time;
+- unedited original image or recording;
+- confirmation that no crop, rescale, recompression, or annotation altered the original;
+- a separate redacted copy if sensitive content must be removed;
+- any missing inventory IDs and why they could not be captured.
+
+Hash the received original bytes. Do not infer omitted metadata from pixels. Manual evidence does not
+satisfy independent review by itself.
+
+## Authentication safety
+
+Use only a designated test account whose owner, purpose, and cleanup policy are recorded. Do not ask
+the user to disclose a password, token, recovery code, or cookie. Let the authorized browser surface
+handle login. Redact private text, account identifiers, headers, internal URLs, and customer data
+before reviewer dispatch while retaining stable placeholders with comparable geometry.
+
+If capture requires a personal or unapproved account, return `BLOCKED_TEST_ACCOUNT_UNSAFE`. If a
+safe account exists but the current session cannot authenticate, return `BLOCKED_AUTH_UNAVAILABLE`.
+
+## Cleanup receipt
+
+At the end, record:
+
+- exact owned process/session stopped;
+- temporary profile and auth state removed;
+- temporary captures removed or promoted to durable redacted evidence;
+- durable evidence paths retained;
+- verification that no owned server, browser context, terminal session, port, or temp directory
+  remains.
+
+Do not terminate or delete anything whose ownership was not established by the start receipt.