docs: add artifact POC analysis document

[TabishB]

Summary

• Add internal documentation for the artifact-based approach to OpenSpec core
• Remove docs/ from .gitignore to allow documentation to be tracked
• Document design decisions, terminology, and philosophy behind artifact tracking with dependency awareness

Test plan

• Documentation renders correctly in markdown
• Review content accuracy

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Introduced comprehensive POC documentation detailing artifact-tracking system design and architecture, including design philosophy and terminology, architecture components, dependency graph semantics with DAG modeling and build-order logic, filesystem-based state management, two-level template resolution mechanisms, CLI command specifications, expected behaviors, and implementation roadmap with integration layers.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Removed docs/ from .gitignore to allow documentation tracking. Added comprehensive artifact_poc.md documentation that outlines the design, architecture, and implementation approach for a filesystem-based artifact-tracking system with dependency awareness using the POC-OpenSpec-Core methodology.

Changes

Cohort / File(s)	Summary
Configuration .gitignore	Removed ignore entries for the internal docs directory (# Internal Docs and docs/ entries deleted), enabling Git tracking of documentation files.
Documentation docs/artifact_poc.md	New comprehensive design document introducing the POC-OpenSpec-Core approach. Covers core concepts (Change, Schema, Artifact, Template), dependency graph semantics, state management using filesystem as primary store, two-level template resolution, artifact pipeline workflows, implementation focus areas, and key design principles emphasizing deterministic CLI and stateless operations.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title 'docs: add artifact POC analysis document' directly and concisely summarizes the main change—adding documentation for an artifact POC approach. It is specific, clear, and accurately reflects the primary objective of the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch artifact-poc

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

docs/artifact_poc.md (2)

31-31: Add language specifications to all fenced code blocks.

All code/pseudocode blocks should declare a language identifier for proper syntax highlighting. The markdown linter flags 11 violations (MD040). Examples:

• Line 31 (tree structure): use ```text or ```sh
• Line 106 (type definitions): use ```typescript or ```javascript
• Line 290 (pseudocode): use ```javascript or ```typescript
• Line 383 (JSON output example): use ```json

🔎 Example fixes for key blocks

- Line 31 - Change:
-   ```
+   ```text
    .openspec/
    ├── templates/...

- Line 106 - Change:
-   ```
+   ```typescript
    Artifact {
      id: string
      ...

- Line 383 - Change:
-   ```
+   ```json
    Input:  schema YAML path + change directory
    Output: {
      completed: ['proposal'],
      ...

Apply similar fixes to all flagged lines (52, 145, 176, 242, 290, 301, 315, 327, 346, 439).

Also applies to: 52-52, 106-106, 145-145, 176-176, 242-242, 290-290, 301-301, 315-315, 327-327, 346-346, 383-383, 439-439

---

172-172: Minor: Capitalize "Markdown" as proper noun.

Line 172: "Formatted markdown" should be "Formatted Markdown" (proper noun).

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c08a53c and 8b428f1.

📒 Files selected for processing (2)

• .gitignore
• docs/artifact_poc.md

💤 Files with no reviewable changes (1)

• .gitignore

🧰 Additional context used

🧠 Learnings (6)

📓 Common learnings

Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Create `design.md` only when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity

📚 Learning: 2025-11-25T01:08:19.004Z

Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Create `design.md` only when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity

Applied to files:

• docs/artifact_poc.md

📚 Learning: 2025-11-25T01:08:19.004Z

Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`

Applied to files:

• docs/artifact_poc.md

📚 Learning: 2025-11-25T01:08:02.839Z

Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines

Applied to files:

• docs/artifact_poc.md

📚 Learning: 2025-11-25T01:08:19.004Z

Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)

Applied to files:

• docs/artifact_poc.md

📚 Learning: 2025-11-25T01:08:02.839Z

Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding

Applied to files:

• docs/artifact_poc.md

🪛 LanguageTool

docs/artifact_poc.md

[uncategorized] ~172-~172: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...| | Generate status reports | Formatted markdown with progress | **Key Class - ChangeSt...

(MARKDOWN_NNP)

🪛 markdownlint-cli2 (0.18.1)

docs/artifact_poc.md

31-31: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

52-52: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

106-106: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

145-145: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

176-176: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

242-242: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

290-290: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

301-301: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

315-315: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

327-327: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

346-346: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

383-383: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

439-439: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (2)

docs/artifact_poc.md (2)

80-530: Validate content accuracy before finalizing design.

The document is AI-generated and comprehensive, but the test plan shows "Review content accuracy" is still unchecked. Before this design guide is finalized and used for implementation, the following should be verified:

1. Component APIs - Ensure method signatures and responsibilities (lines 93-158) align with actual implementation intent
2. Dependency semantics - Verify topological sort, ready-artifact detection, and DAG validation logic (lines 99-131)
3. Template fallback - Confirm 2-level inheritance behavior and glob pattern handling (lines 313-334)
4. CLI design - Validate determinism guarantees and explicit --change parameter approach (lines 199-211)
5. Directory structure - Ensure paths and naming conventions are correct (lines 437-471)
6. YAML schema - Review artifact definition format and validation rules (lines 475-511)

This is critical because the document will guide implementation and establish contracts between components.

Consider:

• Reviewing the document against any existing prototype or design discussions
• Having domain experts (architecture/maintainers) sign off on the component APIs
• Validating examples (dependency graphs, schema format) are internally consistent
• Confirming this matches any preliminary implementation work or discussions

---

1-40: Add language specifications to all code blocks for clarity and proper syntax highlighting.

The document placement in docs/artifact_poc.md is appropriate—AGENTS.md's structured proposal/task/design scaffolding applies specifically to formal change proposals awaiting implementation, not exploratory POC documentation. This is internal analysis that will inform future proposals, so its current location is correct.

However, 27 code blocks lack language specifications (lines 31, 33, 52, 64, 106, 124, 145, 149, 176, 188, 242, 280, 290, 295, 301, 304, 315, 321, 327, 334, 346, 367, 383, 391, 439, 471, 511). Add language tags (e.g., bash, yaml, json, markdown) to all code blocks for readability and syntax highlighting.

⛔ Skipped due to learnings

Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines

Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Create `design.md` only when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity

Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding

Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)

Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`