Docs update - security, issue templates, agentic deployments

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,40 @@
+---
+name: Bug report
+about: Report a problem with SpecFlow
+title: "[Bug] "
+labels: bug
+assignees: ''
+---
+
+## Description
+
+A clear and concise description of what the bug is.
+
+## Steps to Reproduce
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened. Include error messages, logs, or screenshots if relevant.
+
+## Environment
+
+- SpecFlow version (`gd-specflow` / commit SHA):
+- OS:
+- IDE / MCP client (Cursor, Claude Code, etc.):
+- Python version:
+
+## Component
+
+Where does this occur? (e.g. `backend`, `mcp_server`, TUI/CLI)
+
+## Additional Context
+
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: mailto:specflow@griddynamics.com?subject=%5BSECURITY%5D%20
+    about: Please report security vulnerabilities privately by email — see SECURITY.md. Do not open a public issue.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+---
+name: Feature request
+about: Propose an idea or improvement for SpecFlow
+title: "[Feature] "
+labels: enhancement
+assignees: ''
+---
+
+## Problem
+
+What problem are you trying to solve? Who is affected, and how are you working around it today?
+
+## Proposed Solution
+
+Describe the change you'd like to see. If there are multiple options, list the trade-offs.
+
+## Alternatives Considered
+
+Any alternative approaches or workarounds you've considered.
+
+## Component
+
+Where would this live? (e.g. `backend`, `mcp_server`, TUI/CLI, docs)
+
+## Additional Context
+
+Add any other context, mockups, or references here.

QUICKSTART.md

@@ -118,6 +118,35 @@ From your IDE chat:
 Steps 1 and 2 run locally in the IDE and are safe to repeat. Generation uses your
 local backend and workspace repos.
 
+## Agentic Deployment & Integration Tests (Optional)
+
+SpecFlow Harness contains two loops: coding loop to execute the plan, and optional deployment + integration tests loop.
+
+Code generation starts always. A live deploy + end-to-end test run against it is optional and
+gated by **Part F** of `analysis/specification_completeness.md` ("Integration & Deployment
+Readiness"):
+
+- **`LOCAL_ONLY`** (default) — no deploy step; you get generated code only.
+- **`INTEGRATION_TESTS_READY`** — after generation, agents build, deploy, and run E2E tests, then
+  report results back.
+
+`check_specification_completeness` assigns this label deterministically, based on whether your
+specs describe **all three** of: a deploy method/workflow, acceptance/E2E test methodology, and
+infrastructure targets (cluster, registry, namespace, or equivalent). Partial info keeps you at
+`LOCAL_ONLY`.
+
+To opt in, add a short deployment section to your specs — see
+[docs/examples/deployment-spec-example.md](docs/examples/deployment-spec-example.md) for a
+worked example you can adapt.
+
+If you opt in but don't fully specify **how** to deploy, SpecFlow still has a default: agent
+workspaces have no Docker daemon, `kubectl`, or cloud CLIs, so every deploy is always executed as
+a GitHub Actions workflow on a full-access runner (build → push → deploy → E2E). That default
+mechanism is documented in
+[`backend/app/standards/deployment_standards.md`](backend/app/standards/deployment_standards.md).
+Anything that needs a human (cloud resource provisioning, DNS, secrets, IAM) is flagged explicitly
+in the analysis output rather than assumed.
+
 ## Local CLI
 
 After bootstrap, you can also drive runs from the local CLI:
@@ -157,5 +186,6 @@ specflow init --reset-local-db
 ## More Guides
 
 - [Compass/P10Y setup](docs/quickstart-compass.md)
+- [Deployment spec example](docs/examples/deployment-spec-example.md)
 - [MCP usage](MCP_USER.md)
 - [MCP API reference](docs/mcp/API_REFERENCE.md)

README.md

@@ -178,7 +178,7 @@ Full MCP config and usage: **[MCP_USER.md](MCP_USER.md)**
 Full MCP API reference: **[docs/mcp/API_REFERENCE.md](docs/mcp/API_REFERENCE.md)**
 
 
-Detailed SpecFlow harness instructions: [QUICKSTART.md](docs/QUICKSTART.md)
+Detailed SpecFlow harness instructions: [QUICKSTART.md](QUICKSTART.md)
 
 
 > [!Important]
@@ -193,7 +193,7 @@ Detailed SpecFlow harness instructions: [QUICKSTART.md](docs/QUICKSTART.md)
 
 | Document                                                                 | Description                                 |
 | ------------------------------------------------------------------------ | ------------------------------------------- |
-| [QUICKSTART.md](docs/QUICKSTART.md)                                      | Local setup and first run                   |
+| [QUICKSTART.md](QUICKSTART.md)                                           | Local setup and first run                   |
 | [CONTRIBUTING.md](docs/CONTRIBUTING.md)                                  | How to contribute — workflow and PR checklist |
 | [CLAUDE.md](CLAUDE.md)                                                   | Development protocol and STEEL commandments |
 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)                             | System design and data flow                 |
@@ -202,9 +202,19 @@ Detailed SpecFlow harness instructions: [QUICKSTART.md](docs/QUICKSTART.md)
 | [docs/backend/API_REFERENCE.md](docs/backend/API_REFERENCE.md)           | REST API reference                          |
 | [docs/operations/TROUBLESHOOTING.md](docs/operations/TROUBLESHOOTING.md) | Troubleshooting guide                       |
 | [docs/IDE-SETUP.md](docs/IDE-SETUP.md)                                   | IDE configuration (Cursor + Claude Code)    |
+| [docs/examples/deployment-spec-example.md](docs/examples/deployment-spec-example.md) | Example spec for agentic deployment + E2E tests |
+| [SECURITY.md](SECURITY.md)                                               | Security policy and vulnerability reporting |
 
 
 
+<!-- CONTACT -->
+## Contact
+
+Questions, feedback, or anything that doesn't fit a GitHub issue: [specflow@griddynamics.com](mailto:specflow@griddynamics.com)
+
+Found a security vulnerability? Please report it privately per [SECURITY.md](SECURITY.md) rather than opening a public issue.
+
+
 <!-- LICENSE -->
 ## License
 

SECURITY.md

@@ -0,0 +1,104 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in SpecFlow, **please report it privately**. Do not open a public GitHub issue.
+
+**Email:** [specflow@griddynamics.com](mailto:specflow@griddynamics.com)
+**Subject line:** `[SECURITY] <brief description>`
+
+Please include:
+
+- A description of the vulnerability and its potential impact
+- Steps to reproduce or a proof of concept
+- Affected component(s) (e.g., `backend`, `mcp_server`, TUI/CLI)
+- Your suggested severity (Critical / High / Medium / Low)
+
+### Response Commitment
+
+| Milestone | Target |
+|---|---|
+| Acknowledgment of report | 3 business days |
+| Initial triage and severity assessment | 7 business days |
+| Patch or mitigation available | Best effort, dependent on severity |
+| Public disclosure (coordinated) | After fix is released, or 90 days from report — whichever comes first |
+
+We follow coordinated disclosure. We ask reporters to give us reasonable time to investigate and remediate before any public disclosure. We will credit reporters in the advisory unless they prefer to remain anonymous.
+
+### Safe Harbor
+
+We consider security research conducted in good faith to be authorized and will not pursue legal action against researchers who comply with this policy.
+
+---
+
+## Supported Versions
+
+Security fixes are applied to the **current release** of the published package. Older releases do not receive backports.
+
+| Component | Package | Supported |
+|---|---|---|
+| SpecFlow MCP Server + CLI | [`gd-specflow`](https://pypi.org/project/gd-specflow/) | Current release |
+
+---
+
+## Security Architecture
+
+### Design Principles
+
+SpecFlow generates code inside sandboxed, isolated agent workspaces with no credentials and no access to customer systems or production infrastructure. All external dependencies used during generation are mocked; there is no infra provisioning and no deploy step during code generation. If user provided instructions for agentic deployment and integration testing (See [QUICKSTART.md](QUICKSTART.md) ) then it happens without any credentials, based only on Service Account and Workflow Identity Federation. The cloud sandbox given to SpecFlow agents is completely owned by the user and must be provisioned to allow SpecFlow agents in GitHub Actions to perform deployments there.
+
+### Data Boundary
+
+- Generation runs against disposable scratchpad repositories created for the run — never against a repository with history or code you want to keep.
+- The MCP server (running locally in your IDE) uploads only your `specs/`, optional `src/`, and planning outputs to the backend for a `run_generation` call; it does not transmit your broader project or credentials.
+- Backend agents operate in per-run, isolated workspaces and hold no standing credentials to external systems.
+
+---
+
+## Supply Chain Security
+
+**Risk:** Compromise of the published `gd-specflow` package or its dependencies.
+
+**Mitigations:**
+- Packages are published to PyPI via the [`publish-mcp.yml`](.github/workflows/publish-mcp.yml) GitHub Actions workflow with controlled access.
+- Secret scanning runs via `gitleaks` (see [`.gitleaks.toml`](.gitleaks.toml)).
+
+**Deployer Responsibility:**
+- Pin dependency versions in production deployments.
+- Monitor dependencies for known vulnerabilities using tools such as `pip-audit`, Dependabot, or equivalent.
+- Review `requirements.txt` / `pyproject.toml` transitive dependencies before deploying in sensitive environments.
+
+---
+
+## AI-Generated Output
+
+SpecFlow's harness produces full-stack codebases via autonomous AI agents over multi-hour runs. Treat all generated output as an untrusted third-party contribution:
+
+- **Mandatory review.** Thoroughly review, test, and validate generated code before it is deployed or used in any production or customer-facing context.
+- **Complexity and variance signals are not a security audit.** P10Y/Compass scoring measures code complexity alignment across parallel runs — it does not substitute for a security review.
+- **Zero-trust assumption.** Never assume the inherent safety, correctness, or security of AI-generated output.
+
+---
+
+## General Security Recommendations
+
+- Apply least-privilege access controls across all components and integrations.
+- Keep dependencies, base images, and infrastructure components up to date.
+- Perform a security review before any production deployment of generated code.
+- Use separate environments (development, staging, production) with appropriate access controls for each.
+
+---
+
+## Scope and Limitations
+
+This policy covers the SpecFlow open-source project as published at [github.com/griddynamics/specflow](https://github.com/griddynamics/specflow), including the `gd-specflow` PyPI package.
+
+This policy does **not** cover:
+- Hosted or managed SpecFlow deployments operated by Grid Dynamics or third parties (these may have their own security policies).
+- Third-party integrations, LLM providers, or IDE platforms used alongside SpecFlow.
+
+---
+
+## Disclaimer
+
+SpecFlow is provided under the [MIT License](LICENSE) on an "AS IS" basis, without warranties or conditions of any kind. The threat model and mitigations described in this document represent best-effort guidance. Deployers are responsible for conducting their own security assessments appropriate to their environment, compliance requirements, and risk tolerance. Nothing in this document constitutes legal advice or a guarantee of security.

docs/CONTRIBUTING.md

@@ -80,6 +80,8 @@ This project is licensed under [MIT](../LICENSE). By contributing, you agree tha
 
 Please treat every interaction with respect. No gatekeeping, no condescension.
 
+Questions or feedback that don't fit a GitHub issue: [specflow@griddynamics.com](mailto:specflow@griddynamics.com). Found a security vulnerability? Report it privately per [SECURITY.md](../SECURITY.md) — do not open a public issue.
+
 ---
 
 ## Related Docs

docs/examples/deployment-spec-example.md

@@ -0,0 +1,51 @@
+# Example: Deployment & Integration Testing Spec
+
+Drop a file like this into your `specs/` directory (e.g. `specs/deployment.md`) to give
+`check_specification_completeness` enough detail to lock **Part F — Integration & Deployment
+Readiness** as `INTEGRATION_TESTS_READY`. Without it, Part F stays `LOCAL_ONLY` and the deploy/E2E
+phase is skipped after code generation — you still get generated code, just no live deploy or
+end-to-end run.
+
+None of these fields are mandatory keywords — the analysis agent extracts them from whatever
+prose or tables you provide. This is a worked example of what "locked" looks like.
+
+```markdown
+## Deployment
+
+- **Deploy method**: GitHub Actions — `.github/workflows/deploy-dev.yml`
+- **Target environment**: GKE cluster `gke-dev-1`, namespace `myapp-dev`
+- **Image registry**: `ghcr.io/myorg/myapp`
+- **Base URL**: `https://myapp-dev.internal`
+- **Health check**: `GET /api/health`
+- **E2E framework**: Playwright
+- **E2E test location**: `e2e/`
+- **Frontend API routing**: relative paths via reverse-proxy rewrites (no hostname baked into the frontend build)
+- **Max QA rounds**: 3
+- **Secret management**: GitHub Secrets only
+- **Namespace pattern**: `{session_id}-{workspace_id}`
+- **Teardown method**: `kubectl delete namespace` + `gcloud secrets delete`
+
+## Manual Prerequisites (USER NOTICE)
+
+- [ ] `gke-dev-1` cluster and `myapp-dev` namespace already exist
+- [ ] `ghcr.io/myorg/myapp` registry access configured for the CI service account
+- [ ] Required secrets (DB credentials, JWT signing key) already created in GitHub Secrets
+```
+
+## What if I don't provide any of this?
+
+Then Part F is `LOCAL_ONLY` and the deploy/E2E phase is skipped after generation — this is the
+default, and it's a fine choice if you just want generated code. The classification is
+deterministic: it only becomes `INTEGRATION_TESTS_READY` once your spec describes **all three**
+of deploy commands/workflow, acceptance/E2E test methodology, and infrastructure targets (cluster,
+registry, namespace, or equivalent). Partial information keeps you at `LOCAL_ONLY`.
+
+You don't, however, need to design your own CI/CD approach from scratch to satisfy the "deploy
+method" dimension. SpecFlow's agent workspaces have no Docker daemon, `kubectl`, or cloud CLIs —
+by design, every deploy always runs as a GitHub Actions workflow on a full-access runner
+(build → push → deploy → E2E), regardless of what you write. That default mechanism is described
+in [`backend/app/standards/deployment_standards.md`](../../backend/app/standards/deployment_standards.md).
+So once you supply your infra targets and test methodology, you can reference "GitHub Actions" as
+the deploy method rather than inventing a different pipeline. Anything that needs a human (cloud
+resource provisioning, DNS, secrets, IAM) is called out explicitly in the analysis output as a
+manual prerequisite rather than assumed.