pi-ui-extend 1.0.40 → 1.0.42

package/skills/spec-wiki/references/focused-spec.md

@@ -0,0 +1,117 @@
+# Focused spec work
+
+Use this workflow for creating, updating, or checking one primary spec. Keep the
+scope narrow; repository-wide indexing is optional unless it helps retrieval.
+
+## Core rules
+
+- Do not change production code unless implementation was requested.
+- Do not invent behavior. Mark ambiguity as inferred or unknown.
+- Prefer compact specs over exhaustive design documents.
+- Read only relevant code, tests, schemas, migrations, entrypoints, docs, and
+  existing specs.
+- Follow the project's existing documentation convention when one exists.
+- Describe current behavior as `as-is`; intended behavior as `change`.
+
+## When a spec is useful
+
+Prefer a focused spec for changes involving security/auth/privacy, data or
+persistence, public APIs/CLI/UI/events, integrations, destructive operations,
+async/concurrency/retries, cross-cutting architecture, non-trivial user-visible
+edge cases, unclear bug-fix contracts, or suspected spec-code drift.
+
+Do not force a spec for formatting-only edits, mechanical renames, or obvious
+local changes without broader behavioral impact.
+
+## As-is / drift workflow
+
+1. Identify the narrow behavior or contract.
+2. If a Spec Wiki already exists, use it only to locate related primary specs.
+3. Inspect the relevant code, tests, docs, schemas, migrations, and entrypoints.
+4. Separate claims as:
+   - confirmed by code;
+   - confirmed by tests;
+   - confirmed by docs;
+   - inferred;
+   - unknown.
+5. Write/update a compact as-is spec.
+6. Report detected drift separately from confirmed behavior.
+7. If the project uses Spec Wiki, `record` the spec/relations, then run `verify`
+   only after the code/test semantic check is complete, and `render`.
+
+## Change workflow
+
+1. Define goal, scope, and non-goals.
+2. State intended behavior.
+3. Capture affected contracts and invariants.
+4. Add relevant edge cases, compatibility, migration, and risks.
+5. Define verification.
+6. Implement only when requested.
+7. After implementation, verify the spec against code/tests.
+8. For a material production-behavior change, run the post-change checkpoint in
+   `maintenance.md` using the paths changed by this task. This is required even
+   when the spec you started from appears sufficient: newly introduced files may
+   reveal previously unknown spec relationships.
+9. If the project uses Spec Wiki, refresh metadata with `record`, repair durable
+   relation changes with `relate`, then establish the verified baseline with
+   `verify` only after implementation/test verification and the impact sweep.
+
+If the task creates a new primary spec, record it immediately. If it moves a
+primary spec, record/verify the new path before removing the old metadata entry.
+
+## Default template
+
+Use only when the repository has no stronger convention. Remove irrelevant
+sections.
+
+```markdown
+# Spec: <name>
+
+## Type
+As-is | Change
+
+## Goal
+...
+
+## Scope
+...
+
+## Non-goals
+...
+
+## Behavior
+...
+
+## Contracts
+Inputs, outputs, APIs, CLI, UI, events, files, schemas.
+
+## Invariants
+...
+
+## Edge cases
+...
+
+## Side effects
+...
+
+## Related files
+...
+
+## Verification
+...
+
+## Risks / unknowns
+...
+
+## Evidence
+- Confirmed by code:
+- Confirmed by tests:
+- Confirmed by docs:
+- Inferred:
+- Unknown:
+```
+
+## Report back
+
+Summarize the spec path, as-is/change mode, strongest evidence, important
+unknowns/drift, and whether production code was changed.

package/skills/spec-wiki/references/index-schema.md

@@ -0,0 +1,330 @@
+# Spec Wiki state and CLI reference
+
+<!-- markdownlint-disable MD013 -->
+
+This reference describes the deterministic storage layer. Primary specification
+documents remain the source of truth.
+
+## Files
+
+```text
+.spec-wiki/index.md      # compact generated routing index
+.spec-wiki/state.json    # semantic metadata + structural/verification baselines
+.spec-wiki/config.jsonc  # optional discovery overrides
+```
+
+## State schema v2
+
+Conceptual primary entry:
+
+```json
+{
+  "path": "docs/auth.md",
+  "title": "Authentication contract",
+  "classification": "spec",
+  "type": "as-is",
+  "lifecycle": "active",
+  "confidence": "high",
+  "summary": "Authentication session lifecycle and refresh invariants.",
+  "topics": ["auth", "sessions"],
+  "relations": {
+    "code": [
+      {"path": "src/auth/session.ts", "source": "explicit"}
+    ],
+    "specs": [
+      {"path": "docs/oauth.md", "source": "inferred", "kind": "related"}
+    ]
+  },
+  "unresolvedReferences": [],
+  "indexed": {
+    "at": "2026-09-09T00:00:00Z",
+    "sourceHash": "sha256:..."
+  },
+  "verified": {
+    "at": "2026-09-09T00:05:00Z",
+    "sourceHash": "sha256:...",
+    "relationsHash": "sha256:...",
+    "codeHashes": {
+      "src/auth/session.ts": "sha256:..."
+    }
+  }
+}
+```
+
+State keys and all stored paths are normalized project-relative POSIX paths.
+
+### Classification
+
+- `spec` — primary behavioral/normative specification.
+- `spec-like` — primary-ish knowledge with mixed/ambiguous purpose.
+- `meta-index` — inventory, overview, catalog, TOC, generated index.
+- `design-only` — design/decision material without enough behavioral contract.
+- `guide` — tutorial, runbook, usage/operational documentation.
+- `other` — not useful specification knowledge.
+
+Only `spec`/`spec-like` are primary specs. `design-only` may be searched as
+secondary context with `search --include-secondary`.
+
+### Type
+
+- `as-is` — describes current behavior.
+- `change` — intended/changed behavior.
+- `mixed` — intentionally contains both.
+- `unknown` — not safely determined.
+
+### Lifecycle
+
+Lifecycle is separate from Type:
+
+- `active` — current authoritative contract.
+- `proposed` — intended contract that is not yet current.
+- `historical` — useful milestone/history, not current precedence.
+- `superseded` — replaced by a newer primary document.
+- `unknown` — precedence cannot be established safely.
+
+For known replacement relationships use:
+
+- `kind: related`
+- `kind: supersedes`
+- `kind: superseded-by`
+
+### Indexed vs verified
+
+`indexed` is refreshed by `record`. It means the document was classified and
+summarized at that exact source hash.
+
+`verified` is written only by `verify`. It means the agent has semantically
+checked the spec against its relevant implementation/tests/evidence and accepted
+the current tracked-input baseline. The baseline also fingerprints the current
+code/spec relation map. Adding or removing a relation therefore invalidates
+freshness until semantic review and `verify` establish a new baseline.
+
+Therefore a clean bootstrap produces `unverified` primary specs, not `fresh`.
+
+## Freshness statuses
+
+- `fresh` — source and tracked code inputs match an explicit verified baseline.
+- `unverified` — indexed but no semantic-verification baseline exists.
+- `spec-changed` — source differs from indexed/verified baseline.
+- `inputs-changed` — one or more tracked implementation inputs differ/missing.
+- `spec+inputs-changed` — both source and implementation inputs changed.
+- `missing-source` — primary source disappeared/moved.
+
+Hash status is structural evidence only; `inputs-changed` requests semantic
+review and must not rewrite behavior automatically.
+
+## Relationship discovery
+
+Explicit path/link resolution tries, in order:
+
+1. the source document directory;
+2. ancestor package roots containing markers such as `package.json`,
+   `pyproject.toml`, `Cargo.toml`, `go.mod`, or `Package.swift`;
+3. repository root.
+
+This lets a doc under `external/package/docs/` resolve `src/foo.ts` against the
+package root. Simple `{a,b}` path groups are expanded.
+
+If the document explicitly says that paths/references below are relative to a
+backticked existing project directory (for example `external/tool-suite/`), that
+directory is also used as a resolution base. This covers root-level specs that
+document one nested package using package-relative paths.
+
+Path-like tokens that still cannot resolve are stored in
+`unresolvedReferences`. They are diagnostic hints, not silently discarded.
+
+## Optional config.jsonc
+
+```jsonc
+{
+  "includeExtensions": [".md", ".mdx", ".rst", ".adoc", ".txt"],
+  "include": ["docs/**", "architecture/**", "features/**"],
+  "exclude": ["legacy/**", "generated-docs/**"],
+  "forceSpecs": ["protocol/*.txt"],
+  "ignoreSpecs": ["docs/spec-template.md"],
+  "minCandidateScore": 3,
+  "maxFileBytes": 524288
+}
+```
+
+The scanner excludes its own state plus common dependency/build/cache dirs.
+When Git is available it uses tracked + unignored untracked files; hashing also
+works without Git.
+
+## CLI
+
+Global options:
+
+```text
+--root PATH       project root; defaults to Git root, then cwd
+--state-dir PATH  alternate wiki directory; relative paths are root-relative
+--config PATH     alternate config.jsonc/json path
+```
+
+### discover
+
+```bash
+spec_wiki.py --root . discover --limit 40
+spec_wiki.py --root . discover --all --json
+spec_wiki.py --root . discover --all-unclassified --limit 40
+```
+
+Produces a heuristic shortlist. `roleHint` is not a semantic classification.
+After recording a page, rerun from offset 0 because the shortlist shrinks.
+`--all-unclassified` is a bounded periodic coverage audit: it bypasses candidate
+score for unclassified document-like files while still excluding known
+fixture/skill-resource noise unless forced by config.
+
+### record
+
+```bash
+spec_wiki.py --root . record \
+  --path docs/auth.md \
+  --classification spec \
+  --type as-is \
+  --lifecycle active \
+  --confidence high \
+  --summary "Authentication lifecycle and refresh invariants." \
+  --topic auth --topic sessions \
+  --code src/auth/session.ts \
+  --related-spec docs/oauth.md
+```
+
+`record` updates classification, summary, topics, relationships, unresolved
+references, and the `indexed` source hash. It **does not verify** the entry.
+The first `spec`/`spec-like` record requires explicit `--type` and
+`--lifecycle` (use `unknown` only after semantic inspection cannot decide).
+
+Additional spec relationship flags are repeatable:
+
+```text
+--supersedes PATH
+--superseded-by PATH
+```
+
+`--clear-code` and `--clear-related-specs` remove previously inferred relations;
+explicit source links are re-extracted each time.
+
+### verify
+
+```bash
+spec_wiki.py --root . verify --path docs/auth.md
+```
+
+Run only after semantic review. It hashes the current source and every tracked
+code/test input plus the current relation map and establishes the new verified
+baseline. Missing tracked inputs fail rather than being silently accepted.
+
+### relate
+
+Use `relate` to repair inferred relations without resupplying the full semantic
+record:
+
+```bash
+spec_wiki.py --root . relate --path docs/auth.md --add-code src/auth/refresh.ts
+spec_wiki.py --root . relate --path docs/auth.md --remove-code src/auth/legacy.ts
+```
+
+It also supports add/remove variants for related specs, `supersedes`, and
+`superseded-by`. Explicit relations extracted from the primary source are not
+removed by this command; correct the source document instead. A real relation
+change makes the previous verified baseline non-fresh through `relationsHash`.
+
+### search
+
+```bash
+spec_wiki.py --root . search "session cancellation retry" --limit 8
+spec_wiki.py --root . search "как восстановить историю" \
+  --also "session recovery raw history after compaction" \
+  --also "session recovery tools" --json
+spec_wiki.py --root . search "context gateway" --include-secondary --json
+```
+
+Searches state metadata directly: title, topics, summary, spec path, known code
+relations, related-spec relations, and supersession edges. Exact spec/relation
+paths have strong weight. Relation token scoring uses concrete leaf names rather
+than generic directory segments.
+
+`--also` is repeatable. The CLI scores each formulation independently, then
+merges them deterministically. The intended caller is the current LLM: preserve
+the original request and, for natural-language intents, add 2–3 genuinely
+different English formulations (canonical contract nouns/synonyms plus implied
+failure/invariant vocabulary) without making another model call. Exact paths and
+symbols usually need no expansion.
+
+JSON output includes `confidence`, `catalogFallbackRecommended`,
+`semanticRerankRecommended`, coverage metrics, and per-query match evidence.
+These are routing hints, not semantic proof. The agent still reranks candidates
+from compact metadata. If fallback is recommended, results are empty, or the
+candidate set plainly misses part of the intent, inspect the compact generated
+`index.md` before deciding no relevant spec exists.
+
+Active specs rank above proposed/historical/superseded ones. This is the normal
+retrieval path; reading the entire generated index is a semantic fallback.
+
+### status / audit
+
+```bash
+spec_wiki.py --root . status
+spec_wiki.py --root . audit --json
+```
+
+Reports current/proposed primary count, fresh/unverified/review counts,
+unresolved reference count, missing sources, and new/changed candidates.
+`needs review` counts structural drift/missing sources; cleanly indexed but never
+verified specs are reported separately as `unverified`.
+
+### affected
+
+```bash
+spec_wiki.py --root . affected src/auth/session.ts src/storage
+```
+
+Returns current/proposed primary specs whose source or tracked code relations
+overlap supplied paths. Historical/superseded specs are skipped.
+
+### changes / impact
+
+```bash
+spec_wiki.py --root . changes --json
+spec_wiki.py --root . impact src/auth/session.ts src/auth/refresh.ts --json
+spec_wiki.py --root . impact --base HEAD --json
+```
+
+`changes` reports Git worktree changes, untracked files, and renames while
+excluding Spec Wiki's own state directory.
+
+`impact` is the deterministic post-change maintenance primitive. Explicit paths
+keep it scoped to the current task; with no paths it uses Git changes against
+`--base`. It returns known affected specs, uncovered changed paths, every changed
+document-like file (even score-0), missing/moved tracked specs, and a
+`semanticSweepRequired` flag. Uncovered paths are search seeds for LLM semantic
+impact review, not proof that a spec is missing.
+
+### render
+
+```bash
+spec_wiki.py --root . render
+```
+
+Generates a compact one-line-per-spec routing index. Historical/superseded specs
+and secondary design references are separate sections. Full summaries remain in
+state and are retrieved through `search`.
+
+### remove
+
+```bash
+spec_wiki.py --root . remove --path docs/old-contract.md
+```
+
+Removes metadata only. For a move, record the new path before removing the old.
+
+### validate
+
+```bash
+spec_wiki.py --root . validate
+```
+
+Checks schema/path/hash/relationship safety. Stale/unverified current specs,
+unresolved path hints, and active as-is specs without implementation relations
+are warnings rather than malformed-state errors.

package/skills/spec-wiki/references/maintenance.md

@@ -0,0 +1,134 @@
+# Maintain an existing Spec Wiki
+
+Use for refresh, audit, changed-code impact analysis, missing/moved specs, and
+repair of an existing `.spec-wiki/` knowledge base.
+
+## Routine refresh
+
+1. Run `status`.
+2. Re-read changed primary specs and reclassify changed non-primary documents
+   when `impact` marks them for classification/reclassification.
+3. For `inputs-changed`, inspect the affected behavior against code/tests before
+   updating any spec claim or verified baseline.
+4. Use the focused workflow in `focused-spec.md` when semantic verification is
+   required.
+5. `record` updated metadata/relations first. This does not clear drift.
+6. After semantic verification succeeds, run `verify --path <spec>` to establish
+   the new source/input baseline.
+7. Run `render` and `validate`.
+
+## Mandatory post-change checkpoint
+
+Run this after any **material production-behavior change** before reporting the
+task complete. Skip it for formatting-only/mechanical edits that cannot affect a
+behavioral contract.
+
+1. Prefer the exact paths changed by the current task and run:
+
+   ```bash
+   spec_wiki.py --root . impact <task-paths...>
+   ```
+
+   If task-scoped paths are unavailable, `impact` with no paths inspects the Git
+   working tree against `HEAD`. On an already-dirty worktree this is broader than
+   the current task, so do not attribute unrelated changes to the user task.
+2. Treat every `knownAffected` primary spec as a semantic-review candidate.
+3. Treat every material `uncoveredPath` as a **mandatory semantic impact sweep**,
+   even when `affected` returned nothing. Inspect the changed code/diff, form 2–3
+   distinct English retrieval formulations, run hybrid `search --also ...`, and
+   semantically rerank the compact candidates. Use the catalog fallback described
+   in `query.md` when search recommends it or coverage is incomplete.
+4. If the sweep reveals a previously unknown durable spec→code dependency, repair
+   the relation map with `relate --add-code ...` (or update the source spec's
+   Related files and `record` it). Do not add relations merely because paths share
+   names.
+5. If a tracked relation is obsolete or a file moved, remove/replace only the
+   inferred edge with `relate --remove-code ...`; explicit source links should be
+   corrected in the primary spec itself. Any relation-map change invalidates the
+   old verified baseline until semantic verification succeeds again.
+6. Every changed/new document reported by `impact.changedDocuments` must be
+   classified for the current task **regardless of heuristic score**. A score-0
+   changed `.txt` may still be a real contract.
+7. After semantic review, update affected specs only when their behavioral claims
+   changed. Then `record` changed metadata/source, `verify` each reviewed current
+   spec, `render`, and `validate`.
+
+The checkpoint is successful when material changed paths have either a known and
+reviewed spec relationship or a documented semantic decision that no current spec
+is affected. `affected` alone is never sufficient proof of no impact.
+
+## Freshness states
+
+- `fresh`: source and tracked inputs match the verified hash baseline.
+- `spec-changed`: primary document changed; review summary/classification.
+- `inputs-changed`: tracked implementation input changed; semantic review needed.
+- `spec+inputs-changed`: both changed.
+- `missing-source`: primary source disappeared or moved.
+- `unverified`: no valid semantic-verification baseline.
+
+Never rewrite behavior automatically from `inputs-changed`.
+
+Historical/superseded specs remain searchable knowledge but are not treated as
+current review obligations. Use lifecycle and supersession relations to keep old
+milestone contracts from competing with current specs.
+
+## Impact analysis
+
+Use `affected <paths...>` after code changes to identify specs with known tracked
+relationships to those paths. It is a conservative hint: absence from the
+result does not prove no spec is affected.
+
+Prefer explicit source links. Add inferred implementation relations only after
+inspection; do not guess paths to improve coverage.
+
+Review unresolved path hints reported by `status`/`validate`, especially for
+active as-is specs. A current as-is spec with no tracked implementation inputs
+cannot provide useful automatic drift detection.
+
+`impact` additionally reports changed paths with **no known** current spec
+relationship. Those paths are where semantic discovery is most important.
+
+## New specs and discovery coverage
+
+- A spec created by the current task should be `record`ed immediately; do not wait
+  for a later repository scan.
+- `impact` exposes every changed/new document-like file for classification even
+  when normal discovery heuristics would rank it below the candidate threshold.
+- Routine `status` still discovers ordinary new/changed high-signal spec
+  candidates across the repository.
+- Before releases, after large refactors, or when coverage is in doubt, run a
+  **bounded deep coverage audit**:
+
+  ```bash
+  spec_wiki.py --root . discover --all-unclassified --limit 40
+  ```
+
+  This intentionally bypasses the heuristic threshold for unclassified document-
+  like files. Page it carefully on large repositories and classify only after
+  reading the document itself. This is the safety net for committed low-signal
+  specs that are no longer visible in the current Git diff.
+
+## Missing or moved specs
+
+- Confirmed deletion: `remove --path <old-path>` removes metadata only.
+- Move: `impact` reports the old tracked source as missing and the new document
+  as a classification candidate. Record the new source first, preserve/repair its
+  relations and lifecycle, verify it, then remove the old metadata entry.
+
+## Safety
+
+- Primary specs remain the source of truth.
+- Do not modify existing project indexes merely to satisfy Spec Wiki.
+- Do not normalize arbitrary specs into a mandatory format.
+- Hash freshness is structural, not semantic correctness.
+- Verified freshness also fingerprints the relation map. Adding/removing tracked
+  inputs invalidates the previous baseline even when no source/code bytes changed.
+- Preserve manual classifications unless source/evidence justifies a change.
+
+## Report back
+
+Summarize wiki path, primary-spec count, unclassified candidates, specs needing
+review and why, missing/moved sources, and whether primary specs or production
+code were modified.
+
+For exact command/config/state details, read `index-schema.md`.

package/skills/spec-wiki/references/query.md

@@ -0,0 +1,74 @@
+# Query existing spec knowledge
+
+Use this mode to find relevant specs or answer a question grounded in existing
+specifications without loading the whole corpus.
+
+## If `.spec-wiki/` exists
+
+1. Turn the user's intent into a small retrieval bundle **in the current model**;
+   do not make a separate model call. Keep the original query. For ordinary
+   natural-language requests add **2–3 genuinely different** concise English
+   aliases rather than echoing the same words:
+   - behavior → canonical contract nouns/synonyms (`recover` → `recovery`,
+     `wrong session update` → `async ownership lifecycle concurrency`);
+   - failure/invariant vocabulary implied by the request (`prompt caching` →
+     `cache stability`, `cannot delete before provider` → provider-seen/result
+     retention);
+   - likely component terminology only when the request itself gives enough
+     evidence.
+   For non-English requests, always include at least one English behavior alias
+   and one compact contract-noun alias. Exact symbols or file paths are already
+   strong retrieval keys and may be searched without extra aliases. Do not invent
+   a feature name merely to make search easier.
+2. Run one deterministic search with the bundle, for example:
+
+   ```bash
+   spec_wiki.py --root . search "<original>" \
+     --also "<behavior alias>" \
+     --also "<component/contract alias>" \
+     --limit 8 --json
+   ```
+
+   Search uses title/topics/summary/spec path plus known code/spec/supersession
+   relations. Exact relation paths receive strong weight.
+3. Semantically rerank the returned candidates yourself from their compact
+   metadata. Numeric score is candidate generation, not the final truth. Prefer
+   entries that satisfy the whole intent, not entries matching one repeated
+   domain word.
+4. If `catalogFallbackRecommended` is true, search returns nothing, or the top
+   candidates plainly miss an important part of the request, read the compact
+   `.spec-wiki/index.md` and select candidates semantically from the catalog.
+   **Never conclude that no relevant spec exists from lexical search alone.**
+5. Prefer `active` entries over `proposed`, `historical`, or `superseded` ones.
+   Use `--include-secondary` only when design/decision context is useful.
+6. Read the selected primary source documents before making detailed claims.
+   When uncertain, read a few plausible specs rather than silently dropping one.
+7. If a selected spec is `unverified`, say that its semantic baseline has not
+   been established. If it is `inputs-changed`, `spec-changed`, or otherwise stale,
+   warn about freshness and use `focused-spec.md` when semantic verification is
+   needed.
+
+Do not run `status` before every narrow query: each search result already carries
+its freshness status. Use `status` for broad wiki-health/audit questions.
+
+Do not treat `index.md` summaries as primary evidence when the source spec is
+available.
+
+## If no wiki exists
+
+For a narrow question, search only for likely relevant specs and answer from
+those sources. Do **not** bootstrap the full wiki unless the user asks for an
+inventory/index or broad spec discovery.
+
+## Existing project indexes
+
+An existing README, overview, spec catalog, or TOC may be used as a discovery
+hint, but its summaries are not primary spec knowledge. Follow links to the
+underlying documents and ground claims there.
+
+## Freshness
+
+`fresh` means known source/input hashes match an **explicit semantic-verification
+baseline**. Bootstrap/classification alone produces `unverified`, never `fresh`.
+
+`inputs-changed` is a review request, not proof of drift.