Nomos Controlled Technical English (NCTE-100) Architectural Specification

Specification Key: SPEC-NCTE-100
Classification: Public Open-Core Specification
Governing Laws: Law 1 (Dual-Core Inversion), Law 2 (Non-Verbal Proof), Law 4 (SSoT), Law 5 (Zero-Hardcoded-Path), Law 6 (Canonical Singularity), Law 7 (Fail-Closed Pre-Flight)

---

1. Executive Summary#

Natural language serves as the compilation source for AI agent execution in the Nomos substrate. Vague syntax and passive voice cause cognitive co-processors to hallucinate. Unbounded sentences waste token budgets during context injection. NCTE-100 defines a deterministic, machine-verifiable subset of English for Intent specifications and task contracts. The substrate enforces NCTE-100 rules deterministically using an AST markdown analysis engine.

---

2. Axiomatic Invariants (The 5 Rules of NCTE-100)#

Rule 1: Length and Structural Bounds#

• Descriptive sentences must not exceed 25 words.
• Procedural sentences must not exceed 20 words.
• Paragraphs must not exceed 6 sentences.

Rule 2: Imperative Mood and Active Voice#

• Procedural instructions must use the imperative mood.
• Specifications must reject passive voice constructions.
• Specifications must prohibit ambiguous modal verbs: should, would, could, might, ideally, as needed, and and/or.

Rule 3: Canonical Term Singularity (Law 6)#

• Every approved term must possess exactly one grammatical part of speech.
• Every approved term must possess exactly one architectural definition.
• Specifications must reject synonyms, convenience wrappers, and colloquial expressions.

Rule 4: Atomic Procedural Actions#

• Procedural steps must contain exactly one discrete action per sentence.
• Specifications must reject compound instructions joined by conjunctions.

Rule 5: Non-Verbal Proof Assertions (Law 2 & Law 7)#

• Acceptance criteria must declare measurable bounds, exit codes, or AST properties.
• Specifications must fail closed on qualitative adjectives lacking measurable bounds.

---

3. Dual-Core Interface Contracts and SSoT Data Structures#

NCTE-100 enforces a strict separation between Intent policy and Substrate execution. The Intent plane defines declarative rules in CUE. The Substrate plane implements the AST analysis engine in Go.

3.1 Declarative CUE Policy Schema#

The Intent schema defines mathematical bounds, banned tokens, and vocabulary contracts.

package schemas

// #NCTEBounds declares numeric constraints for markdown prose.
#NCTEBounds: {
	max_descriptive_words:   int & <= 25 | *25
	max_procedural_words:    int & <= 20 | *20
	max_paragraph_sentences: int & <= 6  | *6
	max_table_cell_words:    int & <= 12 | *12
	max_passive_adverb_gap:  int & <= 2  | *2
}

// #VocabularyDefinition declares a single approved architectural term.
#VocabularyDefinition: {
	canonical_term:   string & != ""
	part_of_speech:   "verb" | "noun" | "adjective"
	approved_meaning: string & != ""
	banned_synonyms:  [...string]
}

// #NCTEPolicy defines the authoritative validation schema.
#NCTEPolicy: {
	bounds: #NCTEBounds
	banned_modals: [...string] | *[
		"should",
		"would",
		"could",
		"might",
		"ideally",
		"as needed",
		"and/or",
	]
	exempt_table_headers: [...string] | *[
		"Input Sentence",
		"Approved Semantic Meaning",
	]
	severity: "ERROR"
	vocabulary: [...#VocabularyDefinition]
}

3.2 Compiled Go SSoT Execution Contracts#

The Substrate compiles interface definitions for high-speed AST traversal.

package ncte

import (
	"time"
)

// DiagnosticSeverity defines fail-closed pre-flight levels.
type DiagnosticSeverity string

const (
	// SeverityError halts the verification pipeline immediately with exit code 1.
	SeverityError DiagnosticSeverity = "ERROR"
)

// ErrorCode identifies the violated NCTE-100 invariant.
type ErrorCode string

const (
	ErrSentenceTooLong      ErrorCode = "ERR_NCTE_SENTENCE_TOO_LONG"
	ErrParagraphTooLong     ErrorCode = "ERR_NCTE_PARAGRAPH_TOO_LONG"
	ErrTableCellTooLong     ErrorCode = "ERR_NCTE_TABLE_CELL_TOO_LONG"
	ErrPassiveVoiceDetected ErrorCode = "ERR_NCTE_PASSIVE_VOICE"
	ErrAmbiguousModal       ErrorCode = "ERR_NCTE_AMBIGUOUS_MODAL"
	ErrCompoundAction       ErrorCode = "ERR_NCTE_COMPOUND_ACTION"
	ErrNonSingularTerm      ErrorCode = "ERR_NCTE_NON_SINGULAR_TERM"
	ErrSubjectiveAssertion   ErrorCode = "ERR_NCTE_SUBJECTIVE_ASSERTION"
)

// VocabularyEntry defines a canonical term in the compiled SSoT registry.
type VocabularyEntry struct {
	CanonicalTerm   string   `json:"canonical_term"`
	PartOfSpeech    string   `json:"part_of_speech"`
	ApprovedMeaning string   `json:"approved_meaning"`
	BannedSynonyms  []string `json:"banned_synonyms"`
}

// NCTEToken represents a parsed token with AST metadata.
type NCTEToken struct {
	Text         string `json:"text"`
	Line         int    `json:"line"`
	Column       int    `json:"column"`
	IsLiteral    bool   `json:"is_literal"`
	PartOfSpeech string `json:"part_of_speech"`
}

// NCTESentence represents an analyzed sentence unit.
type NCTESentence struct {
	RawText      string      `json:"raw_text"`
	WordCount    int         `json:"word_count"`
	IsProcedural bool        `json:"is_procedural"`
	HasPassive   bool        `json:"has_passive"`
	LineNumber   int         `json:"line_number"`
	Tokens       []NCTEToken `json:"tokens"`
}

// NCTEDiagnostic describes a deterministic rule violation.
type NCTEDiagnostic struct {
	Code     ErrorCode          `json:"code"`
	Severity DiagnosticSeverity `json:"severity"`
	Line     int                `json:"line"`
	Column   int                `json:"column"`
	Message  string             `json:"message"`
	Sentence string             `json:"sentence"`
	Remedy   string             `json:"remedy"`
}

// NCTESpecReport contains the complete verification outcome.
type NCTESpecReport struct {
	FilePath        string           `json:"file_path"`
	TotalSentences  int              `json:"total_sentences"`
	TotalWords      int              `json:"total_words"`
	ViolationsCount int              `json:"violations_count"`
	Diagnostics     []NCTEDiagnostic `json:"diagnostics"`
	Passed          bool             `json:"passed"`
	VerifiedAt      time.Time        `json:"verified_at"`
}

// NCTELinter defines the mechanical AST verification contract.
type NCTELinter interface {
	LintMarkdown(filePath string, content []byte) (*NCTESpecReport, error)
	ValidateSentence(sentence NCTESentence) []NCTEDiagnostic
}

---

4. Markdown AST Parsing and Tokenization Mechanics#

The NCTE linter converts raw markdown into an Abstract Syntax Tree using yuin/goldmark. Token counting executes under deterministic isolation rules:

4.1 Frontmatter Isolation#

• The parser extracts YAML frontmatter before AST evaluation.
• The parser evaluates frontmatter against CUE schemas.
• Frontmatter words do not contribute to document sentence counts.

4.2 Fenced Code Block and Inline Literal Handling#

• Fenced code blocks (```) represent executable artifacts.
• The parser excludes fenced code blocks from prose word counts.
• Inline code spans (`) count as exactly one atomic technical token.

4.3 Table Cell Word Counting and Exemption Markers#

• The parser evaluates standard prose table cells as independent statements.
• Standard prose table cells must not exceed 12 words.
• The parser exempts table cells from word bounds when the column header matches any entry in exempt_table_headers.
• The parser exempts code-wrapped or quoted table cells representing test literals.

4.4 Sentence Delimitation Algorithm#

• The parser splits prose on periods, question marks, and exclamation points followed by whitespace.
• Numeric decimals (3.14) and version strings (v3.0.0) must not trigger sentence splits.
• Hyphenated technical identifiers (NCTE-100, INT-590) count as single words.

4.5 Passive Voice Detection Algorithm#

• The engine identifies forms of the auxiliary verb be: am, is, are, was, were, been, being, be.
• The engine scans forward for past participles within a maximum window of 2 intervening adverb tokens.
• The engine flags matching sequences and outputs ErrPassiveVoiceDetected.

---

5. Controlled Vocabulary Registry (SSoT)#

The substrate maintains the canonical vocabulary registry dynamically. The system rejects unregistered synonyms.

Canonical Term	Part of Speech	Approved Semantic Meaning	Banned Synonyms
Verify	Verb	Execute automated validation checks and assert exit code 0.	check, test, inspect
Reject	Verb	Abort execution and return a structured non-zero exit code.	drop, ignore, fail
Trunk	Noun	The primary protected git branch (main).	master, root, upstream
Worktree	Noun	An isolated transient git worktree directory.	sandbox, folder, temp branch
Mutate	Verb	Modify or write persistent state or files.	change, edit, tweak
Prune	Verb	Remove transient worktrees or merged branches safely.	delete, clean up, wipe
Receipt	Noun	A cryptographic review or release proof stored in the database.	note, log, certificate
Seal	Verb	Commit an immutable cryptographic Git Note onto release refs.	stamp, finalize, tag

---

6. Table-Driven Test Matrix (TV-01 through TV-07)#

The table below defines the deterministic test vectors for the NCTE AST engine.

Vector ID	Input Sentence	Target Classification	Expected Word Count	Expected Violation Code	Expected Pass
TV-01	"Execute baseline verification across all quality gates."	Procedural	7	None	true
TV-02	"The database record was updated by the background agent worker."	Descriptive	10	ERR_NCTE_PASSIVE_VOICE	false
TV-03	"Developers should ideally configure the cache properly before executing heavy queries to avoid degraded system response times."	Descriptive	17	ERR_NCTE_AMBIGUOUS_MODAL	false
TV-04	"Start the transient worktree and compile the substrate binary and run all unit tests."	Procedural	14	ERR_NCTE_COMPOUND_ACTION	false
TV-05	"The system initializes the telemetry collector across twelve distinct distributed network nodes during the primary boot sequence phase to ensure optimal log synchronization and cluster discovery."	Descriptive	26	ERR_NCTE_SENTENCE_TOO_LONG	false
TV-06	"Please check the root branch sandbox before submitting your changes."	Procedural	10	ERR_NCTE_NON_SINGULAR_TERM	false
TV-07	"Ensure the parser performance is very fast and extremely robust under heavy concurrency."	Procedural	12	ERR_NCTE_SUBJECTIVE_ASSERTION	false

---

7. Dynamic Substrate Integration (Law 5 & Law 7)#

1. Dynamic Path Resolution (Law 5):

   • The NCTE engine discovers Intent source roots using config.LoadConfig().
   • The engine resolves directories dynamically via cfg.Governance.QualityGates.IntentSourceRoots.
   • The engine never embeds hardcoded repository paths.

2. Fail-Closed Gatekeeper Enforcement (Law 7):

   • The engine registers as Gate 29 in the Definition of Done pipeline.
   • Any diagnostic with SeverityError terminates verification with exit code 1.
   • Pre-commit hooks reject commits containing NCTE violations.
   • The engine permits zero warning overrides.