devspec 0.1.0__py3-none-any.whl

devspec_installer/payload/devspec/foundation/_template/tech-stack.md

@@ -0,0 +1,49 @@
+# Technology Stack
+
+Use this artifact for technology, version, support, hosting, and delivery facts that affect implementation or validation decisions.
+
+## Stack Documentation Policy
+
+| Policy area | Requirement |
+| --- | --- |
+| Evidence sources | Use manifests, lockfiles, framework config, CI config, infrastructure config, and docs as version evidence. |
+| Discovery boundary | Do not inspect dependency folders, generated output, or excluded paths listed in `devspec/foundation/discovery-exclusions.md`. |
+| Inventory scope | Use one stack inventory table per repository, deployable unit, or named project component. |
+| Categories | Use clear categories such as `Language`, `Runtime`, `Framework`, `Library`, `Database`, `Service`, `Tooling`, `Hosting`, or `Delivery Constraint`. |
+| Support status | Record support status from official release, lifecycle, or support pages when practical. |
+| Unknown support | Use `no LTS channel`, `managed service`, or `unknown - needs lookup` instead of defaulting to `n/a`. |
+| Not applicable support | Use `n/a` only when version support does not apply. |
+| Verification date | Fill `Verified on` with the date the version or support status was checked. |
+| Implementation impact | Include guidance when a technology affects coding, validation, hosting, compatibility, or support decisions. |
+| Blocked facts | Record blocked stack, version, support, or hosting details as inventory rows with `blocked` confidence, the evidence gap, and the next action. |
+| Row quality | Omit rows for technologies that are not confirmed, observed, inferred, or blocked by a specific evidence gap. |
+
+## Stack Inventory
+
+### Project: <project-name>
+
+| Category | Technology | Project version or configuration | Support status | Evidence | Confidence | Verified on | Implementation impact or next action |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Runtime | <runtime> | <version> | <lts-version-or-status> | <manifest-or-doc-path> | observed | <yyyy-mm-dd> | <implementation-or-validation-impact> |
+| Framework | <framework> | <version> | <lts-version-or-status> | <manifest-or-config-path> | observed | <yyyy-mm-dd> | <implementation-or-validation-impact> |
+| Service | <service-or-platform> | <version-or-managed-plan> | <managed-service-or-support-status> | <config-or-doc-path> | observed | <yyyy-mm-dd> | <implementation-or-validation-impact> |
+| Delivery Constraint | <blocked-or-unknown-stack-fact> | unknown | unknown - needs lookup | <missing-or-inconclusive-evidence> | blocked | <yyyy-mm-dd> | <next-action-needed> |
+
+## Support Lifecycle References
+
+Maintain this lookup with official release, lifecycle, or support pages. Update these sources when a project uses a different vendor distribution or a better official endpoint becomes available.
+
+| Technology or ecosystem | Official source | Lookup guidance | Verified on |
+| --- | --- | --- | --- |
+| Node.js | https://nodejs.org/en/about/releases/ | Use active or maintenance LTS release lines. | 2026-05-20 |
+| Python | https://devguide.python.org/versions/ | Use supported Python versions; Python does not label releases as LTS. | 2026-05-20 |
+| Java SE | https://www.oracle.com/java/technologies/java-se-support-roadmap.html | Use the vendor-supported LTS line relevant to the chosen JDK distribution. | 2026-05-20 |
+| .NET | https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core | Use releases marked LTS by Microsoft. | 2026-05-20 |
+| Go | https://go.dev/doc/devel/release | Use the supported release policy; Go does not label releases as LTS. | 2026-05-20 |
+| PHP | https://www.php.net/supported-versions | Use actively supported or security-supported PHP branches. | 2026-05-20 |
+| Ruby | https://www.ruby-lang.org/en/downloads/branches/ | Use branches under normal or security maintenance; Ruby does not label releases as LTS. | 2026-05-20 |
+| Angular | https://angular.dev/reference/releases | Use versions marked active or LTS by Angular. | 2026-05-20 |
+| React | https://react.dev/community/versioning-policy | Use React release policy and security maintenance notes; React does not label releases as LTS. | 2026-05-20 |
+| Next.js | https://nextjs.org/support-policy | Use versions covered by the official support policy and LTS policy. | 2026-05-20 |
+| Vite | https://vite.dev/releases | Use the official release policy; Vite does not label releases as LTS. | 2026-05-20 |
+| Laravel | https://laravel.com/docs/releases | Use the official support policy table for bug-fix and security-fix windows. | 2026-05-20 |

devspec_installer/payload/devspec/foundation/codebase-structure.md

@@ -0,0 +1,64 @@
+# Codebase Structure
+
+Use this artifact to help developers and agents decide where work belongs, which repositories are usable, and which boundaries must be preserved. Keep repository trees selective and keep optional tables only when they contain real project facts or unresolved blockers.
+
+## Repository Layouts
+
+Use this section for selective repository trees, up to a maximum of 4-5 levels, that help agents decide where to create, edit, or inspect files. Include important source roots, feature or module folders, tests, scripts, config, infrastructure, docs, and routing-critical files when relevant. Do not list every file. When deeper detail is needed for placement, capture the specific path or rule in `Work Areas and Boundaries` instead of expanding the tree. Omit paths excluded by `devspec/foundation/discovery-exclusions.md` unless a project override marks them source-owned.
+
+Use one `### Repository: <repository-name>` subsection per repository when multiple repositories participate.
+
+### Repository: <repository-name>
+
+```text
+<repository-name>/
+|-- <source-root>/
+|   |-- <feature-or-module>/
+|   |   |-- <components-or-handlers>/
+|   |   `-- <services-or-utils>/
+|-- <tests>/
+|   |-- <unit-or-integration>/
+|   `-- <e2e>/
+|-- <scripts-or-tools>/
+|-- <config-or-infra>/
+|-- <docs>/
+`-- <routing-or-package-file>
+```
+
+## Repository Configuration
+
+Use this section only when multiple repositories participate in delivery, or when a non-default repository path or access limit affects work. Do not omit it for multi-repo sources or dependencies; record missing role, workspace, path, or access facts as blockers instead of dropping the section.
+
+Rows may be seeded from named `/devspec.extract` input such as `UI - D:\repo-ui, API - D:\repo-api`. Use the supplied label as the initial repository name and role candidate, then refine it with evidence or user confirmation.
+
+| Repository | Role | Local path | In current workspace | Access requirement | Evidence | Confidence | Work guidance |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| <repository-name> | <delivery-role> | <local-path-or-unknown> | yes, no, unknown | See `devspec/glossary.md#access-requirement-values` | <input-or-source> | confirmed, observed, inferred, blocked | <how work should use-or-avoid-this-repository> |
+
+Do not infer access from repository location. For missing or ambiguous access requirements, ask the user to confirm one value from `devspec/glossary.md#access-requirement-values` before relying on the row.
+
+## Work Areas and Boundaries
+
+Use this section for internal file-placement decisions: modules, bounded contexts, layers, shared packages, ownership or review routing, and cross-cutting code placement. Put a fact here only when it tells future work where code belongs, who owns it, what must not cross a boundary, or how related code should be grouped. Put external service, API, event, database, or cross-repo contracts in `Integration Contracts` instead.
+
+Common area types include `module`, `feature`, `layer`, `service`, `shared-package`, `cross-cutting`, and `ownership`.
+
+| Scope | Area | Area type | Responsibility | Key paths | Boundary or placement rule | Owner or reviewer | Evidence | Confidence | Work guidance |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| repository:<repository-name> | <area-name> | <area-type> | <primary-responsibility> | <path-or-pattern> | <allowed-dependencies-placement-or-review-rule> | <owner-team-reviewer-or-unknown> | <source-path-or-input> | confirmed, observed, inferred, blocked | <what future work should do> |
+
+## Integration Contracts
+
+Use this section for boundaries between repositories, modules, services, users, data stores, queues, APIs, providers, or external systems. A row belongs here when future work must preserve a protocol, data shape, dependency direction, lifecycle, or validation expectation.
+
+| Source scope | Target or system | Contract or interface | Direction | Data or protocol | Required handling | Evidence | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| repository:<repository-name> | <target-system> | <api-event-db-package-or-user-contract> | inbound, outbound, bidirectional | <data-shape-or-protocol> | <what to preserve-or-validate> | <source-path-or-input> | confirmed, observed, inferred, blocked |
+
+## Structure Gaps and Blockers
+
+Use this section only for missing or conflicting facts that prevent reliable repository selection, file placement, access validation, ownership routing, or integration handling. Do not duplicate normal open risks from work-item artifacts.
+
+| Gap or blocker | Affected section | Impact | Required resolution | Status |
+| --- | --- | --- | --- | --- |
+| <missing-or-conflicting-fact> | Repository Configuration, Work Areas and Boundaries, Integration Contracts, or Repository Layouts | <why agents cannot proceed safely> | <question-evidence-or-access-needed> | open |

devspec_installer/payload/devspec/foundation/coding-standards.md

@@ -0,0 +1,46 @@
+# Coding Standards
+
+Use this artifact as a compact, evidence-backed catalog for how developers should write, test, document, and review code. Prefer source references and short rules over copied prose. Omit optional rows or sections with no real standards or evidence.
+
+## Standards Evidence Sources
+
+Use this section only for source documents, configuration files, or representative code that support one or more catalog rows. Do not infer coding standards from paths excluded by `devspec/foundation/discovery-exclusions.md`, such as installed dependencies or generated output.
+
+| Source | Source type | Applies to | Confidence | Notes |
+| --- | --- | --- | --- | --- |
+| <path-or-link> | formatter, linter, standards-doc, config, source-sample, user-input | <language-framework-layer-or-area> | confirmed, observed, inferred, blocked | <why-this-source-matters> |
+
+## Standards Catalog
+
+Use this as the single place for language, framework, testing, error-handling, logging, documentation, review, observed-pattern, and anti-pattern guidance. Add a row only when the rule changes how developers should write or review code. Keep examples as references to `Standards Examples`, not long snippets in this table.
+
+Use `Type` values as follows:
+- `rule`: explicit standard from a project source, user instruction, or config.
+- `observed-pattern`: recurring style or structure found in source evidence.
+- `anti-pattern`: forbidden or discouraged pattern with the preferred replacement in `Developer guidance`.
+- `expectation`: cross-cutting review or quality expectation that applies across multiple areas.
+
+| ID | Scope | Category | Type | Developer guidance | Evidence | Confidence | Example |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| CS-001 | <language-framework-layer-or-area> | file-naming, formatting, sql-layout, comments, member-ordering, linting, testing, framework, error-handling, logging, documentation, review | rule, observed-pattern, anti-pattern, expectation | <what-to-do-or-avoid-and-preferred-pattern> | <source-id-path-or-link> | confirmed, observed, inferred, blocked | EX-001 or n/a |
+
+## Standards Examples
+
+Include this section only when a short snippet clarifies a style, indentation, naming, grouping, SQL layout, testing pattern, or framework pattern better than a catalog row alone. Keep examples minimal and canonical, usually 5-20 lines. Link each example to one or more catalog row IDs.
+
+### EX-001: <example-name>
+
+Applies to: CS-001
+Source: `<source-path>`
+
+```text
+<short representative snippet>
+```
+
+## Standards Blockers and Conflicts
+
+Use this section only when standards evidence conflicts, required source evidence is missing, or a project decision is needed before agents can apply a standard.
+
+| Topic | Affected catalog row | Conflict or gap | Evidence | Resolution needed | Status |
+| --- | --- | --- | --- | --- | --- |
+| <topic> | CS-001 or new | <conflict-or-gap> | <source-paths-or-input> | <question-or-decision> | open |

devspec_installer/payload/devspec/foundation/discovery-exclusions.md

@@ -0,0 +1,52 @@
+# Discovery Exclusions
+
+Use this file to keep discovery focused on project-owned source, configuration, tests, scripts, infrastructure, and docs.
+
+Apply exclusions before broad search, extraction, code-pattern discovery, layout mapping, generated helper scripts, and validation discovery. Respect repository ignore files as a baseline while still applying this file. Do not infer coding standards, architecture, ownership, or implementation behavior from installed dependencies, generated output, caches, coverage output, VCS internals, or tool output. Use manifests, lockfiles, framework config, CI config, docs, source roots, tests, and scripts as evidence instead. Omit excluded folders from layout maps unless `Project Overrides` includes them.
+
+Record intentional exceptions in `Project Overrides` before relying on normally excluded paths or adding project-specific exclusions.
+
+## Baseline Exclusions
+
+Use these categories for every repository, regardless of ecosystem. Ecosystem rules below add framework-specific patterns and evidence hints; they do not replace these defaults.
+
+| Category | Exclude by default | Reason | Include only if |
+| --- | --- | --- | --- |
+| VCS internals | `.git/`, `.svn/`, `.hg/` | Version-control metadata is not project source. | User explicitly asks for VCS internals. |
+| Generated or build output | `dist/`, `build/`, `out/`, generated artifacts | Output can be stale, duplicated, minified, or machine-produced. | Output is intentionally source-owned and recorded in `Project Overrides`. |
+| Test and coverage output | `coverage/`, `.nyc_output/`, test result folders | Reports are run artifacts, not source conventions. | User asks for coverage or test-output diagnostics. |
+| Cache and temporary output | `.cache/`, `tmp/`, `temp/`, tool caches | Cache content is transient and often huge. | User asks for cache diagnostics. |
+| Local IDE or machine metadata | `.idea/`, `.vscode/`, editor user settings | Local settings usually reflect one machine, not project standards. | Repository standards explicitly depend on these files. |
+| Dependency installs and package caches | Installed dependency folders and package manager caches | Third-party code and package caches should not drive project conventions. | Dependency source inspection is explicitly requested or overridden. |
+
+## Ecosystem Discovery Rules
+
+Use this table after detecting the ecosystem. Exclusions listed here are ecosystem-specific additions to `Baseline Exclusions`. Preferred evidence sources are safe discovery targets unless a project override says otherwise.
+
+| Ecosystem or framework | Detect from | Additional exclusions | Prefer as evidence |
+| --- | --- | --- | --- |
+| JavaScript and TypeScript, Node.js | `package.json`, lockfiles, `.npmrc`, `.yarnrc*`, `pnpm-workspace.yaml` | `node_modules/`, `.npm/`, `.yarn/cache/`, `.pnpm-store/` | `package.json`, lockfiles, `tsconfig*.json`, scripts, source roots, tests |
+| Angular | `angular.json`, `package.json`, `tsconfig*.json` | `.angular/`, `.nx/` | `angular.json`, `tsconfig*.json`, `src/`, `projects/`, tests |
+| React, Vue, Vite, SvelteKit, Astro, Remix | `package.json`, `vite.config.*`, `vue.config.*`, `svelte.config.*`, `astro.config.*`, `remix.config.*` | `.vite/`, `.svelte-kit/`, `.astro/` | framework config, `src/`, `app/`, `pages/`, `components/`, tests |
+| Next.js and Nuxt | `next.config.*`, `nuxt.config.*`, `package.json` | `.next/`, `.nuxt/`, `.output/`, `.vercel/` | framework config, `app/`, `pages/`, `components/`, `server/`, tests |
+| Nx and Turborepo | `nx.json`, `workspace.json`, `project.json`, `turbo.json`, `pnpm-workspace.yaml` | `.nx/`, `.turbo/` | workspace config, project config, package scripts, source roots |
+| .NET SDK, ASP.NET, Blazor, MAUI | `.sln`, `.csproj`, `.fsproj`, `Directory.Build.*`, `global.json` | `bin/`, `obj/`, `TestResults/`, `artifacts/`, `.vs/` | solution, project files, props, targets, app settings, source and tests |
+| JVM: Java, Kotlin, Spring, Maven, Gradle | `pom.xml`, `build.gradle*`, `settings.gradle*`, `gradle.properties`, `src/main/` | `target/`, `.gradle/`, `.mvn/wrapper/maven-wrapper.jar` | build files, wrapper config, `src/`, resources, tests |
+| Python, Django, Flask, FastAPI, pytest, Poetry, uv | `pyproject.toml`, `requirements*.txt`, `setup.py`, `tox.ini`, `poetry.lock`, `uv.lock`, `manage.py` | `.venv/`, `venv/`, `env/`, `__pycache__/`, `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/`, `.tox/`, `site-packages/`, `htmlcov/` | project metadata, lockfiles, app packages, source and tests |
+| PHP, Composer, Laravel, Symfony | `composer.json`, `composer.lock`, `artisan`, `symfony.lock` | `vendor/`, `var/cache/`, `var/log/`, `storage/framework/`, `storage/logs/`, `bootstrap/cache/`, `public/build/` | composer files, framework config, `app/`, `src/`, routes, tests |
+| Ruby, Bundler, Rails | `Gemfile`, `Gemfile.lock`, `.ruby-version`, `config/application.rb` | `vendor/bundle/`, `.bundle/`, `tmp/`, `log/`, `public/assets/`, `storage/` | Gemfile, lockfile, `app/`, `config/`, `lib/`, tests |
+| Go | `go.mod`, `go.work` | module cache, generated `vendor/` unless source-owned, `bin/`, `coverage.out` | `go.mod`, `go.sum`, `go.work`, source and tests |
+| Rust | `Cargo.toml`, `Cargo.lock` | `target/`, `tarpaulin-report.html` | manifests, lockfile, `src/`, tests, benches |
+| Android | `settings.gradle*`, `build.gradle*`, `gradle.properties`, `AndroidManifest.xml` | `.gradle/`, `build/`, `app/build/`, `.cxx/`, `captures/` | Gradle files, manifests, `src/`, resources, tests |
+| iOS, SwiftPM, CocoaPods | `Package.swift`, `*.xcodeproj`, `*.xcworkspace`, `Podfile`, `Cartfile` | `DerivedData/`, `Pods/`, `.build/`, `build/`, `xcuserdata/`, `Carthage/Build/` | package manifests, project/workspace files, `Sources/`, `Tests/`, app source |
+| C/C++, CMake, Bazel, Meson, Make | `CMakeLists.txt`, `WORKSPACE`, `MODULE.bazel`, `BUILD.bazel`, `meson.build`, `Makefile` | `cmake-build-*/`, `bazel-*`, `CMakeFiles/`, generated `compile_commands.json` | build files, `src/`, `include/`, `tests/`, toolchain files |
+| Data and ML: notebooks, MLflow, Weights & Biases, checkpoints | `*.ipynb`, `mlflow.yml`, `wandb/`, `requirements*.txt`, `pyproject.toml` | `.ipynb_checkpoints/`, `mlruns/`, `wandb/`, `checkpoints/`, `models/`, `outputs/`, `runs/`, `lightning_logs/` unless source-owned | notebooks, experiment config, requirements, source modules, tests, docs |
+| Infrastructure as code: Terraform, Terragrunt, Pulumi, CDK, Serverless, Helm, Kustomize | `*.tf`, `.terraform.lock.hcl`, `terragrunt.hcl`, `Pulumi.yaml`, `cdk.json`, `serverless.yml`, `Chart.yaml`, `kustomization.yaml` | `.terraform/`, `.terragrunt-cache/`, `cdk.out/`, `.serverless/`, `.pulumi/`, `tfplan`, `crash.log`, packaged `*.tgz` charts | IaC source, lockfiles, modules, manifests, environment config, docs |
+
+## Project Overrides
+
+Use this table only when a project intentionally owns a normally excluded path or needs an additional exclusion. Overrides must be specific enough that future agents know whether to include the path for evidence, exclude it from broad discovery, or inspect it only for a named purpose.
+
+| Scope | Pattern | Action | Purpose | Confirmed by |
+| --- | --- | --- | --- | --- |
+| <repository-or-area> | <path-or-glob> | include, exclude, include-for-purpose | <why-this-exception-exists> | <user-source-or-date> |

devspec_installer/payload/devspec/foundation/extraction-state.md

@@ -0,0 +1,45 @@
+# Extraction State
+
+Use this artifact only for the `/devspec.extract` queue, resume state, blockers, and confirmations. Keep extracted facts in target artifacts, reusable discovery methods in `devspec/foundation/exploration-state.md`, and diagram queue state in `devspec/architecture/artifact-queue.md`.
+
+## Resume State
+
+| Field | Value |
+| --- | --- |
+| Current stage | extract |
+| Current command | `/devspec.extract` |
+| Current agent | devspec.extract |
+| Run status | See `devspec/glossary.md#run-status-values` |
+| Current task | |
+| Last completed step | |
+| Next required action | |
+| Pending user question | |
+| Recommended option | |
+| Resume command | `/devspec.extract` |
+| Resume notes | |
+| Updated | |
+
+## Extraction Queue
+
+Use status values from `devspec/glossary.md#task-status-values`; keep exactly one row `active` while extraction is running.
+
+| ID | Stage | Target artifact | Evidence focus | Status | Next action | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| EXT-001 | source-and-access | `devspec/foundation/extraction-state.md` | source input, source labels, source validation, access requirements | pending | Validate sources and required access. | |
+| EXT-002 | discovery-preparation | `devspec/foundation/discovery-exclusions.md` | exclusion rules, ignore files, reusable discovery methods | pending | Apply discovery rules before broad search. | |
+| EXT-003 | project-context | `devspec/foundation/project-context.md` | documentation, README files, product signals, user-facing behavior | pending | Extract evidence-backed project context. | |
+| EXT-004 | technology-stack | `devspec/foundation/tech-stack.md` | manifests, lockfiles, runtime configuration, tooling, CI/CD | pending | Extract stack and version evidence. | |
+| EXT-005 | codebase-structure | `devspec/foundation/codebase-structure.md` | layout, modules, work areas, boundaries, integration contracts, multi-repo configuration | pending | Extract placement and boundary guidance. | |
+| EXT-006 | coding-standards | `devspec/foundation/coding-standards.md` | style guides, observed patterns, tests, examples | pending | Extract standards and anti-patterns. | |
+| EXT-007 | rules-and-constraints | `devspec/foundation/rules.md` | compliance, security, delivery gates, operational constraints | pending | Extract actionable rules only. | |
+| EXT-008 | architecture-overview | `devspec/architecture/overview.md` | components, integrations, runtime boundaries, data movement | pending | Extract high-level architecture context. | |
+| EXT-009 | process-flows | `devspec/architecture/artifact-queue.md` | business-centric end-to-end workflows, user journeys, lifecycle flows, cross-service process sequences, hybrid user-to-data operational flow | pending | Queue eligible process-flow diagram candidates. | |
+| EXT-010 | diagram-candidates | `devspec/architecture/artifact-queue.md` | evidence-backed diagram candidates and duplicate checks | pending | Queue eligible non-process-flow diagram candidates. | |
+| EXT-011 | constitution-candidates | `devspec/constitution.md` | durable principle candidates requiring confirmation | pending | Ask before writing principle changes. | |
+| EXT-012 | closure | `devspec/foundation/extraction-state.md` | artifact update summary, blockers, confirmations, next action | pending | Summarize extraction and select one next action. | |
+
+## Blockers and Confirmations
+
+| ID | Kind | Related task | Subject | Required action | Resolution | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+|  | blocker or confirmation |  |  |  |  |  |

devspec_installer/payload/devspec/foundation/project-context.md

@@ -0,0 +1,33 @@
+# Project Context
+
+Use this artifact for durable product facts that should shape future work items. Keep it concise and developer-facing. Omit optional rows or sections with no project content.
+
+## Product Overview
+
+| Field | Description | Source | Confidence |
+| --- | --- | --- | --- |
+| Purpose |  |  |  |
+| Problem |  |  |  |
+| Target outcome |  |  |  |
+
+## Audiences and Stakeholders
+
+| Group | Category | Need or responsibility | Source | Confidence |
+| --- | --- | --- | --- | --- |
+|  |  |  |  |  |
+
+## Outcomes and Scope
+
+Use this section for product goals, explicit scope exclusions, and measurable success signals. Keep operational rules and delivery gates in `rules.md`.
+
+| Type | Outcome, boundary, or metric | Implementation implication | Source | Confidence |
+| --- | --- | --- | --- | --- |
+|  |  |  |  |  |
+
+## Delivery Context
+
+Use this section for product or business constraints and unresolved blockers that affect implementation planning. Keep repository location, access, ownership, and path facts in `codebase-structure.md`.
+
+| Type | Context item | Scope | Required handling or next step | Source | Confidence | Status |
+| --- | --- | --- | --- | --- | --- | --- |
+|  |  |  |  |  |  |  |

devspec_installer/payload/devspec/foundation/provider-integrations.md

@@ -0,0 +1,94 @@
+# Provider Integrations
+
+Use this policy to resolve external work items during `/devspec.story`. Keep provider-specific lookup behind MCP servers or equivalent integration tools. Manual intake is an explicit fallback, available only when provider resolution is unavailable or intentionally skipped.
+
+## Resolution Policy
+
+| Policy area | Requirement |
+| --- | --- |
+| Workflow boundary | Keep work-item intake provider-agnostic; provider-specific lookup belongs in integration tools. |
+| Resolution preference | Prefer exact provider URLs or provider-qualified identifiers over inferred matches. |
+| Ambiguity handling | Ask one structured `clarification` question before resolving an ambiguous provider or identifier. |
+| Manual fallback | Allow manual intake only when external resolution is unavailable and the user explicitly chooses to proceed. |
+| Work-item creation gate | Do not create or update the work-item folder from provider input until the resolved item is shown to the user and explicitly confirmed. |
+| Secret handling | Keep provider authentication, credentials, and secrets outside prompt artifacts. |
+
+## Supported Provider Inputs
+
+| Provider | Preferred input | Accepted shorthand | Validation guardrail |
+| --- | --- | --- | --- |
+| GitHub | Full issue URL or supported pull request URL | `owner/repo#123` | Reject bare numbers unless repository context is configured. |
+| Jira | Full issue URL | Issue key such as `ABC-123` | Reject malformed keys or keys outside configured project patterns. |
+| Azure DevOps | Full work item URL | Numeric ID only with configured organization and project context | Reject numeric IDs when organization or project context is missing. |
+
+## Resolution Flow and Outcomes
+
+Resolve inputs in this order:
+
+| Order | Input path | Required handling |
+| --- | --- | --- |
+| 1 | Full provider URL | Validate format, resolve through the configured provider tool, and request structured confirmation on success. |
+| 2 | Provider-qualified identifier | Validate provider context, resolve through the configured provider tool, and request structured confirmation on success. |
+| 3 | Ambiguous identifier | Ask a structured provider `clarification` question before lookup. |
+| 4 | Manual intake | Continue only after the user explicitly chooses manual intake and supplies required manual fields. |
+
+Handle outcomes as follows:
+
+| Condition | Required handling |
+| --- | --- |
+| Invalid input format | Stop intake and explain why the input is invalid. |
+| Ambiguous provider | Ask one structured `clarification` question to identify the provider. |
+| Known provider cannot resolve item | Stop intake and classify the failure as not found, access denied, or integration unavailable when possible. |
+| Integration unavailable | Offer manual intake as an explicit fallback. |
+| Provider resolution succeeds | Show the confirmation summary and require structured confirmation before creating or updating the work-item folder. |
+| Unverified provider input | Treat as blocked or manual fallback only; do not create a normal resolved work item. |
+
+## Confirmation Requirements
+
+Show this minimum summary when provider resolution succeeds:
+
+| Field | Required |
+| --- | --- |
+| Provider | yes |
+| Identifier | yes |
+| Title | yes |
+| Type | when available |
+| Current external status | when available |
+| Canonical link | yes |
+| Short summary | yes |
+
+Offer only these structured `confirmation` actions:
+
+| Action | Result |
+| --- | --- |
+| Confirm and continue | Continue normal resolved intake. |
+| Reject and retry input | Ask a structured `retry` or source-correction question. |
+| Switch to manual intake | Continue only with manual intake requirements. |
+| Cancel | Stop intake. |
+| Custom Answer | Route to clarification; do not create or update the work-item folder until resolved. |
+
+## Integration Tooling and Access
+
+| Area | Requirement |
+| --- | --- |
+| Tooling model | Use a provider-specific MCP server or one internal MCP server that wraps multiple providers. |
+| Lookup tools | Validate and fetch work items by URL or provider-specific identifier. |
+| Returned data | Include title, description, status, labels or type, links, and relevant metadata. |
+| Failure detail | Distinguish not found, unauthorized, malformed input, and transient provider failures. |
+| Authentication configuration | Keep provider authentication outside prompt artifacts. |
+| Privilege model | Use least-privilege tokens or service identities. |
+| Access mode | Prefer read-only access for intake and review unless write-back is required. |
+
+## Work-Item Intake Recording Requirements
+
+| Recording area | Requirement |
+| --- | --- |
+| Source resolution status | Record a value from `devspec/glossary.md#source-resolution-status-values` in `meta.md`. |
+| Lookup attempt | Record provider and resolution notes. |
+| Manual source status | Use source resolution status `manual` only when the user explicitly chooses to continue without external resolution. |
+| Manual intake | Require external reference, manual description, and manual acceptance criteria. |
+| Resolved items | Require structured confirmation after showing resolved details. |
+| Blocked status | Use when input is invalid or required resolution failed. |
+| Confirmation result | Record it in `meta.md` and record the shown summary in `story.md`. |
+| Provider policy ownership | Keep provider-specific details here instead of duplicating them across prompt files. |
+| Maintenance trigger | Update this file when provider formats, supported tools, authentication expectations, or fallback policy changes. |

devspec_installer/payload/devspec/foundation/rules.md

@@ -0,0 +1,52 @@
+# Operational Rules
+
+Use this artifact for project-operational rules that affect planning, implementation, review, or release. Keep enduring principles in `devspec/constitution.md`; keep product goals and scope boundaries in `project-context.md`.
+
+## Rule Governance
+
+| Boundary | Guidance |
+| --- | --- |
+| Purpose | Record operational constraints, governance requirements, delivery gates, and evolving project rules. |
+| Exclusions | Do not duplicate durable principles from `devspec/constitution.md` or product intent from `project-context.md`. |
+| Record quality | Write actionable records with scope, enforcement point, source, and confidence. |
+| Optional content | Omit rows or sections that have no project-specific content. |
+
+## Operational Rule Catalog
+
+Use this section for hard constraints, compliance requirements, and forbidden patterns. Use `Type` to distinguish the rule kind instead of creating separate overlapping sections.
+
+| Type | Rule | Scope | Requirement or prohibition | Enforcement point | Evidence, rationale, or preferred alternative | Source | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+|  |  |  |  |  |  |  |  |
+
+## Delivery Gate Catalog
+
+| Gate | Applies to | Required evidence | Blocking condition | Source | Confidence |
+| --- | --- | --- | --- | --- | --- |
+|  |  |  |  |  |  |
+
+## Work-Item Handling Rules
+
+Use this section for rules that vary by work-item type or workflow stage. These defaults apply unless a stricter project-specific rule or delivery gate supersedes them.
+
+| Work-item type | Stage | Requirement |
+| --- | --- | --- |
+| bug | Intake and readiness | Capture expected behavior, actual behavior, reproduction steps, impact, and regression context unless blocked. |
+| bug | Planning | Include reproduce, fix, and regression-validation work when practical. |
+| bug | Implementation | Record regression validation and useful before-and-after snippets for code fixes. |
+| bug | Review | Review bugs with meaningful regression risk before closure. |
+| security-vulnerability | Intake and readiness | Capture severity, affected scope, attack surface, exploitability, disclosure status, and containment or remediation plan. |
+| security-vulnerability | Shared artifacts | Minimize or redact sensitive exploit details when full disclosure is unsafe. |
+| security-vulnerability | Planning | Include impact confirmation, remediation, supported-version verification, and follow-up needs when applicable. |
+| security-vulnerability | Implementation | Verify remediation across affected supported versions and record backport, release, or advisory follow-up. |
+| security-vulnerability | Review | Review security vulnerabilities before closure. |
+| all | Review | Check scope adherence, bugs, regressions, missing validation, and rule violations against the finalized brief. |
+| all | Changes requested | Route the work item back to implementation before marking it complete. |
+
+## Exceptions and Waivers
+
+Include this section only when exception handling differs from the normal rules or gates.
+
+| Exception | Affected rule or gate | Approval or handling process | Status | Source |
+| --- | --- | --- | --- | --- |
+|  |  |  | open |  |

devspec_installer/payload/devspec/foundation/tech-stack.md

@@ -0,0 +1,49 @@
+# Technology Stack
+
+Use this artifact for technology, version, support, hosting, and delivery facts that affect implementation or validation decisions.
+
+## Stack Documentation Policy
+
+| Policy area | Requirement |
+| --- | --- |
+| Evidence sources | Use manifests, lockfiles, framework config, CI config, infrastructure config, and docs as version evidence. |
+| Discovery boundary | Do not inspect dependency folders, generated output, or excluded paths listed in `devspec/foundation/discovery-exclusions.md`. |
+| Inventory scope | Use one stack inventory table per repository, deployable unit, or named project component. |
+| Categories | Use clear categories such as `Language`, `Runtime`, `Framework`, `Library`, `Database`, `Service`, `Tooling`, `Hosting`, or `Delivery Constraint`. |
+| Support status | Record support status from official release, lifecycle, or support pages when practical. |
+| Unknown support | Use `no LTS channel`, `managed service`, or `unknown - needs lookup` instead of defaulting to `n/a`. |
+| Not applicable support | Use `n/a` only when version support does not apply. |
+| Verification date | Fill `Verified on` with the date the version or support status was checked. |
+| Implementation impact | Include guidance when a technology affects coding, validation, hosting, compatibility, or support decisions. |
+| Blocked facts | Record blocked stack, version, support, or hosting details as inventory rows with `blocked` confidence, the evidence gap, and the next action. |
+| Row quality | Omit rows for technologies that are not confirmed, observed, inferred, or blocked by a specific evidence gap. |
+
+## Stack Inventory
+
+### Project: <project-name>
+
+| Category | Technology | Project version or configuration | Support status | Evidence | Confidence | Verified on | Implementation impact or next action |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Runtime | <runtime> | <version> | <lts-version-or-status> | <manifest-or-doc-path> | observed | <yyyy-mm-dd> | <implementation-or-validation-impact> |
+| Framework | <framework> | <version> | <lts-version-or-status> | <manifest-or-config-path> | observed | <yyyy-mm-dd> | <implementation-or-validation-impact> |
+| Service | <service-or-platform> | <version-or-managed-plan> | <managed-service-or-support-status> | <config-or-doc-path> | observed | <yyyy-mm-dd> | <implementation-or-validation-impact> |
+| Delivery Constraint | <blocked-or-unknown-stack-fact> | unknown | unknown - needs lookup | <missing-or-inconclusive-evidence> | blocked | <yyyy-mm-dd> | <next-action-needed> |
+
+## Support Lifecycle References
+
+Maintain this lookup with official release, lifecycle, or support pages. Update these sources when a project uses a different vendor distribution or a better official endpoint becomes available.
+
+| Technology or ecosystem | Official source | Lookup guidance | Verified on |
+| --- | --- | --- | --- |
+| Node.js | https://nodejs.org/en/about/releases/ | Use active or maintenance LTS release lines. | 2026-05-20 |
+| Python | https://devguide.python.org/versions/ | Use supported Python versions; Python does not label releases as LTS. | 2026-05-20 |
+| Java SE | https://www.oracle.com/java/technologies/java-se-support-roadmap.html | Use the vendor-supported LTS line relevant to the chosen JDK distribution. | 2026-05-20 |
+| .NET | https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core | Use releases marked LTS by Microsoft. | 2026-05-20 |
+| Go | https://go.dev/doc/devel/release | Use the supported release policy; Go does not label releases as LTS. | 2026-05-20 |
+| PHP | https://www.php.net/supported-versions | Use actively supported or security-supported PHP branches. | 2026-05-20 |
+| Ruby | https://www.ruby-lang.org/en/downloads/branches/ | Use branches under normal or security maintenance; Ruby does not label releases as LTS. | 2026-05-20 |
+| Angular | https://angular.dev/reference/releases | Use versions marked active or LTS by Angular. | 2026-05-20 |
+| React | https://react.dev/community/versioning-policy | Use React release policy and security maintenance notes; React does not label releases as LTS. | 2026-05-20 |
+| Next.js | https://nextjs.org/support-policy | Use versions covered by the official support policy and LTS policy. | 2026-05-20 |
+| Vite | https://vite.dev/releases | Use the official release policy; Vite does not label releases as LTS. | 2026-05-20 |
+| Laravel | https://laravel.com/docs/releases | Use the official support policy table for bug-fix and security-fix windows. | 2026-05-20 |

devspec_installer/payload/devspec/glossary.md

@@ -0,0 +1,111 @@
+# Glossary
+
+Use this file for shared devspec terms and status values.
+
+Status values are scoped. Use a value only in the table named by the consuming artifact. When the same literal appears in more than one table, its meaning is limited to that table's context.
+
+## Workflow State Values
+
+Use these values to track command recovery, work-item lifecycle, and task execution. Do not use workflow state values as review or readiness decisions.
+
+### Run Status Values
+
+Use for the current command or agent run in a `Resume State` or `Workflow State` table.
+
+| Status | Meaning |
+| --- | --- |
+| `active` | Work is in progress. |
+| `waiting-for-user` | Work is paused until the user answers a recorded question. |
+| `paused` | Work is intentionally paused and can resume from the recorded state. |
+| `stopped` | Work stopped without an active resume path. |
+| `blocked` | Required evidence, access, or context is missing. |
+| `complete` | The stage or run is finished. |
+
+### Work-Item Status Values
+
+Use for the durable lifecycle of a work item in `meta.md`. Readiness, review outcomes, blockers, and run interruptions are recorded in their own fields or artifacts, not encoded into the work-item status.
+
+| Status | Meaning |
+| --- | --- |
+| `intake` | Initial work-item capture is in progress. |
+| `clarifying` | The item needs user or source clarification. |
+| `finalized` | Scope is captured; readiness status records whether task planning may proceed. |
+| `tasks-planned` | Implementation tasks are recorded. |
+| `implementing` | Implementation is in progress. |
+| `implemented` | Implementation is complete and awaiting review. |
+| `reviewing` | Review is in progress. |
+| `reviewed` | Review is complete. |
+
+### Task Status Values
+
+Use for executable implementation tasks and implementation task ledgers.
+
+| Status | Meaning |
+| --- | --- |
+| `pending` | Not started. |
+| `active` | In progress. |
+| `paused` | Paused mid-task. |
+| `blocked` | Cannot proceed until a blocker is resolved. |
+| `complete` | Finished. |
+| `skipped` | Intentionally not performed. |
+
+## Decision Values
+
+Use these values for gates and outcomes. They are decisions, not workflow progress markers.
+
+### Readiness Status Values
+
+Use for readiness gates and the overall readiness field. Overall readiness uses `ready` or `not ready`; individual gate rows may use `not applicable` when the gate does not apply.
+
+| Status | Meaning |
+| --- | --- |
+| `ready` | Meets readiness gates. |
+| `not ready` | Missing required information, approval, access, or evidence. |
+| `not applicable` | The readiness gate does not apply to this work item. |
+
+### Review Status Values
+
+Use only for review outcomes.
+
+| Status | Meaning |
+| --- | --- |
+| `approved` | Review found no required changes. |
+| `approved-with-follow-ups` | Review passed with non-blocking follow-ups. |
+| `changes-requested` | Review requires implementation changes. |
+
+### Source Resolution Status Values
+
+Use for intake provenance in `meta.md`.
+
+| Status | Meaning |
+| --- | --- |
+| `resolved` | External source was found and confirmed. |
+| `manual` | User chose manual intake without external resolution. |
+| `blocked` | Source resolution is required but unavailable or invalid. |
+
+### Artifact Status Values
+
+Use for generated or queued devspec artifacts, including architecture diagram queue rows.
+
+| Status | Meaning |
+| --- | --- |
+| `proposed` | Candidate identified from evidence. |
+| `confirmed` | User approved generation, not yet generated. |
+| `generated` | Artifact was added to the target location. |
+| `skipped` | User declined generation. |
+| `blocked` | Evidence or context is insufficient. |
+
+## Access Values
+
+### Access Requirement Values
+
+Use for repository access requirements in `devspec/foundation/codebase-structure.md` and task rows. Access values describe the allowed interaction with a repository; they are permissions for repository use, not task or run statuses. When a task needs more access than the repository value allows, stop and ask before changing scope.
+
+| Value | Meaning |
+| --- | --- |
+| `reference-only` | Read or search the repository for context only; do not edit files, run validation, or treat the repository as a delivery target. |
+| `edit` | File changes are allowed in this repository, but validation is not confirmed here; record any needed validation as a separate task, handoff, or blocker. |
+| `edit-and-test` | File changes and validation commands are allowed in this repository; use for normal implementation targets where the agent may both modify and verify. |
+| `validation-only` | Validation commands or manual checks are allowed, but file changes are not; use for smoke tests, compatibility checks, or downstream verification repos. |
+| `release-coordination` | Track release, deployment, advisory, backport, or dependency coordination for this repository; do not edit or validate it without separate confirmation. |
+| `unavailable` | The repository is required but cannot currently be accessed or used; record the impact as a blocker and do not rely on this repository until access is restored. |