From ebeb802f88fc4469b9ea975aec03c9f1f1e6783d Mon Sep 17 00:00:00 2001 From: Elizabeth W Date: Mon, 25 May 2026 01:06:00 -0600 Subject: [PATCH] initial decomposition --- .../01-decomposition.md | 32 ++++++++++++++++++ .../shared-language.md | 14 ++++++++ .../01-decomposition.md | 31 +++++++++++++++++ .../01-decomposition.md | 33 +++++++++++++++++++ .../dependency-recovery/shared-language.md | 14 ++++++++ .../01-decomposition.md | 32 ++++++++++++++++++ .../ingest-snapshot/shared-language.md | 14 ++++++++ .../01-decomposition.md | 32 ++++++++++++++++++ .../execute-wave-batches/01-decomposition.md | 32 ++++++++++++++++++ .../plan-relabel-queue/01-decomposition.md | 33 +++++++++++++++++++ .../iterative-naming/shared-language.md | 14 ++++++++ .../01-decomposition.md | 31 +++++++++++++++++ .../shared-language.md | 14 ++++++++ .../01-decomposition.md | 33 +++++++++++++++++++ .../release-packaging/shared-language.md | 14 ++++++++ .../diff-adjacent-runs/01-decomposition.md | 31 +++++++++++++++++ .../snapshot-lineage/shared-language.md | 14 ++++++++ .../01-decomposition.md | 32 ++++++++++++++++++ .../shared-language.md | 14 ++++++++ 19 files changed, 464 insertions(+) create mode 100644 design/workflows/codebase-regularization/regularize-editable-tree/01-decomposition.md create mode 100644 design/workflows/codebase-regularization/shared-language.md create mode 100644 design/workflows/dependency-recovery/externalize-accepted-dependencies/01-decomposition.md create mode 100644 design/workflows/dependency-recovery/identify-vendored-packages/01-decomposition.md create mode 100644 design/workflows/dependency-recovery/shared-language.md create mode 100644 design/workflows/ingest-snapshot/deterministic-bundle-ingest/01-decomposition.md create mode 100644 design/workflows/ingest-snapshot/shared-language.md create mode 100644 design/workflows/iterative-naming/evaluate-and-apply-renames/01-decomposition.md create mode 100644 design/workflows/iterative-naming/execute-wave-batches/01-decomposition.md create mode 100644 design/workflows/iterative-naming/plan-relabel-queue/01-decomposition.md create mode 100644 design/workflows/iterative-naming/shared-language.md create mode 100644 design/workflows/maintained-transform-replay/replay-maintained-transforms/01-decomposition.md create mode 100644 design/workflows/maintained-transform-replay/shared-language.md create mode 100644 design/workflows/release-packaging/build-and-publish-artifacts/01-decomposition.md create mode 100644 design/workflows/release-packaging/shared-language.md create mode 100644 design/workflows/snapshot-lineage/diff-adjacent-runs/01-decomposition.md create mode 100644 design/workflows/snapshot-lineage/shared-language.md create mode 100644 design/workflows/static-context-evidence/extract-segment-context/01-decomposition.md create mode 100644 design/workflows/static-context-evidence/shared-language.md diff --git a/design/workflows/codebase-regularization/regularize-editable-tree/01-decomposition.md b/design/workflows/codebase-regularization/regularize-editable-tree/01-decomposition.md new file mode 100644 index 0000000..90a8172 --- /dev/null +++ b/design/workflows/codebase-regularization/regularize-editable-tree/01-decomposition.md @@ -0,0 +1,32 @@ +# Workflow Decomposition: Regularize Editable Tree + +- Bounded context: `codebase-regularization` +- Workflow slug: `regularize-editable-tree` +- Trigger: `Regularize recovered source into canonical editable tree` +- Success outcome: Deterministic file placement, structural splits, and import/export reconstruction yield the canonical regularized tree at repo root. + +## Inputs Owned by This Context + +- structural split rules +- placement mapping rules +- import/export reconstruction rules + +## Inputs Observed from Other Contexts + +- safely renamed generated source from `iterative-naming` +- lineage or placement-stability hints from earlier phases when available + +## Downstream Handoffs + +- emit canonical editable tree and regularization manifests to `maintained-transform-replay` +- emit placement mappings and recovery-scaffolding counts for release summaries + +## Slice Boundaries + +- Decision logic is owned only by `codebase-regularization`. +- Cross-context orchestration belongs in feature-level notes. + +## Dependencies + +- Requires `iterative-naming/evaluate-and-apply-renames` so regularization uses the best accepted recovered names. +- Must preserve the build-first invariant before handoff. diff --git a/design/workflows/codebase-regularization/shared-language.md b/design/workflows/codebase-regularization/shared-language.md new file mode 100644 index 0000000..fac074c --- /dev/null +++ b/design/workflows/codebase-regularization/shared-language.md @@ -0,0 +1,14 @@ +# Shared Language: Codebase Regularization + +## Context Meaning + +- Owns deterministic reshaping of recovered source into the canonical editable tree that humans can browse and modify. + +## Preferred Terms + +| Term | Meaning | Use this, not that | Notes | +| :--- | :------ | :----------------- | :---- | +| `Regularized Tree` | Canonical editable source tree emitted from recovered source | `Regularized Tree` not `original repo layout` | The goal is navigability, not historical reconstruction. | +| `Placement Mapping` | Deterministic record of where recovered units are placed in the editable tree | `Placement Mapping` not `file map` | Emphasizes stable placement as a domain output. | +| `Recovery Scaffolding` | Wrapper or bridge kept only when deterministic reconstruction is insufficient | `Recovery Scaffolding` not `hack` | Makes exceptional structure explicit and reviewable. | +| `Structural Split` | Deterministic division of a coarse recovered unit into smaller modules | `Structural Split` not `file breakup` | Domain term for regularization reshaping. | diff --git a/design/workflows/dependency-recovery/externalize-accepted-dependencies/01-decomposition.md b/design/workflows/dependency-recovery/externalize-accepted-dependencies/01-decomposition.md new file mode 100644 index 0000000..56814f2 --- /dev/null +++ b/design/workflows/dependency-recovery/externalize-accepted-dependencies/01-decomposition.md @@ -0,0 +1,31 @@ +# Workflow Decomposition: Externalize Accepted Dependencies + +- Bounded context: `dependency-recovery` +- Workflow slug: `externalize-accepted-dependencies` +- Trigger: `Externalize accepted vendored packages` +- Success outcome: Accepted vendored packages are replaced with external dependency references while unresolved or unsafe cases keep bundled fallbacks. + +## Inputs Owned by This Context + +- accepted dependency decisions +- fallback preservation rules +- externalization output records + +## Inputs Observed from Other Contexts + +- canonical source projection from `ingest-snapshot` +- accepted, rejected, and unresolved dependency decisions from `identify-vendored-packages` + +## Downstream Handoffs + +- emit post-externalization recovered source and fallback records to `static-context-evidence` +- emit dependency externalization results to later release summaries + +## Slice Boundaries + +- Decision logic is owned only by `dependency-recovery`. +- Cross-context orchestration belongs in feature-level notes. + +## Dependencies + +- Requires `dependency-recovery/identify-vendored-packages` before execution because only accepted decisions may be externalized. diff --git a/design/workflows/dependency-recovery/identify-vendored-packages/01-decomposition.md b/design/workflows/dependency-recovery/identify-vendored-packages/01-decomposition.md new file mode 100644 index 0000000..b5f5442 --- /dev/null +++ b/design/workflows/dependency-recovery/identify-vendored-packages/01-decomposition.md @@ -0,0 +1,33 @@ +# Workflow Decomposition: Identify Vendored Packages + +- Bounded context: `dependency-recovery` +- Workflow slug: `identify-vendored-packages` +- Trigger: `Identify vendored packages from ingest artifacts` +- Success outcome: Vendored candidates receive accepted, rejected, or unresolved dependency decisions with evidence and rationale. + +## Inputs Owned by This Context + +- vendored candidate scoring rules +- dependency decision records +- confidence thresholds and rationale model + +## Inputs Observed from Other Contexts + +- run manifest from `ingest-snapshot` +- segment records and canonical projection from `ingest-snapshot` +- optional runtime traces treated only as tie-break evidence + +## Downstream Handoffs + +- emit dependency decisions and evidence to `externalize-accepted-dependencies` +- emit accepted, rejected, and unresolved decision manifests for later review and release summaries + +## Slice Boundaries + +- Decision logic is owned only by `dependency-recovery`. +- Cross-context orchestration belongs in feature-level notes. + +## Dependencies + +- Requires `ingest-snapshot/deterministic-bundle-ingest` first because vendored matching starts from deterministic ingest evidence. +- Precedes `dependency-recovery/externalize-accepted-dependencies` because externalization depends on accepted decisions. diff --git a/design/workflows/dependency-recovery/shared-language.md b/design/workflows/dependency-recovery/shared-language.md new file mode 100644 index 0000000..3f850f3 --- /dev/null +++ b/design/workflows/dependency-recovery/shared-language.md @@ -0,0 +1,14 @@ +# Shared Language: Dependency Recovery + +## Context Meaning + +- Owns decisions about which bundled code is third-party, how confident that decision is, and whether it can be externalized safely. + +## Preferred Terms + +| Term | Meaning | Use this, not that | Notes | +| :--- | :------ | :----------------- | :---- | +| `Vendored Package` | Third-party code embedded inside the upstream bundle | `Vendored Package` not `library blob` | Keeps ownership focused on package recovery. | +| `Dependency Decision` | Accepted, rejected, or unresolved determination about a vendored candidate | `Dependency Decision` not `match result` | Emphasizes reviewer-facing judgment with rationale. | +| `Fallback Preservation` | Keeping bundled code available when externalization is unsafe or unresolved | `Fallback Preservation` not `leave old code around` | Safety term for preserving executable behavior. | +| `Externalization` | Replacing accepted vendored code with an external dependency reference | `Externalization` not `strip dependency` | Avoids implying destructive removal. | diff --git a/design/workflows/ingest-snapshot/deterministic-bundle-ingest/01-decomposition.md b/design/workflows/ingest-snapshot/deterministic-bundle-ingest/01-decomposition.md new file mode 100644 index 0000000..8a8d1b1 --- /dev/null +++ b/design/workflows/ingest-snapshot/deterministic-bundle-ingest/01-decomposition.md @@ -0,0 +1,32 @@ +# Workflow Decomposition: Deterministic Bundle Ingest + +- Bounded context: `ingest-snapshot` +- Workflow slug: `deterministic-bundle-ingest` +- Trigger: `Ingest upstream bundle snapshot` +- Success outcome: Deterministic run artifacts exist for one upstream snapshot, including manifest, segment records, canonical projection, and summary. + +## Inputs Owned by This Context + +- upstream bundle snapshot selected for ingest +- run identity inputs +- deterministic segment-boundary rules +- emitted run manifest and segment records + +## Inputs Observed from Other Contexts + +- previous run manifest snapshot reference when reuse or continuity checks are helpful +- upstream snapshot metadata used later by release-packaging + +## Downstream Handoffs + +- emit run manifest, segment records, canonical source projection, and summary to `dependency-recovery` +- emit stable segment records to `static-context-evidence` + +## Slice Boundaries + +- Decision logic is owned only by `ingest-snapshot`. +- Cross-context orchestration belongs in feature-level notes. + +## Dependencies + +- Foundational first slice for the feature; later slices depend on its artifacts. diff --git a/design/workflows/ingest-snapshot/shared-language.md b/design/workflows/ingest-snapshot/shared-language.md new file mode 100644 index 0000000..dfcccc7 --- /dev/null +++ b/design/workflows/ingest-snapshot/shared-language.md @@ -0,0 +1,14 @@ +# Shared Language: Ingest Snapshot + +## Context Meaning + +- Owns deterministic intake of an upstream bundle snapshot into stable per-run recovery artifacts. + +## Preferred Terms + +| Term | Meaning | Use this, not that | Notes | +| :--- | :------ | :----------------- | :---- | +| `Snapshot Ingest` | Deterministic intake of one upstream bundle snapshot into recovery artifacts | `Snapshot Ingest` not `import step` | Focus on the domain event, not the script shape. | +| `Run Manifest` | Canonical record that identifies one ingest run and its emitted artifacts | `Run Manifest` not `build metadata` | Downstream slices treat it as the primary run reference. | +| `Segment Record` | One deterministic ingest-level code unit with hashes and canonical source | `Segment Record` not `chunk` | Matches the Phase 1 unit of work. | +| `Canonical Source Projection` | Pretty-printed recovered code emitted from ingest for downstream phases | `Canonical Source Projection` not `formatted bundle` | Preferred when the artifact is used as domain evidence. | diff --git a/design/workflows/iterative-naming/evaluate-and-apply-renames/01-decomposition.md b/design/workflows/iterative-naming/evaluate-and-apply-renames/01-decomposition.md new file mode 100644 index 0000000..3b241e6 --- /dev/null +++ b/design/workflows/iterative-naming/evaluate-and-apply-renames/01-decomposition.md @@ -0,0 +1,32 @@ +# Workflow Decomposition: Evaluate and Apply Renames + +- Bounded context: `iterative-naming` +- Workflow slug: `evaluate-and-apply-renames` +- Trigger: `Reconcile one completed wave and evaluate naming proposals` +- Success outcome: Safe accepted names are applied after wave reconciliation, queue state is updated, and naming memory is refreshed. + +## Inputs Owned by This Context + +- deterministic naming validation rules +- wave reconciliation rules +- naming memory update rules + +## Inputs Observed from Other Contexts + +- executed request and response artifacts from `execute-wave-batches` +- current generated source and context references from earlier slices + +## Downstream Handoffs + +- emit safely renamed generated source to `codebase-regularization` +- emit refreshed naming memory back into later `plan-relabel-queue` iterations + +## Slice Boundaries + +- Decision logic is owned only by `iterative-naming`. +- Cross-context orchestration belongs in feature-level notes. + +## Dependencies + +- Requires `iterative-naming/execute-wave-batches` because evaluation operates on persisted wave outcomes. +- Iterates with `iterative-naming/plan-relabel-queue` until naming work is complete or terminal. diff --git a/design/workflows/iterative-naming/execute-wave-batches/01-decomposition.md b/design/workflows/iterative-naming/execute-wave-batches/01-decomposition.md new file mode 100644 index 0000000..540a8d9 --- /dev/null +++ b/design/workflows/iterative-naming/execute-wave-batches/01-decomposition.md @@ -0,0 +1,32 @@ +# Workflow Decomposition: Execute Wave Batches + +- Bounded context: `iterative-naming` +- Workflow slug: `execute-wave-batches` +- Trigger: `Execute one planned relabel wave` +- Success outcome: Batch request and response artifacts are persisted for one wave, with transport outcomes recorded, but no names are applied yet. + +## Inputs Owned by This Context + +- wave execution rules +- provider/model configuration for one wave +- transport retry and rate-limit handling + +## Inputs Observed from Other Contexts + +- batch-ready request artifacts from `plan-relabel-queue` +- queue snapshot references from the iterative-naming queue store + +## Downstream Handoffs + +- emit persisted request, response, and execution metadata to `evaluate-and-apply-renames` +- emit transport failure and retry records for review artifacts when needed + +## Slice Boundaries + +- Decision logic is owned only by `iterative-naming`. +- Cross-context orchestration belongs in feature-level notes. + +## Dependencies + +- Requires `iterative-naming/plan-relabel-queue` because execution consumes persisted queue packets. +- Precedes `iterative-naming/evaluate-and-apply-renames` because responses must exist before evaluation. diff --git a/design/workflows/iterative-naming/plan-relabel-queue/01-decomposition.md b/design/workflows/iterative-naming/plan-relabel-queue/01-decomposition.md new file mode 100644 index 0000000..c170a57 --- /dev/null +++ b/design/workflows/iterative-naming/plan-relabel-queue/01-decomposition.md @@ -0,0 +1,33 @@ +# Workflow Decomposition: Plan Relabel Queue + +- Bounded context: `iterative-naming` +- Workflow slug: `plan-relabel-queue` +- Trigger: `Plan deterministic relabel work from changed segments` +- Success outcome: New and modified naming candidates are ranked into deterministic batch-ready work packets with attempt metadata. + +## Inputs Owned by This Context + +- relabel candidate ranking rules +- naming difficulty and priority scoring +- queue packet schema + +## Inputs Observed from Other Contexts + +- relabel-eligible changed/new segments from `snapshot-lineage` +- context packet references from `static-context-evidence` +- prior naming memory from previous iterative-naming cycles + +## Downstream Handoffs + +- emit batch-ready relabel request artifacts to `execute-wave-batches` +- persist queue state for later evaluation and feedback loops + +## Slice Boundaries + +- Decision logic is owned only by `iterative-naming`. +- Cross-context orchestration belongs in feature-level notes. + +## Dependencies + +- Requires `snapshot-lineage/diff-adjacent-runs` because unchanged and deleted segments must stay out of the queue. +- Precedes the other iterative-naming slices because it owns queue formation. diff --git a/design/workflows/iterative-naming/shared-language.md b/design/workflows/iterative-naming/shared-language.md new file mode 100644 index 0000000..fd698f9 --- /dev/null +++ b/design/workflows/iterative-naming/shared-language.md @@ -0,0 +1,14 @@ +# Shared Language: Iterative Naming + +## Context Meaning + +- Owns the relabel queue, model batch execution handoff, safe acceptance of names, and feedback loops that improve later passes. + +## Preferred Terms + +| Term | Meaning | Use this, not that | Notes | +| :--- | :------ | :----------------- | :---- | +| `Relabel Candidate` | One binding or symbol that still needs a better recovered name | `Relabel Candidate` not `rename task` | Candidate remains undecided until evaluation. | +| `Wave` | Set of batches executed against one shared pre-wave queue snapshot | `Wave` not `parallel run` | Carries a specific reconciliation rule. | +| `Naming Attempt` | One candidate-level attempt to recover a better name | `Naming Attempt` not `retry` | Distinct from transport retries and batch attempts. | +| `Naming Memory` | Small reusable history of accepted names that can inform later relabel work | `Naming Memory` not `cache` | Reviewable memory, not opaque storage. | diff --git a/design/workflows/maintained-transform-replay/replay-maintained-transforms/01-decomposition.md b/design/workflows/maintained-transform-replay/replay-maintained-transforms/01-decomposition.md new file mode 100644 index 0000000..3f31ae4 --- /dev/null +++ b/design/workflows/maintained-transform-replay/replay-maintained-transforms/01-decomposition.md @@ -0,0 +1,31 @@ +# Workflow Decomposition: Replay Maintained Transforms + +- Bounded context: `maintained-transform-replay` +- Workflow slug: `replay-maintained-transforms` +- Trigger: `Replay maintained transforms onto the regularized tree` +- Success outcome: Durable maintained transforms are applied, skipped, or surfaced as conflicts against the current regularized tree. + +## Inputs Owned by This Context + +- maintained transform metadata +- replay ordering and dependency rules +- conflict reporting rules + +## Inputs Observed from Other Contexts + +- canonical editable tree and placement mappings from `codebase-regularization` +- long-lived maintained transform store from stable metadata + +## Downstream Handoffs + +- emit replay outcomes and transformed tree state to `release-packaging` +- emit conflict reports for later review when replay is unsafe + +## Slice Boundaries + +- Decision logic is owned only by `maintained-transform-replay`. +- Cross-context orchestration belongs in feature-level notes. + +## Dependencies + +- Requires `codebase-regularization/regularize-editable-tree` because replay targets the canonical editable tree. diff --git a/design/workflows/maintained-transform-replay/shared-language.md b/design/workflows/maintained-transform-replay/shared-language.md new file mode 100644 index 0000000..df5ccce --- /dev/null +++ b/design/workflows/maintained-transform-replay/shared-language.md @@ -0,0 +1,14 @@ +# Shared Language: Maintained Transform Replay + +## Context Meaning + +- Owns replay of long-lived locally maintained changes onto the latest regularized upstream-derived tree. + +## Preferred Terms + +| Term | Meaning | Use this, not that | Notes | +| :--- | :------ | :----------------- | :---- | +| `Maintained Transform` | Durable replayable local change stored outside the numbered pipeline phases | `Maintained Transform` not `manual patch` | Preferred repository-wide term. | +| `Replay Conflict` | Explicit report that a transform cannot be applied safely to the current tree | `Replay Conflict` not `failed patch` | Signals surfaced review rather than hidden failure. | +| `Transform Anchor` | Stable file, module, segment, or lineage reference used to target replay | `Transform Anchor` not `patch location` | Better expresses deterministic targeting. | +| `Replay Outcome` | Applied, skipped, or conflict result for one maintained transform | `Replay Outcome` not `patch status` | Shared term used by release-packaging too. | diff --git a/design/workflows/release-packaging/build-and-publish-artifacts/01-decomposition.md b/design/workflows/release-packaging/build-and-publish-artifacts/01-decomposition.md new file mode 100644 index 0000000..c664cc8 --- /dev/null +++ b/design/workflows/release-packaging/build-and-publish-artifacts/01-decomposition.md @@ -0,0 +1,33 @@ +# Workflow Decomposition: Build and Publish Artifacts + +- Bounded context: `release-packaging` +- Workflow slug: `build-and-publish-artifacts` +- Trigger: `Assemble final release artifacts for one published version` +- Success outcome: Processed and unmodified release artifacts, release manifest, and publication-ready metadata are emitted for the same upstream snapshot identity. + +## Inputs Owned by This Context + +- release artifact assembly rules +- provenance manifest rules +- publication target metadata + +## Inputs Observed from Other Contexts + +- transformed canonical tree and replay outcomes from `maintained-transform-replay` +- compact upstream summary facts from `snapshot-lineage` +- dependency and regularization summary facts from earlier contexts + +## Downstream Handoffs + +- emit release artifact set and release manifest for publication or retryable publication handoff +- emit release notes grounded in recorded pipeline facts + +## Slice Boundaries + +- Decision logic is owned only by `release-packaging`. +- Cross-context orchestration belongs in feature-level notes. + +## Dependencies + +- Requires `maintained-transform-replay/replay-maintained-transforms` because releases are built from the post-replay tree. +- Depends on earlier summary facts because release notes and manifests must stay traceable. diff --git a/design/workflows/release-packaging/shared-language.md b/design/workflows/release-packaging/shared-language.md new file mode 100644 index 0000000..8b05ab3 --- /dev/null +++ b/design/workflows/release-packaging/shared-language.md @@ -0,0 +1,14 @@ +# Shared Language: Release Packaging + +## Context Meaning + +- Owns final artifact assembly, provenance reporting, and publication-ready release outputs for the recovery pipeline. + +## Preferred Terms + +| Term | Meaning | Use this, not that | Notes | +| :--- | :------ | :----------------- | :---- | +| `Release Artifact Set` | Processed and unmodified outputs emitted for one published recovery version | `Release Artifact Set` not `build output` | Includes more than the installable package. | +| `Release Manifest` | Machine-readable provenance record for one published version | `Release Manifest` not `release notes json` | Canonical artifact identity document. | +| `Processed Source Artifact` | Release artifact built from the post-Phase-9 tree | `Processed Source Artifact` not `final code zip` | Distinguishes it from the unmodified artifact. | +| `Unmodified Source Artifact` | Traceability artifact derived from the same upstream snapshot without maintained transforms | `Unmodified Source Artifact` not `raw source zip` | Important for debugging and provenance. | diff --git a/design/workflows/snapshot-lineage/diff-adjacent-runs/01-decomposition.md b/design/workflows/snapshot-lineage/diff-adjacent-runs/01-decomposition.md new file mode 100644 index 0000000..ef010bf --- /dev/null +++ b/design/workflows/snapshot-lineage/diff-adjacent-runs/01-decomposition.md @@ -0,0 +1,31 @@ +# Workflow Decomposition: Diff Adjacent Runs + +- Bounded context: `snapshot-lineage` +- Workflow slug: `diff-adjacent-runs` +- Trigger: `Compare current run to previous run` +- Success outcome: Every next-run segment gets a lineage-aware change classification, queue eligibility facts, and upstream summary evidence. + +## Inputs Owned by This Context + +- lineage minting and append-only rules +- change classification rules +- ambiguity handling rules + +## Inputs Observed from Other Contexts + +- previous and current run manifests from `ingest-snapshot` +- previous and current context packets from `static-context-evidence` + +## Downstream Handoffs + +- emit changed-segment facts and relabel eligibility to `iterative-naming` +- emit ambiguous match review artifacts and upstream summary facts for release reporting + +## Slice Boundaries + +- Decision logic is owned only by `snapshot-lineage`. +- Cross-context orchestration belongs in feature-level notes. + +## Dependencies + +- Requires `static-context-evidence/extract-segment-context` for both adjacent runs because deterministic evidence supports fuzzy matching and summary claims. diff --git a/design/workflows/snapshot-lineage/shared-language.md b/design/workflows/snapshot-lineage/shared-language.md new file mode 100644 index 0000000..9ebc339 --- /dev/null +++ b/design/workflows/snapshot-lineage/shared-language.md @@ -0,0 +1,14 @@ +# Shared Language: Snapshot Lineage + +## Context Meaning + +- Owns durable identity and adjacent-run change facts for recovered segments across upstream snapshots. + +## Preferred Terms + +| Term | Meaning | Use this, not that | Notes | +| :--- | :------ | :----------------- | :---- | +| `Lineage Record` | Durable identity record carried across runs for a recovered segment or family | `Lineage Record` not `persistent ID row` | Keeps the concept domain-first. | +| `Change Classification` | Deterministic label such as unchanged, modified, new, deleted, split, merged, or ambiguous | `Change Classification` not `diff flag` | Human-reviewable change fact. | +| `Retained Tombstone` | Durable record for a deleted segment lineage | `Retained Tombstone` not `deleted row` | Important because deletions remain part of history. | +| `Ambiguous Match` | Contested lineage candidate that must not be forced into a winner | `Ambiguous Match` not `best effort match` | Signals explicit review-needed state. | diff --git a/design/workflows/static-context-evidence/extract-segment-context/01-decomposition.md b/design/workflows/static-context-evidence/extract-segment-context/01-decomposition.md new file mode 100644 index 0000000..2e418b5 --- /dev/null +++ b/design/workflows/static-context-evidence/extract-segment-context/01-decomposition.md @@ -0,0 +1,32 @@ +# Workflow Decomposition: Extract Segment Context + +- Bounded context: `static-context-evidence` +- Workflow slug: `extract-segment-context` +- Trigger: `Extract deterministic context packets for each segment` +- Success outcome: Each segment has machine-readable context evidence usable for diffing, relabel planning, summaries, and transform anchoring. + +## Inputs Owned by This Context + +- context packet schema +- binding graph extraction rules +- usage-hint extraction rules + +## Inputs Observed from Other Contexts + +- stable segment records from `ingest-snapshot` +- post-externalization recovered source view from `dependency-recovery`; this is the canonical input for context extraction + +## Downstream Handoffs + +- emit context packets, binding graphs, and context summary artifacts to `snapshot-lineage` +- emit deterministic evidence usable later by `iterative-naming` and `maintained-transform-replay` + +## Slice Boundaries + +- Decision logic is owned only by `static-context-evidence`. +- Cross-context orchestration belongs in feature-level notes. + +## Dependencies + +- Requires `ingest-snapshot/deterministic-bundle-ingest` because context is segment-scoped. +- Should follow dependency recovery treatment so later slices see the intended recovered code surface. diff --git a/design/workflows/static-context-evidence/shared-language.md b/design/workflows/static-context-evidence/shared-language.md new file mode 100644 index 0000000..7000ea2 --- /dev/null +++ b/design/workflows/static-context-evidence/shared-language.md @@ -0,0 +1,14 @@ +# Shared Language: Static Context Evidence + +## Context Meaning + +- Owns deterministic evidence packets that describe how each segment behaves without asking an LLM to infer structure. + +## Preferred Terms + +| Term | Meaning | Use this, not that | Notes | +| :--- | :------ | :----------------- | :---- | +| `Context Packet` | Machine-readable evidence emitted for one segment | `Context Packet` not `prompt context` | The packet exists before any model request. | +| `Binding Graph` | Deterministic record of local names and relationships in one segment | `Binding Graph` not `scope dump` | Preferred for reviewer-readable evidence. | +| `Usage Hint` | Deterministic clue from calls, assignments, returns, or literals | `Usage Hint` not `guess` | Keeps evidence separate from inference. | +| `Observed Origin` | Visible import-like or member-access source seen in code | `Observed Origin` not `dependency source` | Avoids confusion with dependency-recovery decisions. |