red-methodology 0.1.0__py3-none-any.whl

red_cli/__init__.py

@@ -0,0 +1,4 @@
+"""RED methodology command-line interface."""
+
+__version__ = "0.1.0"
+PROTOCOL_VERSION = 1

red_cli/bundled/protocol/artifact-schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/exoticknight/red/blob/main/spec/artifact-schema.json",
+  "title": "RED Protocol 1 artifact metadata",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "state", "status", "title", "created"],
+  "properties": {
+    "id": { "type": "string" },
+    "state": { "enum": ["research", "evolve"] },
+    "status": { "enum": ["open", "closed", "accepted", "rejected"] },
+    "title": { "type": "string", "minLength": 1 },
+    "created": {
+      "type": "string",
+      "format": "date",
+      "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-([0-2][0-9]|3[01])$"
+    },
+    "based_on": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^[RE]-(?:[1-9][0-9]*|0[0-9]{3})$" }
+    },
+    "document_paths": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "allOf": [
+          { "not": { "pattern": "^(?:[A-Za-z]:|/|\\\\)" } },
+          { "not": { "pattern": "(^|[\\\\/])\\.\\.([\\\\/]|$)" } }
+        ]
+      }
+    },
+    "verified": { "type": "boolean" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "state": { "const": "research" } }, "required": ["state"] },
+      "then": {
+        "properties": {
+          "id": { "type": "string", "pattern": "^R-(?:[1-9][0-9]*|0[0-9]{3})$" },
+          "status": { "enum": ["open", "closed"] }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "state": { "const": "evolve" } }, "required": ["state"] },
+      "then": { "properties": { "id": { "type": "string", "pattern": "^E-(?:[1-9][0-9]*|0[0-9]{3})$" } } }
+    },
+    {
+      "if": { "properties": { "status": { "const": "accepted" } }, "required": ["status"] },
+      "then": {
+        "required": ["document_paths", "verified"],
+        "properties": { "verified": { "const": true } }
+      }
+    }
+  ]
+}

red_cli/bundled/protocol/config-schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/exoticknight/red/blob/main/spec/config-schema.json",
+  "title": "RED Protocol 1 configuration",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "document", "research", "evolve", "policy"],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "document": { "$ref": "#/$defs/document" },
+    "research": { "$ref": "#/$defs/artifactDirectory" },
+    "evolve": { "$ref": "#/$defs/artifactDirectory" },
+    "policy": { "$ref": "#/$defs/policy" }
+  },
+  "$defs": {
+    "relativePath": {
+      "type": "string",
+      "minLength": 1,
+      "allOf": [
+        { "not": { "pattern": "^(?:[A-Za-z]:|/|\\\\)" } },
+        { "not": { "pattern": "(^|[\\\\/])\\.\\.([\\\\/]|$)" } }
+      ]
+    },
+    "document": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["paths"],
+      "properties": {
+        "paths": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/relativePath" }
+        }
+      }
+    },
+    "artifactDirectory": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path"],
+      "properties": { "path": { "$ref": "#/$defs/relativePath" } }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["document_requires_approval", "report_document_implementation_conflicts"],
+      "properties": {
+        "document_requires_approval": { "type": "boolean" },
+        "report_document_implementation_conflicts": { "type": "boolean" }
+      }
+    }
+  }
+}

red_cli/bundled/skill/red/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: red
+description: Manage project knowledge and engineering changes with Research, Evolve, and Document. Use when the user requests RED, or when a repository declares RED through red.toml, RED.md, or AGENTS.md. Do not impose RED on undeclared projects.
+metadata:
+  red-protocol: "1"
+---
+
+# RED
+
+Keep accepted knowledge, unresolved research, and ongoing change distinct.
+
+## Knowledge and authority
+
+- Document is the normative baseline for people and agents using, maintaining, or changing the project. Organize accepted knowledge and necessary rationale around their tasks; keep R/E record references, provenance, and work history on the R/E side. Use the Document writing guidance in `references/artifacts.md` when drafting or updating it.
+- Research holds unverified evidence, claims, and questions. Evolve holds proposed or ongoing change and unresolved alternatives.
+- Code, tests, configuration, and runtime output are implementation evidence. Investigate and report conflicts with Document before choosing a side.
+- At an R/E boundary, present the reviewable result and wait for a separately authorized transition. A broad earlier request does not supply that decision. Update Document only after acceptance.
+- Preserve existing documentation structure and project storage/version-control policy. Keep small, resolved work in the task; persist consequential or shared work using the criteria in `references/work.md`.
+
+## Load context on demand
+
+1. Follow applicable repository instructions. Read `red.toml` when present; otherwise locate likely Document sources. Create configuration only for requested adoption or deterministic operations needing a mapping.
+2. Read the reference for the current route below. Load additional references only when their operation becomes necessary; links are lookup targets, not a recursive reading list.
+3. Find relevant Document sections, active E items, R evidence, and implementation with filenames, headings, or scoped search before reading bodies. Widen the search when dependencies or conflicts require it.
+4. Reuse instructions and evidence already available in context. Re-read changed sections, or missing material after compaction, rather than restarting discovery each turn. Keep tool output focused on relevant excerpts and results.
+
+## Routes
+
+- Engineering work and E maintenance: [work.md](references/work.md).
+- First-time or brownfield adoption: [adopt.md](references/adopt.md).
+- Project health checks: [inspect.md](references/inspect.md).
+- Creating/promoting artifacts or drafting/updating Document: [artifacts.md](references/artifacts.md).
+- Using, enabling, or falling back from the CLI: [cli.md](references/cli.md).
+- Unclear state semantics: [protocol.md](references/protocol.md); unfamiliar routing cases: [scenarios.md](references/scenarios.md).
+
+## Finish
+
+Reconcile active E with current decisions, evidence, remaining work, and open alternatives. Report verification, conflicts, and unknowns; apply the transition boundary above. Run `red check --json` when the CLI is available, and state when it could not run.

red_cli/bundled/skill/red/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "RED"
+  short_description: "Manage project knowledge through RED states"
+  default_prompt: "Use $red to handle this project task with the RED methodology."
+
+policy:
+  allow_implicit_invocation: true

red_cli/bundled/skill/red/assets/AGENTS.fragment.md

@@ -0,0 +1,5 @@
+<!-- red:start protocol=1 -->
+## RED workflow
+
+Use Research for unresolved evidence and questions, Evolve for proposed or ongoing changes, and Document for accepted project knowledge. A clear change may enter Evolve directly. After Research, report findings and wait for explicit authority before Evolve. After Evolve passes verification, report evidence and proposed Document changes, then wait for separate acceptance before updating Document. Do not treat Research as a requirement or silently resolve open Evolve alternatives. Follow the project's version-control policy for Research and Evolve; RED does not choose one. Report conflicts between Document and implementation evidence.
+<!-- red:end -->

red_cli/bundled/skill/red/assets/RED.md

@@ -0,0 +1,33 @@
+# RED Agent Instructions
+
+This project uses RED Protocol 1 to separate unresolved research, ongoing change, and accepted project knowledge.
+
+## Knowledge states
+
+### Research
+
+Research contains unresolved questions, evidence, hypotheses, experiments, and conflicting claims. Do not treat it as accepted requirements.
+
+### Evolve
+
+Evolve contains proposed or active changes, their rationale, affected areas, acceptance conditions, and open questions. Preserve unresolved alternatives until the user or project policy decides them.
+
+### Document
+
+Document contains accepted project goals, terminology, interfaces, architecture rules, operating instructions, and contribution rules. Treat it as the normative baseline.
+
+Code, tests, configuration, and runtime output provide implementation evidence. Report conflicts with Document and investigate them through Research. A resulting decision may repair the implementation or create an Evolve item that changes Document.
+
+## Workflow
+
+1. Read repository instructions and `red.toml` when present.
+2. Load only the Document, active Evolve, Research, and implementation evidence relevant to the task.
+3. Implement directly when accepted knowledge specifies the work.
+4. Use Research when an unknown can change the decision. Report findings and wait for explicit authority before entering Evolve.
+5. Use Evolve when the task changes accepted behavior, data, public interfaces, architecture, or engineering rules. A clear change may enter Evolve directly.
+6. Design, implement, test, and revise inside the authorized Evolve scope.
+7. When acceptance conditions pass, report evidence and proposed Document changes. Wait for separate acceptance before updating Document.
+8. Persist R or E when work crosses tasks, needs review, presents alternatives, or leaves an unresolved conflict.
+9. Run `red check --json` when the CLI is available.
+
+Prefer the RED CLI for deterministic operations. If it is unavailable, follow the same protocol by hand. CLI promotion records a decision supplied by the user or project; it does not authorize the transition. Follow the project's version-control policy for Research and Evolve; RED does not require tracked files, local files, or an external tracker. Do not reorganize existing documentation or install tools globally without authorization.

red_cli/bundled/skill/red/assets/red.toml

@@ -0,0 +1,14 @@
+version = 1
+
+[document]
+paths = ["README.md", "docs/**"]
+
+[research]
+path = "research"
+
+[evolve]
+path = "evolve"
+
+[policy]
+document_requires_approval = true
+report_document_implementation_conflicts = true

red_cli/bundled/skill/red/references/adopt.md

@@ -0,0 +1,15 @@
+# Adopt RED
+
+Adopt RED without reorganizing the repository.
+
+1. Inventory existing README files, maintained docs, ADRs, proposals, investigations, issues, and contribution rules.
+2. Propose a mapping for Document, Evolve, and Research. Explain ambiguous locations.
+3. Prefer the RED CLI. Run `red init` only after the task authorizes project setup.
+4. Edit the generated `red.toml` to reflect the accepted mapping.
+5. Run `red check --json`.
+
+Do not migrate old documents or reconstruct historical decisions. Classify current sources and use RED for work from this point forward.
+
+Choose whether the project tracks Research and Evolve files, keeps them local, or uses its issue or pull-request system. Record the choice in repository guidance or ignore rules; RED supplies no default.
+
+For agents without Skill support, use `red instructions install --target AGENTS.md` or `red instructions export --output RED.md`.

red_cli/bundled/skill/red/references/artifacts.md

@@ -0,0 +1,69 @@
+# RED artifacts
+
+Use UTF-8 Markdown with TOML front matter delimited by `+++` for Research and Evolve artifacts. Document follows the project's documentation format and the writing guidance below.
+
+## Research
+
+```md
++++
+id = "R-1"
+state = "research"
+status = "open"
+title = "Tag semantics"
+created = "2026-09-05"
++++
+
+# R-1: Tag semantics
+
+## Question
+
+## Evidence
+
+## Unknowns
+```
+
+## Evolve
+
+```md
++++
+id = "E-1"
+state = "evolve"
+status = "open"
+title = "Add tags"
+created = "2026-09-05"
+based_on = ["R-1"]
++++
+
+# E-1: Add tags
+
+## Change
+
+## Rationale
+
+## Acceptance
+
+## Open questions
+```
+
+Create new artifacts with sequential positive integers without leading zeros within each state. Identifiers have no fixed digit width. Accept legacy four-digit, zero-padded identifiers when reading an existing project, and count them during allocation. Filenames start with the identifier and a readable slug. Keep source artifacts in the working environment while their history remains useful.
+
+Version control is project policy. Inspect repository guidance and ignore rules before staging Research or Evolve. A project may track the files, keep them local, or represent shared work in issues or pull requests.
+
+The CLI may validate promotion readiness and record an accepted decision. The agent presents Research findings before Research-to-Evolve promotion and presents Evolve evidence plus proposed Document changes before Evolve-to-Document promotion. It must not invent agreement or rewrite Document content without an authorized decision.
+
+## Write Document for its readers
+
+Document serves people and agents who need accepted project knowledge while using a feature, implementing a change, reviewing behavior, or diagnosing a problem. Assume they arrive through a search or a direct link without the originating conversation.
+
+Before writing, identify the intended reader, the situation that brings them here, and the question or action the page should support. Use those answers to choose the scope and presentation: procedures for performing tasks, contracts and examples for implementing against interfaces, or boundaries and rationale for making design decisions. Fit the existing documentation structure; these are choices, not mandatory sections.
+
+When drafting proposed Document content or applying an accepted change:
+
+1. Lead with the answer the reader needs. Extract the accepted definitions, behavior, rules, boundaries, and necessary rationale, and state them directly. Use descriptive headings and concrete examples where they help the reader act. Update the relevant explanation in place when behavior changes.
+2. Keep working history and unresolved alternatives in R/E. Remove R/E record identifiers, links, citations, provenance footnotes, and narratives about how those records produced the result. This includes optional history or source links. Record any traceability from R/E to the relevant Document paths instead.
+3. Omit authoring dates, last-updated stamps, implementation commit hashes, completion reports, and verification logs from ordinary knowledge pages. Keep delivery evidence in E or version-control history. Include a date, version, or revision only when it changes how the reader interprets or uses the content, or a project-required document format calls for it; explain its role. Examples include an effective date, a supported version range, or an exact revision required for a reproducible procedure. Preserve purposeful metadata in established ADR, release, or audit formats without spreading that format to other pages.
+4. Review the page as its intended reader with R/E, task history, and commit history unavailable. Can they find the answer, understand its scope and rationale, and take the intended action? Remove metadata that does not help those tasks. Fill gaps from accepted knowledge; if a gap needs a new decision, keep it open in E and obtain that decision before presenting it as accepted content.
+
+For example, replace “Implemented retry handling in commit abc123 on 2026-09-11; verification passed” with the accepted contract: “Transient failures are retried up to three times. Authentication failures return immediately.” Add the rationale or usage detail the reader needs. Keep a migration deadline when it determines when the reader must act.
+
+Completion requires both independent readability and absence of references to R/E working records. Existing Document-to-Document organization may be preserved. A document whose subject is RED may explain Research and Evolve as concepts; that does not make a particular working record part of Document.

red_cli/bundled/skill/red/references/cli.md

@@ -0,0 +1,44 @@
+# RED CLI
+
+Prefer the CLI for configuration, identifiers, templates, installation, status, and structural checks.
+
+## Detection and enablement
+
+1. Use an existing `red` executable.
+2. In a Node project, try the project-local package or the official pinned `npx` package.
+3. In a Python project, try the installed package or the official pinned `pipx` runner.
+4. Make at most one network-backed attempt in a task. Follow the host's approval rules.
+5. Do not install globally or change project dependencies unless the user asks.
+6. Continue by hand when the CLI is unavailable, incompatible, declined, or offline.
+
+## Commands
+
+```text
+red init
+red new research --title <title>
+red new evolve --title <title> [--from <id>]
+red status --json
+red check --json
+red promote <artifact> --to evolve
+red promote <artifact> --to document --accepted --verified --document <path>
+red skill install [--scope user|repo]
+red skill status [--scope user|repo]
+red skill update [--scope user|repo]
+red skill uninstall [--scope user|repo]
+red instructions install --target AGENTS.md
+red instructions uninstall --target AGENTS.md
+red instructions export --output RED.md
+```
+
+One-shot forms:
+
+```text
+npx -y @exoticknight/red@latest <command>
+pipx run --spec red-methodology red <command>
+```
+
+The CLI installs the Skill snapshot shipped in its own release. Use `skill status` to inspect `.red-install.json` and `skill update` to replace only an installation managed by RED.
+
+The CLI handles structure, not transition authority. Invoke Research-to-Evolve promotion only after the user or a project-authorized decision source approves the proposed scope. Pass `--accepted` and `--verified` only after Evolve evidence has been presented and the result has received separate acceptance. A successful command records those supplied assertions; it does not prove that the decision occurred.
+
+Use `--json` when consuming command output. Protocol incompatibility is a hard stop for CLI mutation; fall back to manual work under the protocol supported by the project.

red_cli/bundled/skill/red/references/inspect.md

@@ -0,0 +1,15 @@
+# Inspect a RED project
+
+Inspect these conditions:
+
+- `red.toml` parses and uses a supported protocol version.
+- Declared paths exist or have a clear reason to remain empty.
+- R and E identifiers are unique.
+- Research claims have not leaked into Document as accepted facts.
+- Evolve alternatives have not been resolved without a recorded decision.
+- Accepted changes have matching implementation and Document updates.
+- Document meets the reader and writing criteria in [artifacts.md](artifacts.md): readers can find and use accepted knowledge without working history; dates and revisions have a reader-facing purpose or a required format; R/E record references and process narratives stay in R/E.
+- Document conflicts with code, tests, configuration, or runtime evidence are visible.
+- Installed Skill or exported instructions implement the configured protocol.
+
+Use `red status --json` and `red check --json` when available. Add semantic findings from reading the relevant content; the CLI cannot make those judgments.

red_cli/bundled/skill/red/references/protocol.md

@@ -0,0 +1,33 @@
+# RED Protocol 1
+
+RED assigns project knowledge to one of three states.
+
+## Research
+
+Research holds unresolved questions, observations, external sources, hypotheses, experiments, and conflicting evidence. A Research item may stay incomplete. Label claims and uncertainty so an agent cannot mistake them for requirements.
+
+Research supports an Evolve proposal through explicit references. Promotion does not copy every note into Evolve.
+
+When Research can support an Evolve scope, the agent reports its findings and waits for an explicit human decision or a decision source that the project has authorized. RED does not require Research when the change and its acceptance conditions are already clear.
+
+## Evolve
+
+Evolve holds a proposed or active change. Record the problem, proposed change, tradeoffs, affected areas, acceptance conditions, and open questions. Design, implementation, tests, revision, and user interaction remain in Evolve until acceptance. An explicit user request can authorize work on an Evolve item. Open alternatives remain undecided until the user or project policy resolves them.
+
+After implementation and verification, the agent reports its evidence and proposed Document changes, then waits for explicit acceptance. An accepted Evolve item updates the relevant Document sources. A rejected item leaves Document unchanged. A partially accepted item records the accepted boundary and updates Document only for that part.
+
+## Document
+
+Document contains accepted goals, boundaries, terminology, public interfaces, architecture rules, operating instructions, and contribution rules. Agents start from Document and treat it as the normative baseline.
+
+Document can become stale. Code, tests, configuration, and runtime output provide implementation evidence. A conflict between the baseline and evidence enters Research. The resulting decision may restore the implementation to Document or create an Evolve item that changes the baseline.
+
+## Transition authority
+
+A broad request to complete work does not authorize later transitions whose results were not ready for review when the request was made. The user decides at the Research and Evolve checkpoints, unless the project defines another human-approved decision source such as an issue state or pull-request approval. CLI flags record a supplied decision; they do not create authority.
+
+## Persistence
+
+RED classifies knowledge in every task but does not require a file for every thought. Persist Research or Evolve when work crosses tasks, needs review, presents alternatives, affects public behavior or architecture, or leaves an unresolved conflict. Keep short-lived local reasoning in the active task.
+
+Persistence and publication are separate decisions. Each project chooses whether to track Research and Evolve files, keep them local, or publish the work through another collaboration system. Tracking changes availability, not knowledge state: an R or E artifact does not become Document when committed.

red_cli/bundled/skill/red/references/scenarios.md

@@ -0,0 +1,25 @@
+# Scenario routing
+
+| Situation | Route | Persistent artifact |
+|---|---|---|
+| Work already specified by Document | Implement | Usually none |
+| Clear accepted feature request | Evolve | Persist for public or cross-task change |
+| Ambiguous feature request | Research, then Evolve | Persist unresolved evidence and consequential change |
+| Research has enough evidence for a proposal | Report findings and stop | Wait for explicit authority before Evolve |
+| Diagnose a bug | Research | Persist when findings must survive the task |
+| Repair behavior that violates Document | Research, then repair | Document stays unchanged |
+| Change a public interface | Evolve | Persist and update Document after acceptance |
+| Mechanical internal refactor | Implement | Usually none |
+| Architectural refactor | Evolve | Persist |
+| Experimental spike | Research | Do not promote without a decision |
+| Document conflicts with implementation | Research | Persist unresolved conflict |
+| Evolve item rejected | Close Evolve | Document stays unchanged |
+| Evolve item partly accepted | Record boundary | Update Document for accepted part |
+| Evolve passes its acceptance conditions | Report evidence and stop | Wait for explicit acceptance before Document |
+| Urgent repair | Restore accepted behavior, then record material findings | Keep the record proportional |
+| Repository is read-only | Analyze and report | No writes |
+| User declines CLI or docs | Work in task context | Explain unresolved continuity risk |
+| CLI cannot run | Follow artifact rules by hand | Report skipped structural validation |
+| Concurrent Evolve items conflict | Preserve both and request a decision | Do not merge conclusions |
+
+“Persist” means keep the work available beyond the current task. The project decides whether that means tracked files, local files, issues, pull requests, or another system.

red_cli/bundled/skill/red/references/work.md

@@ -0,0 +1,31 @@
+# Work with RED
+
+## Ground and route
+
+Use the entrypoint's context-loading rules. Start from the relevant Document baseline and active E summary; follow R or historical evidence to resolve current questions.
+
+- Implement directly when Document or active E specifies the work and no decision-blocking unknown remains.
+- Use Research for unknowns that can change implementation or acceptance, including Document/evidence conflicts.
+- Use Evolve for changes to accepted behavior, public interfaces, data, architecture, or engineering rules.
+
+A clear feature request may authorize direct entry to Evolve. A bug violating Document may proceed from diagnosis to repair without changing Document. Route by knowledge state rather than a mandatory R-to-E-to-D sequence.
+
+## Maintain active E
+
+On resumption or new instructions, compare active E with the request and current evidence. Before dependent work, record material changes to scope, design, acceptance, decisions, or constraints, including findings that change the plan. Distinguish authorized decisions from unresolved alternatives; a user request clearly authorizing an adjustment supplies that authority. Ordinary E maintenance needs no separate approval.
+
+After meaningful results, record concise evidence, verification status (including failed or pending checks), and remaining work. Before pause, handoff, or completion, reconcile E with actual work and current decisions. Batch minor edits until these triggers. If storage is unavailable, preserve the update in the task and identify the blocker.
+
+Keep current scope, decisions, acceptance, verification, and next steps easy to resume. Replace stale status while retaining decision rationale, unresolved alternatives, and review evidence. Link detailed logs or experiments from R/E instead of copying output or appending every turn. Update affected sections without re-reading the whole record after each edit.
+
+## Persist
+
+Persist work that crosses tasks, needs review, presents alternatives, affects public behavior or architecture, or leaves an unresolved conflict. Keep small local work in task context when persistence is unnecessary. Use the CLI when available; consult `artifacts.md` for record structure. Follow project storage and version-control policy; artifact creation does not authorize publication.
+
+## Execute and report
+
+Investigate within Research; design, implement, verify, and revise within authorized Evolve scope. Seek a decision for scope expansion. Apply the entrypoint's transition boundary:
+
+- Present R findings, uncertainty, risks, and proposed E scope for a decision.
+- Present E verification evidence and proposed Document changes for acceptance.
+- Record authorized promotions; synchronize accepted E behavior with Document.