forge-workflow 0.0.10 → 0.1.0-beta.3

package/docs/architecture/index.md

@@ -0,0 +1,66 @@
+# Architecture Index
+
+**Status:** Architecture record index and scoped navigation entry point.  
+**Update rule:** Any architecture-significant behavior that future implementers need must be captured as a scoped architecture record, ADR, work-folder evidence, or future Kernel/KnowledgeStore proposal.
+
+## Record types
+
+```text
+architecture_note      observed architectural fact, rule, constraint, or behavior
+architecture_decision  accepted direction after tradeoffs
+architecture_question  unresolved ambiguity or decision needed
+architecture_conflict  contradictory records or code/docs disagreement
+architecture_exception deliberate deviation with owner, reason, and review/expiry
+```
+
+## Scope map
+
+Add project scopes here as they become known:
+
+```text
+project
+  domain
+    bounded_context
+      subsystem
+        component
+          API / data model / workflow / operation
+```
+
+## Scoped files
+
+- `subsystems/` — subsystem/component architecture records.
+- `notes/` — individual architecture notes when no better scoped file exists yet.
+- `decisions/` — scoped decision records that are smaller than ADRs or waiting for ADR promotion.
+- `questions/` — open architecture questions.
+- `conflicts/` — active architecture conflicts.
+
+## Mandatory capture rule
+
+If future users or agents would need the information to avoid breaking the system, capture it with source evidence.
+
+Use:
+
+```text
+Observed fact      -> architecture_note
+Accepted direction -> architecture_decision or ADR
+Unclear topic      -> architecture_question
+Contradiction      -> architecture_conflict
+Temporary deviation -> architecture_exception
+```
+
+## Brownfield adoption
+
+For existing products, do not block work waiting for complete documentation. Start with partial records and improve coverage as files are touched.
+
+Each discovered note should include:
+
+```yaml
+id: AN-YYYYMMDD-short-slug
+record_type: architecture_note
+topic: <domain.subsystem.detail>
+scope: <project/domain/subsystem/component>
+status: observed
+confidence: low | medium | high
+source:
+  - path: <file-or-doc>
+```

package/docs/architecture/notes/README.md

@@ -0,0 +1,35 @@
+# Architecture Notes
+
+Use this directory for architecture-significant observations that do not yet belong in a scoped subsystem file.
+
+## Template
+
+```markdown
+# AN-YYYYMMDD-short-slug — Title
+
+```yaml
+id: AN-YYYYMMDD-short-slug
+record_type: architecture_note
+topic: domain.subsystem.detail
+scope: subsystem-or-component
+status: observed | reviewed | accepted | stale | superseded | conflict
+confidence: low | medium | high
+source:
+  - path: path/to/source
+    lines: 1-20
+supersedes: []
+conflicts_with: []
+```
+
+## Statement
+
+What architectural fact, rule, behavior, or constraint was discovered?
+
+## Evidence
+
+- Source links, code paths, tests, docs, issues, PRs, sessions.
+
+## Implications
+
+What should future humans/agents know before changing this area?
+```

package/docs/architecture/subsystems/README.md

@@ -0,0 +1,46 @@
+# Subsystem Architecture Records
+
+Use this directory for scoped architecture maps and records by subsystem/component.
+
+Recommended file names:
+
+```text
+cart.md
+pricing.md
+checkout.md
+identity.md
+kernel.md
+knowledge.md
+```
+
+Each subsystem file should stay readable and link to detailed notes, ADRs, work folders, tests, and source files.
+
+## Subsystem file template
+
+```markdown
+# <Subsystem> Architecture
+
+## Current summary
+
+Short current-state overview.
+
+## Active records
+
+- `<ID>` — short statement and link.
+
+## Data model / contracts
+
+Important entities, invariants, APIs, events, and ownership rules.
+
+## Operational behavior
+
+Runtime flows, failure behavior, retries, consistency model, queues, projections.
+
+## Open questions and conflicts
+
+- `<AQ/AC ID>` — link and short summary.
+
+## Source evidence
+
+- Code/docs/tests/work-folder links.
+```