Replies: 19 comments 30 replies
Thread 1 — Product boundary and authority modelStatus: canonical topic thread for what Spec owns and what is outside the MVP boundary. Current accepted direction
Product-model invariantThe primary conceptual chain is: These layers do not replace one another. Existing implementation behavior is evidence, not normative truth. Existing-project / reverse-spec boundaryReverse engineering adds an evidence/discovery concern before reconciliation. Observed or inferred behavior must never automatically become normative specification. A tracked/reviewable evidence representation remains desirable for existing-project reconstruction, but its exact MVP storage shape is still open and must remain separate from normative Artifact authority. Deferred beyond MVPEarlier discussion about target-scoped authority, realized-vs-future specification lines, target identity, and Git integration boundaries is preserved in Threads 2 and 3 as future-design input. It is no longer a prerequisite for the first useful Spec Tool release. Use replies here for product-boundary questions and changes to what belongs inside/outside Spec Core. |
Discussion kickoff: what does “authoritative specification state” mean in Spec?This thread starts from the accepted product reset in #63. Baseline already accepted
First design questionThe old wording tends to collapse two independent ideas into one word: We need to decide whether Spec should model these separately:
A likely model is therefore: Under this model, a future target branch may be authoritative for that target lineage without being the currently realized specification. Why this mattersIf authority and realization are collapsed, then either:
This distinction will constrain Thread 2 (targets / topology) and Thread 3 (mutation policy), so it should be settled here first. Open questions
|
Thread 2 — Targets, versions, and Git topologyStatus: deferred beyond MVP. This thread preserves accepted future-design work; it does not constrain the current single-workspace MVP. Current accepted MVP boundary
Preserved future-design decisionsIf/when concurrent future targets are reintroduced, the earlier accepted direction remains useful input:
These are future constraints, not fields or runtime behavior to build into the MVP now. Revisit triggerReopen this topic only when a real use case requires concurrently accepted future specification states or maintenance lines. Until then, do not add target/version abstractions merely for extensibility. |
Exploration checkpoint: simplify PLAN persistence around Git candidate stateThis exploration follows the consolidated body and intentionally revisits earlier proposals rather than preserving them for minimum-change compatibility. Proposed simplification 1: the branch tree is the proposed future stateDo not create a second Existing Core already defines the authoritative integration boundary separately from feature-branch authoring: feature-branch commits may contain intermediate candidate work, while only Conceptually: This removes the need to invent a duplicate future-Artifact serialization and keeps final integration diffing against the same Artifact files that will actually become authoritative. A consequence is that query/context tooling must clearly distinguish an authoritative integration snapshot from a candidate/worktree snapshot so an Agent does not mistake candidate Proposed simplification 2: READY checkpoint stays branch-localDrop the earlier idea that a READY planning checkpoint should normally merge into Instead:
A deterministic marker mechanism is still open. One candidate is a standard commit trailer identifying PLAN/gate; tooling can locate the commit and re-run the gate against its tree rather than trusting the marker itself. A later material discovery can produce P2 after scoped reconciliation; affected implementation must be reconciled against the latest applicable READY checkpoint. Proposed simplification 3: unify consensus unit and blocking/work scopeThe previous discussion used Prefer one PLAN-local node, provisionally
Then the same DAG drives review invalidation, impact closure and implementation continuation gates. Proposed simplification 4: PLAN makes early draft CHG unnecessary by defaultThe current consolidated body still says to keep CHG draft during planning/implementation. With a first-class PLAN this is redundant as a default workflow. Recommended revision: Draft CHG remains a legal Core capability, but should no longer be the normal long-running companion to PLAN. This reduces drift between Draft Artifact role after this simplificationDraft Artifacts remain useful on They should not be forced into service as alternate revisions of an already-active Artifact. A proposed modification of an active Artifact can live directly as the speculative version of that same Artifact on the planning branch. Potential PLAN lifecycle simplification
where the latter three are terminal/frozen. This is not yet a recommendation until persistence semantics are settled, but should be evaluated rather than preserving two fields by default. Proposed final integration shapeFor work that reaches implementation: If canonical EF truth does not change, no CHG is required merely because a PLAN existed. Retention direction to evaluateA useful possible boundary is:
Exact retention, identity, checkpoint-marker and on-disk schema remain open. |
Thread 3 — Authoritative mutation policy and integration boundariesStatus: deferred beyond MVP except for ordinary Artifact lifecycle invariants. Current accepted MVP boundary
Preserved future-design inputThe earlier authority work remains relevant if stronger publication guarantees become necessary later:
None of that should introduce fields or validation requirements into the MVP before a concrete use case requires them. Use replies here when/if publication authorization, Git-host enforcement, or multi-line authority becomes an active product requirement again. |
Exploration checkpoint: semantic mutation engine and safe PLAN confirmation updatesThis continues from the accepted canonical body. It is exploration until explicitly accepted/folded into the body. The goal is not to add a generic file editor. The goal is to generalize the existing mutation plan/authorization architecture so semantic Agent-friendly commands can safely update existing EF files without asking Humans/Agents to hand-maintain derived cryptographic fields. 1. Keep inline PLAN confirmations; do not create append-only sidecar attestation files just to avoid replacementA create-only attestation directory could avoid update-existing publication, but it introduces more concepts than it removes: Keep the accepted single PLAN Artifact with 2. Semantic mutation architectureGeneralize Core CLI mutation into four layers: Do not expose a generic Examples: 3. Separate semantic authorization from byte materializationThe bytes written after authorization may legitimately differ from the bytes previewed before authorization when an unrelated concurrent edit can be preserved without changing the authorized semantic effect. Example: EF should preserve the other Role's new confirmation instead of rejecting solely because the complete PLAN file bytes changed. Therefore a planned mutation has two distinct concepts: After authorization, the same semantic Intent is planned again from freshly loaded state. Publication proceeds only when: If the semantic effect changed, reject as stale and require a new preview/authorization. This is semantic optimistic concurrency, not blind byte replacement. 4. Re-plan after authorization, before every writeDo not hold a filesystem lock while waiting for Human confirmation. Flow: Important consequences:
5. Writer locking is coordination, not the final source of correctnessThe existing Core contract correctly avoids making implementation-local advisory locks the authoritative engineering-transaction boundary. Preserve that principle. A conforming implementation SHOULD serialize its own cooperating mutation processes around the short re-plan/publication critical section, but correctness still relies on fresh semantic re-planning, exact materialization preconditions, complete-file publication, and final Git validation/integration. Do not introduce a permanently authoritative lock registry or organization-wide mutex into EF state. 6. General file-mutation materializationInternal materialization operations should be deliberately small: Do not add general delete merely for symmetry; issued Artifact deletion remains forbidden and future removal use-cases should prove their need. Conceptual fresh materialization: create {
path
after_bytes
}
replace {
path
expected_before_sha256
after_bytes
}The expected-before digest is from the fresh post-authorization re-plan, not the stale pre-prompt snapshot. 7. Preserve the existing strong create-only protocol
Create and replace have different correctness primitives and should share orchestration, not necessarily the final syscall. 8. Replace-existing publication primitiveCandidate replacement algorithm: The user-visible file is therefore old-complete or new-complete rather than incrementally rewritten. 9. Be explicit about the filesystem boundary: this is not perfect path-level CASPortable Node/libuv filesystem APIs do not expose a generic atomic operation equivalent to: as one compare-and-replace syscall across all supported platforms. Therefore the implementation must not claim perfect CAS against a non-cooperating external editor that changes the target in the final check->rename window. This is consistent with EF's existing honest filesystem boundary: working-tree path handling is not an adversarial filesystem-security boundary, while authoritative engineering correctness is decided at explicit Git tree/transition publication. The implementation should make the race window as narrow as practical, serialize its own cooperating writers, detect all observable precondition changes, and never misreport publication state. 10. Post-publication failure semantics for replacementReplacement differs from create-only publication in one important way: after successful target replacement, do not automatically roll back by rewriting the old file if later verification/cleanup fails. A rollback could destroy a newer edit made after publication. Instead: This follows the existing rule that physical publication must never be misreported as unapplied. Before the replacement syscall, a proven stale precondition/race remains: 11.
|
Thread 4 — Specification model, artifacts, lifecycle, and provenanceStatus: canonical topic thread for the persisted Spec MVP data model. Current accepted directionThe MVP principle is:
The copied EF implementation is reusable mechanism, not a frozen ontology. Canonical content modelThe main specification chain is first-class through the contract layer: Accepted first-class Artifact kinds for MVP:
Identity and layout
Common Artifact envelopeEvery stored Artifact uses the standard structural fields: schema: ...
kind: ...
id: ...
title: ...
status: ...
relations: []
resources: []
Required body structureAll kinds allow additional custom sections after their required semantic core.
Draft Artifacts may omit required sections or contain placeholders. Active Artifacts must contain complete required sections and no placeholder-only content. LifecycleStatuses: Knowledge/specification Artifacts ( PROJECT is always active. CHG uses:
Physical deletion is allowed only for draft Artifacts. Active content must leave current truth through lifecycle operations; terminal Artifacts are retained. Lifecycle is strictly specification authority/currentness. RelationsRelations are stored on the source Artifact frontmatter. The vertical chain uses one relation semantic: with adjacent-layer compatibility only:
MVP also retains explicit horizontal relation concepts: Accepted compatibility rules for MVP:
Canonical replacement relation is ResourcesResources are Artifact-owned descriptors, not first-class Artifacts and do not have an independent lifecycle. Minimal descriptor: This is intended to cover machine-readable contracts, schema files, examples, diagrams, benchmarks, evidence, references, and similar supporting material without introducing a second Artifact ontology. Resource
CHG simplificationCHG remains, but only as a lightweight specification change/provenance record. It no longer owns EF's old exactly-once effect coverage, integration-boundary transaction semantics, or implementation-repository coupling in the MVP. Required body sections remain: Validation boundaryMVP
It does not pretend to determine natural-language semantic correctness. Human/Agent review remains responsible for whether a Story, Use Case, Feature semantics, Contract, ADR, or POL is substantively correct. Existing-project / reverse-spec requirementObserved behavior remains evidence, not normative truth. Existing-project reconstruction needs a tracked/reviewable way to retain discovered/inferred evidence without promoting it automatically into active specification. The exact representation remains open, but it must stay separate from lifecycle authority and must not turn accidental legacy behavior into Use replies here for persisted schemas, Artifact vocabulary, lifecycle, relations, Resources, reverse-spec evidence, validation, and provenance. |
Exploration checkpoint: reuse Artifact infrastructure for PLAN; minimize persisted coordination stateThis comment records the next design exploration after the accepted simplification that the candidate branch tree is the proposal, PLAN Scope is the single consensus/blocking unit, READY checkpoints are branch-local, Transition Delta is derived, and CHG is normally materialized late. It is not yet folded into the canonical issue body. Key simplification: do not add a new
|
#70 validation implementation clarification
Validation remains deterministic over the current |
Thread 5 — Planning, decisions, review, and consensusStatus: canonical topic thread for the human/agent process that produces an accepted specification change. Current accepted directionThe normal high-level flow is: Planning is not permanently frozen once implementation starts. Material discoveries can return the affected specification to discussion/review and produce another ordinary specification change. What is no longer assumedThe inherited EF design developed a large first-class model around The underlying needs remain relevant—recording decisions, review context, unresolved concerns, evidence, and acceptance—but we should re-derive the smallest model from specification maintenance rather than preserve an EF workflow engine. Open design questions
Use replies here for PLAN/decision/review/approval concepts. Historical EF PLAN design is archived below this thread as replies for reference, not as presumed current truth. |
Exploration checkpoint: commit-backed formal Review Packet, material manifest, and precise stale guidanceThis continues from the accepted Agent-first Review Packet model now folded into the issue body. It is exploration until explicitly accepted/folded into the body. 1. Strong simplification: formal Human confirmation should be commit-backedA Review Packet may still be generated from the working tree for fast Agent/Human iteration, but a packet that can produce a durable EF Confirmation should use an explicit immutable proposed commit. Conceptual commands: This is deliberately stronger than the previous exploration. It solves several problems at once:
This does not mean freshness is bound to the whole proposed commit. The proposed OID is review provenance/material source only. Confirmation currentness remains determined by Therefore unrelated later commits do not stale confirmation when those revisions remain equal. 2. Confirmation should retain reviewed proposed OID as provenanceRecommended Confirmation shape becomes: confirmations:
- scope: api-contract
role: be
proposal_revision: sha256:...
review_context_revision: sha256:...
baseline_oid: <reviewed authoritative commit>
proposed_oid: <reviewed candidate commit>
It is not an additional freshness equality condition. This small field allows future 3. Review token can therefore stay compact and self-containedCandidate binding payload: {
"schema": "ef/review-binding@1",
"integration_ref": "refs/heads/main",
"plan_id": "PLN-018",
"scope_id": "api-contract",
"role": "be",
"baseline_oid": "<A>",
"proposed_oid": "<P>",
"proposal_revision": "sha256:P1",
"review_context_revision": "sha256:C1"
}Possible wire form remains: No secret/MAC/signature is required because this is not authentication. 4.
|
Exploration checkpoint: exact
|
Follow-up recommendations to
|
Exploration checkpoint: exact
|
Exploration checkpoint: near-spec
|
Thread 6 — Implementation linkage, stale detection, and reconciliationStatus: implementation linkage is deferred / out of MVP scope. Current accepted directionThe conceptual model still includes Implementation as the fifth layer: However, the persisted Spec authority boundary stops at the normative Contract.
Future revisit ruleImplementation linkage should be reconsidered only when the linkage can be backed by verifiable or derived evidence, for example tests, explicit code annotations, generated manifests, CI-produced mappings, or another mechanism that can detect drift mechanically. If such a feature is added later, derived linkage/evidence should remain distinct from canonical specification authority rather than turning code into a second normative source. Out of MVP
Use replies here only when a concrete, mechanically verifiable implementation-linkage use case is ready to justify re-opening the design. |
Exploration checkpoint: scoped blocking and replanning during implementationThis comment records the next design exploration and is not yet accepted consensus until folded into the issue body. Correction: global BLOCKED is appropriate for implementation entry, not every mid-development concernA single PLAN-wide Recommended distinction: This preserves the original guardrail (no implementation before sufficient alignment) without making one local concern idle an entire multi-person team. PLAN does not actually “go back to a planning lifecycle state”PLAN remains A mid-implementation discovery creates a local replanning/reconciliation loop: No Questions should declare affected consensus unitsConceptually: question:
id: Q-009
blocking: true
affects:
- api-contractConsensus units should also be able to declare explicit dependencies, e.g.: Blocking propagation is then deterministic over the unit dependency graph: If Two kinds of readinessExpose both: Before implementation starts, require plan readiness. After implementation has started, continuation may use scope readiness so independent workstreams can proceed. Implementation work should declare which PLAN/unit scope it relies onEF should not become an implementation task planner, but a work/PR/agent session needs enough metadata to ask the gate correctly: Exact CLI is only illustrative. For a simple/solo flow the default may be the whole PLAN. For parallel team work, FE/BE PRs or agent sessions may declare narrower unit scopes. GitHub/Jira integration can carry that delivery metadata; EF Core only validates the declared coordination scope and cannot prove that a developer did not under-declare it. What happens to code already written when a scope becomes blocked?Do not automatically revert it. Treat it as a speculative implementation based on a superseded/uncertain assumption:
Reconciliation classifies existing work conceptually as: These classifications are implementation workflow, not persistent Artifact lifecycle states. Where impact analysis belongsImpact analysis must happen immediately after the concern is raised, not at final CHG completion. Recommended loop:
Deterministic EF can prove structural/unit graph effects and revision staleness. Agent/Human judgment is still required for semantic code impact and whether a new engineering decision is correct. Multi-person vs solo projectsRoles represent engineering perspectives/authority, not necessarily distinct people. Multi-person project:
Solo project:
The data model should therefore be identical for both. Team size changes role bindings and work-scope granularity, not EF semantics. Investigation is allowed while blocked
Otherwise blocking would prevent the very engineering work often required to resolve uncertainty. |
Exploration checkpoint: near-spec
|
Thread 7 — Agent UX, CLI, Git-host collaboration, and provider adaptersStatus: canonical topic thread for the Agent-facing operating surface around the Spec MVP. Current accepted direction
Accepted MVP command shapeThe intended operation families are approximately: Exact flags/result schemas still need implementation-level design, but the boundary is accepted. Update boundary
Lifecycle, graph, and Resource mutations use invariant-aware dedicated operations. Query baselineThe MVP must support Agent-friendly deterministic discovery for at least:
Agents should not need to scan every Markdown file simply to discover relevant context. Validation UX
Provider boundaryProvider Discussions/Issues/PRs may be excellent Human collaboration surfaces, but provider metadata is not automatically specification truth. In this repository, GitHub Discussion #65 is intentionally the canonical product-design discussion, which is a repository-governance choice rather than a generic runtime requirement of Spec Tool. Use replies here for CLI/Agent ergonomics, stable JSON contracts, query composition, provider adapters, and optional higher-level collaboration surfaces. |
Exploration checkpoint: Git + CLI are primitives; strict staged workflow needs a Coordinator runtimeThis is exploration, not accepted canonical direction yet. It responds to the real-world concern that a desired Core observationDo not equate Git-native EF truth with Git-only workflow orchestration. Git is good at: The EF CLI/Core is good at: Neither is naturally responsible for: Trying to implement those responsibilities as branch conventions, lock files, force-push prohibitions, and every-Agent discipline would make the operational model fragile. Candidate architectureIntroduce a separate EF Coordinator / Workflow Runtime layer: Responsibilities: The Coordinator SHOULD use the same reusable Core application/domain API rather than reimplementing semantics or depending only on parsing CLI prose. CLI remains a thin external tool interface. Runtime phases are not PLAN lifecycleThe Coordinator may expose derived runtime phases such as: These are operational projections, not persisted PLAN lifecycle states. PLAN remains The Coordinator recomputes eligible next actions from EF Core state after every relevant event rather than trusting a stored phase flag as engineering truth. Runtime state may be non-authoritativeSome information is inherently operational rather than engineering truth and should not be forced into Git: A Coordinator may persist this in a runtime database. It must never silently become canonical engineering truth. Durable semantic decisions still return to EF files/Git. For single-user/local operation this runtime could be an in-process/local daemon with a local store. Team/multi-Agent operation may require a shared service/store. Core should not depend on either deployment shape. Strict staged executionA Coordinator can implement the desired chain without encoding it into Git branches: Parallelism is therefore allowed only where the dependency/gate graph permits it. Downstream Agents do not independently decide that a gate has passed. Multi-Agent consequenceFor coordinated mode, prefer single-writer orchestration authority over requiring every Agent to mutate the shared coordination branch directly. Agents may work in isolated worktrees/branches and return commits/patches/semantic mutation intents. The Coordinator serializes integration into the current candidate state, performs Core rechecks, and uses Git CAS for publication. Conflicting semantic edits become explicit reconciliation work rather than accidental YAML merge behavior.
Enforcement boundaryNo local tool can prevent a Human from manually editing files or bypassing an Agent workflow. The official workflow is enforced at two levels: This is a more realistic notion of control than attempting distributed locks over arbitrary developer worktrees. Deployment modesThe same EF Core can support: This prevents multi-user orchestration requirements from contaminating deterministic Core while preserving a low-friction local mode. Important architectural implicationIf this direction is accepted, EF should be designed as a reusable Core/domain library first, CLI adapter second, even though the CLI remains the preferred tool surface for ordinary Agents. A future Coordinator must call the same revision/gate/mutation logic directly rather than duplicate or shell-script EF semantics. Open questions
Until accepted, keep Git+CLI-only coordination as a workable low-level/manual mode rather than assuming it is the ideal multi-Agent workflow architecture. |
Exploration checkpoint: central EF service as the unified live worldlineThis is exploration, not accepted canonical direction yet. It supersedes the previous assumption that a shared coordination branch plus CLI discipline should be the primary multi-Human/multi-Agent coordination model. New architectural hypothesisIntroduce a central EF service that is the runtime authority for collaborative candidate state and workflow execution. CLI becomes a client of this service rather than every user/Agent independently mutating a local EF checkout. Keep the accepted Human/Agent/Core semantics, but move distributed workflow authority out of branch conventions. Explicit truth layersDo not claim one physical store is the source of truth for every concern. Define separate authority domains: The service presents these as one coherent logical worldline to clients. Workspace as service-level execution containerDo not overload PLAN into the runtime container. Add a server-side concept provisionally called Workspace: A product milestone or workstream may map to a Workspace, but avoid baking provider/project-management Different Workspaces can progress in parallel from related baselines. Within one Workspace, every Human/device/Agent sees the same service-owned current candidate state. Git's new roleGit remains essential, but no longer acts as scheduler:
This removes the operational requirement that every Human/Agent understands Yjs / CRDT roleYjs is promising for live collaborative draft convergence, especially when humans, web UI, and Agents edit the same EF material concurrently. It should not replace EF Core semantic validation or Git checkpoint truth. Recommended boundary: Important caution: CRDT convergence does not imply engineering-semantic correctness. Concurrent edits may converge to syntactically or semantically invalid PLAN/YAML/Markdown. The service must materialize and run Core validation before a state becomes a stable checkpoint, formal review, gate candidate, or integration candidate. Yjs may be unnecessary for every CLI operation. Agent/CLI mutations can still be versioned semantic/patch requests serialized by the service; the service can project successful mutations into the live Yjs document so browser co-editors see them. Use Yjs where real-time co-editing provides value, not as a mandatory replacement for all mutation logic. Stable vs live stateA useful split is: Formal review and entry checking use stable checkpoints, never an arbitrary live Yjs state. CLI/client implicationRemote mode becomes the primary multi-user model: The service authenticates caller identity, resolves the current Project/Workspace, serializes state-changing operations, invokes the same EF Core library, and returns stable machine-readable results. The CLI should not independently decide workflow eligibility or mutate the canonical Workspace behind the service. A local/embedded mode can remain for single-user/offline use, ideally using the same service/core interfaces without requiring hosted infrastructure. Identity/governance benefitCentral service creates a clean place for concerns intentionally excluded from EF Core:
Core Confirmation can remain Role-level semantic consensus while service audit records who actually produced that event. Parallel Agent implementationDo not require every worker to mutate one shared filesystem worktree. A Coordinator/Service can fan out worker tasks from one Workspace checkpoint: Workers submit candidate commits/results back to the Workspace. Service serially integrates/reconciles them into the single current Workspace candidate and reruns Core impact/gate analysis. Semantic conflicts become explicit reconciliation tasks rather than accidental YAML merge races. Remote Agents may use their own local clones; server worktrees are an implementation detail for service-side materialization/evaluation and server-hosted workers, not a requirement that all clients share a filesystem. Service durability / failure modelDo not let runtime DB become hidden canonical engineering knowledge. On service restart/loss:
The exact checkpoint/ref retention policy and event-log durability remain open. Main open architectural questions
This direction potentially simplifies several prior problems: distributed |
Exploration checkpoint: provider-hosted coordination repo instead of self-hosted EF serviceThis supersedes the immediately prior self-hosted central Coordinator service exploration. It is exploration, not accepted canonical direction yet. Core product resetDo not operate a long-running EF service containing Agents or a custom workflow database. Instead, require one dedicated EF coordination repository hosted by GitHub or GitLab and treat the provider itself as the remote coordination substrate. There is no remote EF Agent. Agents run locally or in the user's chosen harness. The provider centralizes state; the CLI materializes the relevant remote state into local Agent context. Dedicated coordination repositoryA project using coordinated EF should have a dedicated repository (name/policy still open) separate from implementation repositories. It owns EF files/history and provider workflow items. Implementation repositories become linked execution surfaces rather than the place where EF coordination runtime lives. This naturally supports multiple people/devices/Agents: every CLI invocation resolves the same provider repository, Issue state, Git revision, and linked implementation work before acting. Provider responsibilitiesGit remains the time machine and stable engineering representation. Issues/labels are deliberately used for mutable workflow/runtime coordination rather than trying to encode workflow phase into EF Artifact files. Candidate issue responsibilities:
Portable state-label modelPrefer a provider-neutral namespaced label vocabulary, potentially using GitLab-compatible scoped syntax such as: GitLab Premium/Ultimate scoped labels provide native mutual exclusion for one scope. GitHub labels do not provide that guarantee, so EF CLI/CI must enforce exactly one state label and legal transitions on GitHub; provider-native stronger behavior is an optimization, not Core semantics. Because no remote Agent automatically executes on label events, an invalid manual label transition need not trigger unsafe work. Every local EF operation can fetch current labels/timeline/dependencies, validate the transition history/state, and refuse action until repaired. CI can additionally report/reconcile invalid provider state. Provider dependenciesUse native issue dependency/blocking relationships when available. GitHub currently exposes blocked-by/blocking relationships through UI, REST, and This may remove the previously identified cross-PLAN dependency gap at the runtime/task layer: cross-task gating can live in provider Issue dependencies rather than PLAN Scope DAG semantics. CLI architecture
using Possible local flow: The local cache/context is disposable; provider repo + Git history + Issue state are the shared worldline. Major design consequence: reconsider PLANThe existing accepted PLAN design currently mixes two classes of responsibility:
Under this provider-hosted model, aggressively reconsider PLAN rather than preserving it unchanged. Likely provider-owned concerns: Likely Git/EF-owned concerns: This may allow PLAN lifecycle fields, some persisted Confirmation/runtime data, and branch-level coordination conventions to be removed or simplified. Do not decide exact PLAN deletion/reduction until the Issue<->Git binding model is designed. Important limitationLabels are mutable provider metadata, not a transactional custom workflow engine. GitHub in particular does not natively enforce an EF-specific legal transition graph. Therefore the design should distinguish: Do not pretend labels alone provide strict server-side transition enforcement. The absence of remote Agents makes validate-on-use practical, but exact provider-state repair/audit semantics remain open. Next design questions
|
Exploration checkpoint: provider-hosted task lifecycle scenario inventoryThis is exploration, not accepted canonical direction yet. It pressure-tests the provider-hosted coordination-repository model across normal and exceptional workflows. Core splitUse a dedicated GitHub/GitLab coordination repository as the remote control plane: No remote Agent and no self-hosted EF service are required. Important Human-comment boundaryCI must not semantically interpret arbitrary Human prose. A natural-language Issue reply is durable provider input only until a local Agent consumes it. An optional future provider-native machine approval shortcut can exist, but it must not replace the default Human+Agent dialogue model. Recommended low-cardinality labelsAvoid per-Scope/per-Role/per-Concern label explosion.
Happy pathPhase regressionWorkflow is staged but not strictly monotonic. Deterministically justified regression is required when implementation/finalization invalidates prior consensus: The provider state machine must distinguish valid regression from arbitrary label tampering. Parallel tasksEach Issue gets an independent candidate branch/PR-MR. Tasks can proceed concurrently. If two open tasks produce CHG-relevant candidate effects on the same Knowledge Artifact, EF reports candidate overlap and blocks entry rather than inventing dependency direction. Human/Agent then either merge the tasks, order them via Issue dependency, or redesign scope. Cross-task dependencyPrefer provider-native Issue dependency/linked-item relationships for task DAGs. Scope Main advances while task is openAuthoritative EF main may move independently. CI on authoritative updates may re-evaluate impacted open tasks (initial implementation may conservatively scan all open EF tasks; later optimize via impact indexing). Only tasks whose proposal/context binding is affected become stale; unrelated tasks remain review-current. Human changes labels directlyA Human UI label mutation is provider input, not proof that the requested transition is EF-valid. CI triggered by the Human event validates the transition. Invalid state must be repaired/rejected with an explanatory comment. Local CLI also validates current provider projection before acting, so CI downtime cannot make an impossible phase trustworthy. Multiple devices / AgentsNo local state is authoritative. Human replies from mobile without AgentValid and expected. The reply remains queued durable input in the Issue; workflow does not advance semantically until a local Agent consumes it. This is a deliberate consequence of having no remote Agent. Implementation discovers a new engineering problemLocal Agent updates candidate EF state / Concern and pushes. CI deterministically marks affected review stale or blocked and can regress phase from implementation to review. Investigation/spike work may continue if allowed, but implementation authorization for affected scope is revoked until re-review. No-change taskPlanning/review may conclude authoritative knowledge and implementation already satisfy intent. No implementation phase is needed. Task finalizes/ closes as Abandoned taskIssue may close from planning/review/implementation with HotfixA critical implementation/code hotfix may move faster than ordinary planning. EF still records a task Issue and later reconciles authoritative engineering knowledge. Policy may permit an emergency transition path, but the exception must be explicit/auditable rather than silently bypassing EF. Exact emergency semantics remain open. Multi-repository implementationOne task may link FE/BE/infra PRs/MRs. Coordination repo CI cannot automatically read every private linked repository using its default token on all providers/configurations. Two operating levels are therefore useful: Do not pretend multi-repo publication is atomic. CI mutation behaviorCI may update labels/comments after deterministic evaluation. Do not design workflow correctness around recursive provider events caused by CI itself; perform one complete transition/projection/notification transaction in the same workflow run where practical. Provider-specific event recursion differs and GitHub Provider outage / CI failureGit retains authoritative EF state and candidate snapshots. Issue state may temporarily lag. Existing-project adoptionCreate the dedicated coordination repo and reconstruct current PROJECT/PRD/REQ/ADR/POL incrementally through Human+Agent dialogue. Gaps become ordinary Issues; do not require a big-bang perfect migration before using the task workflow. Major simplification to reconsiderOnce the provider Issue is the durable coordination/task history, the current PLAN design is likely over-owning runtime semantics. Reconsider: This may eliminate the need for terminal PLANs on authoritative main and may reduce PLAN to a branch-local proposal/consensus manifest. Do not finalize this simplification until the full scenario model is accepted. Main open design questions
|
#70 implementation clarification — deterministic query / trace / JSON contractThis records the concrete MVP command contract for the accepted query baseline without adding new product concepts.
|
Thread 8 — EF compatibility, migration, and deprecationStatus: canonical topic thread for the transition from Current accepted direction
Accepted MVP implementation strategyThe current implementation is being replaced on a dedicated rewrite branch rather than incrementally preserving two domain/storage modes inside the package.
Deferred / separate concerns
Use replies here for package/versioning compatibility, future migration tooling, EF deprecation, and release transition decisions. |
Accepted MVP decision — CHG completion command and chained supersessionAccepted on 2026-09-16 as a clarification of the canonical MVP lifecycle/replacement model. CHG completion CLICHG keeps its accepted lifecycle: The public CLI command is explicit:
Chained supersession
If A currently supersedes O, and B later supersedes A, B takes over A's current replacement targets. The resulting current graph is: and More generally, when replacement R supersedes current Artifact X, R inherits X's outgoing
This is MVP canonical behavior and should be reflected in the #69 mutation slice and command surface. |
PR #72 x-review hardening — accepted implementation contractThis records implementation-level behavior clarified while reviewing the accepted Spec MVP. It does not add a new product layer.
These choices keep the MVP deterministic for Agents without reintroducing EF transaction/history semantics. |
PR #72 x-review round 2 — adjudicated hardeningSecond-round review against the full
One reviewer candidate is clarified rather than treated as a defect: Regression coverage now includes stale-lock recovery with a concurrent second writer, |
PR #72 x-review round 3 — lock protocol correctionRound 3 confirmed that the round-2 shared-path stale-lock reclaim algorithm still admitted a TOCTOU interleaving between two ordinary reclaimers. That implementation detail is superseded. Canonical implementation contract for MVP mutation serialization is now:
This replaces the previous shared The separate reviewer candidate about a symlink appearing between |
PR #72 x-review round 4 — final adjudicationRound 4 reviewed only the final unique-claim correction (
Final evidence at head
This closes the PR #72 x-review loop for the accepted MVP contract. |
Thread 8 follow-up — EF removal and first Spec releaseWith PR #72 merged, the transition direction is now:
This supersedes the earlier deferred state for EF deprecation/archive and first Spec release numbering. |
Thread 8 follow-up — bootstrap 0.0.1 tag semanticsOne release-operational clarification is required for the manual first publish:
This refines the earlier first-release bootstrap decision without changing the package version ( |
Thread 8 follow-up — bootstrap tag safetyThe accepted
This tightens the operational contract already recorded for the bootstrap and prevents the generic release path from contradicting it. |
Thread 8 follow-up — bootstrap artifact integrityThe manual
The packed-consumer CI also keeps a direct npm-bin probe with a spaced argument so the published user-facing bin shim is exercised on the Windows matrix, while multiline/body-heavy smoke cases may invoke the installed JS entry directly to avoid shell re-parsing. |
|
Spec Tool bootstrap release completed.
Bootstrap is therefore complete. The next release should resume the normal tag-driven Trusted Publishing flow after the npm Trusted Publisher is configured. |
|
Trusted Publisher bootstrap status update (2026-09-16):
|
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Spec canonical design discussion
This Discussion is the highest-authority canonical design record for Spec /
@deviltea/spec-tool/spec.It replaces standalone chronological planning documents with topic-oriented discussion threads. Design exploration, alternatives, corrections, and accepted decisions belong here so there is one durable continuation point.
Authority and decision protocol
docs/ef-core/, issue feat(spec-tool): fork EF into Spec and redefine the product around specification maintenance #63, issue feat(ef): model planning consensus, backlog, staleness, and implementation gates #11, or other historical material, Discussion spec-tool: canonical design discussion #65 wins.packages/spec-tool/docs/ef-core/is retained as inherited EF implementation/history reference while the Spec-native model is implemented. It is not the canonical Spec product model.packages/spec-tool/docs/planning/. New design work must be recorded in this Discussion instead of creating a competing planning authority.Current high-level product baseline
Product / concept: Spec
npm package:
@deviltea/spec-toolCLI:
specSpec is a Git-native engineering specification maintenance tool designed first for Agent use.
The MVP intentionally optimizes for a single canonical workspace with reliable CRUD, query, lifecycle operations, Resource handling, and deterministic structural/reference validation.
MVP simplicity applies to workflow and authority mechanics, not to specification expressiveness.
The core specification chain is:
PROJECT and PRD provide higher-level project/product context; ADR, POL, CHG, and Artifact-owned Resources remain supported specification/provenance concepts.
Implementation remains conceptually the fifth layer but is not a persisted Spec Artifact and has no manual implementation-linkage record in the MVP. Manual linkage is deferred because it readily drifts.
Every persisted Artifact uses a collision-resistant UUIDv7 stable identity independent from title, kind, and path.
The Spec-native workspace root is
.spec/with canonical kind-based directories and a minimal tracked config. The current shipped implementation may still use inherited.engineering/paths until migrated.MVP lifecycle keeps
draft / active / superseded / retired; CHG additionally usescompleted. Lifecycle describes specification authority/currentness, not implementation progress or verification status.Deterministic validation covers schema/structure, identity uniqueness, relation/reference integrity, lifecycle invariants, Resource integrity, and other machine-checkable constraints. Natural-language semantic adequacy remains a Human/Agent review responsibility.
Human-readable CLI output and stable JSON output are both formal interfaces; the CLI follows
spec <noun> <verb>and is primarily an Agent tool protocol.Multi-target/version topology, target freshness, realized-vs-future authority lines, stale implementation gates, and Git integration-policy machinery are deferred beyond the MVP. Earlier accepted exploration is preserved in the relevant threads as future-design input but must not constrain the MVP data model.
Canonical topic threads
Historical archive
The original EF canonical body and discussion remain readable in issue #11. Its migrated design checkpoints remain preserved as historical replies in this Discussion. Issue #63 remains the historical Spec product-reset record.
History is preserved, but current Spec design authority lives here and is organized by topic rather than chronology.
All reactions