Spec kit C++ constitution.md

constitution.md

C++ Client Application Development Constitution

Location: .specify/memory/constitution.md

This constitution governs C++ code for client-side tools, utilities, and applications that interact with PostgreSQL.

I. Language Standard

C++ code MUST use C++14 standard. Code MUST emphasize clarity and modern idiomatic C++.

II. Code Style & Formatting

Follow K&R style with 2-space indentation, same-line opening braces. Use camelCase for functions/variables, PascalCase for classes/types.

class PgConnection {
  std::unique_ptr<PGconn, decltype(&PQfinish)> conn_;

public:
  explicit PgConnection(const std::string& connStr)
    : conn_(PQconnectdb(connStr.c_str()), PQfinish) {
    if (PQstatus(conn_.get()) != CONNECTION_OK) {
      throw std::runtime_error("Connection failed");
    }
  }

  auto execute(const std::string& query) {
    return std::unique_ptr<PGresult, decltype(&PQclear)>(
      PQexec(conn_.get(), query.c_str()), PQclear);
  }
};

III. Resource Management

RAII and smart pointers are REQUIRED. No naked new/delete.

Encouraged:

• unique_ptr, shared_ptr for ownership
• Standard library containers and algorithms
• Range-based for loops
• auto for type deduction
• Lambdas for std algorithms

Forbidden:

• Template metaprogramming (SFINAE, enable_if, CRTP)
• Expression templates
• Operator overloading without clear benefit
• Excessive template usage

IV. Documentation Standards

File Headers

Every source file MUST begin with copyright notice and doxygen-style header:

/*
 * Copyright (c) 2026 dataStone Inc.
 * SPDX-License-Identifier: MIT
 */

/**
 * @file connection_manager.cpp
 * @brief PostgreSQL connection pool manager
 * @author Dave Sharpe
 * @date 2025-12-13
 * This file was developed with assistance from AI tools.
 */

The @date tag reflects original file creation; updates tracked via version control.

Function Documentation

Function headers MUST document purpose, parameters (@param), and return values (@return). Use @throws for exceptions.

/**
 * @brief Execute query and return result set
 * @param query SQL query string
 * @return Unique pointer to PGresult
 * @throws std::runtime_error on connection failure
 */
auto execute(const std::string& query);

Inline Comments

Inline comments MUST use // style. Focus on explaining WHY decisions were made, not WHAT the code does when self-evident.

V. Build Requirements

Code MUST compile cleanly with:

CXXFLAGS="-std=c++14 -Wall -Wextra -Werror"

VI. Project Structure

Every repository MUST include:

• LICENSE file containing full MIT License text
• README.md with installation and usage instructions
• CHANGELOG.md following Keep a Changelog format
• doc/ folder for detailed documentation

See project_template.md for documentation templates and structure guidelines.

VII. Code Review

Code submissions MUST pass all applicable checks in code_review_checklist.md before merge.

VIII. Governance

This constitution supersedes all other development practices for this project.

Deviations require documented approval with clear reasoning.

---

Version: 1.0.0 | Ratified: 2026-01-07