uncoded 2.1.0__tar.gz → 3.0.0__tar.gz

{uncoded-2.1.0/.claude → uncoded-3.0.0/.agents}/skills/uncoded-code-navigation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uncoded-code-navigation
-description: Use before searching, reading, or editing Python source in a codebase indexed by uncoded. This covers locating a symbol, reading a definition, or checking references before you refactor, rename, or delete.
+description: Load once per session, before the first search, read, or edit of Python source in a codebase indexed by uncoded. Covers locating a symbol, reading a definition, or checking references before you refactor, rename, or delete.
 ---
 
 <!-- Generated by uncoded — do not edit; regeneration overwrites. -->
@@ -17,23 +17,25 @@ for reading a symbol's body and `uncoded refs` for finding references.
 symbols are classes, functions, methods, attributes, and module-level constants.
 If it's a pattern, regex, or free-text phrase, use grep.**
 
-This applies to every tool call where you find code, not just the first in the
-session. The pretrained reflex for "find X" is grep, and that reflex is wrong
-here. Reaching for `grep -rn 'def parse_config'` to read a function's body is a
-case for `uncoded body`. Reaching for `grep -rn 'validate_input'` to check
-callers before a refactor is a case for `uncoded refs`. Reaching for `grep` then
-`Edit` to delete dead code is a case for `uncoded refs` to confirm the code is
-dead, then `Edit`. The grep version of any of these is noisier and less
-reliable. Grep matches comments, strings, and unrelated attributes. Grep misses
-re-exports, so caller and delete checks come back incomplete. Grep forces offset
-arithmetic to slice a body. The indexed tools don't.
+This dispatch rule applies to every tool call where you find code, not just the
+first in the session. The pretrained reflex for "find X" is grep, and that
+reflex is wrong here. Reaching for `grep -rn 'def parse_config'` to read a
+function's body is a case for `uncoded body`. Reaching for
+`grep -rn 'validate_input'` to check callers before a refactor is a case for
+`uncoded refs`. Reaching for `grep` then `Edit` to delete dead code is a case
+for `uncoded refs` to confirm the code is dead, then `Edit`. The grep version of
+any of these is noisier and less reliable. Grep matches comments, strings, and
+unrelated attributes. Grep misses re-exports, so caller and delete checks come
+back incomplete. Grep forces offset arithmetic to slice a body. The indexed
+tools don't.
 
 ## How to execute the rule
 
-The index has two parts (a namespace map and per-file stubs) and three steps
-(orient, understand, act).
+The index has two parts: a namespace map and per-file stubs. Follow this
+sequence.
 
-**Step 1: Orient. Read the namespace map first.** Before answering the user,
+**Step 1: Orient. Read the namespace map first.** If the map is missing, run the
+repository's configured `uncoded sync` command. Then, before answering the user,
 before any other tool call:
 
 ```text
@@ -74,10 +76,11 @@ for a method and `function_name` for a top-level function. Per task:
 
 - **Find every reference to a symbol.**
   `uvx uncoded refs <name_path> --in <relative_path>`. Prints one reference per
-  line as `file:line:col`, sorted. Grep on the name misses re-exports and adds
-  false positives from comments, strings, and attribute lookups on other types.
-  If the next move depends on the answer being complete, grep cannot give you
-  that.
+  line as `<path>:<line>:<col>`, sorted by path, then line, then column. Each
+  path is relative to the current working directory when possible and otherwise
+  absolute. Grep on the name misses re-exports and adds false positives from
+  comments, strings, and attribute lookups on other types. If the next move
+  depends on the answer being complete, grep cannot give you that.
 
 - **Edit a symbol.** `uvx uncoded body <name_path> --in <relative_path>` gives
   the exact `old_string`; then `Edit` to apply the change.
@@ -88,6 +91,10 @@ for a method and `function_name` for a top-level function. Per task:
 - **Safely delete.** `uvx uncoded refs <name_path> --in <relative_path>` must
   return empty; then `Edit` to remove.
 
+**Step 4: Refresh.** After every modification to indexed Python source, run the
+repository's configured `uncoded sync` command before the next code-navigation
+operation. The modification can change the namespace map and stubs.
+
 ## Where Read, Edit, and grep are still the right tools
 
 The rule is about source navigation by symbol name. Outside that, Read, Edit,

uncoded-3.0.0/.agents/skills/uncoded-consistency-review/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: uncoded-consistency-review
+description: Review a Python codebase for semantic and naming consistency. It reports only concrete disagreements between two claims about the same concept, with verbatim evidence for each claim. It assumes uncoded is installed (.uncoded/namespace.yaml and .uncoded/stubs/ present).
+---
+
+<!-- Generated by uncoded — do not edit; regeneration overwrites. -->
+
+# Semantic Consistency Review
+
+Review a Python codebase for concrete disagreements in its vocabulary and symbol
+contracts. A finding must identify two claims about the same concept that ought
+to agree, but do not.
+
+## Guardrails
+
+Admit a finding only when the codebase supports both claims, their observable
+difference, and the reason that they should agree. Quote both claims verbatim.
+Omit a candidate when either claim or the reason for comparing them is
+unsupported.
+
+Review semantic and naming consistency, not formatting or style consistency. Do
+not report general bugs, complexity, performance, security, or design
+preferences unless they appear as a disagreement between two supported claims.
+Do not report overgrown public surfaces, private imports, cross-domain imports,
+zero-reference symbols, or redundant public surfaces merely because they exist.
+
+## Prerequisites
+
+Run the repository's configured `uncoded sync` command. Read the repository's
+agent instructions and follow its navigation rules.
+
+## Orientation
+
+Read `.uncoded/namespace.yaml` in full. Use its package structure and symbol
+names to map the codebase's main concepts and vocabulary.
+
+## Vocabulary sweep
+
+Use the namespace and stubs to find candidates, then confirm semantic overlap
+from signatures, docstrings, or bodies. Look for:
+
+- **Competing terms:** different names for substantively the same concept.
+- **Conflicting use:** the same term used incompatibly within a shared context.
+- **Stale qualifiers:** names such as `legacy`, `v2`, or `final` whose
+  distinction conflicts with another symbol or a symbol's docstring.
+
+Similar spelling, low vocabulary overlap, or the presence of a qualifier is not
+evidence on its own. A finding needs two concrete claims that establish the
+shared concept and the disagreement.
+
+## Symbol-contract sweep
+
+Compare a symbol's name, signature, docstring, and, when needed, behaviour.
+Findings may cover:
+
+- name-signature disagreement
+- name-docstring disagreement
+- docstring-signature disagreement
+- name-behaviour disagreement
+
+Read each relevant source file's stub for names and signatures. Run the
+repository's configured `uncoded body` command only when a docstring or
+implementation is needed to confirm a candidate. Do not retrieve every symbol
+body.
+
+## Report
+
+Return the report directly as the final turn output.
+
+Use this structure:
+
+```markdown
+## Semantic Consistency Review
+
+### Scope
+
+<What was reviewed and intentionally omitted.>
+
+### Summary
+
+<Two or three sentences that summarise the supported findings.>
+
+### Vocabulary findings
+
+#### 1. <Summary>
+
+**Claim A** — `<path>` · `<symbol>` · name | signature | docstring | body
+
+> Verbatim evidence
+
+**Claim B** — `<path>` · `<symbol>` · name | signature | docstring | body
+
+> Verbatim evidence
+
+**How they differ:** <The observable disagreement.>
+
+**Why these should agree:** <Evidence that both claims describe the same
+concept.>
+
+### Symbol-contract findings
+
+#### 1. <Summary>
+
+<Use the same finding structure.>
+```
+
+Keep both finding headings. If a group has no supported findings, state that
+under its heading. Number findings independently within each group.
+
+## Examples
+
+### Vocabulary finding
+
+#### 1. Customer lookup uses competing verbs
+
+**Claim A** — `storage.py` · `fetch_customer` · signature
+
+> `fetch_customer(customer_id: str) -> Customer`
+
+**Claim B** — `adapter.py` · `load_customer` · signature
+
+> `load_customer(customer_id: str) -> Customer`
+
+**How they differ:** The same lookup uses `fetch` in one module and `load` in
+another.
+
+**Why these should agree:** Both signatures accept a customer ID and return a
+customer through sibling adapters.
+
+### Symbol-contract finding
+
+#### 1. Predicate name promises a boolean but returns a value
+
+**Claim A** — `cache.py` · `is_cached` · name
+
+> `is_cached`
+
+**Claim B** — `cache.py` · `is_cached` · signature
+
+> `is_cached(key: str) -> str | None`
+
+**How they differ:** The name promises a predicate, while the return type holds
+a cached value or absence.
+
+**Why these should agree:** Both claims describe the contract of `is_cached`.

uncoded-3.0.0/.agents/skills/uncoded-doc-navigation/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: uncoded-doc-navigation
+description: Load once per session, before the first search or read of a codebase's Markdown documentation indexed by uncoded. Covers locating which file and section cover a topic, or orienting to what documentation exists.
+---
+
+<!-- Generated by uncoded — do not edit; regeneration overwrites. -->
+
+# Documentation Navigation
+
+This codebase uses [uncoded](https://github.com/alimanfoo/uncoded) to maintain a
+documentation index.
+
+**Step 1: Orient. Read the docs map first.** If the map is missing, run the
+repository's configured `uncoded sync` command. Then, before answering the user,
+before any other tool call:
+
+```text
+Read .uncoded/docs.yaml
+```
+
+`.uncoded/docs.yaml` is an orientation outline: it lists every Markdown file and
+its heading hierarchy. Read it once, in full, at session start.
+
+**Step 2: Navigate.** Headings in the map are literal text. Use `Read` or `grep`
+to navigate to a specific section identified in the map.
+
+**Step 3: Refresh.** After every modification to indexed Markdown, run the
+repository's configured `uncoded sync` command before the next
+documentation-navigation operation. The modification can change the heading map.

uncoded-2.1.0/src/uncoded/code_navigation.md → uncoded-3.0.0/.claude/skills/uncoded-code-navigation/SKILL.md

@@ -1,3 +1,10 @@
+---
+name: uncoded-code-navigation
+description: Load once per session, before the first search, read, or edit of Python source in a codebase indexed by uncoded. Covers locating a symbol, reading a definition, or checking references before you refactor, rename, or delete.
+---
+
+<!-- Generated by uncoded — do not edit; regeneration overwrites. -->
+
 # Code Navigation
 
 This codebase uses [uncoded](https://github.com/alimanfoo/uncoded) to maintain a
@@ -10,23 +17,25 @@ for reading a symbol's body and `uncoded refs` for finding references.
 symbols are classes, functions, methods, attributes, and module-level constants.
 If it's a pattern, regex, or free-text phrase, use grep.**
 
-This applies to every tool call where you find code, not just the first in the
-session. The pretrained reflex for "find X" is grep, and that reflex is wrong
-here. Reaching for `grep -rn 'def parse_config'` to read a function's body is a
-case for `uncoded body`. Reaching for `grep -rn 'validate_input'` to check
-callers before a refactor is a case for `uncoded refs`. Reaching for `grep` then
-`Edit` to delete dead code is a case for `uncoded refs` to confirm the code is
-dead, then `Edit`. The grep version of any of these is noisier and less
-reliable. Grep matches comments, strings, and unrelated attributes. Grep misses
-re-exports, so caller and delete checks come back incomplete. Grep forces offset
-arithmetic to slice a body. The indexed tools don't.
+This dispatch rule applies to every tool call where you find code, not just the
+first in the session. The pretrained reflex for "find X" is grep, and that
+reflex is wrong here. Reaching for `grep -rn 'def parse_config'` to read a
+function's body is a case for `uncoded body`. Reaching for
+`grep -rn 'validate_input'` to check callers before a refactor is a case for
+`uncoded refs`. Reaching for `grep` then `Edit` to delete dead code is a case
+for `uncoded refs` to confirm the code is dead, then `Edit`. The grep version of
+any of these is noisier and less reliable. Grep matches comments, strings, and
+unrelated attributes. Grep misses re-exports, so caller and delete checks come
+back incomplete. Grep forces offset arithmetic to slice a body. The indexed
+tools don't.
 
 ## How to execute the rule
 
-The index has two parts (a namespace map and per-file stubs) and three steps
-(orient, understand, act).
+The index has two parts: a namespace map and per-file stubs. Follow this
+sequence.
 
-**Step 1: Orient. Read the namespace map first.** Before answering the user,
+**Step 1: Orient. Read the namespace map first.** If the map is missing, run the
+repository's configured `uncoded sync` command. Then, before answering the user,
 before any other tool call:
 
 ```text
@@ -67,10 +76,11 @@ for a method and `function_name` for a top-level function. Per task:
 
 - **Find every reference to a symbol.**
   `uvx uncoded refs <name_path> --in <relative_path>`. Prints one reference per
-  line as `file:line:col`, sorted. Grep on the name misses re-exports and adds
-  false positives from comments, strings, and attribute lookups on other types.
-  If the next move depends on the answer being complete, grep cannot give you
-  that.
+  line as `<path>:<line>:<col>`, sorted by path, then line, then column. Each
+  path is relative to the current working directory when possible and otherwise
+  absolute. Grep on the name misses re-exports and adds false positives from
+  comments, strings, and attribute lookups on other types. If the next move
+  depends on the answer being complete, grep cannot give you that.
 
 - **Edit a symbol.** `uvx uncoded body <name_path> --in <relative_path>` gives
   the exact `old_string`; then `Edit` to apply the change.
@@ -81,6 +91,10 @@ for a method and `function_name` for a top-level function. Per task:
 - **Safely delete.** `uvx uncoded refs <name_path> --in <relative_path>` must
   return empty; then `Edit` to remove.
 
+**Step 4: Refresh.** After every modification to indexed Python source, run the
+repository's configured `uncoded sync` command before the next code-navigation
+operation. The modification can change the namespace map and stubs.
+
 ## Where Read, Edit, and grep are still the right tools
 
 The rule is about source navigation by symbol name. Outside that, Read, Edit,

uncoded-3.0.0/.claude/skills/uncoded-consistency-review/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: uncoded-consistency-review
+description: Review a Python codebase for semantic and naming consistency. It reports only concrete disagreements between two claims about the same concept, with verbatim evidence for each claim. It assumes uncoded is installed (.uncoded/namespace.yaml and .uncoded/stubs/ present).
+---
+
+<!-- Generated by uncoded — do not edit; regeneration overwrites. -->
+
+# Semantic Consistency Review
+
+Review a Python codebase for concrete disagreements in its vocabulary and symbol
+contracts. A finding must identify two claims about the same concept that ought
+to agree, but do not.
+
+## Guardrails
+
+Admit a finding only when the codebase supports both claims, their observable
+difference, and the reason that they should agree. Quote both claims verbatim.
+Omit a candidate when either claim or the reason for comparing them is
+unsupported.
+
+Review semantic and naming consistency, not formatting or style consistency. Do
+not report general bugs, complexity, performance, security, or design
+preferences unless they appear as a disagreement between two supported claims.
+Do not report overgrown public surfaces, private imports, cross-domain imports,
+zero-reference symbols, or redundant public surfaces merely because they exist.
+
+## Prerequisites
+
+Run the repository's configured `uncoded sync` command. Read the repository's
+agent instructions and follow its navigation rules.
+
+## Orientation
+
+Read `.uncoded/namespace.yaml` in full. Use its package structure and symbol
+names to map the codebase's main concepts and vocabulary.
+
+## Vocabulary sweep
+
+Use the namespace and stubs to find candidates, then confirm semantic overlap
+from signatures, docstrings, or bodies. Look for:
+
+- **Competing terms:** different names for substantively the same concept.
+- **Conflicting use:** the same term used incompatibly within a shared context.
+- **Stale qualifiers:** names such as `legacy`, `v2`, or `final` whose
+  distinction conflicts with another symbol or a symbol's docstring.
+
+Similar spelling, low vocabulary overlap, or the presence of a qualifier is not
+evidence on its own. A finding needs two concrete claims that establish the
+shared concept and the disagreement.
+
+## Symbol-contract sweep
+
+Compare a symbol's name, signature, docstring, and, when needed, behaviour.
+Findings may cover:
+
+- name-signature disagreement
+- name-docstring disagreement
+- docstring-signature disagreement
+- name-behaviour disagreement
+
+Read each relevant source file's stub for names and signatures. Run the
+repository's configured `uncoded body` command only when a docstring or
+implementation is needed to confirm a candidate. Do not retrieve every symbol
+body.
+
+## Report
+
+Return the report directly as the final turn output.
+
+Use this structure:
+
+```markdown
+## Semantic Consistency Review
+
+### Scope
+
+<What was reviewed and intentionally omitted.>
+
+### Summary
+
+<Two or three sentences that summarise the supported findings.>
+
+### Vocabulary findings
+
+#### 1. <Summary>
+
+**Claim A** — `<path>` · `<symbol>` · name | signature | docstring | body
+
+> Verbatim evidence
+
+**Claim B** — `<path>` · `<symbol>` · name | signature | docstring | body
+
+> Verbatim evidence
+
+**How they differ:** <The observable disagreement.>
+
+**Why these should agree:** <Evidence that both claims describe the same
+concept.>
+
+### Symbol-contract findings
+
+#### 1. <Summary>
+
+<Use the same finding structure.>
+```
+
+Keep both finding headings. If a group has no supported findings, state that
+under its heading. Number findings independently within each group.
+
+## Examples
+
+### Vocabulary finding
+
+#### 1. Customer lookup uses competing verbs
+
+**Claim A** — `storage.py` · `fetch_customer` · signature
+
+> `fetch_customer(customer_id: str) -> Customer`
+
+**Claim B** — `adapter.py` · `load_customer` · signature
+
+> `load_customer(customer_id: str) -> Customer`
+
+**How they differ:** The same lookup uses `fetch` in one module and `load` in
+another.
+
+**Why these should agree:** Both signatures accept a customer ID and return a
+customer through sibling adapters.
+
+### Symbol-contract finding
+
+#### 1. Predicate name promises a boolean but returns a value
+
+**Claim A** — `cache.py` · `is_cached` · name
+
+> `is_cached`
+
+**Claim B** — `cache.py` · `is_cached` · signature
+
+> `is_cached(key: str) -> str | None`
+
+**How they differ:** The name promises a predicate, while the return type holds
+a cached value or absence.
+
+**Why these should agree:** Both claims describe the contract of `is_cached`.

uncoded-3.0.0/.claude/skills/uncoded-doc-navigation/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: uncoded-doc-navigation
+description: Load once per session, before the first search or read of a codebase's Markdown documentation indexed by uncoded. Covers locating which file and section cover a topic, or orienting to what documentation exists.
+---
+
+<!-- Generated by uncoded — do not edit; regeneration overwrites. -->
+
+# Documentation Navigation
+
+This codebase uses [uncoded](https://github.com/alimanfoo/uncoded) to maintain a
+documentation index.
+
+**Step 1: Orient. Read the docs map first.** If the map is missing, run the
+repository's configured `uncoded sync` command. Then, before answering the user,
+before any other tool call:
+
+```text
+Read .uncoded/docs.yaml
+```
+
+`.uncoded/docs.yaml` is an orientation outline: it lists every Markdown file and
+its heading hierarchy. Read it once, in full, at session start.
+
+**Step 2: Navigate.** Headings in the map are literal text. Use `Read` or `grep`
+to navigate to a specific section identified in the map.
+
+**Step 3: Refresh.** After every modification to indexed Markdown, run the
+repository's configured `uncoded sync` command before the next
+documentation-navigation operation. The modification can change the heading map.

{uncoded-2.1.0 → uncoded-3.0.0}/.github/workflows/ci.yml

@@ -31,3 +31,5 @@ jobs:
       - run: uv python install ${{ matrix.python-version }}
       - run: uv sync --extra dev
       - run: uv run pytest -v -m "integration or not integration"
+        env:
+          PYTHONWARNDEFAULTENCODING: "1"

{uncoded-2.1.0 → uncoded-3.0.0}/.pre-commit-config.yaml

@@ -13,18 +13,28 @@ repos:
       - id: check-toml
       - id: check-added-large-files
 
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.10
-    hooks:
-      - id: ruff
-        args: [--fix]
-      - id: ruff-format
-
   - repo: local
     hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix --exit-non-zero-on-fix --show-fixes
+        language: system
+        types_or: [python, pyi]
+        pass_filenames: false
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types_or: [python, pyi]
+        pass_filenames: false
       - id: ty
         name: ty
-        entry: uvx ty check src tests
+        entry: uv run ty check src tests
+        language: system
+        pass_filenames: false
+      - id: complexipy
+        name: complexipy
+        entry: uv run complexipy src tests
         language: system
         pass_filenames: false
       # Runs before uncoded so the generated skill files are built from
@@ -42,4 +52,5 @@ repos:
         name: uncoded
         entry: uv run uncoded sync
         language: system
+        always_run: true
         pass_filenames: false