@dtt_siye/atool 1.1.0

package/skills/doc-standards-enforcer/examples/valid-document-example.md

@@ -0,0 +1,67 @@
+---
+doc_id: PROD-IA-0201
+title: Inspection Agent Project Brief
+status: approved
+owner: PM
+last_updated: 2026-01-09
+related_docs:
+  - docs/200-product/200-index.md
+  - docs/100-standards/101-documentation-standards.md
+---
+
+## Purpose
+
+This document provides a brief overview of the Inspection Agent project, including its objectives, scope, and key stakeholders. It serves as the entry point for understanding the project's vision and direction.
+
+## Project Overview
+
+### Objectives
+
+The Inspection Agent project aims to develop a comprehensive inspection system that:
+
+1. Automates inspection workflows
+2. Provides real-time data visualization
+3. Ensures data security and auditability
+4. Supports scalable architecture
+
+### In Scope
+
+- Inspection data collection and processing
+- Admin system for configuration
+- Reporting and analytics dashboards
+- Integration with external systems
+
+### Out of Scope
+
+- Mobile applications (future phase)
+- Third-party API access (Phase 2)
+- Multi-language support (future consideration)
+
+## Stakeholders
+
+| Role | Responsibility |
+|---|---|
+| PM | Product requirements and roadmap |
+| TechLead | Technical architecture and standards |
+| Engineering | Implementation and quality |
+| Operations | Deployment and monitoring |
+
+## Key Deliverables
+
+- Phase 1: Core inspection system
+- Phase 2: Advanced analytics
+- Phase 3: Integration capabilities
+
+## References
+
+- Technical specifications: See docs/400-design/401-system-design.md (architecture overview)
+- Data model: Refer to docs/500-data/501-data-model.md (entity definitions)
+- API documentation: See docs/700-engineering/701-api-reference.md (endpoint specifications)
+
+## Version History
+
+| Version | Date | Owner | Change |
+|---|---|---|---|
+| v1.0.0 | 2026-01-09 | PM | Initial approved version |
+| v0.2 | 2026-01-08 | PM | Added stakeholder section |
+| v0.1 | 2026-01-05 | PM | Initial draft |

package/skills/doc-standards-enforcer/references/101-standards-summary.md

@@ -0,0 +1,318 @@
+---
+doc_id: REF-DOC-0101
+title: Documentation Standards Quick Reference
+status: approved
+owner: PM
+last_updated: 2026-01-09
+related_docs:
+  - ../100-standards/101-documentation-standards.md
+---
+
+# Documentation Standards Quick Reference
+
+Quick reference guide for the Inspection Agent project's documentation standards.
+
+## File Naming
+
+### Pattern
+```
+<3-digit-id>-<slug>.md
+```
+
+### Rules
+- **Lowercase only** - No uppercase letters
+- **Kebab-case** - Use hyphens to separate words
+- **No spaces** - Use hyphens instead
+- **No Chinese characters** - ASCII only in filenames
+- **3-digit prefix** - Matches directory structure
+
+### Examples
+- ✓ `201-project-brief.md`
+- ✓ `310-fr-nfr.md`
+- ✓ `701-api-reference.md`
+- ✗ `test.md` (missing 3-digit ID)
+- ✗ `Project-Brief.md` (uppercase)
+- ✗ `201 project brief.md` (spaces)
+- ✗ `201-项目简介.md` (Chinese characters)
+
+## Directory Structure
+
+### Hundreds-Based Directories
+```
+docs/
+├── 100-standards/      # Project standards
+├── 200-product/        # Product documentation
+├── 300-requirements/   # Requirements
+├── 400-design/         # Design documents
+├── 500-data/           # Data documentation
+├── 600-architecture/   # Architecture
+├── 700-engineering/    # Engineering standards
+├── 800-operations/     # Operations
+├── 900-project-mgmt/   # Project management
+└── 990-archive/        # Historical archives
+```
+
+### Naming Pattern
+```
+<hundreds>-<slug>/
+```
+
+### Examples
+- ✓ `100-standards/`
+- ✓ `200-product/`
+- ✓ `300-requirements/`
+
+### File-Directory Matching
+Files should match their directory's hundreds digit:
+- Files in `200-product/` start with `2` (e.g., `201-*.md`)
+- Files in `300-requirements/` start with `3` (e.g., `301-*.md`)
+
+## Frontmatter Template
+
+### Standard Document
+```yaml
+---
+doc_id: XXX-XXX-0100
+title: Document Title
+status: draft
+owner: Your Name
+last_updated: 2026-01-09
+related_docs:
+  - docs/100-standards/101-documentation-standards.md
+---
+```
+
+### User Story
+```yaml
+---
+doc_id: US-XXX-3301
+title: User Story Title
+status: draft
+owner: PM
+last_updated: 2026-01-09
+related_docs:
+  - docs/300-requirements/300-index.md
+us_id: US-IA-0001
+module: IA
+priority: P1
+---
+```
+
+### Required Fields
+
+| Field | Format | Example |
+|---|---|---|
+| `doc_id` | XXX-XXX-#### | STD-DOC-0101 |
+| `title` | Plain text | Documentation Standards |
+| `status` | draft|review|approved|deprecated | draft |
+| `owner` | Role or Name | PM, TechLead |
+| `last_updated` | YYYY-MM-DD | 2026-01-09 |
+| `related_docs` | List of paths or IDs | - docs/100-standards/100-index.md |
+
+### Optional Business Fields
+
+| Field | Format | Example |
+|---|---|---|
+| `us_id` | US-XX-#### | US-IA-0001 |
+| `module` | Module code | IA |
+| `priority` | P0|P1|P2 | P1 |
+
+## Status Values
+
+| Status | Meaning | Chinese |
+|---|---|---|
+| `draft` | Initial draft version | 草稿 |
+| `review` | Under review | 评审中 |
+| `approved` | Approved, can serve as delivery basis | 已批准 |
+| `deprecated` | Deprecated (must reference replacement) | 已废弃 |
+
+### Status Workflow
+```
+draft → review → approved
+              ↓
+         deprecated (with replacement reference)
+```
+
+## Required Sections
+
+Every document must include:
+
+### 1. Purpose/Scope (目的/范围)
+Describe what this document covers and its objectives.
+
+```markdown
+## Purpose
+
+This document defines...
+```
+
+### 2. Main Content (主体内容)
+The primary content of your document.
+
+```markdown
+## Main Content
+
+Your content here...
+```
+
+### 3. Version History (版本历史)
+Table tracking all changes.
+
+```markdown
+## Version History
+
+| Version | Date | Owner | Change |
+|---|---|---|---|
+| v0.1 | 2026-01-09 | Name | Initial version |
+```
+
+## Cross-Document References
+
+### Format
+Use relative paths from repository root:
+
+```markdown
+See docs/500-data/502-data-dictionary.md (field definitions)
+```
+
+### Rules
+- **Path format**: `docs/<hundreds>-<slug>/<file>.md`
+- **Context required**: Explain WHY you're referencing
+- **Clear descriptions**: Add parenthetical context
+
+### Good Examples
+- ✓ `See docs/500-data/502-data-dictionary.md (field definitions)`
+- ✓ `As defined in docs/100-standards/106-engineering-standards.md (tech stack)`
+- ✓ `Refer to docs/300-requirements/310-prd.md (business requirements)`
+
+### Bad Examples
+- ✗ `See docs/500-data/502-data-dictionary.md` (no context)
+- ✗ `Check the data dictionary` (ambiguous)
+
+## Common Mistakes
+
+### 1. Invalid Filename
+❌ `test.md`
+✅ `201-project-brief.md`
+
+### 2. Missing Frontmatter
+❌ Document without YAML block
+✅ Include all required fields
+
+### 3. Invalid Status
+❌ `status: in-progress`
+✅ `status: draft`
+
+### 4. No Version History
+❌ Document ends without table
+✅ Include version history table
+
+### 5. Broken References
+❌ Link to non-existent file
+✅ Verify all `docs/` paths exist
+
+### 6. Chinese in Filename
+❌ `201-项目简介.md`
+✅ `201-project-brief.md`
+
+### 7. Mixed Concerns
+❌ Business requirements + technical implementation in same doc
+✅ Separate business and technical documents
+
+## Index Files
+
+Each directory should have an index file:
+- Pattern: `x00-index.md`
+- Examples: `200-index.md`, `300-index.md`
+
+Purpose: Navigation and directory overview.
+
+## Version History Table Format
+
+```markdown
+| Version | Date | Owner | Change |
+|---|---|---|---|
+| v0.1 | 2026-01-09 | Name | Initial version |
+| v0.2 | 2026-01-10 | Name | Added section X |
+```
+
+### Columns
+- **Version**: Semantic version (v0.1, v0.2, etc.)
+- **Date**: YYYY-MM-DD format
+- **Owner**: Author or role
+- **Change**: Description of changes
+
+## Validation Scripts
+
+### Run Validation
+```bash
+python skills/doc-standards-enforcer/scripts/validate_doc_standards.py <file.md>
+```
+
+### Check References
+```bash
+python skills/doc-standards-enforcer/scripts/check_references.py <file.md>
+```
+
+### Auto-Fix Issues
+```bash
+python skills/doc-standards-enforcer/scripts/fix_common_issues.py <file.md> --interactive
+```
+
+## Document Templates
+
+### Minimal Template
+```markdown
+---
+doc_id: XXX-XXX-0100
+title: Document Title
+status: draft
+owner: Your Name
+last_updated: 2026-01-09
+related_docs:
+  - docs/100-standards/101-documentation-standards.md
+---
+
+## Purpose
+
+Describe the purpose of this document.
+
+## Content
+
+Your content here.
+
+## Version History
+
+| Version | Date | Owner | Change |
+|---|---|---|---|
+| v0.1 | 2026-01-09 | Your Name | Initial version |
+```
+
+## Quick Checklist
+
+Before marking a document complete:
+
+- [ ] Filename follows `<3-digit-id>-<slug>.md` pattern
+- [ ] Directory follows `<hundreds>-<slug>/` pattern
+- [ ] Frontmatter includes all 6 required fields
+- [ ] Status is one of: draft|review|approved|deprecated
+- [ ] Date format is YYYY-MM-DD
+- [ ] Purpose/Scope section exists
+- [ ] Main content exists
+- [ ] Version History table exists
+- [ ] All `docs/` references exist
+- [ ] References include context ("why reference")
+- [ ] No Chinese characters in filename
+- [ ] File is lowercase kebab-case
+
+## Related Standards
+
+- **Full standards**: `100-standards/101-documentation-standards.md`
+- **Agent workflow**: `100-standards/109-agent-llm-guidelines.md`
+- **Repository guide**: `CLAUDE.md`
+
+## Version History
+
+| Version | Date | Owner | Change |
+|---|---|---|---|
+| v1.0.0 | 2026-01-09 | PM | Initial quick reference |

package/skills/doc-standards-enforcer/scripts/check_references.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""
+Documentation Cross-Reference Validator
+
+Validates cross-document references in Markdown files.
+Checks if referenced files exist and provides suggestions for unclear references.
+
+Usage:
+    python check_references.py <file.md>
+    python check_references.py <file.md> --verbose
+"""
+
+import sys
+import re
+from pathlib import Path
+import argparse
+
+
+class Colors:
+    RED = '\033[91m'
+    GREEN = '\033[92m'
+    YELLOW = '\033[93m'
+    BLUE = '\033[94m'
+    RESET = '\033[0m'
+    BOLD = '\033[1m'
+
+
+class ReferenceChecker:
+    """Checks cross-document references in Markdown files."""
+
+    def __init__(self, filepath, repo_root=None, verbose=False):
+        self.filepath = Path(filepath)
+        self.repo_root = Path(repo_root) if repo_root else self.find_repo_root()
+        self.verbose = verbose
+        self.content = None
+        self.references = []
+
+    def find_repo_root(self):
+        """Find repository root by looking for .git or specific directories."""
+        current = self.filepath.parent
+        while current != current.parent:
+            if (current / '.git').exists() or (current / '100-standards').exists():
+                return current
+            current = current.parent
+        return self.filepath.parent.parent  # Fallback
+
+    def check(self):
+        """Run reference checks."""
+        if not self.filepath.exists():
+            self.print_error(f"File not found: {self.filepath}")
+            return False
+
+        try:
+            self.content = self.filepath.read_text(encoding='utf-8')
+        except Exception as e:
+            self.print_error(f"Error reading file: {e}")
+            return False
+
+        # Extract and check references
+        self.extract_references()
+        self.validate_references()
+
+        return self.print_results()
+
+    def extract_references(self):
+        """Extract all docs/ references from the document."""
+        # Pattern: docs/... followed by optional context in parentheses
+        # Examples:
+        # - docs/100-standards/101-documentation-standards.md
+        # - See docs/500-data/502-data-dictionary.md (field definitions)
+        pattern = r'docs/[\w-]+/[\w-]+\.md'
+
+        matches = re.finditer(pattern, self.content)
+
+        for match in matches:
+            ref_path = match.group(0)
+
+            # Extract context (text after reference in parentheses)
+            start = match.end()
+            context_match = re.match(r'\s*\(([^)]+)\)', self.content[start:start+50])
+
+            context = context_match.group(1) if context_match else None
+
+            self.references.append({
+                'path': ref_path,
+                'context': context,
+                'position': match.start()
+            })
+
+        if self.verbose:
+            self.print_info(f"Found {len(self.references)} reference(s)")
+
+    def validate_references(self):
+        """Check if referenced files exist."""
+        for ref in self.references:
+            ref_path = ref['path']
+            full_path = self.repo_root / ref_path
+
+            # Check if file exists
+            if full_path.exists():
+                ref['status'] = 'valid'
+                ref['exists'] = True
+            else:
+                ref['status'] = 'broken'
+                ref['exists'] = False
+
+            # Check if reference has context
+            if ref['context']:
+                ref['has_context'] = True
+            else:
+                ref['has_context'] = False
+                ref['context_warning'] = 'No context provided (explain "why reference")'
+
+    def print_results(self):
+        """Print validation results."""
+        print(f"\n{Colors.BOLD}Reference Check: {self.filepath.name}{Colors.RESET}\n")
+
+        if not self.references:
+            print(f"{Colors.YELLOW}No docs/ references found{Colors.RESET}")
+            return True
+
+        all_valid = True
+        for i, ref in enumerate(self.references, 1):
+            status_icon = '✓' if ref['exists'] else '✗'
+            status_color = Colors.GREEN if ref['exists'] else Colors.RED
+
+            print(f"{i}. {status_color}{status_icon}{Colors.RESET} {ref['path']}")
+
+            if not ref['exists']:
+                all_valid = False
+                print(f"   {Colors.RED}→ File does not exist{Colors.RESET}")
+
+            if not ref['has_context']:
+                print(f"   {Colors.YELLOW}→ No context - explain why this reference is needed{Colors.RESET}")
+                print(f"   {Colors.BLUE}Example: {ref['path']} (field definitions){Colors.RESET}")
+
+        # Summary
+        valid_count = sum(1 for r in self.references if r['exists'])
+        with_context = sum(1 for r in self.references if r['has_context'])
+
+        print(f"\n{Colors.BOLD}Summary:{Colors.RESET}")
+        print(f"  Total references: {len(self.references)}")
+        print(f"  {Colors.GREEN}Valid: {valid_count}{Colors.RESET}")
+        print(f"  {Colors.RED}Broken: {len(self.references) - valid_count}{Colors.RESET}")
+        print(f"  {Colors.BLUE}With context: {with_context}{Colors.RESET}")
+
+        return all_valid
+
+    def print_error(self, message):
+        print(f"{Colors.RED}{message}{Colors.RESET}")
+
+    def print_info(self, message):
+        if self.verbose:
+            print(f"{Colors.BLUE}{message}{Colors.RESET}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Check cross-document references in Markdown files'
+    )
+    parser.add_argument('file', help='Markdown file to check')
+    parser.add_argument('-r', '--repo-root', help='Repository root path')
+    parser.add_argument('-v', '--verbose', action='store_true',
+                       help='Enable verbose output')
+
+    args = parser.parse_args()
+
+    checker = ReferenceChecker(args.file, repo_root=args.repo_root, verbose=args.verbose)
+    valid = checker.check()
+
+    sys.exit(0 if valid else 1)
+
+
+if __name__ == '__main__':
+    main()