syntagmax 2026.7.6__tar.gz

syntagmax-2026.7.6/.gemini/commands/sc.critique.spec.md

@@ -0,0 +1,142 @@
+---
+name: sc.critique.spec.md
+description: Challenge the specification and implementation plan through two distinct expert lenses.
+---
+
+## Goal
+
+Challenge the specification and implementation plan through two distinct expert lenses BEFORE committing to implementation. The **Product Lens** evaluates whether the right problem is being solved in the right way for users. The **Engineering Lens** evaluates whether the technical approach is sound, scalable, and free of hidden risks. This dual review prevents costly mid-implementation pivots and catches strategic and technical blind spots early.
+
+## Operating Constraints
+
+**CONSTRUCTIVE CHALLENGE**: The goal is to strengthen the spec and plan, not to block progress. Every critique item must include a constructive suggestion for improvement.
+
+1. **Product Lens Review** (CEO/Product Lead Perspective):
+
+   Adopt the mindset of an experienced product leader who cares deeply about user value, market fit, and business impact. Evaluate:
+
+   #### 1a. Problem Validation
+   - Is the problem statement clear and well-defined?
+   - Is this solving a real user pain point, or is it a solution looking for a problem?
+   - What evidence supports the need for this feature? (user research, data, customer requests)
+   - Is the scope appropriate — not too broad (trying to do everything) or too narrow (missing the core value)?
+
+   #### 1b. User Value Assessment
+   - Does every user story deliver tangible user value?
+   - Are the acceptance criteria written from the user's perspective (outcomes, not implementation)?
+   - Is the user journey complete — or are there gaps where users would get stuck?
+   - What's the simplest version that would deliver 80% of the value? (MVP analysis)
+   - Are there unnecessary features that add complexity without proportional value?
+
+   #### 1c. Alternative Approaches
+   - Could a simpler solution achieve the same outcome?
+   - Are there existing tools, libraries, or services that could replace custom implementation?
+   - What would a competitor's approach look like?
+   - What would happen if this feature were NOT built? What's the cost of inaction?
+
+   #### 1d. Edge Cases & User Experience
+   - What happens when things go wrong? (error states, empty states, loading states)
+   - How does this feature interact with existing functionality?
+   - Are accessibility considerations addressed?
+   - Is the feature discoverable and intuitive?
+   - What are the onboarding/migration implications for existing users?
+
+   #### 1e. Success Measurement
+   - Are the success criteria measurable and time-bound?
+   - How will you know if this feature is successful after launch?
+   - What metrics should be tracked?
+   - What would trigger a rollback decision?
+
+2. **Engineering Lens Review** (Staff Engineer Perspective):
+
+   Adopt the mindset of a senior staff engineer who has seen projects fail due to hidden technical risks. Evaluate:
+
+   #### 2a. Architecture Soundness
+   - Does the architecture follow established patterns for this type of system?
+   - Are boundaries and interfaces well-defined (separation of concerns)?
+   - Is the architecture testable at each layer?
+   - Are there circular dependencies or tight coupling risks?
+   - Does the architecture support future evolution without major refactoring?
+
+   #### 2b. Failure Mode Analysis
+   - What are the most likely failure modes? (network failures, data corruption, resource exhaustion)
+   - How does the system degrade gracefully under each failure mode?
+   - What happens under peak load? Is there a scaling bottleneck?
+   - What are the blast radius implications — can a failure in this feature affect other parts of the system?
+   - Are retry, timeout, and circuit-breaker strategies defined?
+
+   #### 2c. Security & Privacy Review
+   - What is the threat model? What attack vectors does this feature introduce?
+   - Are trust boundaries clearly defined (user input, API responses, third-party data)?
+   - Is sensitive data handled appropriately (encryption, access control, retention)?
+   - Are there compliance implications (GDPR, SOC2, HIPAA)?
+   - Is the principle of least privilege followed?
+
+   #### 2d. Performance & Scalability
+   - Are there potential bottlenecks in the data flow?
+   - What are the expected data volumes? Will the design handle 10x growth?
+   - Are caching strategies appropriate and cache invalidation well-defined?
+   - Are database queries optimized (indexing, pagination, query complexity)?
+   - Are there resource-intensive operations that should be async or batched?
+
+   #### 2e. Testing Strategy
+   - Is the testing plan comprehensive (unit, integration, E2E)?
+   - Are the critical paths identified for priority testing?
+   - Is the test data strategy realistic?
+   - Are there testability concerns (hard-to-mock dependencies, race conditions)?
+   - Is the test coverage target appropriate for the risk level?
+
+   #### 2f. Operational Readiness
+   - Is observability planned (logging, metrics, tracing)?
+   - Are alerting thresholds defined?
+   - Is there a rollback strategy?
+   - Are database migrations reversible?
+   - Is the deployment strategy clear (blue-green, canary, feature flags)?
+
+   #### 2g. Dependencies & Integration Risks
+   - Are third-party dependencies well-understood (stability, licensing, maintenance)?
+   - Are integration points with existing systems well-defined?
+   - What happens if an external service is unavailable?
+   - Are API versioning and backward compatibility considered?
+
+3. **Cross-Lens Synthesis**:
+   Identify items where both lenses converge (these are highest priority):
+   - Product simplification that also reduces engineering risk
+   - Engineering constraints that affect user experience
+   - Scope adjustments that improve both value delivery and technical feasibility
+
+4. **Severity Classification**:
+   Classify each finding:
+
+   - 🎯 **Must-Address**: Blocks proceeding to implementation. Critical product gap, security vulnerability, or architecture flaw.
+   - 💡 **Recommendation**: Strongly suggested improvement that would significantly improve quality, value, or risk profile. Should be addressed but won't block progress.
+   - 🤔 **Question**: Ambiguity or assumption that needs stakeholder input. Cannot be resolved by the development team alone.
+
+7. **Generate Critique Report**:
+   Ensure the directory `docs/critiques/` exists (create it if necessary), then create the critique report. The report must include:
+
+   - **Executive Summary**: Overall assessment and readiness to proceed
+   - **Product Lens Findings**: Organized by subcategory
+   - **Engineering Lens Findings**: Organized by subcategory
+   - **Cross-Lens Insights**: Items where both perspectives converge
+   - **Findings Summary Table**: All items with ID, lens, severity, summary, suggestion
+
+   **Findings Table Format**:
+   | ID | Lens | Severity | Category | Finding | Suggestion |
+   |----|------|----------|----------|---------|------------|
+   | P1 | Product | 🎯 | Problem Validation | No evidence of user need | Conduct 5 user interviews or reference support tickets |
+   | E1 | Engineering | 💡 | Failure Modes | No retry strategy for API calls | Add exponential backoff with circuit breaker |
+   | X1 | Both | 🎯 | Scope × Risk | Feature X adds complexity with unclear value | Defer to v2; reduces both scope and technical risk |
+
+8. **Provide Verdict**:
+   Based on findings, provide one of:
+   - ⚠️ **PROCEED WITH UPDATES**: Must-address items found but are resolvable.
+   - 🛑 **RETHINK**: Fundamental product or architecture concerns. Recommend revisiting the spec.
+
+9. **Offer Remediation**:
+   For each must-address item and recommendation:
+   - Provide a specific suggested edit to the spec.
+   - Ask: "Would you like me to apply these changes? (all / select / none)"
+   - If user approves, apply changes to the relevant files
+   - After applying changes, recommend re-running critique` to verify.
+

syntagmax-2026.7.6/.gitignore

@@ -0,0 +1,182 @@
+# Custom
+output
+/tmp
+
+# Other agents
+.claude
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+.aider*

syntagmax-2026.7.6/.kiro/prompts/sc.document.md

@@ -0,0 +1,4 @@
+If the changes affect user interfaces or project configuration, make relevant update to the README.md file.
+
+Capture essential session's information in AGENTS.md. Avoid bloating the AGENTS.md. Compress if it grows too big.
+

syntagmax-2026.7.6/.kiro/prompts/sc.save.spec.md

@@ -0,0 +1 @@
+Save the spec in `docs/specs`, but don't implement it yet.

syntagmax-2026.7.6/.kiro/prompts/sc.split.tasks.md

@@ -0,0 +1,2 @@
+Split the final spec into a set of detailed tasks that can be implemented in parallel. Place the results into a set of files in a new subdirectory. Files shall be named as `docs/tasks/<spec-name>/task-<task-number>-<task-name>.md`. Also, add a summary file in the same subdirectory. The summary shall provide guidance for orchestration and parallel execution.
+

syntagmax-2026.7.6/.pin/ruff.md

@@ -0,0 +1 @@
+After a backend task is completed, run the `ruff` linter and ensure that there are no errors or warnings.

syntagmax-2026.7.6/.pin/specs-location.md

@@ -0,0 +1,2 @@
+Place new specification documents in the `docs/specs` folder.  
+Do not add timestamps to spec filenames.

syntagmax-2026.7.6/.pin/tests.md

@@ -0,0 +1 @@
+After a backend task is completed, run the `pytest tests` and ensure that there are no errors or warnings.

syntagmax-2026.7.6/.pin/versioning.md

@@ -0,0 +1 @@
+This project uses Calendar Versioning (CalVer) with the scheme YYYY.M.D (e.g. 2026.7.6).

syntagmax-2026.7.6/.pin/workflow.md

@@ -0,0 +1,43 @@
+## Specification Workflow: Seed vs Full Specs
+
+This project uses a two-stage specification process. Both live under `docs/`.
+
+### Seed Specs (`docs/seed/`)
+
+A seed spec is a **concise, human-written intent document**. It captures:
+- What the user wants (feature intent, desired behavior)
+- Key examples and expected output formats
+- High-level CLI interface or config shape
+- Follow-up tasks (amend README, add examples, etc.)
+
+Seed specs are informal, written in the user's voice, and may contain typos or shorthand. They do **not** include:
+- Detailed implementation guidance
+- Internal data models or code structure
+- Explicit task breakdowns with test requirements
+- Mermaid diagrams or architecture decisions
+- Background on existing codebase internals
+
+A seed spec is the **input** to the design phase.
+
+### Full Specs (`docs/specs/`)
+
+A full spec is a **detailed implementation blueprint** derived from a seed spec. It includes:
+- **Problem Statement**: Precise restatement of the requirement
+- **Requirements**: Exhaustive list of acceptance criteria
+- **Background**: Relevant codebase internals (existing patterns, modules, data structures)
+- **Proposed Solution**: Architecture with Mermaid diagrams, data models, and code sketches
+- **Task Breakdown**: Numbered implementation tasks, each with:
+  - Objective
+  - Implementation guidance (which files, which patterns to follow)
+  - Test requirements (what to assert, which fixtures to use)
+  - Demo command to verify
+
+Full specs are written for an implementer (human or AI) to execute without further clarification.
+
+### Workflow
+
+1. User writes a seed spec in `docs/seed/` to capture intent.
+2. A full spec is produced in `docs/specs/` (either by the user or with AI assistance) that expands the seed into an actionable plan.
+3. Implementation follows the full spec's task breakdown.
+
+When asked to implement a feature, look for both the seed (for intent) and the full spec (for implementation details). If only a seed exists, offer to produce a full spec first.

syntagmax-2026.7.6/.python-version

@@ -0,0 +1 @@
+3.13

syntagmax-2026.7.6/AGENTS.md

@@ -0,0 +1,14 @@
+## OpenWiki
+
+This repository has documentation located in the /openwiki directory.
+
+Start here:
+- [OpenWiki quickstart](openwiki/quickstart.md)
+
+OpenWiki includes repository overview, architecture notes, workflows, domain concepts, operations, integrations, testing guidance, and source maps.
+
+When working in this repository, read the OpenWiki quickstart first, then follow its links to the relevant architecture, workflow, domain, operation, and testing notes.
+
+<!-- pin mcp start -->
+Before staring the first task, fetch all global and project factoids via Pin MCP and use them as **important** instructions. The Pin workspace for this project is `syntagmax`.
+<!-- pin mcp stop -->

syntagmax-2026.7.6/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project uses [Calendar Versioning](https://calver.org/) with the scheme `YYYY.M.D`.
+
+## [2026.7.6] - 2026-07-06
+
+Initial public release.
+
+### Added
+
+- Core analysis pipeline with DAG-based execution (extract → tree → impact → metrics → AI)
+- Obsidian, Markdown, Text, Sidecar, and Jupyter Notebook artifact extractors
+- Metamodel DSL with attribute types: string, integer, boolean (with custom values), enum, and reference
+- Support for multiple attributes, comma-separated enums, and multi-value parent references
+- Hyphens and underscores in attribute identifiers
+- Custom `atype`/`marker` decoupling for input sources
+- Marked text fragments (Obsidian driver): `[COM]`, `[NOTE]`, etc.
+- Git revision extraction via `git blame` for artifact change history
+- Impact analysis: via-commit (revision pinning) and via-timestamp modes
+- Traceability matrix export (CSV/TSV) with forward/reverse, flat mode, left outer join, and plugin hook
+- Publishing pipeline: block-tree rendering to Markdown with Pandoc DOCX/PDF conversion
+- Publishing configuration: per-record output, `--single` consolidated mode, `--date-suffix`
+- Plugin system: local file and package entry-point plugins with `transform_blocks`, `transform_markdown`, and `export_trace` hooks
+- Bulk attribute manipulation (`edit attrs`): add/del/replace with CSV import support
+- Artifact renumbering (`edit renumber`) with configurable ID schemas
+- Unified Markdown report output (errors, tree, metrics, impact, AI analysis)
+- MCP server with `list_artifacts`, `search_artifacts`, and `get_artifact_content` tools
+- `syntagmax init` command for project scaffolding
+- Configurable AI providers: Ollama, Anthropic, OpenAI, Gemini, AWS Bedrock
+- Localisation support (English, Russian) via Babel
+- Project metrics: requirement coverage, TBD detection, status tracking

syntagmax-2026.7.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Flyvercity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.