docs(content): deterministic principle philosophy doc and BDD strategy (#159, #81)

[MScottAdams]

Summary

Two documentation tasks from SPECIFICATION.md Phase 2.7:

Task A: meta/philosophy.md (t2.7.7, #159) -- Deterministic > Probabilistic design principle

• Created meta/philosophy.md with RFC2119 legend and See also banner
• Documents the principle: prefer deterministic components (fixed commands, schema validators, CI checks, Taskfile tasks) over probabilistic ones (LLM inference) for repeatable actions
• Includes definition, rationale, concrete examples from the Deft framework (Taskfile tasks, spec_validate.py, CI workflows)
• Scope note explicitly defers broad application to Phase 5
• Added reference from contracts/hierarchy.md See also banner

Task B: strategies/bdd.md (t2.7.8, #81) -- BDD/acceptance-test-first strategy

• Created strategies/bdd.md with RFC2119 legend and See also banner
• 6-step workflow: identify scenarios, write failing tests, surface ambiguity, lock decisions, generate spec, chain into sizing gate
• Output artifacts: specs/{feature}/acceptance-tests/ + {feature}-bdd-context.md
• Integrates as a preparatory strategy in the chaining gate
• Anti-patterns section
• Added bdd.md row to strategies/README.md
• Added est_bdd_strategy_exists to ests/content/test_structure.py

Validation

• ask check passes: 875 passed, 25 xfailed
• CHANGELOG.md entries added under [Unreleased]

Files Changed

• meta/philosophy.md (new)
• strategies/bdd.md (new)
• contracts/hierarchy.md (See also link added)
• strategies/README.md (bdd row added)
• ests/content/test_structure.py (bdd assertion added)
• CHANGELOG.md (entries added)

Closes #159
Closes #81

[greptile-apps]

Greptile Summary

This PR adds two documentation files as part of SPECIFICATION.md Phase 2.7: meta/philosophy.md (the deterministic > probabilistic design principle) and strategies/bdd.md (the BDD/acceptance-test-first strategy), along with supporting updates to contracts/hierarchy.md, strategies/README.md, tests/content/test_structure.py, and CHANGELOG.md. All changes are internally consistent with the repo's RFC2119 notation style, relative-link conventions, and chaining gate pattern.

Confidence Score: 5/5

Safe to merge — all findings are P2 style suggestions with no impact on correctness or runtime behavior.

No P0 or P1 issues were found. Both new documentation files are internally consistent, cross-references use correct relative paths, the test passes, and CHANGELOG entries are properly formatted. The two P2 comments (missing AGENTS.md command entry, redundant explicit test) are non-blocking.

No files require special attention; all changes are clean documentation additions.

Important Files Changed

Filename	Overview
meta/philosophy.md	New design principle doc: deterministic > probabilistic; RFC2119 notation, cross-references, and scope note are all consistent with repo style
strategies/bdd.md	New BDD preparatory strategy doc; 6-step workflow, output artifacts, chaining gate integration, and anti-patterns are well-structured and consistent with peer strategy files
contracts/hierarchy.md	Added meta/philosophy.md to See also banner; relative path ../meta/philosophy.md is correct for the contracts/ directory
strategies/README.md	Added bdd.md row with correct type (preparatory), command (/deft:run:bdd), use case, and phases description; table format consistent
tests/content/test_structure.py	Added test_bdd_strategy_exists; provides explicit traceability to t2.7.8/#81 but duplicates coverage already provided by the parametrized test_strategy_file_exists
CHANGELOG.md	Correct [Unreleased] entries for both tasks with issue/task references; format matches existing entries

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A([User triggers /deft:run:bdd]) --> B[Step 1: Identify User Scenarios\nGiven/When/Then → specs/feature/acceptance-tests/]
    B --> C[Step 2: Write Failing Acceptance Tests\nExecutable tests — MUST fail initially]
    C --> D[Step 3: Run Tests\nSurface ambiguity & missing decisions]
    D --> E[Step 4: Lock Decisions\nRecord in feature-bdd-context.md]
    E --> F[Step 5: Generate Spec\nDerive SPECIFICATION.md tasks]
    F --> G[Step 6: Register artifacts in vbrief/plan.vbrief.json]
    G --> H{Chaining Gate}
    H -->|Run more strategies| I[map / discuss / research / ...]
    H -->|Proceed| J[interview.md sizing gate\nLight or Full path]
    I --> H
    J --> K([SPECIFICATION.md finalised])

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: strategies/README.md
Line: 16

Comment:
**`/deft:run:bdd` not listed in AGENTS.md Commands**

The three peer preparatory strategies `discuss`, `research`, and `map` all appear in the `AGENTS.md` Commands section (lines 64–70), making them discoverable without consulting `strategies/README.md`. The new `bdd` strategy is absent from that index. Consider adding `/deft:run:bdd <feature>` alongside the other preparatory commands so agent routing is complete.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: tests/content/test_structure.py
Line: 172-176

Comment:
**Explicit test duplicates parametrized coverage**

`test_bdd_strategy_exists` checks for `strategies/bdd.md`, but adding `bdd.md` to `strategies/README.md` already causes the existing parametrized `test_strategy_file_exists` to cover it automatically. The dedicated function is harmless but redundant — the parametrized test will catch the same absence with a more descriptive failure message. No action required, just noting the overlap.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "docs(content): add meta/philosophy.md an..." | Re-trigger Greptile}