Semiotic Endeavor Specification

This specification defines the conformance requirements for implementing a semiotic endeavor. Where semiotic-endeavor describes what an endeavor IS (its secondary intension), this document specifies what an implementation MUST DO.

The relationship follows the structuration-interface dual: semiotic-endeavor is the internal structuration (the concept on its own terms); this specification is the external interface (what it must satisfy to count as an implementation).

1. Method component interface

Every aspect specification within an endeavor’s method MUST declare these five sections:

Source: pattern extracted from triage/specifications/ simulation specs (interface, scheduler, intake-stack, policy, storage, testing, concurrency). See semiotic-endeavor texts/technical-patterns-from-engine-contracts.md.

1.1 Normative scope declaration

Every aspect specification MUST declare a normative scope: what it IS normative about and what it IS NOT normative about. The normative scope prevents aspect specifications from accumulating unbounded obligations.

Example: semiotic-markdown is normative for file format, identifier derivation, extension recognition, resolution determinism, and minimum extraction outputs. It is not normative about a particular semantic universe, parsing library, or full AST exposure.

Source: triage/engine/contracts/semiotic-markdown/spec/semiotic-markdown.md, section 1.1.

1.2 Aspect interoperability

Aspect outputs must be typed compatibly with consuming aspects’ inputs. Invariants from different aspects must be jointly satisfiable — if two aspects declare contradictory invariants, the method is inconsistent and must be revised.

When an aspect’s invariant depends on guarantees from another aspect, this cross-aspect dependency MUST be stated explicitly.

Source: triage/specifications/ (introspection references scheduling, measurement-fabric references measurement stack, network references intake). See semiotic-endeavor texts/technical-patterns-second-pass.md.

1.3 Shared carriers

When multiple aspects produce or consume the same data structure, that structure is a shared carrier. An endeavor’s method SHOULD declare its shared carriers explicitly, giving each a name, a typed schema, and the list of aspects that produce or consume it.

Shared carriers create coupling between aspects. Declaring them makes the coupling visible and manageable.

Source: texts/technical-patterns-second-pass.md, pattern 5.

2. Method component lifecycle

Each specification within the method has a lifecycle with concrete transition guards:

2.1 Error semantics

Each procedure step in a method component must specify which errors it can emit, with fields for severity (info/warn/error/fatal), fault attribution (producer/consumer), and retryability. Ambiguities in a specification are errors, not unspecified behavior.

Source: normative scaffold from triage/engine/contracts/spec-spec/README.md.

3. Repository conformance

A repository is operable as the body of an endeavor iff it provides a declaration file at its root (currently semantics.yaml) containing:

• kind: a discriminator selecting which operator families apply
• kind-specific parameters (what the repository contains, how to address its artifacts)
• publication parameters (slugs, output formats)

Operators (skills, scripts, MCP tools) are grouped into operator families selected by kind. An operator family is a set of typed operations that share the same preconditions about repository structure. Operators that require a kind not declared by the repository are ill-typed and must not be applied.

Source: triage/engine/contracts/semiotic-repository/semiotic-repository.md.

4. Aspect registration

When a new aspect specification is added to an endeavor’s method, the method’s coherence properties must be preserved. This section specifies the registration process.

4.1 Registration preconditions

Before an aspect specification may be registered as part of a method, it MUST satisfy all of the following:

1. Interface completeness: the aspect declares all five sections from §1 (state representation, inputs, procedures, invariants, outputs).
2. Normative scope declaration: the aspect declares what it IS and IS NOT normative about (§1.1).
3. Lifecycle state: the aspect has at least draft maturity (§2).
4. Unique identity: the aspect has a spec-id that does not collide with any existing registered aspect.

4.2 Compatibility checking

Upon registration, the following compatibility checks MUST be performed against all existing aspects in the method:

1. Invariant compatibility: the new aspect’s invariants MUST be jointly satisfiable with every existing aspect’s invariants. Two invariants conflict when no state exists that satisfies both simultaneously. If a conflict is detected, registration MUST fail with an error identifying the conflicting invariant pair.

2. Input/output type compatibility: if the new aspect declares inputs that consume outputs from existing aspects, the type of each consumed output MUST be compatible with the declared input type. Compatibility means: every value conforming to the output schema also conforms to the input schema (the output type is a subtype of the input type).

3. Cross-aspect dependency declaration: if the new aspect’s invariants depend on guarantees from existing aspects, these dependencies MUST be stated explicitly in the aspect’s specification (§1.2). Implicit cross-aspect dependencies are specification errors.

4.3 Shared carrier update protocol

When a new aspect produces or consumes a data structure that is already a shared carrier (§1.3), the registration process MUST:

1. Identify affected carriers: list each shared carrier that the new aspect reads from or writes to.
2. Verify schema compatibility: the new aspect’s use of the carrier MUST conform to the carrier’s declared typed schema. Extending the schema (adding new fields) requires a coordinated update across all aspects that use the carrier.
3. Update carrier declarations: add the new aspect to each affected carrier’s producer or consumer list.
4. Notify affected aspects: each existing aspect that uses an affected carrier MUST be reviewed for compatibility with the extended usage. If the schema changes, affected aspects MUST be updated to a new minor version (if the change is additive) or major version (if the change is breaking).

When a new aspect introduces a new shared carrier (a data structure not previously shared), the carrier MUST be declared following §1.3 before the aspect is registered.

5. Method coherence verification

An endeavor’s method is coherent when its aspect specifications are jointly satisfiable. This section specifies concrete procedures for verifying coherence.

5.1 What to check

Method coherence verification MUST check these properties:

1. Invariant joint satisfiability: for every pair of aspects (A_i, A_j) in the method, there exists at least one state that satisfies all invariants of both A_i and A_j simultaneously. For the full method, there exists at least one state satisfying all invariants of all registered aspects simultaneously.

2. Shared carrier consistency: for each shared carrier, all producing aspects write values conforming to the carrier’s schema, and all consuming aspects accept values conforming to the carrier’s schema.

3. Dependency graph acyclicity: the cross-aspect dependency graph (aspects as nodes, explicit dependency declarations as edges) MUST be a directed acyclic graph. A cycle indicates a specification error — two aspects that mutually depend on each other’s guarantees without a resolution order.

4. Normative scope disjointness: no two aspects SHOULD declare overlapping normative scopes. When overlap is unavoidable (e.g., both semiotic-markdown and semiotic-specification are normative about frontmatter format), the overlap MUST be explicitly acknowledged and the resolution priority declared.

5.2 How to check

Verification may be performed manually or by automated tooling. In either case, the procedure is:

1. Enumerate: list all registered aspects and their invariants.
2. Pair: for each pair of aspects, compare their invariant sets. Flag any pair where the invariants are contradictory (no state satisfies both).
3. Compose: attempt to construct a composite state satisfying all invariants simultaneously. If no such state can be constructed, identify the minimal conflicting subset (the smallest set of invariants that cannot be jointly satisfied).
4. Graph: construct the dependency graph from cross-aspect dependency declarations. Check for cycles using topological sort.
5. Report: produce a coherence report listing: total aspects checked, invariant pairs verified, conflicts found, dependency graph structure (DAG or cyclic), normative scope overlaps.

5.3 What constitutes failure

Method coherence verification fails when ANY of the following hold:

• Two invariants from different aspects are contradictory and no resolution is declared.
• A shared carrier’s schema is violated by a producing or consuming aspect.
• The dependency graph contains a cycle.

A coherence failure MUST be resolved before any affected aspect advances beyond draft maturity. An endeavor MAY operate with known coherence failures during formation, but MUST resolve them before entering active conduct with all affected aspects at candidate or higher maturity.

6. Governance interface

An endeavor MUST have governance structures sufficient to sustain its method-practice loop. This section specifies the minimum governance interface.

6.1 Required governance structures

An endeavor’s governance MUST include:

1. Policies: standing commitments that constrain how work is done. Policies MUST be recorded as durable artifacts in the repository (not ephemeral conversation). Each policy MUST state its source rationale. Policies are append-only: they may be superseded but not silently removed.

2. Decision records: each decision that narrows the space of future decisions MUST be recorded with: the decision made, the alternatives considered, the evidence supporting the choice, and the date. Decision records are append-only.

3. Evidence-gated transitions: lifecycle transitions (§2, §7) MUST require evidence appropriate to the transition. The evidence requirement for each transition MUST be specified in advance, not determined ad hoc.

4. Endeavor ownership: an endeavor MUST have an identifiable owner (individual or group) who reviews plans, accepts or rejects proposals, and resolves disputes. The owner is not a manager but a reviewer — work is selected by leverage (closure pressure and goal alignment), not by assignment.

6.2 Governance evolution

Governance structures MUST be revisable. When practice reveals that a governance structure does not fit reality, the structure is revised through the same evidence-gated process used for any method change: demonstrate the inadequacy, propose the revision, record the decision.

Governance revision is constrained by the same four conditions that constrain method evolution (see semiotic-endeavor §Method evolution): continuity, coherence, closure compatibility, and evidence.

6.3 Primacy of the concrete endeavor

When a concrete endeavor’s practice diverges from an abstract specification’s governance requirements, the concrete endeavor’s practice MAY override the specification — provided the override follows this procedure:

1. Demonstrate the divergence: articulate what the specification requires and what practice does instead, with evidence that practice produces better outcomes for the endeavor’s function.
2. Record the override: write a decision record documenting the divergence and its justification.
3. Update the specification: revise the abstract specification to accommodate the better pattern, so that future endeavors benefit.
4. Propagate: if the change affects dependent specifications, update them.

This primacy principle recognizes that abstract specifications are derived from concrete practice, not imposed upon it. The concrete endeavor’s function is the authorization source for overrides. Override without comprehension (changing practice without understanding what the specification requires and why) is not sanctioned by this provision.

See personal/projects/emsemioverse/texts/emsemioverse-endeavor-primacy.md for the emsemioverse’s articulation of this principle.

7. Lifecycle transition procedures

Section 2 specifies transition guards — the conditions that MUST hold before a method component enters a lifecycle state. This section specifies transition procedures — the steps that MUST be taken to effect each transition.

7.1 Draft → Candidate

Guard (from §2): all five interface sections present; conformance matrix mapping each normative statement to actors.

Procedure:

1. Verify interface completeness: check that state representation, inputs, procedures, invariants, and outputs are all declared. Missing sections MUST be written, not stubbed.
2. Construct conformance matrix: for each normative statement in the specification, identify which actor(s) are responsible for satisfying it (producer, consumer, validator). Every normative statement MUST appear in the matrix. A normative statement with no assigned actor is unimplementable.
3. Run coherence verification (§5) against all existing candidate or stable aspects. New conflicts MUST be resolved before the transition completes.
4. Version: set the version to (n, 0) where n is the next major version if this is a new spec, or increment the minor version if this is a revision of an existing candidate.
5. Record: append a changelog entry documenting the transition, the evidence reviewed, and any coherence issues resolved.

7.2 Candidate → Stable

Guard (from §2): conformance test suite passes; determinism verified; upgrade path documented.

Procedure:

1. Execute conformance tests: run all tests in the conformance test suite against at least one implementation. The test suite MUST cover every normative statement in the conformance matrix. Failing tests MUST be resolved by fixing the implementation, fixing the specification, or documenting the gap as a known limitation.
2. Verify determinism: demonstrate that the same inputs produce identical outputs across at least two independent executions. Non-deterministic behavior MUST be either eliminated or explicitly declared as permitted non-determinism in the normative scope.
3. Document upgrade path: if this specification supersedes a prior version, document: what changed, how to migrate, and what the dual-stack behavior is during transition.
4. Review governance impact: check whether the stable specification changes any governance requirements, policies, or decision records. If so, update those artifacts.
5. Record: append a changelog entry. Update the version to reflect stable status.

7.3 Stable → Deprecated

Guard (from §2): successor identified; deprecation window announced; dual-stack behavior available.

Procedure:

1. Identify successor: name the specification (or revision) that supersedes this one. The successor MUST be at least candidate maturity.
2. Announce deprecation window: declare the period during which both the deprecated specification and its successor are valid. During this window, implementations MAY conform to either.
3. Implement dual-stack behavior: ensure that implementations can operate under both the deprecated and successor specifications during the deprecation window. Document any incompatibilities that prevent full dual-stack operation.
4. Notify dependent specifications: identify all specifications that declare cross-aspect dependencies on this one. Each MUST be notified of the deprecation and given the deprecation window to adapt.
5. Record: append a changelog entry documenting the deprecation, the successor, the window, and the notification recipients.

7.4 Deprecated → Superseded

Guard (from §2): migration complete; deprecated spec’s conformance tests pass against the successor.

Procedure:

1. Verify migration: confirm that all implementations have migrated to the successor specification. “All implementations” means: every active skill, script, or procedure that referenced the deprecated specification now references the successor.
2. Run backward compatibility tests: execute the deprecated specification’s conformance test suite against the successor. All tests MUST pass (the successor must be at least as capable as what it supersedes).
3. Archive: move the deprecated specification to an archival location or mark it with stability: superseded in its frontmatter. The specification MUST remain readable (for historical reference) but MUST NOT be used for new work.
4. Update references: find and update all cross-references to the deprecated specification. References in decision records and changelogs are exempt (they are historical).
5. Record: append a final changelog entry documenting the supersession.

8. Skills specification

Skills are codified capabilities within an endeavor’s method. A skill is a named, versioned, invocable unit of work with a declared interaction surface. This section specifies what skills ARE at the endeavor level — how any endeavor’s method may include skills as method components.

8.1 Skill as method component

A skill is a method component that differs from an aspect specification in scope and granularity. Where an aspect specification governs a domain of practice (file format, version semantics, change tracking), a skill governs a single capability — a specific operation that can be invoked, composed, and versioned.

Skills are how an endeavor’s method is executed. Specifications declare what should be done; skills encode how to do it. The relationship is: specifications prescribe, skills implement, practice is the execution of skills within the context prescribed by specifications.

8.2 Skill kinds

An endeavor’s skill system MUST support at least these kinds:

An implementation MAY define additional kinds. Each kind MUST have a clear definition that distinguishes it from other kinds.

8.3 Runtime types and progressive automation

Skills exist along a progressive automation trajectory. Each runtime type represents a stage of automation maturity:

An endeavor’s method SHOULD encode the progressive automation principle: as a capability becomes well-understood, it SHOULD move from higher-numbered stages toward lower-numbered stages (inference → script → tool). This is not mandatory for every skill — some skills are inherently inference-based (e.g., writing texts) and will not become scripts. The principle applies where the task is well-understood and deterministic.

8.4 Skill composition

Skills compose through two mechanisms:

1. Dependencies: a skill MAY declare dependencies on other skills. The dependency relationship means the depended-upon skill must be available before the dependent skill can be invoked. Dependencies form a directed acyclic graph.

2. Pipelines: skills MAY be composed into pipelines where one skill’s output feeds another’s input. Pipeline composition requires that the output schema of the upstream skill be compatible with the input schema of the downstream skill.

An endeavor MUST maintain the acyclicity invariant: the dependency graph across all registered skills MUST be a DAG. Cyclic dependencies indicate a specification error.

8.5 Skill and specification relationship

Skills and specifications are distinct but related components of method:

• A specification declares normative requirements. A skill implements a capability that may be governed by one or more specifications.
• Multiple skills may implement different aspects of the same specification. A single skill may operate under requirements from multiple specifications.
• When a specification is revised, skills governed by it MUST be reviewed for continued conformance. When a skill’s behavior changes, the specifications it operates under MUST be checked for violations.

9. Skill specification interface

A skill manifest is the declaration that makes a skill part of the method. This section specifies what a skill manifest MUST contain — the normative requirements for skill declarations.

9.1 Required fields

Every skill manifest MUST declare:

These two fields are the minimum viable manifest. A skill with only these fields can be discovered and invoked, though it cannot be validated for region safety or schema correctness.

9.2 Recommended fields

A validation-complete manifest SHOULD additionally declare:

9.3 Region declarations

When a skill manifest declares a region, the declaration MUST specify:

• reads: the set of directory paths the skill reads from.
• writes: the set of directory paths the skill writes to.

A skill MUST NOT write to directories outside its declared write region. A skill MUST NOT read from directories outside its declared read region (with the exception that ancestor directories of write paths are implicitly readable for context discovery).

When a manifest omits the region declaration, the skill is treated as unrestricted — it may read from or write to any directory. Unrestricted skills cannot be parallelized with any skill that declares writes.

9.4 Trigger requirements

A skill with runtime inference or script SHOULD include at least one trigger phrase or a sufficiently specific description to enable prompt-based dispatch. A skill with no triggers and a generic description can only be invoked by direct naming or as a dependency of another skill.

Trigger phrases SHOULD be natural language expressions that a user or agent would plausibly use when intending to invoke the skill. Generic triggers (e.g., “do something”) are discouraged — they create dispatch ambiguity.

9.5 Versioning constraints

Skill manifest versions follow a two-part scheme (major, minor):

• Minor version change (n, m) → (n, m+1): additive changes only. New fields may be added to inputs/outputs; existing fields retain their types. The write region may shrink but not expand. The read surface may expand. Dependencies may be added or removed.

• Major version change (n, m) → (n+1, 0): breaking changes permitted. Field types may change; the write region may expand; schemas may become incompatible with the prior version.

The id field MUST NOT change across versions. The id uniquely identifies the skill across all versions.

9.6 Validation requirements

A skill manifest SHOULD be validated against these checks:

1. Required fields (id, description) are present.
2. The id matches the skill’s directory name.
3. All declared dependencies reference existing skill ids.
4. Region paths reference valid directories.
5. Input and output schemas are well-typed.
6. Triggers are present for invocable skills (runtime inference or script).
7. The dependency graph remains acyclic after registration.

Validation MAY be performed by automated tooling (scripts, hooks) or by manual review. An endeavor SHOULD implement automated validation for at least checks 1-4.

10. What this specification does not yet cover

The conformance areas listed in previous versions of this section (aspect registration, method coherence verification, governance interface, lifecycle transition procedures) are now addressed in §4-§7. Additional gaps remain:

• Conformance test suite framework: the specification requires conformance tests (§7.2) but does not specify the format or framework for writing them.
• Cross-endeavor aspect sharing: how two endeavors share aspect specifications or skills across repository boundaries.
• Governance dispute resolution: §6 requires an endeavor owner for dispute resolution but does not specify the resolution procedure beyond “reviews and resolves.”
• Skill pipeline orchestration: §8.4 describes pipeline composition but does not specify how pipelines are declared, validated, or executed as composite units.