diff --git a/CHANGELOG.md b/CHANGELOG.md index bca0d4b..6222e9e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,21 +6,21 @@ All notable changes to this project will be documented in this file. ### Bug Fixes -- *(test)* Resolve clippy cloned_ref_to_slice_refs warnings -- *(parser)* Prevent block name overwrite by subsequent headings -- *(vsix)* Resolve npm vulnerabilities and enable ci check (#72) -- *(devcontainer)* Propagate CI env var for startup optimization (#84) +- _(test)_ Resolve clippy cloned_ref_to_slice_refs warnings +- _(parser)_ Prevent block name overwrite by subsequent headings +- _(vsix)_ Resolve npm vulnerabilities and enable ci check (#72) +- _(devcontainer)_ Propagate CI env var for startup optimization (#84) - Add tmux to devcontainer and fix remoteUser (#93) - Improve devcontainer configuration (#98) ### Features -- *(docker)* Optimize image size & fix CI environment (#86) +- _(docker)_ Optimize image size & fix CI environment (#86) - Enhance template validation (DG007) and standardize use cases (#87) -- *(core)* Implement DG007 template validation and fix templates (#88) +- _(core)_ Implement DG007 template validation and fix templates (#88) - Refactor Configuration Specs and Enforce Strict Dependencies (#90) - Semantic error messages and traceability refactoring (#94) -- *(cli)* Improve type, describe, and list command output (#95) +- _(cli)_ Improve type, describe, and list command output (#95) - Enhance validate skill with template and structure checks - Enhance file placement validation with consistency checks - Add SRP check to validate skill @@ -39,17 +39,17 @@ All notable changes to this project will be documented in this file. ### Miscellaneous Tasks - Update dependencies -- *(deps)* Bump actions/download-artifact from 4 to 7 (#73) -- *(deps)* Bump actions/checkout from 4 to 6 (#74) -- *(deps)* Bump actions/upload-artifact from 4 to 6 (#78) -- *(deps-dev)* Bump @types/node from 25.1.0 to 25.2.1 in /vsix (#77) -- *(deps)* Bump github/codeql-action from 3 to 4 (#76) -- *(deps-dev)* Bump @biomejs/biome from 2.3.13 to 2.3.14 in /vsix (#79) -- *(ci)* Suppress git init default branch warning (conflict resolved) (#83) -- *(devcontainer)* Wrap dev setup in CI check for startup optimization (#82) -- *(deps)* Bump the dependencies group with 2 updates (#80) -- *(deps-dev)* Bump @types/vscode from 1.108.1 to 1.109.0 in /vsix (#75) -- *(deps)* Bump lsp-types from 0.94.1 to 0.97.0 in the dependencies group (#89) +- _(deps)_ Bump actions/download-artifact from 4 to 7 (#73) +- _(deps)_ Bump actions/checkout from 4 to 6 (#74) +- _(deps)_ Bump actions/upload-artifact from 4 to 6 (#78) +- _(deps-dev)_ Bump @types/node from 25.1.0 to 25.2.1 in /vsix (#77) +- _(deps)_ Bump github/codeql-action from 3 to 4 (#76) +- _(deps-dev)_ Bump @biomejs/biome from 2.3.13 to 2.3.14 in /vsix (#79) +- _(ci)_ Suppress git init default branch warning (conflict resolved) (#83) +- _(devcontainer)_ Wrap dev setup in CI check for startup optimization (#82) +- _(deps)_ Bump the dependencies group with 2 updates (#80) +- _(deps-dev)_ Bump @types/vscode from 1.108.1 to 1.109.0 in /vsix (#75) +- _(deps)_ Bump lsp-types from 0.94.1 to 0.97.0 in the dependencies group (#89) - Integrate prettier for markdown formatting (#96) - Migrate slash commands to antigravity skills - Remove redundant docgraph skill and simplify align/refine skills @@ -63,18 +63,17 @@ All notable changes to this project will be documented in this file. ### Performance -- *(ci)* Implement granular steps with persistent workspace cache (#85) +- _(ci)_ Implement granular steps with persistent workspace cache (#85) ### Refactor - Replace rumdl with custom pulldown-cmark parser and restore rules -- *(lsp)* Remove tower-lsp and optimize dependencies (#69) +- _(lsp)_ Remove tower-lsp and optimize dependencies (#69) ### Ci - Use devcontainers/ci for release workflow (#70) -- *(dependabot)* Add zed-extension config (#71) - +- _(dependabot)_ Add zed-extension config (#71) ## [0.2.1] - 2026-02-06 @@ -89,36 +88,36 @@ All notable changes to this project will be documented in this file. - Dummy bench file and doc lints - Move CARGO_TARGET_DIR to user home to fix permission denied in CI - Move CARGO_HOME to user home to resolve registry permission errors -- *(ci)* Add packages:read permission to CI workflow for GHCR cache access -- *(ci)* Add explicit ghcr login and use full image URL for cache -- *(ci)* Pre-build debug dependency artifacts in Dockerfile to speed up CI -- *(zed)* Update zed_extension_api to 0.7.0 and bind to Markdown language +- _(ci)_ Add packages:read permission to CI workflow for GHCR cache access +- _(ci)_ Add explicit ghcr login and use full image URL for cache +- _(ci)_ Pre-build debug dependency artifacts in Dockerfile to speed up CI +- _(zed)_ Update zed_extension_api to 0.7.0 and bind to Markdown language - Optimize devcontainer build config (#65) ### Documentation -- *(zed)* Add zed extension design and update installation guide -- *(zed)* Separate zed installation into dedicated use case and add settings guide -- *(readme)* Update zed installation guide and reorder options +- _(zed)_ Add zed extension design and update installation guide +- _(zed)_ Separate zed installation into dedicated use case and add settings guide +- _(readme)_ Update zed installation guide and reorder options ### Features - Consolidate development norms and add OSS constraint - Use GHCR for pre-built dev container for faster setup -- *(lsp)* Implement real-time diagnostics and decouple core -- *(zed)* Add zed extension, update docs and workflow +- _(lsp)_ Implement real-time diagnostics and decouple core +- _(zed)_ Add zed extension, update docs and workflow ### Miscellaneous Tasks - Set default user to vscode in Dockerfile - Remove zed-extension/target from git and add .gitignore - Cleanup zed-extension artifacts and update .gitignore -- *(release)* Automate CHANGELOG.md generation and commitment -- *(release)* Bump version to 0.2.1 (#62) -- *(release)* Allow release to continue if changelog push fails (#63) -- *(release)* Remove zed extension from release and ci (#64) +- _(release)_ Automate CHANGELOG.md generation and commitment +- _(release)_ Bump version to 0.2.1 (#62) +- _(release)_ Allow release to continue if changelog push fails (#63) +- _(release)_ Remove zed extension from release and ci (#64) - Refine release workflow and documentation (#66) -- *(release)* Prepare v0.2.1 (#67) +- _(release)_ Prepare v0.2.1 (#67) ### Performance @@ -135,7 +134,7 @@ All notable changes to this project will be documented in this file. ### Bug Fixes - Ci failures (rustfmt and package-lock.json) -- *(vscode)* Update @types/node to 20 and sync lockfile +- _(vscode)_ Update @types/node to 20 and sync lockfile - Resolve unused variable warning - Ignore anchors and links inside code fences - Strip ID prefix from node name in headings @@ -147,7 +146,7 @@ All notable changes to this project will be documented in this file. - Enforce ACT must be referenced by UC, update UC-WRITE actor - Clippy warnings - Run cargo fmt to resolve CI formatting failures -- *(cli)* Resolve clippy warning in glob_to_regex +- _(cli)_ Resolve clippy warning in glob_to_regex - Format code with cargo fmt - Ignore IDs and references inside code blocks - Format code with cargo fmt @@ -155,24 +154,24 @@ All notable changes to this project will be documented in this file. - Resolve clippy lint errors and borrow checker issues - Split cargo llvm-cov to support both lcov and html - Resolve TOML parse error in docgraph.toml -- *(lsp)* Pass ignore config and add SECURITY.md to ignore list +- _(lsp)_ Pass ignore config and add SECURITY.md to ignore list - Resolve clippy and fmt issues -- *(ci)* Fix clippy warnings and include all files +- _(ci)_ Fix clippy warnings and include all files - Apply cargo fmt to CLI handlers - Allow dead_code in common test utilities to fix CI failure - Consolidate LSP tests and fix formatting - Resolve unused code warnings by moving helpers and removing allow(dead_code) - Resolve deprecation warnings for assert_cmd and fix CI failure - Resolve all E2E test failures and deprecation warnings -- *(core)* Ignore anchors and links within inline code and code blocks +- _(core)_ Ignore anchors and links within inline code and code blocks - Resolve clippy warnings and formatting issues - Resolve clippy manual_pattern_char_comparison lints - Robust rename handler logic -- *(lsp)* Resolve overlapping edits and canonicalize paths in rename +- _(lsp)_ Resolve overlapping edits and canonicalize paths in rename - Resolve clippy lints and syntax errors in LSP handlers -- *(core)* Resolve collapsible_if clippy warning in walk.rs -- *(lsp)* Include ID in symbol names for workspace/document symbol search -- *(test)* Update DG004 unit tests to match new function signature +- _(core)_ Resolve collapsible_if clippy warning in walk.rs +- _(lsp)_ Include ID in symbol names for workspace/document symbol search +- _(test)_ Update DG004 unit tests to match new function signature - Replace verify command with type refinement workflow - Update docgraph.toml to explicitly define UC reference rules - Add --force to cargo install in devcontainer.json to avoid prompts @@ -235,7 +234,7 @@ All notable changes to this project will be documented in this file. - Register new rules and dependencies - Add architecture node types (CTX, BB, RT, DEP, CC) - Finalize all reference rules and direction alignment -- *(dg003)* Add strict file link validation with auto-fix +- _(dg003)_ Add strict file link validation with auto-fix - Add list command with prefix matching support - Add trace command with up/down direction support - Add describe command for bidirectional relationship view @@ -255,14 +254,14 @@ All notable changes to this project will be documented in this file. - Implement error handling strategy with thiserror and anyhow - Implement E2E testing strategy with assert_cmd - Introduce Biome for VSIX project and update CI/CD -- *(cli)* Add type subcommand to display node types +- _(cli)_ Add type subcommand to display node types - Optimize lint performance by refactoring DG004 - Add CLI wrapper commands to docgraph-plugin - Add verify workflow command - Add refine-type workflow command - Add tidy workflow command - Add dev container configuration and update developer guide -- *(devcontainer)* Add Claude Code installation and configuration +- _(devcontainer)_ Add Claude Code installation and configuration - Add github release workflow and changelog configuration - Add installation scripts for macOS/Linux and Windows @@ -272,12 +271,12 @@ All notable changes to this project will be documented in this file. - Final formatting and lint fixes for describe command - Update Cargo.lock for LSP dependencies - Security hardening (CI audit, permissions, policy) -- *(deps)* Bump softprops/action-gh-release from 1 to 2 +- _(deps)_ Bump softprops/action-gh-release from 1 to 2 - Refactor ci.yml for efficiency and speed - Parallelize ci jobs (lint and test) -- *(deps)* Bump toml in the dependencies group +- _(deps)_ Bump toml in the dependencies group - Cleanup redundant release workflow and refine coverage visibility -- *(deps)* Bump actions/checkout from 4 to 6 +- _(deps)_ Bump actions/checkout from 4 to 6 - Relocate security policy to root as SECURITY.md - Rename doc/devel/README.md to guide.md - Split core_workflows.md and remove tests @@ -287,19 +286,19 @@ All notable changes to this project will be documented in this file. - Rename markdown files to use kebab-case - Replace test_data with real docs in CI and guide - Remove empty tests directory -- *(core)* Improve coverage and fix warnings +- _(core)_ Improve coverage and fix warnings - Add blank lines for readability in SECURITY.md - Rename all IDs to underscore-separated format - Sync remaining LSP handlers with ID renaming -- *(deps)* Bump actions/upload-artifact from 4 to 6 -- *(deps-dev)* Bump @types/node from 16.18.126 to 25.1.0 in /vsix -- *(deps)* Bump vscode-languageclient from 8.1.0 to 9.0.1 in /vsix -- *(deps-dev)* Bump typescript from 4.9.5 to 5.9.3 in /vsix -- *(deps-dev)* Bump @vscode/vsce from 2.32.0 to 3.7.1 in /vsix +- _(deps)_ Bump actions/upload-artifact from 4 to 6 +- _(deps-dev)_ Bump @types/node from 16.18.126 to 25.1.0 in /vsix +- _(deps)_ Bump vscode-languageclient from 8.1.0 to 9.0.1 in /vsix +- _(deps-dev)_ Bump typescript from 4.9.5 to 5.9.3 in /vsix +- _(deps-dev)_ Bump @vscode/vsce from 2.32.0 to 3.7.1 in /vsix - Cleanup unused shell scripts and update documentation - Enforce strict consistency rules for Use Cases in docgraph.toml - Run docgraph check --fix -- *(devcontainer)* Optimize startup speed using cargo-binstall +- _(devcontainer)_ Optimize startup speed using cargo-binstall - Bump version to 0.2.0 ### Refactor diff --git a/docgraph-plugin/skills/align/SKILL.md b/docgraph-plugin/skills/align/SKILL.md index c2ba688..ad1b606 100644 --- a/docgraph-plugin/skills/align/SKILL.md +++ b/docgraph-plugin/skills/align/SKILL.md @@ -5,25 +5,29 @@ description: Deep Consistency Gate - Verify Vertical and Horizontal relationship # Deep Consistency Gate (Architecture & Meaning) -This skill serves as the **gate for depth and relationship integrity** within the documentation graph. It focuses on ensuring that nodes are not only correct in isolation (as verified by `validate`) but also perfectly aligned with their context (Vertical) and their peers (Horizontal). +This skill serves as the **gate for depth and relationship integrity** within the documentation graph. It focuses on +ensuring that nodes are not only correct in isolation (as verified by `validate`) but also perfectly aligned with their +context (Vertical) and their peers (Horizontal). -> [!IMPORTANT] -> This is an **Architecture & Meaning Gate**. Flag any semantic "fog" (unclear boundaries, implicit assumptions, or overloaded terms). Every node must be fully justified by its context. +> [!IMPORTANT] This is an **Architecture & Meaning Gate**. Flag any semantic "fog" (unclear boundaries, implicit +> assumptions, or overloaded terms). Every node must be fully justified by its context. ## Workflow Steps ### 0. Validation Pre-requisite + - **Level**: STRICT -- **Policy**: +- **Policy**: - If `validate` status is unknown or FAIL -> **STOP** and return FAIL. - Do not re-evaluate surface items (naming, templates) already covered by `validate`. ### 1. Vertical Consistency (Traceability & Context) + - **Level**: STRICT for missing links, HEURISTIC for semantic clarity. - **Vertical Expectations**: - - **Parents (Inbound)**: Define the "Why" (intent, requirement, or goal). - - **This Node**: Defines the "What" at its specific abstraction level. - - **Children (Outbound)**: Define the "How" (realization, implementation, or breakdown). + - **Parents (Inbound)**: Define the "Why" (intent, requirement, or goal). + - **This Node**: Defines the "What" at its specific abstraction level. + - **Children (Outbound)**: Define the "How" (realization, implementation, or breakdown). 1. **Context Check**: Use `docgraph describe ` and verify: - Does the parent node explicitly justify the existence of this node? @@ -32,8 +36,10 @@ This skill serves as the **gate for depth and relationship integrity** within th - Is this node's responsibility fully and exclusively covered by its children? ### 2. Horizontal Consistency (Peer Alignment & MECE) + - **Level**: HEURISTIC -- **Baseline Rule**: Use the dominant pattern among existing peer nodes. Do not invent new abstraction levels unless proposing an explicit refactor. +- **Baseline Rule**: Use the dominant pattern among existing peer nodes. Do not invent new abstraction levels unless + proposing an explicit refactor. 1. **Peer Identification**: Use `docgraph list "_*"`. 2. **Overlap Check**: Verify Mutually Exclusive and Collectively Exhaustive (MECE) status. @@ -41,6 +47,7 @@ This skill serves as the **gate for depth and relationship integrity** within th - Is the granularity consistent with the peer baseline? ### 3. Structural SRP Check + - **Level**: HEURISTIC - **Note**: `validate` checks surface SRP; `align` checks structural SRP (depth, cohesion, and abstraction fit). @@ -48,9 +55,11 @@ This skill serves as the **gate for depth and relationship integrity** within th 2. **Abstraction**: Is the node at the correct level relative to its parents and peers? ### 4. Proposals & Impact Analysis + - **Level**: MANDATORY When proposing changes (Clarify Context, Split, Merge, or Move): + 1. **Affected Nodes**: List all nodes (parents, peers, children) that will be affected. 2. **Re-validation**: Indicate whether `validate` must be re-run for any affected nodes. 3. **Safety**: Ensure no existing references are broken without a remediation plan. @@ -58,34 +67,42 @@ When proposing changes (Clarify Context, Split, Merge, or Move): ## Workflow Cases ### Case 1: TYPE_ID (e.g., FR, MOD) + - Perform a full graph consistency review for the given type. ### Case 2: NODE_ID (e.g., FR_LOGIN) + - **Status**: Focused Refinement. -- Perform a deep analysis specifically for the node and its immediate relations. Do not scan the entire graph unless necessary for baseline identification. +- Perform a deep analysis specifically for the node and its immediate relations. Do not scan the entire graph unless + necessary for baseline identification. ## Alignment Analysis Report + You **must** provide the analysis in the following format: ### Target + - **Node/Scope**: [ID or Type] - **Baseline Peer Pattern**: [Description of dominant convention] ### Consistency Analysis -| Dimension | Check Item | Result | Analysis / Evidence | -|:---|:---|:---|:---| -| **Prerequisite** | Validate PASS | PASS/FAIL | | -| **Vertical** | Parents (Why) | PASS/FAIL | | -| **Vertical** | Children (How) | PASS/FAIL | | -| **Horizontal** | Peer MECE | PASS/FAIL | | -| **SRP** | Abstraction Fit | PASS/FAIL | | + +| Dimension | Check Item | Result | Analysis / Evidence | +| :--------------- | :-------------- | :-------- | :------------------ | +| **Prerequisite** | Validate PASS | PASS/FAIL | | +| **Vertical** | Parents (Why) | PASS/FAIL | | +| **Vertical** | Children (How) | PASS/FAIL | | +| **Horizontal** | Peer MECE | PASS/FAIL | | +| **SRP** | Abstraction Fit | PASS/FAIL | | ### Refinement Proposals + - **Proposal**: [Description] - **Affected IDs**: [List] - **Re-validate Required**: [Yes/No] ### Quality Gate Checklist + In your final report, you **must** include this checklist to demonstrate deep architectural verification: - [ ] **Prerequisite PASS**: The node has successfully cleared the `validate` skill (Quality Gate). @@ -95,7 +112,9 @@ In your final report, you **must** include this checklist to demonstrate deep ar - [ ] **Impact Analysis**: All affected nodes are listed, and re-validation needs are clearly stated. ## Final Decision + ### Decision Semantics + - **PASS**: Node shows deep integrity and may be merged/applied. - **FAIL**: Structural or semantic issues identified. MUST NOT be merged. diff --git a/docgraph-plugin/skills/ask/SKILL.md b/docgraph-plugin/skills/ask/SKILL.md new file mode 100644 index 0000000..e400b7f --- /dev/null +++ b/docgraph-plugin/skills/ask/SKILL.md @@ -0,0 +1,109 @@ +--- +name: ask +description: Documentation Graph Query & Exploration - Find, investigate, and answer questions about the graph. +--- + +# Documentation Graph Query & Exploration + +This skill provides a structured methodology for exploring the documentation graph and answering specific questions +about its contents, relationships, and structure. It emphasizes using `docgraph` specific tools over general text search +(grep) to leverage the semantic structure of the graph. + +> [!TIP] Use this skill whenever you need to understand "how things are connected", "where a requirement is defined", or +> "what is the impact of a change". + +## Exploration Tools + +### 1. `docgraph list` (Discovery) + +Use to find nodes matching a pattern or within a scope. + +- **Usage**: `docgraph list ""` +- **Example**: `docgraph list "FR_LOGIN_*"` +- **Benefit**: Quickly identifies relevant IDs without wading through raw file content. + +### 2. `docgraph type` (Structural Context) + +Use to understand the expected schema and constraints of a specific node type. + +- **Usage**: `docgraph type ` +- **Example**: `docgraph type FR` +- **Benefit**: Reveals what sections and dependencies are mandatory or optional. + +### 3. `docgraph describe` (Deep Dive) + +Use to retrieve the full content and immediate relations of a specific node. + +- **Usage**: `docgraph describe ` +- **Example**: `docgraph describe FR_LOGIN_001` +- **Benefit**: Provides a unified view of the node's text and its incoming/outgoing edges. + +### 4. `docgraph trace` (Impact & Lineage) + +Use to follow a chain of relationships (e.g., from requirement to code, or dependency tree). + +- **Usage**: `docgraph trace --direction ` +- **Example**: `docgraph trace FR_LOGIN_001 --direction down` +- **Benefit**: Visualizes the full path of derivation or satisfaction. + +### 6. Semantic Inference & Terminology Deduction (Cognitive Tool) + +Don't just look for matches; analyze how terms are used. + +- **Contextual Deduction**: If a term is used in multiple `FR` nodes related to "Auth", it likely refers to an + authentication concept. +- **ID Mnemonics**: Use the prefix and mnemonic structure (e.g., `API-BILL-*`) to infer the scope of a term. +- **Relational Meaning**: A node that "realizes" an `IF` (Interface) is likely an implementation detail (Module). + +### 5. `grep` (Keyword Fallback) + +Use only when you don't have a specific ID or node type to start with. + +- **Usage**: `grep -r "keyword" doc/` +- **Benefit**: Finds mentions of terms that aren't formal IDs. + +--- + +## Workflow Steps + +### 1. Intent Clarification + +Identify the core of the question: + +- **Structural**: "What is required for a Functional Requirement?" -> Use `type`. +- **Existence**: "Do we have a requirement for SSO?" -> Use `list` or `grep`. +- **Relationship**: "What modules implement the billing interface?" -> Use `describe` or `trace`. + +### 2. Multi-Layer Exploration + +Don't stop at the first finding. Follow the links: + +1. **Find** the starting node (`list`). +2. **Understand** the starting node (`describe`). +3. **Trace** the connections (`trace`) to see how it fits into the broader system. + +### 3. Contextual Synthesis & Inference + +Combine findings from the graph logic with the actual Markdown content. + +- Use `docgraph describe` to see the semantic links. +- Use `view_file` to read the narrative context. +- **Inference**: If a term is mentioned in the text but has no ID, search for related concepts using `list` or `grep` to + see if it's an alias or a broader system component. + +## Query Resolution Report + +When answering, structure your response as follows: + +### Findings Summary + +- **Primary Node(s)**: [ID(s) found] +- **Key Relationships**: [e.g., "Satisfies ADR_001", "Realized by MOD_AUTH"] + +### Detailed Analysis + +Provide the detailed answer built from the gathered context. + +### Navigation Trace (optional) + +If relevant, show the path taken: `FR_001` -> `IF_001` -> `MOD_001` diff --git a/docgraph-plugin/skills/impact/SKILL.md b/docgraph-plugin/skills/impact/SKILL.md new file mode 100644 index 0000000..b6aa0e5 --- /dev/null +++ b/docgraph-plugin/skills/impact/SKILL.md @@ -0,0 +1,95 @@ +--- +name: impact +description: + Impact Analysis & Ripple Effect Assessment - Evaluate the consequences of adding or changing specifications. +--- + +# Impact Analysis & Ripple Effect Assessment + +This skill defines the process for analyzing the potential consequences of adding, modifying, or removing a +specification node within the documentation graph. It leverages the graph's traceability to identify "ripple effects" +across architectural layers (Requirements, Business, Architecture). + +> [!IMPORTANT] Impact analysis is mandatory before renaming IDs, moving files, or changing core requirement logic to +> ensure the integrity of the entire graph. + +## Assessment Tools + +### 1. `docgraph describe` (Local Impact) + +Identify immediate connections to the node being changed. + +- **Goal**: List all direct inbound and outbound references. +- **Workflow**: `docgraph describe ` and inspect the "Relations" section. + +### 2. `docgraph trace` (Global Ripple Effect) + +Follow the chain of dependencies to the ends of the graph. + +- **Downward Trace**: `docgraph trace --direction down` + - _Identifies_: What modules (`MOD`), interfaces (`IF`), or sub-requirements are forced to change or re-validate. +- **Upward Trace**: `docgraph trace --direction up` + - _Identifies_: What higher-level requirements (`FR`, `NFR`) or architectural decisions (`ADR`) might be affected or + lose their justification. + +### 3. `docgraph check` (Integrity Verification) + +Validate that the proposed change doesn't violate graph rules. + +- **Goal**: Detect broken links (`DG003`), template mismatches (`DG007`), or invalid reference directions (`DG006`). + +--- + +## Analysis Workflow + +### 1. Identify Entry Point + +Define the specific node ID and the nature of the change (Add/Modify/Delete). + +### 2. Upward Impact (Dependencies/Justification) + +Analyze what this node "satisfies" or "derives from". + +- If this node is deleted, are the parent nodes still fully justified? +- If this node is modified, does it still meet the parent's intent? + +### 3. Downward Impact (Satisfaction/Implementation) + +Analyze what "realizes" or "derives from" this node. + +- **Technical Impact**: Which Modules (`MOD`) or Interfaces (`IF`) need implementation changes? +- **Specification Impact**: Are there child requirements that become obsolete or conflicting? + +### 4. Cross-Cutting Impact + +Check for associations with Cross-cutting Concepts (`CC`). + +- Does the change impact global system qualities like "Security" or "Performance"? + +--- + +## Impact Assessment Report + +Structure your findings to provide a clear risk assessment: + +### Change Summary + +- **Target Node**: [ID] +- **Action**: [Add / Modify / Delete] + +### Affected Nodes + +| Layer | ID | Impact Level | Description of Impact | +| :----------- | :-------- | :----------- | :------------------------------------------------------- | +| Requirement | `FR_...` | HIGH/MED/LOW | e.g., "Parent requirement becomes partially unsatisfied" | +| Architecture | `MOD_...` | HIGH/MED/LOW | e.g., "Requires logic change in billing handler" | +| Decision | `ADR_...` | LOW | e.g., "Remains consistent with ADR_001" | + +### Verification Status + +- **Result**: [CLEAN / ERRORS FOUND] +- **Broken References**: [List of IDs or "None"] + +### Remediation Recommendation + +Propose steps to mitigate negative impacts (e.g., "Update `MOD_AUTH` to reflect the new interface"). diff --git a/docgraph-plugin/skills/trace/SKILL.md b/docgraph-plugin/skills/trace/SKILL.md index ba47ad6..d46e351 100644 --- a/docgraph-plugin/skills/trace/SKILL.md +++ b/docgraph-plugin/skills/trace/SKILL.md @@ -5,38 +5,47 @@ description: Realization & Flow Gate - Verify Downstream Traceability and Realiz # Realization & Flow Gate -This skill verifies that a node’s responsibility is fully traceable downstream and ultimately realizable. It focuses on **paths**, ensuring that abstract intent can be traced to concrete realization. +This skill verifies that a node’s responsibility is fully traceable downstream and ultimately realizable. It focuses on +**paths**, ensuring that abstract intent can be traced to concrete realization. -> [!IMPORTANT] -> A node is considered valid only if its intent can be traced through coherent responsibility transitions to at least one **realizable terminal**. A FAIL in `trace` indicates an unrealizable or misleading specification, not merely incomplete documentation. +> [!IMPORTANT] A node is considered valid only if its intent can be traced through coherent responsibility transitions +> to at least one **realizable terminal**. A FAIL in `trace` indicates an unrealizable or misleading specification, not +> merely incomplete documentation. ## Workflow Steps ### 0. Pre-requisites + - **Level**: STRICT -- **Policy**: +- **Policy**: - The target node **MUST** have passed `validate` and `align`. - Do not re-check hygiene (naming, structure) or peer alignment. ### 1. Downstream Expansion (Graph Traversal) + - **Goal**: Enumerate all possible downstream realization paths. - **Process**: 1. Starting from the target node, traverse all outbound relations. 2. Traversal **MUST** be recursive. - 3. Traversal stops when a **terminal type** (project-defined realization boundaries: `BB`, `MOD`, `IF`, `DEP`, `CODE`) is reached or a cycle is detected. + 3. Traversal stops when a **terminal type** (project-defined realization boundaries: `BB`, `MOD`, `IF`, `DEP`, `CODE`) + is reached or a cycle is detected. ### 2. Terminal Reachability Check + - **Purpose**: Ensure at least one path reaches a realizable endpoint. - **Fail Rule**: FAIL if all paths terminate at abstract nodes (FR, UC, ADR) without reaching a terminal boundary. ### 3. Abstraction Level Monotonicity + - **Goal**: Ensure abstraction decreases as we go downstream. - **Rules**: - Abstraction levels: `FR` (High) > `ADR/UC` (Mid) > `MOD/BB` (Low) > `CODE/IF` (Terminal). - No "jump back" to higher abstraction levels is allowed. - - Abstraction may stay the same ONLY if the transition represents an explicit **refinement or decomposition** of responsibility. Lateral transitions without semantic narrowing MUST be flagged. + - Abstraction may stay the same ONLY if the transition represents an explicit **refinement or decomposition** of + responsibility. Lateral transitions without semantic narrowing MUST be flagged. ### 4. Responsibility Preservation (Semantic Continuity) + - **Goal**: Ensure the core intent survives the journey. - **Process**: Identify the semantic core from the target node’s title and primary description. - **Detect**: @@ -45,32 +54,41 @@ This skill verifies that a node’s responsibility is fully traceable downstream - **Silent renaming**: Key terms change without justification. ### 5. Realizability Check (Terminal Adequacy) + - **Goal**: Confirm that the terminal node can actually realize the responsibility. - **Rule**: Terminal nodes must define concrete behavior or interfaces. "Concept-only" terminals are failures. ### 6. Path Sufficiency & Redundancy + - **Check**: **PASS requires at least one fully coherent path.** -- **Check**: Multiple paths must be alternative realizations. Additional incomplete or broken paths MUST still be reported as findings. +- **Check**: Multiple paths must be alternative realizations. Additional incomplete or broken paths MUST still be + reported as findings. ## Trace Analysis Report + You **must** provide the analysis in the following format: ### Target + - **Node**: [ID] - **Terminal Goal**: [e.g., BB_ nodes] ### Trace Summary -| Path | Reaches Terminal | Abstraction OK | Semantic Continuity | Realizable | Failure Cause (if any) | -|:---|:---|:---|:---|:---|:---| -| Path A | PASS/FAIL | PASS/FAIL | PASS/FAIL | PASS/FAIL | [e.g., Stalled at UC, Semantic drift] | -| Path B | ... | ... | ... | ... | ... | + +| Path | Reaches Terminal | Abstraction OK | Semantic Continuity | Realizable | Failure Cause (if any) | +| :----- | :--------------- | :------------- | :------------------ | :--------- | :------------------------------------ | +| Path A | PASS/FAIL | PASS/FAIL | PASS/FAIL | PASS/FAIL | [e.g., Stalled at UC, Semantic drift] | +| Path B | ... | ... | ... | ... | ... | ### Findings + - **Continuity**: [Evidence of drift or preservation from the semantic core] - **Traversal**: [Brief list of identified paths] ## Final Decision + ### Decision Semantics + - **PASS**: At least one path is complete, monotonic, semantically coherent, and realizable. - **FAIL**: All paths break, stall, or drift. diff --git a/docgraph-plugin/skills/validate/SKILL.md b/docgraph-plugin/skills/validate/SKILL.md index 33cc2f2..67ea771 100644 --- a/docgraph-plugin/skills/validate/SKILL.md +++ b/docgraph-plugin/skills/validate/SKILL.md @@ -5,46 +5,56 @@ description: Validation Quality Gate - Ensure project integrity and consistency. # Validation Quality Gate -This skill serves as the **definitive quality threshold** for the documentation graph. It must be executed strictly to ensure that all semantic, structural, and consistency rules are met before finalizing changes. +This skill serves as the **definitive quality threshold** for the documentation graph. It must be executed strictly to +ensure that all semantic, structural, and consistency rules are met before finalizing changes. -> [!IMPORTANT] -> This skill must perform checks **strictly and rigorously**. Accuracy in ID naming, responsibility scope, and template adherence is critical for the integrity of the documentation graph. **Even cosmetic inconsistencies must be flagged.** +> [!IMPORTANT] This skill must perform checks **strictly and rigorously**. Accuracy in ID naming, responsibility scope, +> and template adherence is critical for the integrity of the documentation graph. **Even cosmetic inconsistencies must +> be flagged.** -> [!NOTE] -> For detailed usage and available options of any `docgraph` subcommand, always refer to `docgraph --help` or `docgraph --help`. +> [!NOTE] For detailed usage and available options of any `docgraph` subcommand, always refer to `docgraph --help` or +> `docgraph --help`. ## Workflow Steps ### 0. Automated Check Pre-requisites + - **Level**: STRICT - **Failure Policy**: FAIL immediately if any check fails. Before performing manual semantic checks, ensure all automated validations pass. -1. **Formatting**: Run `npm run format:md -- --check` to verify Markdown style. + +1. **Formatting**: Identify the appropriate Markdown formatter for the project (e.g., Prettier, Biome) and verify + Markdown style (e.g., `npm run format:md -- --check`). 2. **Consistency**: Run `docgraph check` to ensure the internal graph logic is sound. 3. **Rust Integrity**: Run `cargo test` and `cargo clippy` if logic changes are involved. ### 1. Scope Analysis + - **Level**: PREPARATION - **Purpose**: - - Identify peer nodes for comparison (naming, placement, structure). - - Establish the dominant convention (baseline) for the specific node type. + - Identify peer nodes for comparison (naming, placement, structure). + - Establish the dominant convention (baseline) for the specific node type. List elements within the target scope to understand the current state. Use `docgraph list`. ### 2. ID and Title Correspondence + - **Level**: STRICT - **Failure Policy**: FAIL immediately. Verify if the ID mnemonic matches the Title content. + - `FR_LOGIN` -> "User Login" (Correct) - `FR_AUTH` -> "User Login" (Incorrect - too broad or mismatched) ### 3. Prefix Consistency + - **Level**: STRICT - **Failure Policy**: FAIL immediately. Verify if elements in the same category share the same prefix: + - `FR_` (Functional Requirements) - `NFR_` (Non-Functional Requirements) - `UC_` (Use Cases) @@ -55,18 +65,23 @@ Verify if elements in the same category share the same prefix: - `BB_` (Building Blocks) ### 4. File Placement and Categorization + - **Level**: STRICT - **Failure Policy**: FAIL immediately. -- **Rule of Thumb**: Generally, nodes with the same prefix should be grouped in the same file or a specific directory structure. **This is not an exception mechanism.** +- **Rule of Thumb**: Generally, nodes with the same prefix should be grouped in the same file or a specific directory + structure. **This is not an exception mechanism.** Verify if the file location is appropriate for the ID prefix and consistent with baseline nodes identified in Step 1. + - `FR_LOGIN` should be in `doc/requirements/functional/...` ### 5. Template and Structure Validation + - **Level**: STRICT - **Failure Policy**: FAIL immediately. Verify if the node's content follows the defined template and structure rules. + 1. **Retrieve Template**: Use `docgraph type `. 2. **Retrieve Content**: Use `docgraph describe `. 3. **Compare**: @@ -74,51 +89,63 @@ Verify if the node's content follows the defined template and structure rules. - Do list items (dependencies) match the expected patterns? ### 6. Single Responsibility Principle (SRP) Check + - **Level**: HEURISTIC (Judgment required) - **Failure Policy**: FAIL with remediation proposal if violated. Verify if the node represents a single responsibility at the appropriate granularity for its type. + - **Goal**: One ID should correspond to one clear concept or requirement. -- **Check**: Does this node try to address multiple unrelated issues? +- **Check**: Does this node try to address multiple unrelated issues? ### 7. Remediation Safety Rules + - **Level**: MANDATORY Any change to ID or file location **MUST** follow these safety rules: + 1. **Reference Check**: Run `docgraph describe ` and enumerate all inbound/outbound relations. 2. **Impact Assessment**: Verify that proposed changes do not break existing references unless explicitly handled. ### 8. Remediation Proposals + If issues are found, propose: + - **Rename ID**: Suggest a better ID (after Safety Rules). - **Move File**: Suggest moving the definition (after Safety Rules). - **Fix Structure**: Propose adding missing sections or correcting links. - **Split Node**: Propose splitting the node into multiple IDs with narrower scopes. ## Validation Report + You **must** provide the evaluation results in the following format: ### Target + - **Scope**: [e.g., FR_LOGIN] - **Baseline Category**: [e.g., FR_ nodes in doc/requirements/functional/] ### Findings -| Category | Evaluated Item | Result | Notes/Details | -|:---|:---|:---|:---| -| Automated | format:md / check | PASS/FAIL | | -| ID Naming | Mnemonic consistency | PASS/FAIL | | -| Structure | Template adherence | PASS/FAIL | | -| SRP | Single responsibility | PASS/FAIL | | + +| Category | Evaluated Item | Result | Notes/Details | +| :-------- | :-------------------- | :-------- | :------------ | +| Automated | format / check | PASS/FAIL | | +| ID Naming | Mnemonic consistency | PASS/FAIL | | +| Structure | Template adherence | PASS/FAIL | | +| SRP | Single responsibility | PASS/FAIL | | ### Quality Gate Checklist -- [ ] **Automated Checks**: `npm run format:md`, `docgraph check`, etc. + +- [ ] **Automated Checks**: Markdown format, `docgraph check`, etc. - [ ] **ID Naming**: ID is underscore-separated and mnemonic. - [ ] **File Placement**: Consistent with peer baseline. - [ ] **Template Adherence**: All sections from `docgraph type` present. - [ ] **SRP Compliance**: Single responsibility at node level. ## Final Decision + ### Decision Semantics + - **PASS**: Node meets all strict criteria and may be merged/applied. - **FAIL**: Node MUST NOT be merged. Remediation MUST be completed and re-validated.